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

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.

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/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(job_record_t *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 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(job_record_t *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

Last modified 23 October 2019