Jobs

A BOINC job has two parts:

• A workunit describing the computation to be performed.
• One or more results, each of which describes an instance of a computation, either unstarted, in progress, or completed. The BOINC client software refers to results as "tasks".

These entities are stored in the 'workunit' and 'result' database tables respectively.

BOINC provides a utility program and C function for creating jobs.

Workunit attributes

A workunit has several attributes. These are specified when the workunit is created; they are mandatory except where noted.

name

A text string, unique across all workunits in the project.

application

Which application will perform the computation. A workunit is associated with an application, not with a particular version or range of versions. If the input data format changes in a way that is incompatible with older versions, you must either a) release new versions for all supported platforms, or b) create a new application. Such incompatibilities can often be avoided by using XML data format.

input files

A list of the input files: their names, and the names by which the application refers to them. Typically these file are downloaded from a data server. However, if the <generate_locally/> element is present, the file is generated on the client (typically by an earlier instance of the same application). Applications should use file locking to prevent two jobs from generating the file at the same time.

batch

(optional) An integer; can be used to operate (cancel, change priority etc.) on groups of workunits.

Resource estimates and bounds

rsc_fpops_est

An estimate of the average number of floating-point operations required to complete the computation. This is used to estimate how long the computation will take on a given host.

rsc_fpops_bound

A bound on the number of floating-point operations required to complete the computation. If this bound is exceeded, the application will be aborted.

rsc_memory_bound

An estimate of application's largest working set size. The workunit will only be sent to hosts with at least this much available RAM.

rsc_disk_bound

A bound on the maximum disk space used by the application, including all input, temporary, and output files. The workunit will only be sent to hosts with at least this much available disk space. If this bound is exceeded, the application will be aborted.

rsc_bandwidth_bound

If nonzero, this job will be sent only to hosts with at least this much download bandwidth. Use for applications with very large input files.

It's important that you supply accurate values for these parameters. To get initial estimates, run your application on your own machines, and monitor the memory and disk usage. To view the distribution of FLOPs, use the script html/ops/job_times.php (the FLOP count statistics link on your project's administrative web interface).

Redundancy and scheduling attributes

delay_bound

An upper bound on the time (in seconds) between sending a result to a client and receiving a reply. The scheduler won't issue a result if the estimated completion time exceeds this. If the client doesn't respond within this interval, the server 'gives up' on the result and generates a new result, to be assigned to another client. Set this to several times the average execution time of a workunit on a typical PC. If you set it too low, BOINC may not be able to send some results, and the corresponding workunit will be flagged with an error. If you set it too high, there may a corresponding delay in getting results back.

min_quorum

The minimum size of a 'quorum'. The validator is run when there are this many successful results. If a strict majority agree, they are considered correct. Set this to two or more if you want redundant computing.

target_nresults

How many results to create initially. This must be at least min_quorum. It may be more, to reflect the ratio of result loss, or to get a quorum more quickly.

max_error_results

If the number of client error results exceeds this, the work unit is declared to have an error; no further results are issued, and the assimilator is triggered. This safeguards against workunits that cause the application to crash.

max_total_results

If the total number of results for this workunit exceeds this, the workunit is declared to be in error. This safeguards against workunits that are never reported (e.g. because they crash the core client).

max_success_results

If the number of success results for this workunit exceeds this, and a consensus has not been reached, the workunit is declared to be in error. This safeguards against workunits that produce nondeterministic results.

priority

(optional) Higher-priority work is dispatched first

A workunit can experience any of several error conditions:

WU_ERROR_COULDNT_SEND_RESULT

The BOINC scheduler was unable to send the workunit to a large number (~100) of hosts, probably because its resource requirements (disk, memory, CPU) were too large for the hosts, or because no application version was available for the hosts' platforms. In this case BOINC 'gives up' on the workunit.

WU_ERROR_TOO_MANY_ERROR_RESULTS

Too many results with error conditions (upload/download problem, client crashes) have been returned for this work unit.

WU_ERROR_TOO_MANY_SUCCESS_RESULTS

Too many successful results have been returned without consensus. This indicates that the application may be nondeterministic.

WU_ERROR_TOO_MANY_TOTAL_RESULTS

Too many total results have been sent for this workunit.

If any of these conditions holds, BOINC doesn't dispatch more instances of the workunit.

Result attributes

The main attribute of a result is list of the names of the output files, and the names by which the application refers to them.

A result has a server_state whose values include:

	Inactive (not ready to dispatch)
	Unsent (ready to send to a client, but not sent)
	In progress (sent, not done)
	Done successfully
	Timed out
	Done with error
	Not needed (work unit was finalized before this result was sent)

Additional attributes are defined after the result is completed:

host	The host that executed the computation.
exit status	The exit status (0 if success).
CPU time	The CPU time that was used.
output file info	The sizes and checksums of its output files.
stderr	The stderr output of the computation.
received time	The time when the result was received.