Web RPCs for remote job submission

This document describes an API for remotely submitting jobs to a BOINC server. The API supports the submission of batches of jobs. A batch could contain a single job, or many thousands of jobs. Currently, the API has two restrictions:

• All jobs in a batch must use the same application.
• There can be no dependencies between jobs.

The interface is implemented using XML over HTTP. BOINC provides a client-side PHP binding; it's possible to create bindings in other languages.

Input and output files

Input files can be supplied in any of the following ways:

• local: the file is on the BOINC server and is not staged. It's specified by its full path.
• local_staged: the filed has been staged on the BOINC server. It's specified by its physical name.
• semilocal: the file is on a data server that's accessible to the BOINC server but not necessarily to the outside world. The file is specified by its URL. It will be downloaded by the BOINC server during job submission, and served to clients from the BOINC server.

The following modes have been proposed but are not implemented yet:

• remote: the file is on a data server other than the BOINC server, and will be served to clients from that data server. It's specified by the URL, the file size, and the file MD5.

• inline: the file is included in the job submission request XML message.

It will be served to clients from BOINC server.

• sandbox: the file is in the user's sandbox, and is specified by its name in the sandbox.

As jobs are completed, their output files are available to the submitting user via HTTP. When a batch is complete, a zipped archive of all its output files is available via HTTP. Details are here.

PHP interface

The following functions are provided in the PHP file submit.inc, which is independent of other BOINC code and can be used in the Portal web code.

boinc_submit_batch()

Submits a batch.

Arguments: a "request object" whose fields include

• project: the project URL
• authenticator: the user's authenticator
• app_name: the name of the application for which jobs are being submitted
• batch_name: a symbolic name for the batch. Need not be unique.
• jobs: an array of job descriptors, each of which contains
  • rsc_fpops_est: an estimate of the FLOPs used by the job
  • command_line: command-line arguments to the application
  • input_files: an array of input file descriptors, each of which contains
    • mode: "inline", "sandbox", "local", "semilocal", or "remote".
    • source: the file's URL (semilocal and remote modes), path on this host (inline mode) or name on the BOINC server (local mode).
    • size: the file's size in bytes (remote mode)
    • md5: the file's MD5 (remote mode)

Result: a 2-element array containing

• The batch ID
• An error message (null if success)

The following example submits a 10-job batch:

$req->project = "http://foo.bar.edu/test/";
$req->authenticator = "xxx";
$req->app_name = "uppercase";
$req->jobs = array();

$f->mode = "local";
$f->source = "filename.dat";
$job->input_files = array($f);

for ($i=10; $i<20; $i++) {
    $job->rsc_fpops_est = $i*1e9;
    $job->command_line = "--t $i";
    $req->jobs[] = $job;
}

list($batch_id, $errmsg) = boinc_submit_batch($req);
if ($errmsg) {
    echo "Error: $errmsg\n";
} else {
    echo "Batch ID: $batch_id\n";
}

boinc_estimate_batch()

Returns an estimate of the elapsed time required to complete a batch.

Arguments: same as boinc_submit_batch() (only relevant fields need to be populated).

Return value: a 2-element array containing

• The elapsed time estimate, in seconds
• An error message (null if success)

boinc_query_batches()

Returns a list of this user's batches, both in progress and complete.

Argument: a request object with elements

• project and authenticator: as above.

Result: a 2-element array. The first element is an array of batch descriptor objects, each with the following fields:

• id: batch ID
• state: values are
  • 1: in progress
  • 2: completed (all jobs either succeeded or had fatal errors)
  • 3: aborted
  • 4: retired
• name: the batch name
• app_name: the application name
• create_time: when the batch was submitted
• est_completion_time: current estimate of completion time
• njobs: the number of jobs in the batch
• fraction_done: the fraction of the batch that has been completed (0..1)
• nerror_jobs: the number of jobs that had fatal errors
• completion_time: when the batch was completed
• credit_estimate: BOINC's initial estimate of the credit that would be granted to complete the batch, including replication
• credit_canonical: the actual credit granted to canonical instances
• credit_total: the actual credit granted to all instances

boinc_query_batch()

Gets batch details.

Argument: a request object with elements

• project and authenticator: as above
• batch_id: specifies a batch.

Result: a 2-element array. The first element is a batch descriptor object as described above, with one additional field:

• jobs: an array of job descriptor objects, each one containing
  • id: the database ID of the job's workunit record
  • canonical_instance_id: if the job has a canonical result, its database ID

boinc_query_job()

Gets job details.

Argument: a request object with elements:

• project and authenticator: as above
• job_id: specifies a job.

Result: a 2-element array. The first element is a job descriptor object with the following fields:

• instances: an array of job instance descriptors, each containing:
  • name: the instance's name
  • id: the ID of the corresponding result record
  • state: a string describing the instance's state (unsent, in progress, complete, etc.)
  • outfile: if the instance is over, a list of output file descriptors, each containing
    • size: file size in bytes

boinc_abort_batch()

Argument: a request object with elements

• project and authenticator: as above,
• batch_id: specifies a batch.

Result: an error message, null if successful

boinc_retire_batch()

Delete server storage (files, DB records) associated with a batch.

Argument: a request object with elements

• project and authenticator: as above,
• batch_id: specifies a batch.

Result: an error message, null if successful

C++ interface

A C++ interface to the following functions is available in lib/remote_submit.cpp:

create_batch()
submit_jobs()
query_batch()
abort_jobs()

HTTP/XML interface

At a lower level, the APIs are accessed by sending a POST request, using HTTP or HTTPS, to PROJECT_URL/submit_rpc_handler.php. The inputs and outputs of each function are XML documents. The format of the request and reply XML documents can be inferred from inc/submit.inc and user/submit.php.

Bindings of these RPCs can be implemented in languages other than PHP.

Example web interface

An example of a web interface for job submission and control, based on this API, can be found here: http://boinc.berkeley.edu/trac/browser/trunk/boinc/html/user/submit_example.php

This example is functional and it shows how to use the API. However, you will have to modify it heavily for your particular applications and web site.