SLURM Priority Plugin API
Overview
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.
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:
const char
plugin_type[]="major/minor"
The major type must be "priority." The minor type can be any
recognizable abbreviation for the type of priority.
We recommend, for example:
- basicA plugin that implements the API and provides basic FIFO job priority.
- multifactorThe multi-factor job priority plugin.
The plugin_name and plugin_version symbols required by the SLURM Plugin API require no specialization for job priority support. Note carefully, however, the versioning discussion below.
The programmer is urged to study src/plugins/priority/basic/priority_basic.c for an example implementation of a SLURM priority plugin.
Data Objects
The implementation must maintain (though not necessarily directly export) an enumerated errno 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.
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.
job_record
Description: A slurmctld structure that contains details about a job.
acct_association_rec_t
Description: A slurm_accounting_storage structure that contains details about an association.
priority_factors_object_t
Description: A structure that contains a job's priority factors.
priority_factors_request_msg_t
Description: Used to request job priority factors. Contains a list of specific job and user ids of the jobs the user wants to see.
priority_factors_response_msg_t
Description: Used to return the list of priority_factors_object_t's containing the job priority factors the user has asked to see.
API Functions
The following functions must appear. Functions which are not implemented should be stubbed.
uint32_t priority_p_set(uint32_t last_prio, struct job_record *job_ptr)
Description: Sets the priority of the job.
Arguments:
last_prio (input) the priority assigned to the
last job
job_ptr (input) pointer to the job record.
Returns: the priority assigned to the job
void priority_p_reconfig(void)
Description: Refresh the plugin's configuration. Called whenever slurmctld is reconfigured.
Arguments: none
Returns: void
void priority_p_set_assoc_usage(acct_association_rec_t *assoc)
Description: Set the normalized and effective usage for an association.
Arguments: assoc (input/output) pointer to the association.
Returns: void
List priority_p_get_priority_factors_list(priority_factors_request_msg_t *req_msg)
Description: Retrieves the priority factors for all or specified jobs.
Arguments: req_msg (input) pointer to the message request that contains the specific jobs or users of interest (of any).
Returns: a list of priority_factors_object_t's containing the requested job priority factors
Versioning
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.
Last modified 20 February 2009