= Application planning =

'''Application planning''' is a mechanism that lets the scheduler decide,
using project-supplied logic,
whether an application is able to run on a particular host,
and if so what resources it will use and how fast it will 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 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.global_prefs''' field, the user's global preferences
 * in '''sreq.coprocs''', a list of the hosts's coprocessors.

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 {
   COPROCS coprocs;   // coprocessors used by the app (name and count)
   double avg_ncpus;  // avg #CPUs used by app (may be fractional)
   double max_ncpus;  // max #CPUs used (relevant if user changes prefs later)
   double flops;      // estimated FLOPS
   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 '''flops''' is greatest.
The client uses '''flops''' to estimate job completion times.

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_plan.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'''.
 '''cuda''':: A CUDA application that requires 254MB of GPU RAM, and that uses .5% as many CPU FLOPS as GPU FLOPS.
 '''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).



== Notes ==

 * The server code that estimates completion times currently doesn't know about multiprocessors or coprocessors.