# 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:

- basic—A plugin that implements the API and provides basic FIFO job priority.
- multifactor—The 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

int priority_p_set_max_cluster_usage(uint32_t procs, uint32_t half_life)

Description: Conveys the maximum raw usage to the priority plugin. This establishes the reference by which each job's usage can be normalized.

Arguments:
procs (input) the machine's processor count
half_life (input) the configured half-life

Returns: SLURM_SUCCESS if successful, otherwise SLURM_ERROR

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