Pre-Alpha SLURM API for DPCS
Kevin Tew
June 17, 2002

Necessary include files
<slurm.h>

All interaction with slurm consists of structured messages
All messages returned to a double pointer **, and must be freed by calling the corresponding free function

---------------------------
API Layer init/destroy functions
---------------------------
int slurm_set_api_config ( slurm_protocol_config_t * slurm_api_conf )
	Sets the current api configuration

slurm_protocol_config_t * slurm_get_api_config ( )
	Returns the current api configuration

int slurm_set_default_controllers ( char * primary_controller_hostname , char *
secondary_controller_hostname, uint16_t pri_port , uint16_t sec_port )
	This will set the default controllers' addresses and ports.  This is
the minimal amount of initialization that must occur before using the api
functions

---------------------------
INFO Message functions
---------------------------
For all of the following are informational calls, if update_time is equal to the last time changes where made, nothing is returned.  Otherwise all the node, job, or partition records are returned.

int slurm_load_jobs (time_t update_time, job_info_msg_t **job_info_msg_pptr)
	Returns a job_info_msg_t that contains an array of job_table records

int slurm_load_node (time_t update_time, node_info_msg_t **node_info_msg_pptr)
	Returns a node_info_msg_t that contains an array of node_table records

int slurm_load_partitions (time_t update_time, partition_info_msg_t **partition_info_msg_pptr)
	Returns a partition_info_msg_t that contains an array of partition_table records


---------------------------
JOB Allocation functions
---------------------------
Once a job_desc_msg_t structure has been declared it must first be initialized by the following function before it is used.
void slurm_init_job_desc_msg ( job_desc_msg_t * job_desc_msg ) ;

int slurm_submit_batch_job ( job_desc_msg_t * job_desc_msg )
Used to submit a batch/script job

int slurm_will_job_run ( job_desc_msg_t * job_desc_msg , job_allocation_response_msg_t ** job_alloc_msg )
Returns success if the resources are available immediately to launch the job

int slurm_allocate_resources (job_desc_msg_t * job_desc_msg , job_allocation_response_msg_t ** job_alloc_msg , int immediately )
Blocks until resources are allocated.  If the immediate flag is set, the job will either allocate immediately or return a failure code if resources are not available..


---------------------------
JOB Cancel function
---------------------------
int slurm_cancel_job ( uint32_t job_id )
	the job id of the job to cancel.



---------------------------
Error Code Functions
---------------------------
Slurm Functions will return -1 on error and will provide detailed error information using the following functions

	int slurm_get_errno () 
	char * slurm_strerror ( int errno )



---------------------------
Free Functions
---------------------------
void slurm_free_job_allocation_response_msg ( job_allocation_response_msg_t * msg ) ;
void slurm_free_job_desc_msg ( job_desc_msg_t * msg ) ;

void slurm_free_job_info ( job_info_msg_t * msg ) ;
void slurm_free_job_table ( job_table_t * job ) ;

void slurm_free_partition_info ( partition_info_msg_t * msg ) ;
void slurm_free_partition_table ( partition_table_t * part ) ;

void slurm_free_node_info ( node_info_msg_t * msg ) ;
void slurm_free_node_table ( node_table_t * node ) ;



---------------------------
Message Structure definitions
---------------------------
SEE src/common/slurm_protocol_defs.h for the latest structure.

typedef struct slurm_job_allocation_response_msg
{
	uint32_t job_id;
	char* node_list;
} job_allocation_response_msg_t ;



typedef struct job_desc_msg {    /* Job descriptor for submit, allocate, and update requests */
	uint16_t contiguous;    /* 1 if job requires contiguous nodes, 0 otherwise,
				 * default=0 */
	char *features;         /* comma separated list of required features, default NONE */
	char *groups;           /* comma separated list of groups the user can access,
				 * default set output of "/usr/bin/groups" by API,
				 * can only be set if user is root */
	uint32_t job_id;        /* job ID, default set by SLURM */
	char *name;             /* name of the job, default "" */
	void *partition_key;    /* root key to submit job, format TBD, default NONE */
	uint32_t min_procs;     /* minimum processors required per node, default=0 */
	uint32_t min_memory;    /* minimum real memory required per node, default=0 */
	uint32_t min_tmp_disk;  /* minimum temporary disk required per node, default=0 */
	char *partition;        /* name of requested partition, default in SLURM config */
	uint32_t priority;      /* relative priority of the job, default set by SLURM,
				 * can only be explicitly set if user is root, maximum
				 *                                  * value is #fffffffe */
	char *req_nodes;        /* comma separated list of required nodes, default NONE */
	char *job_script;       /* pathname of required script, default NONE */
	uint16_t shared;        /* 1 if job can share nodes with other jobs, 0 otherwise,
				 * default in SLURM configuration */
	uint32_t time_limit;    /* maximum run time in minutes, default is partition
				 * limit as defined in SLURM configuration, maximum
				 *                                  * value is #fffffffe */
	uint32_t num_procs;     /* number of processors required by job, default=0 */
	uint32_t num_nodes;     /* number of nodes required by job, default=0 */
	uint32_t dist;    
	uint32_t procs_per_task;   
	uint32_t user_id;       /* set only if different from current UID, default set
				 * to UID by API, can only be set if user is root */
} job_desc_msg_t ;

struct job_table {
	uint32_t job_id;	/* job ID */
	char *name;		/* name of the job */
	uint32_t user_id;	/* user the job runs as */
	uint16_t job_state;	/* state of the job, see enum job_states */
	uint32_t time_limit;	/* maximum run time in minutes or INFINITE */
	time_t start_time;	/* time execution begins, actual or expected*/
	time_t end_time;	/* time of termination, actual or expected */
	uint32_t priority;	/* relative priority of the job */
	char *nodes;		/* comma delimited list of nodes allocated to job */
	int *node_inx;		/* list index pairs into node_table for *nodes:
				   start_range_1, end_range_1, start_range_2, .., -1  */
	char *partition;	/* name of assigned partition */
	uint32_t num_procs;	/* number of processors required by job */
	uint32_t num_nodes;	/* number of nodes required by job */
	uint16_t shared;	/* 1 if job can share nodes with other jobs */
	uint16_t contiguous;	/* 1 if job requires contiguous nodes */
	uint32_t min_procs;	/* minimum processors required per node */
	uint32_t min_memory;	/* minimum real memory required per node */
	uint32_t min_tmp_disk;	/* minimum temporary disk required per node */
	char *req_nodes;	/* comma separated list of required nodes */
	int *req_node_inx;	/* list index pairs into node_table for *req_nodes:
				   start_range_1, end_range_1, start_range_2, .., -1  */
	char *features;		/* comma separated list of required features */
	char *job_script;	/* pathname of required script */
};
typedef struct job_table job_table_t ;

typedef struct job_info_msg {
	uint32_t last_update;
	uint32_t record_count;
	job_table_t * job_array;
} job_info_msg_t ;

struct part_table {
        char *name;             /* name of the partition */
        uint32_t max_time;      /* minutes or INFINITE */
        uint32_t max_nodes;     /* per job or INFINITE */
        uint32_t total_nodes;   /* total number of nodes in the partition */
        uint32_t total_cpus;    /* total number of cpus in the partition */
        uint16_t default_part;  /* 1 if this is default partition */
        uint16_t key;           /* 1 if slurm distributed key is required for use  */
        uint16_t shared;        /* 1 if job can share nodes, 2 if job must share nodes */
        uint16_t state_up;      /* 1 if state is up, 0 if down */
        char *nodes;            /* comma delimited list names of nodes in partition */
        int *node_inx;          /* list index pairs into node_table:
                                   start_range_1, end_range_1, start_range_2, .., -1  */
        char *allow_groups;     /* comma delimited list of groups, null indicates all */
} ;
typedef struct part_table partition_table_t ;

typedef struct partition_info_msg {
	uint32_t last_update;
	uint32_t record_count;
	partition_table_t * partition_array;
} partition_info_msg_t ;

struct node_table {
	char *name;		/* node name */
	uint16_t node_state;	/* enum node_states, ORed with STATE_NO_RESPOND if down */
	uint32_t cpus;		/* configured count of cpus running on the node */
	uint32_t real_memory;	/* configured megabytes of real memory on the node */
	uint32_t tmp_disk;	/* configured megabytes of total disk in TMP_FS */
	uint32_t weight;	/* arbitrary priority of node for scheduling work on */
	char *features;		/* arbitrary list of features associated with a node */
	char *partition;	/* name of partition node configured to */
};
typedef struct node_table node_table_t ;
typedef struct node_table node_table_msg_t ;

typedef struct node_info_msg {
	uint32_t last_update;
	uint32_t record_count;
	node_table_t * node_array;
} node_info_msg_t ;


