From ccb7042045bf6a38ff2ea8428aa14ba0902ca2cd Mon Sep 17 00:00:00 2001 From: Moe Jette <jette1@llnl.gov> Date: Tue, 24 Aug 2004 21:06:22 +0000 Subject: [PATCH] Added new document on node selection plugin. --- doc/Makefile.am | 1 + doc/html/documentation.html | 5 +- doc/html/selectplugins.html | 234 ++++++++++++++++++++++++++++++++++++ 3 files changed, 238 insertions(+), 2 deletions(-) create mode 100644 doc/html/selectplugins.html diff --git a/doc/Makefile.am b/doc/Makefile.am index f87223209b7..ae41fbbfd5c 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -25,6 +25,7 @@ html_DATA = \ html/quickstart_admin.html \ html/quickstart.html \ html/schedplugins.html \ + html/selectplugins.html \ html/slurm_banner.jpg \ html/slurm_design.pdf \ html/slurm.html \ diff --git a/doc/html/documentation.html b/doc/html/documentation.html index 810708f49e8..35d055e88be 100644 --- a/doc/html/documentation.html +++ b/doc/html/documentation.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="12 January 2004"> +<meta name="LLNLRandRdate" content="24 August 2004"> <meta name="distribution" content="global"> <meta name="description" content="Simple Linux Utility for Resource Management"> <meta name="copyright" @@ -62,6 +62,7 @@ for SLURM administrators and developers.</p> <li><a href="plugins.html">Plugin Programmer Guide</a></li> <li><a href="authplugins.html">Authentication Plugin Programmer Guide</a></li> <li><a href="jobcompplugins.html">Job Completion Logging Plugin Programmer Guide</a></li> +<li><a href="selectplugins.html">Node Selection Plugin Programmer Guide</a></li> <li><a href="schedplugins.html">Scheduler Plugin Programmer Guide</a></li> <li><a href="switchplugins.html">Switch (Interconnect) Plugin Programmer Guide</a></li> <li><a href="maui.html">Maui Scheduler Inegration Guide</a></li> @@ -71,7 +72,7 @@ for SLURM administrators and developers.</p> <td colspan="3"><hr> <p>For information about this page, contact <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 March 12, 2004</p></td> +Last modified 24 August 2004</p></td> </tr> </table> </td> diff --git a/doc/html/selectplugins.html b/doc/html/selectplugins.html new file mode 100644 index 00000000000..b3df463311b --- /dev/null +++ b/doc/html/selectplugins.html @@ -0,0 +1,234 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> + +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<meta http-equiv="Pragma" content="no-cache"> +<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="24 August 2004"> +<meta name="distribution" content="global"> +<meta name="description" content="Simple Linux Utility for Resource Management"> +<meta name="copyright" +content="This document is copyrighted U.S. +Department of Energy under Contract W-7405-Eng-48"> +<meta name="Author" content="Morris Jette"> +<meta name="email" content="jette1@llnl.gov"> +<meta name="Classification" +content="DOE:DOE Web sites via organizational +structure:Laboratories and Other Field Facilities"> +<title>Simple Linux Utility for Resource Management:Node Selection Plugins</title> +<link href="slurmstyles.css" rel="stylesheet" type="text/css"> +</head> + +<body bgcolor="#000000" text="#000000" leftmargin="0" topmargin="0"> +<table width="770" border="0" cellspacing="0" cellpadding="0"> +<tr> +<td><img src="slurm_banner.jpg" width="770" height="145" usemap="#Map" border="0" alt="Simple Linux Utility for Resource Management"></td> +</tr> +</table> +<table width="770" border="0" cellspacing="0" cellpadding="3" bgcolor="#FFFFFF"> +<tr> +<td width="100%"> +<table width="760" border="0" cellspacing="0" cellpadding="4" align="right"> +<tr> +<td valign="top" bgcolor="#000000"><p><img src="spacer.gif" width="110" height="1" alt=""></p> +<p><a href="slurm.html" class="nav" align="center">Home</a></p> +<p><span class="whitetext">About</span><br> +<a href="overview.html" class="nav">Overview</a><br> +<a href="news.html" class="nav">What's New</a><br> +<a href="publications.html" class="nav">Publications</a><br> +<a href="team.html" class="nav">SLURM Team</a></p> +<p><span class="whitetext">Using</span><br> +<a href="documentation.html" class="nav">Documentation</a><br> +<a href="faq.html" class="nav">FAQ</a><br> +<a href="help.html" class="nav">Getting Help</a></p> +<p><span class="whitetext">Installing</span><br> +<a href="platforms.html" class="nav">Platforms</a><br> +<a href="download.html" class="nav">Download</a><br> +<a href="quickstart_admin.html" class="nav">Guide</a></p></td> +<td><img src="spacer.gif" width="10" height="1" alt=""></td> +<td valign="top"><h2><a name="top">SLURM Node Selection Plugin API</a></h2> + +<h3> Overview</h3> +<p><b>NOTE: This document describes a plugin being implemented in SLURM version 0.4. +It is provided at this time for programmers performing the development.</b></p> + +<p> This document describes SLURM node selection plugins and the API that defines +them. It is intended as a resource to programmers wishing to write their own SLURM +node selection plugins. This is version 0 of the API.</p> + +<p>SLURM node selection plugins are SLURM plugins that implement the SLURM node selection +API described herein. They 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 "select." The minor type can be any recognizable +abbreviation for the type of node selection algorithm. We recommend, for example:</p> +<ul> +<li><b>linear</b>—A plugin that selects nodes assuming a one-dimensional +array of nodes. The nodes are selected so as to minimize the number of consecutive +sets of nodes utilizing a best-fit algorithm.</li> +<li><b>bluegene</b>—<a href="http://www.research.ibm.com/bluegene">IBM Blue Gene</a> +node selector. Note that this plugin not only selects the nodes for a job, but performs +some initialization and termination functions for the job.</li> +</ul> +<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 node selection support. +Note carefully, however, the versioning discussion below.</p> + +<h3>Data Objects</h3> +<p> These functions are expected to read and/or modify data structures directly in +the slurmctld daemon's memory. Slurmctld is a multi-threaded program with independent +read and write locks on each data structure type. Thererfore the type of operations +permitted on various data structures is identified for each function.</p> + +<p>These functions make use of bitmaps corresponding to the nodes in a table. +The function <span class="commandline">select_p_node_init()</span> should +be used to establish the initial mapping of bitmap entries to nodes. +Functions defined in <i>src/common/bitmap.h</i> should be used for bitmap +manipulations (these functions are directly accessible from the plugin).</p> + +<p class="footer"><a href="#top">top</a></p> + +<h3>API Functions</h3> +<p>The following functions must appear. Functions which are not implemented should +be stubbed.</p> + +<h4>Global Node Selection Functions</h4> +<p class="commandline">int select_p_state_save (char *dir_name);</p> +<p style="margin-left:.2in"><b>Description</b>: Save any global node selection state +information to a file within the specified directory. The actual file name used is plugin specific. +It is recommended that the global switch state contain a magic number for validation purposes. +This function is called by the slurmctld deamon on shutdown.</p> +<p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> dir_name</span> + (input) fully-qualified pathname of a directory into which user SlurmUser (as defined +in slurm.conf) can create a file and write state information into that file. Cannot be NULL.</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 select_p_state_restore (char *dir_name);</p> +<p style="margin-left:.2in"><b>Description</b>: Restore any global node selection state +information from a file within the specified directory. The actual file name used is plugin specific. +It is recommended that any magic number associated with the global switch state be verified. +This function is called by the slurmctld deamon on startup.</p> +<p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> dir_name</span> + (input) fully-qualified pathname of a directory containing a state information file +from which user SlurmUser (as defined in slurm.conf) can read. Cannot be NULL.</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 select_p_node_init (struct node_record *node_ptr, int node_cnt);</p> +<p style="margin-left:.2in"><b>Description</b>: Note the initialization of the node record data +structure. This function is called when the node records are initially established and again +when any nodes are added to or removed from the data structure. </p> +<p style="margin-left:.2in"><b>Arguments</b>:<br> +<span class="commandline"> node_ptr</span> (input) pointer +to the node data records. Data in these records can read. Nodes deleted after initiialization +may have their the <i>name</i> field in the record cleared (zero length) rather than +rebuilding the node records and bitmaps. <br> +<span class="commandline"> node_cnt</span> (input) number +of node data records.</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="footer"><a href="#top">top</a></p> + +<h4>Job-Specific Node Selection Functions</h4> +<p class="commandline">int select_p_job_test (struct job_record *job_ptr, +bitstr_t * bitmap, int min_nodes, int max_nodes);</p> +<p style="margin-left:.2in"><b>Description</b>: Given a job's scheduling requirement +specification and a set of nodes which might be used to satisfy the request, identify +the nodes which "best" satify the request. Note that nodes being considered for allocation +to the job may include nodes already allocated to other jobs, even if node sharing is +not permitted. This is done to ascertain whether or not job may be allocated resources +at some later time (when the other jobs complete). This permits SLURM to reject +non-runnable jobs at submit time rather than after they have spent hours queued. +Informing users of problems at job submission time permits them to quickly resubmit +the job with appropriate constraints.</p> +<p style="margin-left:.2in"><b>Arguments</b>:<br> +<span class="commandline"> job_ptr</span> (input) pointer +to the job being considered for scheduling. Data in this job record may safely be read. +Data of particular interst include <i>details->contiguous</i>(set if allocated nodes +should be contiguous) <i>num_procs</i> (minimum processors in allocation) and +<i>details->req_node_bitmap</i> (specific required nodes).<br> +<span class="commandline"> bitmap</span> (input/output) +bits representing nodes which might be allocated to the job are set on input. +This function should clear the bits representing nodes not required to satisfy +job's scheduling request. +Bits left set will represent nodes to be used for this job. Note that the job's +required nodes (<i>details->req_node_bitmap</i>) will be a superset +<i>bitmap</i> when the function is called.<br> +<span class="commandline"> min_nodes</span> (input) +minimum number of nodes to allocate to this job. Note this reflects both job +and partition specifications.<br> +<span class="commandline"> max_nodes</span> (input) +maximum number of nodes to allocate to this job. Note this reflects both job +and partition specifications.<br> +</p> +<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure, +the plugin should return SLURM_ERROR (do not set <i>errno</i>).</p> + +<p class="commandline">int select_p_job_init (struct job_record *job_ptr);</p> +<p style="margin-left:.2in"><b>Description</b>: Note the initiation of the specified job +is about to begin. This function is called immediately after +<span class="commandline">select_p_job_test()</span> sucessfully completes for this job. +<p style="margin-left:.2in"><b>Arguments</b>: +<span class="commandline"> job_ptr</span> (input) pointer +to the job being initialized. Data in this job record may safely be read or written. +The <i>nodes</i> and <i>node_bitmap</i> fields of this job record identify the +nodes which have already been selected for this job to use. For an example of +a job record field that the plugin may write into, see <i>select_id</i>.</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 select_p_job_fini (struct job_record *job_ptr);</p> +<p style="margin-left:.2in"><b>Description</b>: Note the termination of the +specified job. This function is called as the termination process for the +job begins (prior to killing the tasks).</p> +<p style="margin-left:.2in"><b>Arguments</b>: +<span class="commandline"> job_ptr</span> (input) pointer +to the job being terminated. Data in this job record may safely be read or written. +The <i>nodes</i> and/or <i>node_bitmap</i> fields of this job record identify the +nodes which were selected for this job to use.</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="footer"><a href="#top">top</a></p> + +<h3>Versioning</h3> +<p> This document describes version 0 of the SLURM node selection API. Future +releases of SLURM may revise this API. A node selection plugin conveys its ability +to implement a particular API version using the mechanism outlined for SLURM plugins. +In addition, the credential is transmitted along with the version number of the +plugin that transmitted it. It is at the discretion of the plugin author whether +to maintain data format compatibility across different versions of the plugin.</p> + +<p class="footer"><a href="#top">top</a></p></td> +</tr> +<tr> +<td colspan="3"><hr> <p>For information about this page, contact +<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 24 August 2004</p></td> +</tr> +</table> +</td> + </tr> +</table> +<map name="Map"> +<area shape="rect" coords="616,4,762,97" href="../"> +<area shape="rect" coords="330,1,468,11" href="http://www.llnl.gov/disclaimer.html"> +<area shape="rect" coords="11,23,213,115" href="slurm.html"> +</map> +</body> +</html> -- GitLab