= Application planning =

'''Application planning''' is a mechanism that lets the scheduler decide,
using project-supplied logic:

 * whether an application should run on a particular host;
 * what resources it will use;
 * how fast it is expected to run.

It works as follows.

An app version has an associated '''plan_class''': a character string, possibly empty.
The plan class is encoded in the app version's directory name,
as used by [UpdateVersions update_versions].

The scheduler is linked with a function
{{{
bool app_plan(SCHEDULER_REQUEST &sreq, char* plan_class, HOST_USAGE&);
}}}
The '''sreq''' argument describes the host.
It contains:
 * in '''sreq.host''' field, a description of the host's hardware, including:
  * In p_vendor and p_model, the processor type
  * In p_features, the processor features (e.g., fpu tsc pae nx sse sse2 mmx)
  * In m_nbytes, the amount of RAM
 * in '''sreq.coprocs''', a list of the hosts's coprocessors.
 * in '''core_client_version''', the client's version number in MMmmRR form.

When called with a particular SCHEDULER_REQUEST and plan class,
the function returns true if the host's resources are sufficient for apps of that class.
If true, it populates the HOST_USAGE structure:
{{{
struct HOST_USAGE {
   double ncudas;     // number of NVIDIA GPUs used
   double natis;      // number of ATI GPUs used
   double gpu_ram;    // max amount of GPU RAM used
   double avg_ncpus;  // avg #CPUs used by app (may be fractional)
   double max_ncpus;  // max #CPUs used (not currently used for anything)
   double projected_flops;
      // an estimate of the actual FLOPS.
      // used to select versions, so make it higher for the preferred version
   double peak_flops;
      // the peak FLOPS of the devices to be used
   char cmdline[256]; // passed to the app as a cmdline argument;
                      // this can be used, e.g. to control the # of threads used
};
}}}

When deciding whether to send a job to a host,
the scheduler examines all latest-version app_versions for the platform,
calls '''app_plan()''' for each,
and selects the one for which '''projected_flops''' is greatest.

If '''gpu_ram''' is nonzero, the BOINC client (6.10.25+)
won't start the app unless that much RAM is available on the allocated GPU.

You are free to define your own set of plan classes,
and to link your own '''app_plan()''' function with the scheduler.
The BOINC scheduler comes with a default '''app_plan()''' (in sched/sched_customize.cpp).
This defines the following plan classes:

 '''mt''':: An application that can use anywhere from 1 to 64 threads, and whose speedup with N CPUs is .95N.  It is passed a command-line argument '''--nthreads N'''.
 '''nci''':: A non-CPU-intensive application that uses 1% of a CPU (this will cause the BOINC client 6.7+ to run it at non-idle priority).
 '''sse3''':: A CPU app that requires the SSE3 CPU feature.

... and a number of [AppCoprocessor GPU plan classes].