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

## 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_cpu_shares(uint32_t procs, uint32_t half_life)

Description: Conveys the machine's processor count and half-life configuration to the priority plugin. Which would be used to set the available shares for underlying layers in a hierarchical fairshare.

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

Returns: SLURM_SUCCESS if successful, otherwise SLURM_ERROR

## 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 12 February 2009