Slurm API(3)

NAME
slurm_spawn - Slurm task spawn functions

SYNTAX

#include <slurm/slurm.h>

slurm_step_ctx slurm_step_ctx_create (
    job_step_create_request_msg_t *step_req
);

int slurm_step_ctx_get (
    slurm_step_ctx ctx,
    int ctx_key,
    ...
);

int slurm_jobinfo_ctx_get (
    switch_jobinfo_t jobinfo,
    int data_type,
    void *data
);

int slurm_step_ctx_set (
    slurm_step_ctx ctx,
    int ctx_key,
    ...
);

int slurm_spawn {
    slurm_step_ctx ctx,
    int *fd_array
);

int slurm_spawn_kill {
        slurm_step_ctx ctx,
    uint16_t signal
);

int slurm_step_ctx_destroy {
    slurm_step_ctx ctx
);

ARGUMENTS

step_req
    Specifies the pointer to the structure with job step request specification. See slurm.h for full details on the data structure's contents.

ctx Job step context. Created by slurm_step_ctx_create, used in subsequent function calls, and destroyed by slurm_step_ctx_destroy.

ctx_key
    Identifies the fields in ctx to be collected by slurm_step_ctx_get or set by slurm_step_ctx_set.

data
    Storage location for requested data. See data_type below.

data_type
    Switch-specific data requested. The interpretation of this field depends upon the switch plugin in use.

fd_array
    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. jobinfo Switch-specific job information as returned by slurm_step_ctx_get.

signal
    Signal to be sent to the spawned tasks.

DESCRIPTION

slurm_jobinfo_ctx_get Get values from a jobinfo field as returned by slurm_step_ctx_get. The operation of this function is highly dependent upon the switch plugin in use.

slurm_step_ctx_create Create a job step context. To avoid memory leaks call slurm_step_ctx_destroy when the use of this context is finished. NOTE: this function creates a slurm job step. Call slurm_spawn in a timely fashion to avoid having job step credentials time out. If slurm_spawn is not used, explicitly cancel the job step.

slurm_step_ctx_get Get values from a job step context. ctx_key identifies the fields to be gathered from the job step context. Subsequent arguments to this function are dependent upon the value of ctx_key. See the CONTEXT KEYS section for details.

slurm_step_ctx_set Set values in a job step context. ctx_key identifies the fields to be set in the job step context. Subsequent arguments to this function are dependent upon the value of ctx_key. See the CONTEXT KEYS section for details.

slurm_spawn 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.

slurm_spawn_kill Signal the tasks spawned for this context by slurm_spawn.

slurm_step_ctx_destroy Destroy a job step context created by slurm_step_ctx_create.

CONEXT KEYS

SLURM_STEP_CTX_ARGS
    Set the argument count and values for the executable. Accepts two additional arguments, the first of type int and the second of type char **.

SLURM_STEP_CTX_CHDIR
    Have the remote process change directory to the specified location before beginning execution. Accepts one argument of type char * indentifying 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.

SLURM_STEP_CTX_ENV
    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.

SLURM_STEP_CTX_RESP
    Get the job step response message. Accepts one additional argument of type job_step_create_response_msg_t **.

SLURM_STEP_CTX_STEPID
    Get the step id of the created job step. Accepts one additional argument of type uint32_t *.

SLURM_STEP_CTX_TASKS
    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 SLURM_STEP_CTX_TID below to determine the task ID numbers associated with each of those tasks.

SLURM_STEP_CTX_TID
    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 SLURM_STEP_CTX_TASKS above to determine how many tasks are associated with each node.

RETURN VALUE

For slurm_step_ctx_create a context is return upon success. On error NULL is returned and the Slurm error code is set appropriately.

For all other functions zero is returned upon success. On error, -1 is returned, and the Slurm error code is set appropriately.

ERRORS

EINVAL Invalid argument

SLURM_PROTOCOL_VERSION_ERROR Protocol version has changed, re-link your code.

ESLURM_INVALID_JOB_ID the requested job id does not exist.

ESLURM_ALREADY_DONE the specified job has already completed and can not be modified.

ESLURM_ACCESS_DENIED the requesting user lacks authorization for the requested action (e.g. trying to delete or modify another user's job).

ESLURM_INTERCONNECT_FAILURE failed to configure the node interconnect.

ESLURM_BAD_DIST task distribution specification is invalid.

SLURM_PROTOCOL_SOCKET_IMPL_TIMEOUT Timeout in communicating with SLURM controller.

EXAMPLE

#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/types.h>
#include <slurm/slurm.h>
#include <slurm/slurm_errno.h>

static int *_build_socket_array(int nodes);
static void _do_task_work(int *fd_array, int nodes);

int main (int argc, char *argv[])
{
    int i, j, nodes = 1, tasks;
    job_desc_msg_t job_req;
    resource_allocation_response_msg_t *job_resp;
    job_step_create_request_msg_t; step_req;
    slurm_step_ctx ctx;
    char *task_argv[2];
    int *fd_array;
    uint32_t *task_cnt; *tid;

    if (argc > 1) {
        i = atoi(argv[1]);
        if (i > 0)
            nodes = i;
    }
    tasks = nodes;

    /* Create a job allocation */
    slurm_init_job_desc_msg( &job_req );
    job_req.min_nodes = nodes;
    if (slurm_allocate_resources(&job_req, &job_resp)) {
        slurm_perror ("slurm_allocate_resources error");
        exit (1);
    }

    /* Set up step configuration */
    bzero(&step_req, sizeof(job_step_create_request_msg_t ));
    step_req.job_id = job_resp->job_id;
    step_req.user_id = getuid();
    step_req.node_count = nodes;
    step_req.num_tasks = tasks;
    step_req.num_tasks = nodes;
    ctx = slurm_step_ctx_create(&step_req);
    if (ctx == NULL) {
        slurm_perror("slurm_step_ctx_create");
        exit(1);
    }

    task_argv[0] = "/bin/hostname";
    if (slurm_step_ctx_set(ctx, SLURM_STEP_CTX_ARGS,
            1, &task_argv))
        slurm_perror("slurm_step_ctx_create");
    fd_array = _build_socket_array(tasks);

    /* Spawn the tasks */
    if (slurm_spawn(ctx, fd_array)) {
        slurm_perror("slurm_spawn");
        slurm_kill_job(job_resp->job_id, SIGKILL, 0);
        exit(1);
    }

    printf("Started %d tasks on %d nodes\n",
        step_req.num_tasks, step_req.node_count);
    if (slurm_step_ctx_get(ctx, SLURM_STEP_CTX_TASKS, &task_cnt)) {
        slurm_perror("slurm_step_ctx_create");
        exit(1);
    }
    for (i=0; i<step_req.node_count; i++) {
        if (slurm_step_ctx_get(ctx, SLURM_STEP_CTX_TID, i, &tid)) {
            slurm_perror("slurm_step_ctx_create");
            exit(1);
        }
        for (j=0; j<task_cnt[i]; j++)
            printf("tid[%d][%d] = %u\n", i, j, tid[j]);

    /* Interact with spawned tasks as desired */
    _do_task_work(fd_array, tasks);

    if (slurm_spawn_kill(ctx, SIGKILL))
        slurm_perror("slurm_spawn_kill");

    /* Terminate the job killing all tasks */
    slurm_kill_job(job_resp->job_id, SIGKILL, 0);
    slurm_step_ctx_destroy(ctx);
    slurm_free_resource_allocation_response_msg(job_resp);
    exit (0);
}

COPYING
Copyright (C) 2004 The Regents of the University of California. Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). UCRL-CODE-217948.

This file is part of SLURM, a resource management program. For details, see <http://www.llnl.gov/linux/slurm/>.

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.

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.

SEE ALSO

slurm_allocate_resources(3), slurm_job_step_create(3), slurm_kill_job(3), slurm_get_errno(3), slurm_perror(3), slurm_strerror(3), srun(1)