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 100 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 informatin.</li>
<li><b>tree</b>&#151;Optimize placement based upon a hiearachy 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 preformed by these plugins vary widely.
In the case of <b>3d_torus</b>, 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 <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>

<h2>Versioning</h2>
<p> This document describes version 100 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 24 March 2009</p>

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