SYNTAX

#include <slurm/slurm.h>

int slurm_allocate_resources (
       job_desc_msg_t *job_desc_msg_ptr,

       resource_allocation_response_msg_t **slurm_alloc_msg_pptr

);

resource_allocation_response_msg_t *slurm_allocate_resources_blocking (
       job_desc_msg_t *job_desc_msg_ptr,

       time_t timeout, void (*pending_callback)(uint32_t job_id)

);

allocation_msg_thread_t *slurm_allocation_msg_thr_create (
       uint16_t *port,

       slurm_allocation_callbacks_t *callbacks

);

void *slurm_allocation_msg_thr_destroy (
       allocation_msg_thread_t *slurm_alloc_msg_thr_ptr

);

int slurm_allocation_lookup {
       uint32_t jobid,

       resource_allocation_response_msg_t **slurm_alloc_msg_pptr

);

int slurm_allocation_lookup_lite {
       uint32_t jobid,

       resource_allocation_response_msg_t **slurm_alloc_msg_pptr

);

int slurm_confirm_allocation (
       old_job_alloc_msg_t *old_job_desc_msg_ptr,

       resource_allocation_response_msg_t **slurm_alloc_msg_pptr

);

void slurm_free_resource_allocation_response_msg (
       resource_allocation_response_msg_t *slurm_alloc_msg_ptr

);

void slurm_free_submit_response_response_msg (
       submit_response_msg_t *slurm_submit_msg_ptr

);

void slurm_init_job_desc_msg (
       job_desc_msg_t *job_desc_msg_ptr

);

int slurm_job_will_run (
       job_desc_msg_t *job_desc_msg_ptr

);

int slurm_job_will_run2 (
       job_desc_msg_t *job_desc_msg_ptr,

       will_run_response_msg_t **will_run_resp

);

int slurm_read_hostfile (
       char *filename, int n

);

int slurm_submit_batch_job (
       job_desc_msg_t *job_desc_msg_ptr,

       submit_response_msg_t **slurm_submit_msg_pptr

);

ARGUMENTS

job_desc_msg_ptr

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

callbacks

Specifies the pointer to a allocation callbacks structure. See slurm.h for full details on the data structure's contents.

old_job_desc_msg_ptr

Specifies the pointer to a description of an existing job. See slurm.h for full details on the data structure's contents.

slurm_alloc_msg_pptr

Specifies the double pointer to the structure to be created and filled with a description of the created resource allocation (job): job ID, list of allocated nodes, processor count per allocated node, etc. See slurm.h for full details on the data structure's contents.

slurm_alloc_msg_ptr

Specifies the pointer to the structure to be created and filled in by the function slurm_allocate_resources, slurm_allocate_resources_blocking, slurm_allocation_lookup, slurm_allocation_lookup_lite, slurm_confirm_allocation, slurm_job_will_run or slurm_job_will_run.

slurm_alloc_msg_thr_ptr

Specifies the pointer to the structure created and returned by the function slurm_allocation_msg_thr_create. Must be destroyed with function slurm_allocation_msg_thr_destroy.

slurm_submit_msg_pptr

Specifies the double pointer to the structure to be created and filled with a description of the created job: job ID, etc. See slurm.h for full details on the data structure's contents.

slurm_submit_msg_ptr

Specifies the pointer to the structure to be created and filled in by the function slurm_submit_batch_job.

will_run_resp

Specifies when and where the specified job descriptor could be started.

DESCRIPTION

slurm_allocate_resources Request a resource allocation for a job. If successful, a job entry is created. Note that if the job's requested node count or time allocation are outside of the partition's limits then a job entry will be created, a warning indication will be placed in the error_code field of the response message, and the job will be left queued until the partition's limits are changed. Always release the response message when no longer required using the function slurm_free_resource_allocation_response_msg. This function only makes the request once. If the allocation is not available immediately the node_cnt variable in the resp will be 0. If you want a function that will block until either an error is received or an allocation is granted you can use the slurm_allocate_resources_blocking function described below.

slurm_allocate_resources_blocking Request a resource allocation for a job. This call will block until the allocation is granted, an error occurs, or the specified timeout limit is reached. The pending_callback parameter will be called if the allocation is not available immediately and the immediate flag is not set in the request. This can be used to get the jobid of the job while waiting for the allocation to become available. On failure NULL is returned and errno is set.

slurm_allocation_msg_thr_create Startup a message handler talking with the controller dealing with messages from the controller during an allocation. Callback functions are declared in the callbacks parameter and will be called when a corresponding message is received from the controller. This message thread is needed to receive messages from the controller about node failure in an allocation and other important messages. Although technically not required, it could be very helpful to inform about problems with the allocation.

slurm_allocation_msg_thr_destroy Shutdown the message handler
 talking with the controller dealing with messages from the controller during
 an allocation.

slurm_confirm_allocation Return detailed information on a specific existing job allocation. OBSOLETE FUNCTION: Use slurm_allocation_lookup instead. This function may only be successfully executed by the job's owner or user root.

slurm_free_resource_allocation_response_msg Release the storage generated in response to a call of the function slurm_allocate_resources, slurm_allocation_lookup, or slurm_allocation_lookup_lite.

slurm_free_submit_response_msg Release the storage generated in response to a call of the function slurm_submit_batch_job.

slurm_init_job_desc_msg Initialize the contents of a job descriptor with default values. Execute this function before issuing a request to submit or modify a job.

slurm_job_will_run Determine if the supplied job description could be executed immediately.

slurm_job_will_run2 Determine when and where the supplied job description can be executed.

slurm_read_hostfile Read a Slurm hostfile specified by "filename". "filename" must contain a list of Slurm NodeNames, one per line. Reads up to "n" number of hostnames from the file. Returns a string representing a hostlist ranged string of the contents of the file. This is a helper function, it does not contact any Slurm daemons.

slurm_submit_batch_job Submit a job for later execution. Note that if the job's requested node count or time allocation are outside of the partition's limits then a job entry will be created, a warning indication will be placed in the error_code field of the response message, and the job will be left queued until the partition's limits are changed and resources are available. Always release the response message when no longer required using the function slurm_free_submit_response_msg.

RETURN VALUE

On success, zero is returned. On error, -1 is returned, and Slurm error code is set appropriately.

NON-BLOCKING EXAMPLE

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <slurm/slurm.h>
#include <slurm/slurm_errno.h>

int main (int argc, char *argv[])
{
       job_desc_msg_t job_desc_msg;

       resource_allocation_response_msg_t* slurm_alloc_msg_ptr ;

       slurm_init_job_desc_msg( &job_desc_msg );

       job_desc_msg. name = ("job01 ");

       job_desc_msg. job_min_memory = 1024;

       job_desc_msg. time_limit = 200;

       job_desc_msg. min_nodes = 400;

       job_desc_msg. user_id = getuid();

       job_desc_msg. group_id = getgid();

       if (slurm_allocate_resources(&job_desc_msg,

        &slurm_alloc_msg_ptr)) {

               slurm_perror ("slurm_allocate_resources error");

               exit (1);

       }

       printf ("Allocated nodes %s to job_id %u\n",

        slurm_alloc_msg_ptr->node_list,

        slurm_alloc_msg_ptr->job_id );

       if (slurm_kill_job(slurm_alloc_msg_ptr->job_id, SIGKILL, 0)) {

               printf ("kill errno %d\n", slurm_get_errno());

               exit (1);

       }

       printf ("canceled job_id %u\n",

        slurm_alloc_msg_ptr->job_id );

       slurm_free_resource_allocation_response_msg(

                       slurm_alloc_msg_ptr);

       exit (0);

}

BLOCKING EXAMPLE

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <slurm/slurm.h>
#include <slurm/slurm_errno.h>

int main (int argc, char *argv[])
{
       job_desc_msg_t job_desc_msg;

       resource_allocation_response_msg_t* slurm_alloc_msg_ptr ;

       slurm_init_job_desc_msg( &job_desc_msg );

       job_desc_msg. name = ("job01 ");

       job_desc_msg. job_min_memory = 1024;

       job_desc_msg. time_limit = 200;

       job_desc_msg. min_nodes = 400;

       job_desc_msg. user_id = getuid();

       job_desc_msg. group_id = getgid();

       if (!(slurm_alloc_msg_ptr =

        slurm_allocate_resources_blocking(&job_desc_msg, 0, NULL))) {

               slurm_perror ("slurm_allocate_resources_blocking error");

               exit (1);

       }

       printf ("Allocated nodes %s to job_id %u\n",

        slurm_alloc_msg_ptr->node_list,

        slurm_alloc_msg_ptr->job_id );

       if (slurm_kill_job(slurm_alloc_msg_ptr->job_id, SIGKILL, 0)) {

               printf ("kill errno %d\n", slurm_get_errno());

               exit (1);

       }

       printf ("canceled job_id %u\n",

        slurm_alloc_msg_ptr->job_id );

       slurm_free_resource_allocation_response_msg(

                       slurm_alloc_msg_ptr);

       exit (0);

}

NOTE

These functions are included in the libslurm library, which must be linked to your process for use (e.g. "cc -lslurm myprog.c").

COPYING

Copyright (C) 2010-2014 SchedMD LLC. Copyright (C) 2002-2006 The Regents of the University of California. Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). CODE-OCEC-09-009. All rights reserved.

This file is part of Slurm, a resource management program. For details, see <http://slurm.schedmd.com/>.

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.