# SLURM Topology Plugin Programmer Guide

## Overview

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

SLURM topology plugins are SLURM plugins that implement convey system topology information so that SLURM is able to optimize resource allocations and minimize communication overhead. The plugins must conform to the SLURM Plugin API with the following specifications:

const char plugin_type[]
The major type must be "topology." The minor type specifies the type of topology mechanism. We recommend, for example:

- 3d_torus—Optimize placement for a three dimensional torus.
- none—No topology informatin.
- tree—Optimize placement based upon a hiearachy of network switches.

The plugin_name and plugin_version symbols required by the SLURM Plugin API require no specialization for topology support. The actions preformed by these plugins vary widely. In the case of 3d_torus, the nodes in configuration file are re-ordeded so that nodes which are nearby in the one-dimensional table are also nearby in logical three-dimensional space. In the case of tree, a tabled is built to reflect network topology and that table is later used by the select plugin to optimize placement. Note carefully, however, the versioning discussion below.

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

int topo_build_config(void);

Description: Generate topology information.

Returns: SLURM_SUCCESS or SLURM_ERROR on failure.

## Versioning

This document describes version 100 of the SLURM topology API. Future releases of SLURM may revise this API.

Last modified 24 March 2009