Changes between Version 10 and Version 11 of RemoteJobs

Timestamp:

Jul 24, 2011, 9:51:19 AM (14 years ago)

Author:

davea

Comment:

--

RemoteJobs

@@ -4 +4 @@
 This document describes APIs for remotely submitting jobs
 to a BOINC server.
-These APIs can be used, for example, to create web interfaces for job submission,
+The APIs support the submission of large '''batches''' of jobs,
+such as parameter sweeps.
+The APIs can be used, for example, to create web interfaces for job submission,
 such as might be found in a science portal web site:
 
@@ -13 +15 @@
 and it is easy to create bindings in other languages.
 
-The APIs are designed for the submission of large '''batches''' of jobs,
-such as parameter sweeps.
-
-Users can submit jobs only if they have been given access
-(via a web interface) by project administrators.
-In addition, admins can restrict the apps for which
+This system is coupled with new
+[MultiUser multi-user project features].
+In particuler, users can submit jobs only if they have been given access
+(via a web interface) by project administrators,
+and admins can restrict the apps for which
 each user is allowed to submit jobs.
-The BOINC admin web pages provide an interface for this access control.
 
 == PHP interface ==
@@ -36 +36 @@
 
 Return value: a 2-element array containing
- * The estimate (in seconds)
+ * The estimate, in seconds
  * An error message (null if success)
 
-Example:
+Example usage:
 {{{
 $req->project = "http://foo.bar.edu/test/";
@@ -57 +57 @@
 
 list($e, $errmsg) = boinc_estimate_batch($req);
+if ($errmsg) {
+        echo "Error: $errmsg\n";
+} else {
+        echo "The batch will take about $e seconds to complete\n";
+}
 }}}
 
@@ -62 +67 @@
 
 Similar to '''boinc_estimate_batch()''', but submits the batch.
-The return value is a 2-element array containing
+
+Result: a 2-element array containing
  * The batch ID
  * An error message (null if success)
@@ -68 +74 @@
 === boinc_query_batches() ===
 
-Argument: a request objects with '''project''' and '''authenticator''' fields as above.
-
-Result: a 2-element array.  The first element is an array of objects describing 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 objects describing batches,
 with the following fields:
- * '''id''': batch ID
+ * '''batch_id''': batch ID
  * '''fraction_done''': a number 0..1 giving the fraction of the batch that has been completed
  * '''create_time''': when the batch was submitted
@@ -80 +90 @@
 === boinc_query_batch() ===
 
-Argument: a request objects with '''project''' and '''authenticator''' fields as above,
-and a '''batch_id''' element specifying a batch.
-
-Result: a 2-element array.  The first element is an array of objects describing jobs
+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 an array of objects describing jobs
 within the batch, with the following fields:
 
- * '''id''': the job ID
- * '''canonical_result_id''': if the job has been completed and validated, the ID of a valid instance
+ * '''job_id''': the job ID
+ * '''canonical_instance_id''':
+  if the job has been completed and validated, the ID of a valid instance
  * '''n_outfiles''': the number of output files
 
+=== 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 an object with the following fields:
+ * '''instances''': an array of job instance descriptors
+
+Each job instances descriptor is an object with the following fields:
+ * '''instance_name''': the instance's name
+ * '''instance_id''': the ID of the corresponding result record
+
 === boinc_abort_batch() ===
 
-Argument: a request objects with '''project''' and '''authenticator''' fields as above,
-and a '''batch_id''' element specifying 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
@@ -99 +131 @@
 === boinc_get_output_file() ===
 
-Argument: a request objects with '''project''' and '''authenticator''' fields as above,
-a '''job_id''' element specifying a job, and a '''file_num''' field giving the
-ordinal number of one of the output files.
-
-Result: A URL from which the output file can be downloaded.
+Get a URL for a particular output file.
+
+Argument: a request object with elements
+ * '''project''' and '''authenticator''': as above,
+ * '''instance_name''': specifies a job instance,
+ * '''file_num''': the ordinal number of one of the output files.
+
+Result: a 2-element array;
+the first element is a URL from which the output file can be downloaded.
 
 === boinc_get_output_files() ===
 
-Argument: a request objects with '''project''' and '''authenticator''' fields as above,
-and a '''batch_id''' element specifying a batch.
-
-Result: A URL from which a zipped archive of all output files from the batch can be downloaded.
+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 URL from which a zipped archive of all
+output files from the batch can be downloaded
+(only the outputs of "canonical" instances are included).
+
+=== boinc_cleanup_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
 
 == HTTPS/XML interface ==
@@ -239 +290 @@
   app_id
 }}}
+