| <!--#include virtual="header.txt"--> |
| |
| <h1><a name="top">SLURM Plugin API</a></h1> |
| <h2>Overview</h2> |
| <p>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.</p> |
| <h2>Identification</h2> |
| <p>A SLURM plugin identifies itself by a short character string formatted similarly |
| to a MIME type: <i><major>/<minor></i>. 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.</p> |
| <h2>Versioning</h2> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| <h2>Data Objects</h2> |
| <p>A plugin must define and export the following symbols:</p> |
| <ul> |
| <li><span class="commandline">char plugin_type[]<br> |
| </span> 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."</li> |
| <li><span class="commandline">char plugin_name[]<br> |
| </span> 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.</li> |
| <li><span class="commandline">const uint32_t plugin_version</span><br> |
| 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 <span class="commandline">plugin_version</span> |
| value of 2035.</li> |
| </ul> |
| <p>A plugin may optionally define and export the following symbols:</p> |
| <ul> |
| <li>const uint32_t plugin_legacy<br> |
| a 32-bit unsigned integer formatted the same as <span class="commandline">plugin_version</span> |
| 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 <span class="commandline">plugin_version</span> |
| rounded to the next lowest 1,000. Only the major version number of this symbol |
| is significant.</li> |
| </ul> |
| <p class="footer"><a href="#top">top</a></p> |
| <h2>API Functions</h2> |
| <p class="commandline">int init (void);</p> |
| <p style="margin-left:.2in"><b>Description</b>: 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.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>: None.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: 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.</p> |
| <p class="commandline">void fini (void);</p> |
| <p style="margin-left:.2in"><b>Description</b>: 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.</p> |
| <p style="margin-left:.2in"><b>Arguments</b>: None.</p> |
| <p style="margin-left:.2in"><b>Returns</b>: None.</p> |
| <p><b>Note</b>: These functions are not the same as those described in the <span class="commandline">dlopen |
| (3)</span> system library. The C run-time system co-opts those symbols for its |
| own initialization. The system <span class="commandline">init()</span> is called |
| before the SLURM <span class="commandline">plugininit()</span>, and the SLURM |
| <span class="commandline">fini()</span> is called before the system's <span class="commandline">fini()</span>.</p> |
| <p>The functions need not appear. The plugin may provide either <span class="commandline">init()</span> |
| or <span class="commandline">fini()</span> or both.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| <h2>Thread Safety</h2> |
| <p>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.</p> |
| <h2>Run-time Support</h2> |
| <p>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.</p> |
| <p>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.</p> |
| <h2>Performance</h2> |
| <p>All plugin functions are expected to execute very quickly. If any function |
| entails delays (e.g. transations with other systems), it should be written to |
| utilize a thread for that functionality. This thread may be created by the |
| <span class="commandline">init()</span> function and deleted by the |
| <span class="commandline">fini()</span> functions. See <b>plugins/sched/backfill</b> |
| for an example of how to do this.</p> |
| <p class="footer"><a href="#top">top</a></p> |
| |
| <p style="text-align:center;">Last modified 9 July 2004</p></td> |
| |
| <!--#include virtual="footer.txt"--> |
