Complete task plugin programmer guide.

doc/html/documentation.shtml

@@ -43,9 +43,10 @@ Jobs throuh LSF</a></li>
 <li><a href="selectplugins.shtml">Node Selection Plugin Programmer Guide</a></li>
 <li><a href="schedplugins.shtml">Scheduler Plugin Programmer Guide</a></li>
 <li><a href="switchplugins.shtml">Switch (Interconnect) Plugin Programmer Guide</a></li>
+<li><a href="taskplugins.shtml">Task Plugin Programmer Guide</a></li>
 <li><a href="mpiplugins.shtml">MPI Plugin Programmer Guide</a></li>
 </ul>
 
-<p style="text-align:center;">Last modified 31 January 2007</p>
+<p style="text-align:center;">Last modified 27 March 2007</p>
 
 <!--#include virtual="footer.txt"-->

doc/html/taskplugins.shtml

 <!--#include virtual="header.txt"-->
 
-<h1><a name="top">SLURM Task Plugin API</a></h1>
+<h1><a name="top">SLURM Task Plugin Programmer Guide</a></h1>
 
 <h2> Overview</h2>
 <p> This document describes SLURM task management plugins and the API 
@@ -36,25 +36,10 @@ Note carefully, however, the versioning discussion below.</p>
 <h2>Data Objects</h2>
 <p>The implementation must maintain (though not necessarily directly export) an
 enumerated <span class="commandline">errno</span>  to allow SLURM to discover
-as practically as possible the reason for any failed API call. Plugin-specific enumerated
-integer values should be used when appropriate. It is desirable that these values 
-be mapped into the range ESLURM_SCHED_MIN and ESLURM_SCHED_MAX
-as defined in <span class="commandline">slurm/slurm_errno.h</span>.
-The error number should be returned by the function
-<a href="#get_errno"><span class="commandline">slurm_sched_get_errno()</span></a>
-and  string describing the error's meaning should be returned by the function
-<a href="#strerror"><span class="commandline">slurm_sched_strerror()</span></a> 
-described below.</p>
-
-<p>These values must not be used as return values in integer-valued functions
-in the API. The proper error return value from integer-valued functions is SLURM_ERROR.
-The implementation should endeavor to provide useful and pertinent information by 
-whatever means is practical. In some cases this means an errno for each credential,
-since plugins must be re-entrant. If a plugin maintains a global errno in place of or in
-addition to a per-credential errno, it is not required to enforce mutual exclusion on it.
-Successful API calls are not required to reset any errno to a known value. However,
-the initial value of any errno, prior to any error condition arising, should be
-SLURM_SUCCESS. </p>
+as practically as possible the reason for any failed API call.
+These values must not be used as return values in integer-valued functions
+in the API. The proper error return value from integer-valued functions is 
+SLURM_ERROR.</p>
 <p class="footer"><a href="#top">top</a></p>
 
 <h2>API Functions</h2>
@@ -63,73 +48,91 @@ be stubbed.</p>
 
 <p class="commandline">int task_slurmd_launch_request (uint32_t job_id, 
 launch_tasks_request_msg_t *req, uint32_t node_id);</p>
-<p style="margin-left:.2in"><b>Description</b>: TBD.</p>
+<p style="margin-left:.2in"><b>Description</b>: Prepare to launch a job.
+Establish node, socket, and core resource availability for it.
+Executed by the <b>slurmd</b> daemon as user root.</p>
 <p style="margin-left:.2in"><b>Arguments</b>:<br>
 <span class="commandline">job_id</span>&nbsp;&nbsp;&nbsp;(input) 
-ID of the<br>
-<span class="commandline">req</span>&nbsp;&nbsp;&nbsp;(input)
-ID of the<br>
+ID of the job to be started.<br>
+<span class="commandline">req</span>&nbsp;&nbsp;&nbsp;(input/output)
+Task launch request specification including node, socket, and
+core specifications.
+See <b>src/common/slurm_protocol_defs.h</b> for the
+data structure definition.<br>
 <span class="commandline">node_id</span>&nbsp;&nbsp;&nbsp;(input)
-ID of the</p>
+ID of the node on which resources are being acquired (zero origin).</p>
 <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. 
-On fail ure, the plugin should return SLURM_ERROR and set the errno to an 
+On failure, the plugin should return SLURM_ERROR and set the errno to an 
 appropriate value to indicate the reason for failure.</p>
 
 <p class="commandline">int task_slurmd_reserve_resources (uint32_t job_id,
-aunch_tasks_request_msg_t *req, uint32_t node_id);</p>
-<p style="margin-left:.2in"><b>Description</b>: TBD.</p>
+launch_tasks_request_msg_t *req, uint32_t node_id);</p>
+<p style="margin-left:.2in"><b>Description</b>: Reserve resources for 
+the initiation of a job. Executed by the <b>slurmd</b> daemon as user root.</p>
 <p style="margin-left:.2in"><b>Arguments</b>:<br>
 <span class="commandline">job_id</span>&nbsp;&nbsp;&nbsp;(input)
-ID of the<br>
+ID of the job being started.<br>
 <span class="commandline">req</span>&nbsp;&nbsp;&nbsp;(input)
-ID of the<br>
+Task launch request specification including node, socket, and 
+core specifications.
+See <b>src/common/slurm_protocol_defs.h</b> for the
+data structure definition.<br>
 <span class="commandline">node_id</span>&nbsp;&nbsp;&nbsp;(input)
-ID of the</p>
-<p style="margin-left:.2in"><b>Arguments</b>: None</p>
+ID of the node on which the resources are being acquired 
+(zero origin).</p>
 <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful.
-On fail ure, the plugin should return SLURM_ERROR and set the errno to an
+On failure, the plugin should return SLURM_ERROR and set the errno to an
 appropriate value to indicate the reason for failure.</p>
 
 <p class="commandline">int task_slurmd_release_resources (uint32_t job_id);</p>
-<p style="margin-left:.2in"><b>Description</b>: Establish the initial priority of a new job.</p>
+<p style="margin-left:.2in"><b>Description</b>: Release resources previously 
+reserved for a job. Executed by the <b>slurmd</b> daemon as user root.</p>
 <p style="margin-left:.2in"><b>Arguments</b>: 
 <span class="commandline">job_id</span>&nbsp;&nbsp;&nbsp;(input)
-ID of the</p>
+ID of the job which has completed.</p>
 <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful.
-On fail ure, the plugin should return SLURM_ERROR and set the errno to an
+On failure, the plugin should return SLURM_ERROR and set the errno to an
 appropriate value to indicate the reason for failure.</p>
 
 <p class="commandline">int task_pre_setuid (slurmd_job_t *job);</p>
 <p style="margin-left:.2in"><b>Description</b>: task_pre_setuid() is called 
 before setting the UID for the user to launch his jobs. 
-Use this to perform any needed work as user root.</p>
+Executed by the <b>slurmstepd</b> program as user root.</p>
 <p style="margin-left:.2in"><b>Arguments</b>: 
 <span class="commandline">job</span>&nbsp;&nbsp;&nbsp;(input)
-pointer to the job to be initiated.</p>
+pointer to the job to be initiated.
+See <b>src/slurmd/slurmstepd/slurmstepd_job.h</b> for the
+data structure definition.</p>
 <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful.
 On failure, the plugin should return SLURM_ERROR and set the errno to an
 appropriate value to indicate the reason for failure.</p>
 
 <p class="commandline">int task_pre_launch (slurmd_job_t *job);</p>
 <p style="margin-left:.2in"><b>Description</b>: task_pre_launch() is called 
-prior to exec of application task. 
+prior to exec of application task.
+Executed by the <b>slurmstepd</b> program as the job's owner.
 It is followed by <b>TaskProlog</b> program (as configured in <b>slurm.conf</b>) 
-and <b>--task-prolog</b> (from srun command line).</p>
+and <b>--task-prolog</b> (from <b>srun</b> command line).</p>
 <p style="margin-left:.2in"><b>Arguments</b>:
 <span class="commandline">job</span>&nbsp;&nbsp;&nbsp;(input)
-pointer to the job to be initiated.</p>
+pointer to the job to be initiated.
+See <b>src/slurmd/slurmstepd/slurmstepd_job.h</b> for the
+data structure definition.</p>
 <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful.
 On failure, the plugin should return SLURM_ERROR and set the errno to an
 appropriate value to indicate the reason for failure.</p>
 
 <a name="get_errno"><p class="commandline">int task_post_term (slurmd_job_t *job);</p></a>
 <p style="margin-left:.2in"><b>Description</b>: task_term() is called 
-after termination of application task.
+after termination of job step.
+Executed by the <b>slurmstepd</b> program as the job's owner.
 It is preceeded by <b>--task-epilog</b> (from <b>srun</b> command line)
-followed by <b>TaskEpilog</b> program ((as configured in <b>slurm.conf</b>).</p>
+followed by <b>TaskEpilog</b> program (as configured in <b>slurm.conf</b>).</p>
 <p style="margin-left:.2in"><b>Arguments</b>:
 <span class="commandline">job</span>&nbsp;&nbsp;&nbsp;(input)
-pointer to the job to be initiated.</p>
+pointer to the job which has terminated.
+See <b>src/slurmd/slurmstepd/slurmstepd_job.h</b> for the 
+data structure definition.</p>
 <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful.
 On failure, the plugin should return SLURM_ERROR and set the errno to an
 appropriate value to indicate the reason for failure.</p>