From 2d28ef524994f71485272780eeb8e2462d620f77 Mon Sep 17 00:00:00 2001 From: Morris Jette <jette@schedmd.com> Date: Fri, 28 Jun 2013 07:30:47 -0700 Subject: [PATCH] Update switch documentation to clarify most calls are for a job step Rather than a job --- doc/html/switchplugins.shtml | 84 ++++++++++++++++++------------------ 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/doc/html/switchplugins.shtml b/doc/html/switchplugins.shtml index a1974528f38..896432e83e1 100644 --- a/doc/html/switchplugins.shtml +++ b/doc/html/switchplugins.shtml @@ -36,8 +36,8 @@ for sample implementations of a SLURM switch plugin.</p> <h2>Data Objects</h2> <p> The implementation must support two opaque data classes. -One is used as an job's switch "credential." -This class must encapsulate all job-specific information necessary +One is used as an job step's switch "credential." +This class must encapsulate all job step 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 @@ -116,7 +116,7 @@ switch state information on a periodic basis.</p> <p class="commandline">int switch_p_clear_node_state (void);</p> <p style="margin-left:.2in"><b>Description</b>: Initialize node state. -If any switch state has previously been established for a job, it will be cleared. +If any switch state has previously been established for a job step, it will be cleared. This will be used to establish a "clean" state for the switch on the node upon which it is executed.</p> <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure, @@ -192,10 +192,10 @@ of buf in bytes.</p> <h3>Job's Switch Credential Management Functions</h3> <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. +<p style="margin-left:.2in"><b>Description</b>: Allocate storage for a job step's switch credential. It is recommended that the credential contain a magic number for validation purposes.</p> <p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> switch_job</span> - (output) location for writing location of job's switch credential.</p> + (output) location for writing location of job step's switch credential.</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> @@ -208,14 +208,14 @@ It is recommended that the credential's magic number be validated.</p> <span class="commandline">switch_job</span> (input/output) Job's switch credential to be updated<br> <span class="commandline">nodelist</span> (input) List of nodes -allocated to the job. This may contain expressions to specify node ranges (e.g. +allocated to the job step. This may contain expressions to specify node ranges (e.g. "linux[1-20]" or "linux[2,4,6,8]").<br> <span class="commandline">tasks_per_node</span> (input) count -of processes per node to be initiated as part of the job.<br> +of processes per node to be initiated as part of the job step.<br> <span class="commandline">tids</span> (input) List of task IDs to be initiated. The first array index is the node ID. The second array index ranges from 0 to tasks_per_node of that node ID minus 1.<br> -<span class="commandline">network</span> (input) Job's network +<span class="commandline">network</span> (input) Job step's network specification from srun command. </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 @@ -225,23 +225,23 @@ to indicate the reason for failure.</p> <p style="margin-left:.2in"><b>Description</b>: Allocate storage for a job's switch credential and copy an existing credential to that location.</p> <p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> switch_job</span> - (input) an existing job switch credential.</p> -<p style="margin-left:.2in"><b>Returns</b>: A newly allocated job switch credential containing a -copy of the function argument.</p> + (input) an existing job step switch credential.</p> +<p style="margin-left:.2in"><b>Returns</b>: A newly allocated job step switch +credential containing a copy of the function argument.</p> <p class="commandline">void switch_p_free_jobinfo (switch_jobinfo_t switch_job);</p> <p style="margin-left:.2in"><b>Description</b>: Release the storage associated with a job's switch credential.</p> <p style="margin-left:.2in"><b>Arguments</b>:<span class="commandline"> switch_job</span> - (input) an existing job switch credential.</p> + (input) an existing job step switch credential.</p> <p style="margin-left:.2in"><b>Returns</b>: None</p> <p class="commandline">int switch_p_pack_jobinfo (switch_jobinfo_t switch_job, Buf buffer);</p> -<p style="margin-left:.2in"><b>Description</b>: Pack the data associated with a job's +<p style="margin-left:.2in"><b>Description</b>: Pack the data associated with a job step's switch credential into a buffer for network transmission.</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> -<span class="commandline"> switch_job</span> (input) an existing job -switch credential.<br> +<span class="commandline"> switch_job</span> (input) an +existing job step switch credential.<br> <span class="commandline"> buffer</span> (input/output) buffer onto which the credential's contents are appended.</p> <p style="margin-left:.2in"><b>Returns</b>: @@ -254,7 +254,7 @@ to indicate the reason for failure.</p> switch credential from a buffer.</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> <span class="commandline"> switch_job</span> (input/output) a previously -allocated job switch credential to be filled in with data read from the buffer.<br> +allocated job step switch credential to be filled in with data read from the buffer.<br> <span class="commandline"> buffer</span> (input/output) buffer from which the credential's contents are read.</p> <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure, @@ -279,10 +279,10 @@ char *nodelist);</p> with the specified nodelist has completed execution.</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> <span class="commandline"> switch_job</span> (input) -The completed job's switch credential.<br> +The completed job step's switch credential.<br> <span class="commandline"> nodelist</span> (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> +on which the job step 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> @@ -335,11 +335,11 @@ bytes</p> <p class="commandline">int switch_p_get_data_jobinfo(switch_jobinfo_t switch_job, int key, void *resulting_data);</p> -<p style="margin-left:.2in"><b>Description</b>: Get data from a job's +<p style="margin-left:.2in"><b>Description</b>: Get data from a job step's switch credential.</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> -<span class="commandline"> switch_job</span> (input) a job's -switch credential.<br> +<span class="commandline"> switch_job</span> (input) a job +step's switch credential.<br> <span class="commandline"> key</span> (input) identification of the type of data to be retrieved from the switch credential. NOTE: The interpretation of this key is dependent upon the switch type. <br> @@ -370,7 +370,7 @@ 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>Job Management Functions</h3> +<h3>Job Step Management Functions</h3> <pre> ========================================================================= Process 1 (root) Process 2 (root, user) | Process 3 (user task) @@ -387,7 +387,7 @@ switch_p_job_postfini | <p class="commandline">int switch_p_job_preinit (switch_jobinfo_t jobinfo switch_job);</p> <p style="margin-left:.2in"><b>Description</b>: Preinit is run as root in the first slurmd process, -the so called job manager. This function can be used to perform any initialization +the so called job step manager. This function can be used to perform any initialization that needs to be performed in the same process as switch_p_job_fini().</p> <p style="margin-left:.2in"><b>Arguments</b>: <span class="commandline"> switch_job</span> (input) a job's @@ -402,10 +402,10 @@ This function is run from the second slurmd process (some interconnect implement may require the switch_p_job_init functions to be executed from a separate process than the process executing switch_p_job_fini() [e.g. Quadrics Elan]).</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> -<span class="commandline"> switch_job</span> (input) a job's -switch credential.<br> +<span class="commandline"> switch_job</span> (input) a job +step's switch credential.<br> <span class="commandline"> uid</span> (input) the user id -to execute a job.</p> +to execute a job step.</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> @@ -419,16 +419,16 @@ environment variables here).</p> <span class="commandline"> switch_job</span> (input) a job's switch credential.<br> <span class="commandline"> env</span> (input/output) the -environment variables to be set upon job initiation. Switch specific environment -variables are added as needed.<br> +environment variables to be set upon job step initiation. Switch specific +environment variables are added as needed.<br> <span class="commandline"> nodeid</span> (input) zero-origin id of this node.<br> <span class="commandline"> procid</span> (input) zero-origin process id local to slurmd and <b>not</b> equivalent to the global task id or MPI rank.<br> <span class="commandline"> nnodes</span> (input) count of -nodes allocated to this job.<br> +nodes allocated to this job step.<br> <span class="commandline"> nprocs</span> (input) total count of -processes or tasks to be initiated for this job.<br> +processes or tasks to be initiated for this job step.<br> <span class="commandline"> rank</span> (input) zero-origin id of this task.</p> <p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure, @@ -438,10 +438,10 @@ to indicate the reason for failure.</p> <p class="commandline">int switch_p_job_fini (switch_jobinfo_t jobinfo switch_job);</p> <p style="margin-left:.2in"><b>Description</b>: This function is run from the same process as switch_p_job_init() after all job tasks have exited. It is *not* run as root, because -the process in question has already setuid to the job owner.</p> +the process in question has already setuid to the job step owner.</p> <p style="margin-left:.2in"><b>Arguments</b>: -<span class="commandline"> switch_job</span> (input) a job's -switch credential.</p> +<span class="commandline"> switch_job</span> (input) a job +step's switch credential.</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> @@ -452,8 +452,8 @@ uid_t pgid, uint32_t job_id, uint32_t step_id );</p> process (same process as switch_p_job_preinit()), and is run as root. Any cleanup routines that need to be run with root privileges should be run from this function.</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> -<span class="commandline"> switch_job</span> (input) a job's -switch credential.<br> +<span class="commandline"> switch_job</span> (input) a job +step's switch credential.<br> <span class="commandline"> pgid</span> (input) The process group id associated with this task.<br> <span class="commandline"> job_id</span> (input) the @@ -489,9 +489,9 @@ to indicate the reason for failure.</p> <p style="margin-left:.2in"><b>Description</b>: Determine if a specific job step can be preempted.</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> -<span class="commandline"> switch_job</span> (input) a job's -switch credential.</p> -<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if the job can be +<span class="commandline"> switch_job</span> (input) a job +step's switch credential.</p> +<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if the job step can be preempted and SLURM_ERROR otherwise.</p> <p class="commandline">void switch_p_job_suspend_info_get(switch_jobinfo_t *switch_job, @@ -509,7 +509,7 @@ for addition function call (i.e. for each addition job step).</p> <p class="commandline">void switch_p_job_suspend_info_pack(void *suspend_info, Buf buffer);</p> <p style="margin-left:.2in"><b>Description</b>: Pack the information needed -for a job step to be preempted into a buffer</p> +for a job to be preempted into a buffer</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> <span class="commandline"> suspend_info</span> (input) information needed for a job to be preempted, including information for all @@ -519,7 +519,7 @@ the buffer that has suspend_info added to it.</p> <p class="commandline">int switch_p_job_suspend_info_unpack(void **suspend_info, Buf buffer);</p> <p style="margin-left:.2in"><b>Description</b>: Unpack the information needed -for a job step to be preempted from a buffer.<br> +for a job to be preempted from a buffer.<br> <b>NOTE</b>: Use switch_p_job_suspend_info_free() to free the opaque data structure.</p> <p style="margin-left:.2in"><b>Arguments</b>:<br> <span class="commandline"> suspend_info</span> (output) @@ -590,6 +590,6 @@ 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> -<p style="text-align:center;">Last modified 6 August 2012</p> +<p style="text-align:center;">Last modified 26 June 2013</p> <!--#include virtual="footer.txt"--> -- GitLab