# Slurm Preemption Plugin API

## Overview

This document describes Slurm preemption plugins and the API that defines them. It is intended as a resource to programmers wishing to write their own Slurm preemption plugins. This is version 100 of the API.

Slurm preemption plugins are Slurm plugins that identify which jobs can be preempted by a pending job. They must conform to the Slurm Plugin API with the following specifications:

const char plugin_type[]="major/minor"
The major type must be "preempt." The minor type can be any recognizable abbreviation for the type of preemption. We recommend, for example:

- none—This plugin prevents any job preemption.
- partition_prio—This plugin permit pending jobs from one partition to preempt jobs from a lower priority partition.
- qos—This plugin permits jobs to preempt others based upon their Quality Of Service values as defined in the Slurm database.

The plugin_name and plugin_version symbols required by the Slurm Plugin API require no specialization for job preemption support. Note carefully, however, the versioning discussion below.

The programmer is urged to study src/plugins/preempt/partition_prio/preempt_partition_prio.c for an example implementation of a Slurm preemption plugin.

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

List find_preemptable_jobs( struct job_record *job_ptr)

Description: Identifies the jobs which can be preempted by a specific pending job.

Arguments:
job_ptr (input) a pointer to the pending job which is attempting to be started

Returns: A list of pointers to jobs which may be preempted. The list should be be released using the list_destroy function when no longer required. This list should be sorted in order from most attractive to preempt to least attractive to preempt (e.g. lowest to highest priority). For example, even within a given partition or QOS one might want to smaller jobs first.

uint16_t job_preempt_mode( struct job_record *job_ptr)

Description: Identifies the mechanism used to preempt the specified job.

Arguments:
job_ptr (input) a pointer to the running job to be preempted

Returns: PREEMPT_MODE as defined in the slurm/slurm.h file

bool preemption_enabled(void)

Description: Report whether or not job preemption is enabled.

Returns: true if running jobs may be preempted, otherwise false

## Versioning

This document describes version 100 of the Slurm Preemption API. Future releases of Slurm may revise this API. A preemption plugin conveys its ability to implement a particular API version using the mechanism outlined for Slurm plugins.

Last modified 8 May 2014