Workunits

TODO: don't separate into XML/other parts; describe XML format only in the tools doc.

A workunit describes a computation to be performed. Workunits are maintained in the workunit table in the BOINC DB. The attributes of a workunit include:

Its name (unique across all workunits in the project).
Its application.
An XML document describing its input files and other parameters (see below).
The estimated resource requirements of the work unit (computation, memory, disk space).
A delay bound: upper bound on how long (in real time) a result associated with this work unit should take to complete. This determines which hosts the workunit can be sent to, and it's used to assign result deadlines and times for retrying results.

Some parameters of a workunit are described by an XML document of the form

[ <file_info>...</file_info> ]
[ ... ]
<workunit>
    [ <command_line>-flags xyz</command_line> ]
    [ <env_vars>name=val&name=val</env_vars> ]
    [ <max_processing>...</max_processing> ]
    [ <max_disk>...</max_disk> ]
    [ <file_ref>...</file_ref> ]
    [ ... ]
</workunit>

The components are:

<command_line>	The command-line arguments to be passed to the main program.
<env_vars>	A list of environment variables in the form name=value&name=value&name=value.
<max_processing>	Maximum processing (measured in Cobblestones). An instance of the computation that exceeds this bound will be aborted. This mechanism prevents an infinite-loop bug from indefinitely incapacitating a host. The default is determined by the client; typically it is 1.
<max_disk>	Maximum disk usage (in bytes). The default is determined by the client; typically it is 1,000,000.
<file_ref>	describes a reference to an input file, each of which is described by a <file_info> element.

A workunit is associated with an application, not with a particular version or range of versions. If the format of your input data changes in a way that is incompatible with older versions, you must create a new application. This can often be avoided by using XML data format.

The create_work utility program provides a simplified interface for creating workunits.