<!--#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 "priority." The minor type can be any recognizable abbreviation for the type of priority. We recommend, for example:</p> <ul> <li><b>basic</b>—A plugin that implements the API and provides basic FIFO job priority.</li> <li><b>multifactor</b>—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"-->