doc/html/topology_plugin.shtml

<!--#include virtual="header.txt"-->

<h1><a name="top">SLURM Topology Plugin Programmer Guide</a></h1>

<h2> Overview</h2>
<p> 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 101 of the API.</p>

<p>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:</p>

<p><span class="commandline">const char plugin_type[]</span><br>
The major type must be &quot;topology.&quot;
The minor type specifies the type of topology mechanism.
We recommend, for example:</p>
<ul>
<li><b>3d_torus</b>&#151;Optimize placement for a three dimensional torus.</li>
<li><b>none</b>&#151;No topology information.</li>
<li><b>tree</b>&#151;Optimize placement based upon a hierarchy of network
switches.</li>
</ul></p>

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

<h2>Data Objects</h2>
<p>The implementation must maintain (though not necessarily directly export) an
enumerated <span class="commandline">errno</span> 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.

<p>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. </p>
<p class="footer"><a href="#top">top</a></p>

<h2>API Functions</h2>
<p>The following functions must appear.
Functions which are not implemented should be stubbed.</p>

<p class="commandline">int topo_build_config(void);</p>
<p style="margin-left:.2in"><b>Description</b>: Generate topology information.</p>
<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS or
SLURM_ERROR on failure.</p>

<p class="commandline">bool topo_generate_node_ranking(void)</p>
<p style="margin-left:.2in"><b>Description</b>: Determine if this plugin will
reorder the node records based upon each job's node rank field.</p>
<p style="margin-left:.2in"><b>Returns</b>: true if node reording is supported,
false otherwise.</p>

<p class="commandline">int topo_get_node_addr(char* node_name, char** paddr, char** ppatt);</p>
<p style="margin-left:.2in"><b>Description</b>: Get Topology address of a given node.</p>
<p style="margin-left:.2in"><b>Arguments</b>:<br>
<b>node_name</b> (input) name of the targeted node<br>
<b>paddr</b> (output) returns the topology address of the node and connected
switches. If there are multiple switches at some level in the hierarchy, they
will be represented using SLURM's hostlist expression (e.g. "s0" and "s1" are
reported as "s[0-1]").  Each level in the hierarchy is separated by a period.
The last element will always be the node's name (i.e. "s0.s10.nodename")<br>
<b>ppatt</b> (output) returns the pattern of the topology address. Each level
in the hierarchy is separated by a period. The final element will always be
"node" (i.e. "switch.switch.node")<br>
<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS or
SLURM_ERROR on failure.</p>

<h2>Versioning</h2>
<p> This document describes version 101 of the SLURM topology API.
Future releases of SLURM may revise this API.</p>
<p class="footer"><a href="#top">top</a></p>

<p style="text-align:center;">Last modified 13 January 2011</p>

<!--#include virtual="footer.txt"-->