# Slurm Plugin API

## Overview

A Slurm plugin is a dynamically linked code object which is loaded explicitly at run time by the Slurm libraries. A plugin provides a customized implementation of a well-defined API connected to tasks such as authentication, interconnect fabric, and task scheduling.

## Identification

A Slurm plugin identifies itself by a short character string formatted similarly to a MIME type: <major>/<minor>. The major type identifies which API the plugin implements. The minor type uniquely distinguishes a plugin from other plugins that implement that same API, by such means as the intended platform or the internal algorithm. For example, a plugin to interface to the Maui scheduler would give its type as "sched/maui." It would implement the Slurm Scheduler API.

## Versioning

Slurm plugin version numbers comprise a major, minor and micro revision number. If the major and/or minor revision number changes, this indicates major changes to the Slurm functionality including changes to APIs, command options, and plugins. These plugin changes may include new functions and/or function arguments. If only the micro revision number changes, this is indicative of bug fixes and possibly minor enhancements which should not adversely impact users. In all cases, rebuilding and installing all Slurm plugins is recommended at upgrade time. Not all compute nodes in a cluster need be updated at the same time, but all Slurm APIs, commands, plugins, etc. on a compute node should represent the same version of Slurm.

## Data Objects

A plugin must define and export the following symbols:

- char plugin_type[]
  a unique, short, formatted string to identify the plugin's purpose as described above. A "null" plugin (i.e., one that implements the desired API as stubs) should have a minor type of "none."
- char plugin_name[]
  a free-form string that identifies the plugin in human-readable terms, such as "Kerberos authentication." Slurm will use this string to identify the plugin to end users.

A plugin may optionally define and export the following symbols:

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

## API Functions in All Plugins

int init (void);

Description: If present, this function is called just after the plugin is loaded. This allows the plugin to perform any global initialization prior to any actual API calls.

Arguments: None.

Returns: SLURM_SUCCESS if the plugin's initialization was successful. Any other return value indicates to Slurm that the plugin should be unloaded and not used.

void fini (void);

Description: If present, this function is called just before the plugin is unloaded. This allows the plugin to do any finalization after the last plugin-specific API call is made.

Arguments: None.

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

The functions need not appear. The plugin may provide either init() or fini() or both.

## Thread Safety

Slurm is a multithreaded application. The Slurm plugin library may exercise the plugin functions in a re-entrant fashion. It is the responsibility of the plugin author to provide the necessarily mutual exclusion and synchronization in order to avoid the pitfalls of re-entrant code.

## Run-time Support

The standard system libraries are available to the plugin. The Slurm libraries are also available and plugin authors are encouraged to make use of them rather than develop their own substitutes. Plugins should use the Slurm log to print error messages.

The plugin author is responsible for specifying any specific non-standard libraries needed for correct operation. Plugins will not load if their dependent libraries are not available, so it is the installer's job to make sure the specified libraries are available.

## Performance

All plugin functions are expected to execute very quickly. If any function entails delays (e.g. transactions with other systems), it should be written to utilize a thread for that functionality. This thread may be created by the init() function and deleted by the fini() functions. See plugins/sched/backfill for an example of how to do this.

Last modified 27 March 2015