Add descriptions of new functions required for Federation switch.

doc/html/switchplugins.html

@@ -9,7 +9,7 @@
 <meta http-equiv="keywords" content="Simple Linux Utility for Resource Management, SLURM, resource management, 
 Linux clusters, high-performance computing, Livermore Computing">
 <meta name="LLNLRandR" content="UCRL-WEB-204324"
-<meta name="LLNLRandRdate" content="18 February 2004">
+<meta name="LLNLRandRdate" content="17 July 2004">
 <meta name="distribution" content="global">
 <meta name="description" content="Simple Linux Utility for Resource Management">
 <meta name="copyright"
@@ -81,10 +81,13 @@ for sample implementations of a SLURM switch plugin.</p>
 <p class="footer"><a href="#top">top</a></p>
 
 <h3>Data Objects</h3>
-<p> The implementation must support an opaque class, which it defines, to be used 
-as an job's switch &quot;credential.&quot; This class must encapsulate all job-specific 
-information necessary for the operation of the API specification below. The credential 
-is referred to in SLURM code by an anonymous pointer (void *).</p>
+<p> The implementation must support two opaque data classes.
+One is used as an job's switch &quot;credential.&quot; 
+This class must encapsulate all job-specific information necessary 
+for the operation of the API specification below. 
+The second is a node's switch state record.
+Both data classes are referred to in SLURM code using an anonymous 
+pointer (void *).</p>
 
 <p>The implementation must maintain (though not necessarily directly export) an 
 enumerated <span class="commandline">errno</span>  to allow SLURM to discover 
@@ -146,6 +149,80 @@ If so, delay scheduling a new job while another is in the process of terminating
 any other job is in the process of terminating.</p>
 <p class="footer"><a href="#top">top</a></p>
 
+<h4>Node's Switch State Monitoring Functions</h4>
+<p><b>NOTE: Functions in this section will be defined and deployed in SLURM version 0.4
+and are included here for reference by developers.</b></p>
+
+<p>Nodes will register with current switch state information when the slurmd daemon 
+is initiated. The slurmctld daemon will also request that slurmd supply current 
+switch state information on a periodic basis.</p>
+
+<p class="commandline">int switch_alloc_node_info(switch_node_info_t *switch_node);</p>
+<p style="margin-left:.2in"><b>Description</b>: Allocate storage for a node's switch 
+state record. It is recommended that the record contain a magic number for validation 
+purposes.</p>
+<p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> switch_node</span>&nbsp;
+&nbsp;&nbsp;(output) location for writing location of node's switch state record.</p>
+<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure,
+the plugin should return SLURM_ERROR and set the errno to an appropriate value
+to indicate the reason for failure.</p>
+
+<p class="commandline">int switch_build_node_info(switch_node_info_t switch_node);</p>
+<p style="margin-left:.2in"><b>Description</b>: Build the current switch state 
+record for the node on which this function is executed. 
+It is recommended that the magic number be validated.
+<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure,
+the plugin should return SLURM_ERROR and set the errno to an appropriate value
+to indicate the reason for failure.</p>
+
+<p class="commandline">int switch_pack_node_info (switch_node_info_t switch_node, 
+Buf buffer);</p>
+<p style="margin-left:.2in"><b>Description</b>: Pack the data associated with a 
+node's switch state into a buffer for network transmission.</p>
+<p style="margin-left:.2in"><b>Arguments</b>:<br>
+<span class="commandline"> switch_node</span>&nbsp; &nbsp;&nbsp;(input) an existing 
+node's switch state record.<br>
+<span class="commandline"> buffer</span>&nbsp; &nbsp;&nbsp;(input/output) buffer onto
+which the switch state information is appended.</p>
+<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure,
+the plugin should return SLURM_ERROR and set the errno to an appropriate value
+to indicate the reason for failure.</p>
+
+<p class="commandline">int switch_unpack_node_info (switch_node_info_t switch_node, 
+Buf buffer);</p>
+<p style="margin-left:.2in"><b>Description</b>: Unpack the data associated with a 
+node's switch state record from a buffer.</p>
+<p style="margin-left:.2in"><b>Arguments</b>:<br>
+<span class="commandline"> switch_node</span>&nbsp; &nbsp;&nbsp;(input/output) a 
+previously allocated node switch state record to be filled in with data read from 
+the buffer.<br>
+<span class="commandline"> buffer</span>&nbsp; &nbsp;&nbsp;(input/output) buffer from
+which the record's contents are read.</p>
+<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure,
+the plugin should return SLURM_ERROR and set the errno to an appropriate value
+to indicate the reason for failure.</p>
+
+<p class="commandline">void switch_free_node_info (switch_node_info_t switch_node);</p>
+<p style="margin-left:.2in"><b>Description</b>: Release the storage associated with 
+a node's switch state record.</p>
+<p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> switch_node</span>&nbsp;
+&nbsp;&nbsp;(intput) an existing node switch state record.</p>
+<p style="margin-left:.2in"><b>Returns</b>: None</p>
+
+<p class="commandline">int switch_job_complete (switch_jobinfo_t switch_job, 
+char *nodelist);</p>
+<p style="margin-left:.2in"><b>Description</b>: Note that the job step associated 
+with the specified node has completed execution.</p>
+<p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> switch_job</span>
+&nbsp;
+&nbsp;&nbsp;(input) The completed job's switch credential.<br>
+<span class="commandline"> nodelist</span>&nbsp; &nbsp;&nbsp;(input) A list of nodes 
+on which the job has completed. This may contain expressions to specify node ranges.
+(e.g. "linux[1-20]" or "linux[2,4,6,8]").</p> 
+<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure,
+the plugin should return SLURM_ERROR and set the errno to an appropriate value
+to indicate the reason for failure.</p>
+
 <h4>Job's Switch Credential Management Functions</h4>
 <p class="commandline">int switch_p_alloc_jobinfo(switch_jobinfo_t *switch_job);</p>
 <p style="margin-left:.2in"><b>Description</b>: Allocate storage for a job's switch credential.
@@ -204,7 +281,7 @@ the plugin should return SLURM_ERROR and set the errno to an appropriate value
 to indicate the reason for failure.</p>
 
 <p class="commandline">int switch_p_unpack_jobinfo (switch_jobinfo_t switch_job, Buf buffer);</p>
-<p style="margin-left:.2in"><b>Description</b>: Unack the data associated with a job's 
+<p style="margin-left:.2in"><b>Description</b>: Unpack the data associated with a job's 
 switch credential from a buffer.</p>
 <p style="margin-left:.2in"><b>Arguments</b>:<br>
 <span class="commandline"> switch_job</span>&nbsp; &nbsp;&nbsp;(input/output) a previously
@@ -384,7 +461,7 @@ to maintain data format compatibility across different versions of the plugin.</
 <a href="mailto:slurm-dev@lists.llnl.gov">slurm-dev@lists.llnl.gov</a>.</p>
 <p><a href="http://www.llnl.gov/"><img align=middle src="lll.gif" width="32" height="32" border="0"></a></p>
 <p class="footer">UCRL-WEB-204324<br>
-Last modified February 18, 2004</p></td>
+Last modified July 17, 2004</p></td>
 </tr>
 </table>
 </td>