diff --git a/doc/html/Makefile.am b/doc/html/Makefile.am index f1980b58d54ba0785301531f8da012973ab335f8..2e869398a26be3e02112b19938d0cbc3fcf2cb43 100644 --- a/doc/html/Makefile.am +++ b/doc/html/Makefile.am @@ -34,6 +34,7 @@ generated_html = \ selectplugins.html \ slurm.html \ switchplugins.html \ + taskplugins.html \ team.html \ testimonials.html \ troubleshoot.html diff --git a/doc/html/Makefile.in b/doc/html/Makefile.in index f9cef1993c5d06db31023b6d411df30600045256..77d3eca893adea43f741fd65f669a595f37d9c93 100644 --- a/doc/html/Makefile.in +++ b/doc/html/Makefile.in @@ -295,6 +295,7 @@ generated_html = \ selectplugins.html \ slurm.html \ switchplugins.html \ + taskplugins.html \ team.html \ testimonials.html \ troubleshoot.html diff --git a/doc/html/taskplugins.shtml b/doc/html/taskplugins.shtml new file mode 100644 index 0000000000000000000000000000000000000000..ae5bb85758e08141fd7f8c7ba0a0ef87c1ba4a8e --- /dev/null +++ b/doc/html/taskplugins.shtml @@ -0,0 +1,144 @@ +<!--#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 "task." The minor type can be any recognizable +abbreviation for the type of task management. We recommend, for example:</p> +<ul> +<li><b>affinity</b>—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>—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> (input) +ID of the<br> +<span class="commandline">req</span> (input) +ID of the<br> +<span class="commandline">node_id</span> (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> (input) +ID of the<br> +<span class="commandline">req</span> (input) +ID of the<br> +<span class="commandline">node_id</span> (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> (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> (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> (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> (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"-->