doc/html/priority_plugins.shtml

<!--#include virtual="header.txt"-->

<h1><a name="top">SLURM Priority Plugin API</a></h1>

<h2> Overview</h2>
<p> This document describes SLURM priority plugins and the API that defines
them. It is intended as a resource to programmers wishing to write their own
SLURM priority plugins. This is version 100 of the API.</p>

<p>SLURM priority plugins are SLURM plugins that implement the SLURM priority
API described herein. They must conform to the SLURM Plugin API with the
following specifications:</p>

<p><span class="commandline">const char
plugin_type[]="<i>major/minor</i>"</span><br>
The major type must be &quot;priority.&quot; The minor type can be any
recognizable abbreviation for the type of priority.
We recommend, for example:</p>

<ul>
<li><b>basic</b>&#151;A plugin that implements the API and provides basic FIFO
job priority.</li>
<li><b>multifactor</b>&#151;The multi-factor job priority plugin.</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 job priority support.
Note carefully, however, the versioning discussion below.</p>

<p>The programmer is urged to study
<span class="commandline">src/plugins/priority/basic/priority_basic.c</span> 
for an example implementation of a SLURM priority plugin.</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 <b>errno</b> to allow SLURM to discover as practically as possible
the reason for any failed API call.  Plugin-specific enumerated integer values
may be used when appropriate.</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. 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="commandline"> job_record</p>
<p style="margin-left:.2in"><b>Description</b>: A slurmctld structure that
contains details about a job.</p>

<p class="commandline"> acct_association_rec_t</p>
<p style="margin-left:.2in"><b>Description</b>: A slurm_accounting_storage
structure that contains details about an association.</p>

<p class="commandline"> priority_factors_object_t</p>
<p style="margin-left:.2in"><b>Description</b>: A structure that contains a
job's priority factors.</p>

<p class="commandline"> priority_factors_request_msg_t</p>
<p style="margin-left:.2in"><b>Description</b>: Used to request job priority
factors.  Contains a list of specific job and user ids of the jobs the user
wants to see.</p>

<p class="commandline"> priority_factors_response_msg_t</p>
<p style="margin-left:.2in"><b>Description</b>: Used to return the list of
priority_factors_object_t's containing the job priority factors the user has
asked to see.</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">uint32_t priority_p_set(uint32_t last_prio, struct job_record *job_ptr)</p>
<p style="margin-left:.2in"><b>Description</b>: Sets the priority of the job.</p>
<p style="margin-left:.2in"><b>Arguments</b>:<br>
<span class="commandline">last_prio</span> (input) the priority assigned to the
last job<br>
<span class="commandline">job_ptr</span> (input) pointer to the job record.</p>
<p style="margin-left:.2in"><b>Returns</b>: the priority assigned to the job</p>

<p class="commandline">void priority_p_reconfig(void)</p>
<p style="margin-left:.2in"><b>Description</b>: Refresh the plugin's
configuration. Called whenever slurmctld is reconfigured.</p>
<p style="margin-left:.2in"><b>Arguments</b>:
<span class="commandline">none</span></p>
<p style="margin-left:.2in"><b>Returns</b>: void</p>

<p class="commandline">int priority_p_set_max_cluster_usage(uint32_t procs, uint32_t half_life)</p>
<p style="margin-left:.2in"><b>Description</b>: Conveys the maximum
raw usage to the priority plugin.  This establishes the reference by
which each job's usage can be normalized.</p>
<p style="margin-left:.2in"><b>Arguments</b>:<br>
<span class="commandline">procs</span> (input) the machine's processor count<br>
<span class="commandline">half_life</span> (input) the configured half-life</p>
<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful,
otherwise SLURM_ERROR</p>

<p class="commandline">void priority_p_set_assoc_usage(acct_association_rec_t *assoc)</p>
<p style="margin-left:.2in"><b>Description</b>: Set the normalized and
effective usage for an association.</p>
<p style="margin-left:.2in"><b>Arguments</b>:
<span class="commandline">assoc</span> (input/output) pointer to the association.</p>
<p style="margin-left:.2in"><b>Returns</b>: void</p>

<p class="commandline">List priority_p_get_priority_factors_list(priority_factors_request_msg_t *req_msg)</p>
<p style="margin-left:.2in"><b>Description</b>: Retrieves the priority factors
for all or specified jobs.</p>
<p style="margin-left:.2in"><b>Arguments</b>:
<span class="commandline">req_msg</span> (input) pointer to the message request
that contains the specific jobs or users of interest (of any).</p>
<p style="margin-left:.2in"><b>Returns</b>: a list of priority_factors_object_t's
containing the requested job priority factors</p>

<h2>Versioning</h2>
<p> This document describes version 100 of the SLURM Priority API. Future
releases of SLURM may revise this API. A priority plugin conveys its ability
to implement a particular API version using the mechanism outlined for SLURM
plugins.</p>

<p class="footer"><a href="#top">top</a></p>

<p style="text-align:center;">Last modified 20 February 2009</p>

<!--#include virtual="footer.txt"-->