Add task plugin API doc, still under development.

doc/html/Makefile.am

@@ -34,6 +34,7 @@ generated_html = \
 	selectplugins.html \
 	slurm.html \
 	switchplugins.html \
+	taskplugins.html \
 	team.html \
 	testimonials.html \
 	troubleshoot.html

doc/html/Makefile.in

@@ -295,6 +295,7 @@ generated_html = \
 	selectplugins.html \
 	slurm.html \
 	switchplugins.html \
+	taskplugins.html \
 	team.html \
 	testimonials.html \
 	troubleshoot.html

doc/html/taskplugins.shtml

+<!--#include virtual="header.txt"-->
+
+<h1><a name="top">SLURM Task Plugin API</a></h1>
+
+<h2> Overview</h2>
+<p> This document describes SLURM task management plugins and the API 
+that defines them. It is intended as a resource to programmers wishing 
+to write their own SLURM scheduler plugins. This is version 1 of the API.</p>
+
+<p>SLURM task management plugins are SLURM plugins that implement the 
+SLURM task management API described herein. They would typically be 
+used to control task affinity (i.e. binding tasks to processors). 
+They must conform to the SLURM Plugin API with the following 
+specifications:</p>
+<p><span class="commandline">const char plugin_type[]</span><br>
+The major type must be &quot;task.&quot; The minor type can be any recognizable 
+abbreviation for the type of task management. We recommend, for example:</p>
+<ul>
+<li><b>affinity</b>&#151;A plugin that implements task binding to processors.
+The actual mechanism used to task binding is dependent upon the available
+infrastruture as determined by the "configure" program when SLURM is built
+and the value of the <b>TaskPluginParam</b> as defined in the <b>slurm.conf</b>
+(SLURM configuration file).</li>
+<li><b>none</b>&#151;A plugin that implements the API without providing any
+services. This is the default behavior and provides no task binding.</li>
+</ul>
+
+<p>The <span class="commandline">plugin_name</span> and 
+<span class="commandline">plugin_version</span> 
+symbols required by the SLURM Plugin API require no specialization 
+for task support. 
+Note carefully, however, the versioning discussion below.</p>
+
+<p class="footer"><a href="#top">top</a></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>
+<p class="footer"><a href="#top">top</a></p>
+
+<h2>API Functions</h2>
+<p>The following functions must appear. Functions which are not implemented should 
+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>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>
+<span class="commandline">node_id</span>&nbsp;&nbsp;&nbsp;(input)
+ID of the</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 
+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>
+<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>
+<span class="commandline">node_id</span>&nbsp;&nbsp;&nbsp;(input)
+ID of the</p>
+<p style="margin-left:.2in"><b>Arguments</b>: None</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
+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>Arguments</b>: 
+<span class="commandline">job_id</span>&nbsp;&nbsp;&nbsp;(input)
+ID of the</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
+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>
+<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>
+<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. 
+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>
+<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>
+<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.
+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>
+<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>
+<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>
+
+<h2>Versioning</h2>
+<p> This document describes version 1 of the SLURM Task Plugin API.
+Future releases of SLURM may revise this API.</p>
+<p class="footer"><a href="#top">top</a></p>
+
+<p style="text-align:center;">Last modified 27 March 2007</p>
+
+<!--#include virtual="footer.txt"-->