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.

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:

• basic — A plugin that implements the API and provides basic FIFO job priority.
• multifactor — The multi-factor job priority plugin.

const char plugin_name[]
Some descriptive name for the plugin. There is no requirement with respect to its format.

const uint32_t plugin_version
If specified, identifies the version of Slurm used to build this plugin and any attempt to load the plugin from a different version of Slurm will result in an error. If not specified, then the plugin may be loaded by Slurm commands and daemons from any version, however this may result in difficult to diagnose failures due to changes in the arguments to plugin functions or changes in other Slurm functions used by the plugin.

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_assoc_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.

int init (void)

Description:
Called when the plugin is loaded, before any other functions are called. Put global initialization here.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

void fini (void)

Description:
Called when the plugin is removed. Clear any allocated storage here.

Returns: None.

Note: These init and fini functions are not the same as those described in the dlopen (3) system library. The C run-time system co-opts those symbols for its own initialization. The system _init() is called before the Slurm init(), and the Slurm fini() is called before the system's _fini().

uint32_t priority_p_set(uint32_t last_prio, job_record_t *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(bool assoc_clear)

Description: Refresh the plugin's configuration. Called whenever slurmctld is reconfigured.

Arguments: assoc_clear (input) true if association and QOS used_cpu_run_secs field has been reset. This should be set to true when Slurm is reconfigured, but false if an RPC is used to change only the debug level of debug flags.

Returns: void

void priority_p_set_assoc_usage(acct_assoc_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

void priority_p_job_end(job_record_t *job_ptr)

Description: Handle ending of job with decayable limits.

Arguments: job_ptr (input) pointer to the job record.

Returns: void

Last modified 23 October 2019