# 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 and minor revision number. As Slurm evolves, changes to the individual plugin APIs may be necessary to implement new features. The major number identifies the version of the applicable API that the plugin implements. Incrementing the major version number denotes that the API has changed significantly and possibly incompatibly over prior versions.

Because plugins are separate code objects and perhaps under the control of third parties, version skew may occur in a Slurm installation. Slurm may support multiple versions of each API in a backward-compatible fashion to provide time for plugin authors to update their plugins. Conversely, the plugin may support multiple versions of the API in order to be transparently portable across different Slurm installations. The version of the API spoken in an installation will be the highest-numbered version which is common to both Slurm and the plugin. Each Slurm release will document which API versions it supports. From time to time ancient API versions will be deprecated.

The minor version number is incremented at the discretion of the plugin author and denotes revisions or upgrades particular to that implementation. If two or more plugins of the same type are provided in an installation, the plugin with the highest minor revision will be selected.

## 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.
- const uint32_t plugin_version
  a 32-bit unsigned integer giving the version of the plugin as described above. The major revision number is multiplied by 1,000 and added to the minor revision number to produce the integer value. Thus, a plugin with a major revision number of 2 and a minor revision number of 35 will have a plugin_version value of 2035.

A plugin may optionally define and export the following symbols:

- const uint32_t min_plug_version
  a 32-bit unsigned integer formatted the same as plugin_version giving the lowest API version number with which this plugin is compatible. If this symbol is omitted, its value is assumed to be equivalent to the plugin_version rounded to the next lowest 1,000. Only the major version number of this symbol is significant.

## 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 9 October 2014