Changes between Version 8 and Version 9 of RemoteJobs


Ignore:
Timestamp:
Jul 23, 2011, 1:26:18 PM (13 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • RemoteJobs

    v8 v9  
    11[[PageOutline]]
    2 = Web services for remote job submission =
     2= Remote job submission =
    33
    4 This document describes remote interfaces for remotely submitting jobs and batches of jobs
     4This document describes interfaces for remotely submitting batches of jobs
    55to a BOINC server.
     6
     7Users can submit jobs only if they have been given access
     8(via a web interface) by project administrators.
     9
     10In addition, project admins can restrict the apps for which
     11each user is allowed to submit jobs.
     12
     13== PHP interface ==
     14
     15=== boinc_estimate_batch() ===
     16
     17This function returns an estimate of the elapsed time
     18required to complete a given batch.
     19
     20Arguments: a "request object" whose fields include
     21 * '''project''': the project URL
     22 * '''authenticator''': the user's authenticator
     23 * '''app_name''': the name of the application for which jobs are being submitted
     24 * '''jobs''': an array of job descriptors (see example)
     25
     26Return value: a 2-element array containing
     27 * The estimate (in seconds)
     28 * An error message (null if success)
     29
     30Example:
     31{{{
     32$req->project = "http://foo.bar.edu/test/";
     33$req->authenticator = "xxx";
     34$req->app_name = "uppercase";
     35$req->jobs = array();
     36
     37$f->source = "http://foo.bar.edu/index.php";
     38$f->name = "in";
     39$job->input_files = array($f);
     40
     41for ($i=10; $i<20; $i++) {
     42        $job->rsc_fpops_est = $i*1e9;
     43        $job->command_line = "--t $i";
     44        $req->jobs[] = $job;
     45}
     46
     47list($e, $errmsg) = boinc_estimate_batch($req);
     48}}}
     49
     50=== boinc_submit_batch() ===
     51
     52Similar to '''boinc_estimate_batch()''', but submits the batch.
     53The return value is a 2-element array containing
     54 * The batch ID
     55 * An error message (null if success)
     56
     57=== boinc_query_batches() ===
     58=== boinc_query_batch() ===
     59=== boinc_abort_batch() ===
     60
     61== HTTPS/XML interface ==
     62
    663The APIs are accessed by sending a POST request,
    7 using HTTPS, to PROJECT_URL/job_control.php
     64using HTTPS, to PROJECT_URL/submit.php
    865
    9 The inputs and outputs of each API are XML documents.
     66The inputs and outputs of each function are XML documents.
    1067If an operation fails, the output is of the form
    1168{{{
    … …  
    1976This user must be marked as a "job submitter" in the BOINC database.
    2077
    21 == Describing a batch ==
     78=== Describing a batch ===
    2279
    2380A job is described by
    … …  
    3087}}}
    3188
    32 Each input file is specified by either a URL accessible to the server,
     89Each input file is specified either by a URL accessible to the server,
    3390or by a path on the server.
    3491
    … …  
    47104otherwise the defaults '''appname_in''' and '''appname_out''' are used.
    48105
    49 == Batch runtime estimation ==
     106=== Batch runtime estimation ===
    50107
    51 Estimates the completion time of a batch.
     108This function estimates the completion time of a batch.
    52109Input:
    53110{{{
    … …  
    68125}}}
    69126
    70 == Submitting a batch ==
     127=== Submitting a batch ===
    71128
    72129Input:
    … …  
    84141}}}
    85142
    86 == Querying jobs ==
    87 
    88 The jobs in a batch are numbered starting from 0.
    89 
    90 Input:
    91 {{{
    92 <query_job>
    93    <authenticator>X</authenticator>
    94    <batch_id>N</batch_id>
    95    <job_num>M</job_num>
    96 </query_job>
    97 }}}
    98 
    99 Output:
    100 {{{
    101 <job_status>
    102    <aborted/>
    103    or
    104    <instance>
    105       <unsent/>
    106       or
    107       <hostid>N</hostid>
    108       <userid>M</userid>
    109       <runtime>X</runtime>
    110       <fraction_done>X</fraction_done>
    111    </instance>
    112    ... other instances
    113 </job_status>
    114 }}}
    115 
    116 == Querying batches ==
     143=== Querying batches ===
     144=== Querying a batch ===
    117145
    118146Input:
    … …  
    133161}}}
    134162
    135 == Aborting jobs ==
    136 
    137 Input:
    138 {{{
    139 <abort_batch>
    140    <authenticator>X</authenticator>
    141    <batch_id>N</batch_id>
    142 </abort_batch>
    143 }}}
    144 
    145 Output:
    146 {{{
    147 <aborted/>
    148 }}}
    149 
    150 == Access control ==
    151 
    152 Users can submit jobs only if they have been
    153 given access (via a web interface) by project administrators.
    154 
    155 In addition, project admins can allow users to submit jobs for any app,
    156 or can designate which apps they can submit jobs to.
    157 
    158 == Example usage ==
    159 PHP:
    160 
    161 {{{
    162 $ch = curl_init("https://project.edu/job_control.php");
    163 curl_setopt($ch, CURLOPT_POST, 1);
    164 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    165 curl_setopt($ch, CURLOPT_POSTFIELDS, "request=
    166    <batch_estimate>
    167       <batch>
    168          <app>myappname</app>
    169          <job>
    170              <command_line>--t ALPHA</command_line>
    171          </job>
    172       </batch>
    173    </batch_estimate>
    174 ");
    175 $reply = curl_exec($ch);
    176 if (!$reply) die("HTTP op failed\n");
    177 $r = simplexml_load_string($reply);
    178 if (!$r) die("bad reply: $reply\n");
    179 $name = $r->getName();
    180 if ($name == 'estimate') {
    181     echo "estimate: ".(string)$r->seconds."\n";
    182 } else if ($name == 'error') {
    183     foreach ($r->message as $msg) {
    184         echo "$msg\n";
    185     }
    186 } else {
    187     die("bad reply\n");
    188 }
    189 }}}
     163=== Aborting a batch ===
    190164
    191165== Implementation notes ==