Changes between Version 36 and Version 37 of RemoteJobs

Timestamp:

Oct 7, 2013, 10:43:56 PM (11 years ago)

Author:

davea

Comment:

--

RemoteJobs

@@ -2 +2 @@
 = 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.
+This document describes APIs for remotely submitting,
+monitoring, and controlling jobs on a BOINC server.
+The APIs supports the submission of '''batches''' of jobs,
+which may contain a single job or many thousands of jobs.
 Currently, the API has two restrictions:
 
@@ -10 +11 @@
  * 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 ==
+At the bottom level, the interface uses XML over HTTP.
+At a higher level,
+BOINC provides client-side bindings in PHP and C++;
+these are somewhat different.
+
+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 [RemoteOutputFiles here].
+
+== PHP interface ==
+
+The following functions are provided in the PHP file
+[/trac/browser/trunk/boinc/html/inc/submit.inc submit.inc],
+which is independent of other BOINC PHP 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''': "local", "semilocal", "local_staged", or "inline" (see below).
+   * '''source''': meaning depends on mode:
+    * local: path on the BOINC server
+    * semilocal: the file's URL
+    * local_staged: physical name
+    * inline: the file's contents
+
+Result: a 2-element array containing
+ * The batch ID
+ * An error message (null if success)
 
 Input files can be supplied in any of the following ways:
- * '''local''': the file is on the BOINC server and is not [JobStage staged].  It's specified by its full path.
+ * '''local''': the file is on the BOINC server and is not [JobStage staged].
+  It's specified by its full path.
  * '''local_staged''': the filed has been [JobStage staged] on the BOINC server.
   It's specified by its physical name.
@@ -34 +69 @@
  * '''sandbox''': the file is in the user's [RemoteInputFiles#Per-userfilesandbox 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 [RemoteOutputFiles here].
-
-== PHP interface ==
-
-The following functions are provided in the PHP file
-[/trac/browser/trunk/boinc/html/inc/submit.inc 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''': "local", "semilocal", "local_staged", or "inline".
-   * '''source''': meaning depends on mode:
-    * local: path on the BOINC server
-    * semilocal: the file's URL
-    * local_staged: physical name
-    * inline: the file's contents
-
-Result: a 2-element array containing
- * The batch ID
- * An error message (null if success)
 
 The following example submits a 10-job batch:
@@ -188 +189 @@
 == C++ interface ==
 
-A C++ interface to the following functions is available in lib/remote_submit.cpp:
-{{{
-create_batch()
-submit_jobs()
-query_batch()
-abort_jobs()
-}}}
+A C++ interface to the following functions is available in lib/remote_submit.cpp.
+Include lib/remote_submit.h.
+
+All functions return zero on success,
+else an error code as defined in lib/error_numbers.h
+
+=== create_batch() ===
+
+Create a batch - a set of jobs, initially empty.
+{{{
+int create_batch(
+    const char* project_url,
+    const char* authenticator,
+    const char* batch_name,
+    const char* app_name,
+    double expire_time,
+    int &batch_id,
+    string& error_msg
+);
+}}}
+
+ project_url:: the project URL
+ authenticator:: the authenticator of the submitting user
+ batch_name:: a name for the batch.  Must be unique over all batches.
+ app_name:: the name of an application on the BOINC server
+ expire_time:: if nonzero, the Unix time when the batch should
+   be aborted and removed from the server, whether or not it's completed.
+ batch_id:: (out) the batch's database ID
+ error_msg:: (out) an error message if the operation failed
+
+=== submit_jobs() ===
+
+Submit a set of jobs; place them in an existing batch, and make them runnable.
+{{{
+int submit_jobs(
+    const char* project_url,
+    const char* authenticator,
+    char app_name[256],
+    int batch_id,
+    vector<JOB> jobs,
+    string& error_msg
+);
+
+struct JOB {
+    char job_name[256];
+    string cmdline_args;
+    vector<INFILE> infiles;
+};
+
+struct INFILE {
+    char physical_name[256]; 
+};
+}}}
+ batch_id:: ID of a previously created batch
+
+For each job:
+ job_name:: must be unique over all jobs
+ cmdline_args:: command-line arguments
+ infiles:: list of input files
+
+For each input file:
+ physical_name:: BOINC's physical name for the file.  The file must already be staged.
+
+
+=== query_batches() ===
+
+Query the status of a set of batches.
+{{{
+extern int query_batches(
+    const char* project_url,
+    const char* authenticator,
+    vector<string> &batch_names,
+    QUERY_BATCH_REPLY& reply,
+    string& error_msg
+);
+
+struct QUERY_BATCH_JOB {
+    string job_name;
+    string status;              // DONE, ERROR, or IN_PROGRESS
+    QUERY_BATCH_JOB(){}
+};
+
+struct QUERY_BATCH_REPLY {
+    vector<int> batch_sizes;    // how many jobs in each of the queried batches
+    vector<QUERY_BATCH_JOB> jobs;   // the jobs, sequentially
+};
+
+}}}
+
+=== abort_jobs() ===
+
+Abort a set of jobs.
+{{{
+extern int abort_jobs(
+    const char* project_url,
+    const char* authenticator,
+    vector<string> &job_names,
+    string& error_msg
+);
+
+}}}
+
+=== query_completed_job() ===
+{{{
+extern int query_completed_job(
+    const char* project_url,
+    const char* authenticator,
+    const char* job_name,
+    COMPLETED_JOB_DESC&,
+    string& error_msg
+);
+
+struct COMPLETED_JOB_DESC {
+    int canonical_resultid;
+    int error_mask;
+    int error_resultid;
+    int exit_status;
+    double elapsed_time;
+    double cpu_time;
+    string stderr_out;
+};
+}}}
+
+=== retire_batch() ===
+
+{{{
+extern int retire_batch(
+    const char* project_url,
+    const char* authenticator,
+    const char* batch_name,
+    string& error_msg
+);
+}}}
+
+=== set_expire_time() ===
+{{{
+extern int set_expire_time(
+    const char* project_url,
+    const char* authenticator,
+    const char* batch_name,
+    double expire_time,
+    string& error_msg
+);
+}}}
+
+=== ping_server() ===
+
+Ping the project's server; return zero if the server is up.
+{{{
+extern int ping_server(
+    const char* project_url,
+    string& error_msg
+);
+}}}
+
 
 == HTTP/XML interface ==
@@ -202 +351 @@
 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.
+can be inferred from inc/submit.inc and user/submit_rpc_handler.php.
 
 == Example web interface ==