Generating Work
From Unofficial BOINC Wiki
Contents |
[edit] General
As described elsewhere, a Work Unit represents the inputs to a computation. The steps in creating a Work Unit are:
- Write XML 'template files' that describe the Work Unit and its corresponding Results. Generally the same templates will be used for a large number work of Work Units.
- Create the Work Unit's Data File(s) and place them in the Download Directory.
- Call a BOINC function that creates a database Work Unit Record for the Work Unit.
Once this is done, BOINC System Software takes over: it creates one or more Results for the Work Unit, distributes them to Participant Hosts, collects the output files, finds a Canonical Result, Assimilates the Canonical Result, and deletes files.
During the testing phase of a Project, you can use the Make Work Daemon to replicate a given Work Unit as needed to maintain a constant supply of work. This is useful while testing and debugging the Application.
[edit] Work Unit Template File
A Work Unit Template File has the form:
<file_info>
<number>0</number>
[ <sticky/>, other attributes]
</file_info>
[ ... ]
<workunit>
<file_ref>
<file_number>0</file_number>
<open_name>NAME</open_name>
</file_ref>
[ ... ]
[ <command_line>-flags xyz</command_line> ]
[ <rsc_fpops_est>x</rsc_fpops_est> ]
[ <rsc_fpops_bound>x</rsc_fpops_bound> ]
[ <rsc_memory_bound>x</rsc_memory_bound> ]
[ <rsc_disk_bound>x</rsc_disk_bound> ]
[ <delay_bound>x</delay_bound> ]
[ <min_quorum>x</min_quorum> ]
[ <target_nresults>x</target_nresults> ]
[ <max_error_results>x</max_error_results> ]
[ <max_total_results>x</max_total_results> ]
[ <max_success_results>x</max_success_results> ]
</workunit>
The components are:
| <file_info>, <file_ref> | Each pair describes an Work Unit Data File. |
| <command_line> | The command-line arguments to be passed to the main program. |
| Other elements | The attributes of information corresponding to the information in the Work Unit Record. |
When a Work Unit is created, the template file is processed as follows:
- Within a <file_info> element, <number>x</number> identifies the order of the file. It is replaced with elements giving the filename, download URL, MD5 checksum, and size.
- Within a <file_ref> element, <file_number>x</file_number> is replaced with an element giving the filename.
[edit] Result Template File
A Result Template File has the form:
<file_info>
<name><OUTFILE_0/></name>
<generated_locally/>
<upload_when_present/>
<max_nbytes>32768</max_nbytes>
<url><UPLOAD_URL/></url>
</file_info>
<result>
<file_ref>
<file_name><OUTFILE_0/></file_name>
<open_name>result.sah</open_name>
</file_ref>
</result>
The result file template is macro-substituted as follows:
- <OUTFILE_n> is replaced with a string of the form 'wuname_resultnum_n' where wuname is the workunit name and resultnum is the ordinal number of the result (0, 1, ...).
- <UPLOAD_URL/> is replaced with the upload URL.
[edit] Moving Input Files to the Download Directory
If you're a flat download directory, just put input files in that directory. If you're using Hierarchical Upload/Download Directories, you must put each input file in the appropriate directory; the directory is determined by the file's name. To find this directory, call the C++ function
dir_hier_path(
const char* filename,
const char* root, // root of download directory
int fanout, // from config.xml
bool new_hash, // use true here
char* result // path of file in hierarchy
);
If you're using scripts, you can invoke the program
dir_hier_path filename
It prints the full pathname. Run this in the project's root directory. For example:
cp test_workunits/12ja04aa `bin/dir_hier_path 12ja04aa`
copies an input file from the test_workunits directory to the Download Directory Hierarchy.
[edit] Creating Work Unit Records
Workunits can be created using either a script (using the create_work program) or a program (using the create_work() function). The input files must already be in the download directory.
The utility program is:
create_work
-appname name // Application Name
-wu_name name // Work Unit's Name
-wu_template filename // WU template filename
// relative to project root
-result_template filename // result template filename
// relative to project root
[ -batch n ]
[ -priority n ]
// The following are normally supplied in the WU template:
[ -rsc_fpops_est x ]
[ -rsc_fpops_bound x ]
[ -rsc_memory_bound x ]
[ -rsc_disk_bound x ]
[ -delay_bound x ]
[ -min_quorum x ]
[ -target_nresults x ]
[ -max_error_results x ]
[ -max_total_results x ]
[ -max_success_results x ]
infile_1 ... infile_m // input files
The Work Unit Record (Parameters) are used as inputs to this function. The program must be run in the project root directory.
The C++ library (crypt.C, backend_lib.C,h) provides the functions:
int read_key_file(char* path, R_RSA_PRIVATE_KEY& key);
int create_work(
DB_WORKUNIT&,
const char* wu_template, // contents, not path
const char* result_template_filename, // relative to project root
const char* result_template_filepath, // absolute,
// or relative to current dir
const char* infile_dir, // where input files are
const char** infiles, // array of input file names
int ninfiles
R_RSA_PRIVATE_KEY& key, // upload authentication key
SCHED_CONFIG&
);
read_key_file() reads a private key from a file. Use this to read the file upload authentication key.
create_work() creates a Work Unit and one or more Results. The arguments are similar to those of the utility program; some of the information is passed in the WORKUNIT structure, namely the following fields:
- name
- appid
- batch
- rsc_fpops
- rsc_iops
- rsc_memory
- rsc_disk
- delay_bound
All other fields should be zeroed.
[edit] UCB Source
[edit] Copyright ©
- 2005 University of California
- 2005 Paul D. Buck
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation.
