| .TH "Slurm API" "3" "March 2007" "Morris Jette" "Slurm job step context functions" |
| |
| .SH "NAME" |
| slurm_step_ctx_create, slurm_step_ctx_create_no_alloc, |
| slurm_step_ctx_daemon_per_node_hack, slurm_step_ctx_get, |
| slurm_step_ctx_params_t_init, slurm_jobinfo_ctx_get, |
| slurm_spawn_kill, slurm_step_ctx_destroy \- Slurm task spawn functions |
| |
| .SH "SYNTAX" |
| .LP |
| #include <slurm/slurm.h> |
| .LP |
| .LP |
| slurm_step_ctx \fBslurm_step_ctx_create\fR ( |
| .br |
| slurm_step_ctx_params_t *\fIstep_req\fP |
| .br |
| ); |
| .LP |
| slurm_step_ctx \fBslurm_step_ctx_create_no_alloc\fR ( |
| .br |
| slurm_step_ctx_params_t *\fIstep_req\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_step_ctx_daemon_per_node_hack\fR ( |
| .br |
| slurm_step_ctx_t *\fIctx\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_step_ctx_get\fR ( |
| .br |
| slurm_step_ctx_t *\fIctx\fP, |
| .br |
| int \fIctx_key\fP, |
| .br |
| ... |
| .br |
| ); |
| .LP |
| int \fBslurm_jobinfo_ctx_get\fR ( |
| .br |
| switch_jobinfo_t \fIjobinfo\fP, |
| .br |
| int \fIdata_type\fP, |
| .br |
| void *\fIdata\fP |
| .br |
| ); |
| .LP |
| void \fBslurm_step_ctx_params_t_init\fR ( |
| .br |
| slurm_step_ctx_params_t *\fIstep_req\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_spawn\fR { |
| .br |
| slurm_step_ctx \fIctx\fP, |
| .br |
| int *\fIfd_array\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_spawn_kill\fR { |
| .br |
| slurm_step_ctx \fIctx\fP, |
| .br |
| uint16_t \fIsignal\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_step_ctx_destroy\fR { |
| .br |
| slurm_step_ctx \fIctx\fP |
| .br |
| ); |
| .SH "ARGUMENTS" |
| .LP |
| .TP |
| \fIstep_req\fP |
| Specifies the pointer to the structure with job step request specification. See |
| slurm.h for full details on the data structure's contents. |
| .TP |
| \fIctx\fP |
| Job step context. Created by \fBslurm_step_ctx_create\fR, or |
| \fBslurm_step_ctx_create_no_alloc\fR used in subsequent |
| function calls, and destroyed by \fBslurm_step_ctx_destroy\fR. |
| .TP |
| \fIctx_key\fP |
| Identifies the fields in \fIctx\fP to be collected by \fBslurm_step_ctx_get\fR. |
| .TP |
| \fIdata\fP |
| Storage location for requested data. See \fIdata_type\fP below. |
| .TP |
| \fIdata_type\fP |
| Switch\-specific data requested. The interpretation of this field depends |
| upon the switch plugin in use. |
| .TP |
| \fIfd_array\fP |
| Array of socket file descriptors to be connected to the initiated tasks. |
| Tasks will be connected to these file descriptors in order of their |
| task id. |
| This socket will carry standard input, output and error for the task. |
| \fIjobinfo\fP |
| Switch\-specific job information as returned by \fBslurm_step_ctx_get\fR. |
| .TP |
| \fIsignal\fP |
| Signal to be sent to the spawned tasks. |
| .SH "DESCRIPTION" |
| .LP |
| \fBslurm_jobinfo_ctx_get\fR Get values from a \fIjobinfo\fR field as |
| returned by \fBslurm_step_ctx_get\fR. The operation of this function |
| is highly dependent upon the switch plugin in use. |
| .LP |
| \fBslurm_step_ctx_create\fR Create a job step context. To avoid memory |
| leaks call \fBslurm_step_ctx_destroy\fR when the use of this context is |
| finished. NOTE: this function creates a slurm job step. Call \fBslurm_spawn\fR |
| in a timely fashion to avoid having job step credentials time out. If |
| \fBslurm_spawn\fR is not used, explicitly cancel the job step. |
| .LP |
| \fBslurm_step_ctx_create_no_alloc\fR Same as above, only no |
| allocation is made. To avoid memory leaks call |
| \fBslurm_step_ctx_destroy\fR when the use of this context is finished. |
| .LP |
| \fBslurm_step_ctx_daemon_per_node_hack\fR Hack the step context to run |
| a single process per node, regardless of the settings selected at |
| slurm_step_ctx_create time. |
| .LP |
| \fBslurm_step_ctx_get\fR Get values from a job step context. |
| \fIctx_key\fP identifies the fields to be gathered from the job step context. |
| Subsequent arguments to this function are dependent upon the value |
| of \fIctx_key\fP. See the \fBCONTEXT KEYS\fR section for details. |
| .LP |
| \fBslurm_step_ctx_params_t_init\fR This initializes parameters in the |
| structure that you will pass to slurm_step_ctx_create(). |
| .LP |
| \fBslurm_spawn\fR Spawn tasks based upon a job step context |
| and establish communications with the tasks using the socket |
| file descriptors specified. |
| Note that this function can only be called once for each job |
| step context. |
| Establish a new job step context for each set of tasks to be spawned. |
| .LP |
| \fBslurm_spawn_kill\fR Signal the tasks spawned for this context |
| by \fBslurm_spawn\fR. |
| .LP |
| \fBslurm_step_ctx_destroy\fR Destroy a job step context created by |
| \fBslurm_step_ctx_create\fR. |
| .SH "CONEXT KEYS" |
| .TP |
| \fBSLURM_STEP_CTX_ARGS\fR |
| Set the argument count and values for the executable. |
| Accepts two additional arguments, the first of type int and |
| the second of type char **. |
| .TP |
| \fBSLURM_STEP_CTX_CHDIR\fR |
| Have the remote process change directory to the specified location |
| before beginning execution. Accepts one argument of type |
| char * identifying the directory's pathname. By default |
| the remote process will execute in the same directory pathname |
| from which it is spawned. NOTE: This assumes that same directory |
| pathname exists on the other nodes. |
| .TP |
| \fBSLURM_STEP_CTX_ENV\fR |
| Sets the environment variable count and values for the executable. |
| Accepts two additional arguments, the first of type int and |
| the second of type char **. By default the current environment |
| variables are copied to started task's environment. |
| .TP |
| \fBSLURM_STEP_CTX_RESP\fR |
| Get the job step response message. |
| Accepts one additional argument of type job_step_create_response_msg_t **. |
| .TP |
| \fBSLURM_STEP_CTX_STEPID\fR |
| Get the step id of the created job step. |
| Accepts one additional argument of type uint32_t *. |
| .TP |
| \fBSLURM_STEP_CTX_TASKS\fR |
| Get the number of tasks per node for a given job. |
| Accepts one additional argument of type uint32_t **. |
| This argument will be set to point to an array with the |
| task counts of each node in an element of the array. |
| See \fBSLURM_STEP_CTX_TID\fR below to determine the |
| task ID numbers associated with each of those tasks. |
| .TP |
| \fBSLURM_STEP_CTX_TID\fR |
| Get the task ID numbers associated with the tasks allocated to |
| a specific node. |
| Accepts two additional arguments, the first of type int and |
| the second of type uint32_t **. The first argument identifies |
| the node number of interest (zero origin). The second argument |
| will be set to point to an array with the task ID numbers of |
| each task allocated to the node (also zero origin). |
| See \fBSLURM_STEP_CTX_TASKS\fR above to determine how many |
| tasks are associated with each node. |
| .SH "RETURN VALUE" |
| .LP |
| For \fB slurm_step_ctx_create\fR a context is return upon success. On error |
| NULL is returned and the Slurm error code is set appropriately. |
| .LP |
| For all other functions zero is returned upon success. |
| On error, \-1 is returned, and the Slurm error code is set appropriately. |
| .SH "ERRORS" |
| .LP |
| \fBEINVAL\fR Invalid argument |
| .LP |
| \fBSLURM_PROTOCOL_VERSION_ERROR\fR Protocol version has changed, re\-link your code. |
| .LP |
| \fBESLURM_INVALID_JOB_ID\fR the requested job id does not exist. |
| .LP |
| \fBESLURM_ALREADY_DONE\fR the specified job has already completed and can not be modified. |
| .LP |
| \fBESLURM_ACCESS_DENIED\fR the requesting user lacks authorization for the requested action (e.g. trying to delete or modify another user's job). |
| .LP |
| \fBESLURM_DISABLED\fR the ability to create a job step is currently disabled. |
| This is indicative of the job being suspended. Retry the call as desired. |
| .LP |
| \fBESLURM_INTERCONNECT_FAILURE\fR failed to configure the node interconnect. |
| .LP |
| \fBESLURM_BAD_DIST\fR task distribution specification is invalid. |
| .LP |
| \fBSLURM_PROTOCOL_SOCKET_IMPL_TIMEOUT\fR Timeout in communicating with |
| SLURM controller. |
| .SH "EXAMPLE |
| .LP |
| SEE \fBslurm_step_launch\fR(3) man page for an example of slurm_step_ctx_create |
| and slurm_step_launch in use together. |
| |
| .SH "NOTE" |
| These functions are included in the libslurm library, |
| which must be linked to your process for use |
| (e.g. "cc \-lslurm myprog.c"). |
| |
| .SH "COPYING" |
| Copyright (C) 2004-2007 The Regents of the University of California. |
| Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). |
| CODE\-OCEC\-09\-009. All rights reserved. |
| .LP |
| This file is part of SLURM, a resource management program. |
| For details, see <http://slurm.schedmd.com/>. |
| .LP |
| SLURM is free software; you can redistribute it and/or modify it under |
| the terms of the GNU General Public License as published by the Free |
| Software Foundation; either version 2 of the License, or (at your option) |
| any later version. |
| .LP |
| SLURM is distributed in the hope that it will be useful, but WITHOUT ANY |
| WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
| FOR A PARTICULAR PURPOSE. See the GNU General Public License for more |
| details. |
| .SH "SEE ALSO" |
| .LP |
| \fBslurm_allocate_resources\fR(3), \fBslurm_job_step_create\fR(3), |
| \fBslurm_kill_job\fR(3), |
| \fBslurm_get_errno\fR(3), \fBslurm_perror\fR(3), \fBslurm_strerror\fR(3), |
| \fBsrun\fR(1) |
