tm (3) - Linux Manuals

tm: task management API

NAME

tm_init, tm_nodeinfo, tm_poll, tm_notify, tm_spawn, tm_kill, tm_obit, tm_taskinfo, tm_atnode, tm_rescinfo, tm_publish, tm_subscribe, tm_finalize - task management API

SYNOPSIS

#include <tm.h>

int tm_init(info, roots)
void *info;
struct tm_roots *roots;

int tm_nodeinfo(list, nnodes)
tm_node_id ***list;
int *nnodes;

int tm_poll(poll_event, result_event, wait, tm_errno)
tm_event_t poll_event;
tm_event_t *result_event;
int wait;
int *tm_errno;

int tm_notify(tm_signal)
int tm_signal;

int tm_spawn(argc, argv, envp, where, tid, event)
int argc;
char **argv;
char **envp;
tm_node_id where;
tm_task_id *tid;
tm_event_t *event;

int tm_kill(tid, sig, event)
tm_task_id tid;
int sig;
tm_event_t event;

int tm_obit(tid, obitval, event)
tm_task_id tid;
int *obitval;
tm_event_t event;

int tm_taskinfo(node, tid_list, list_size, ntasks, event)
tm_node_id node;
tm_task_id *tid_list;
int list_size;
int *ntasks;
tm_event_t event;

int tm_atnode(tid, node)
tm_task_id tid;
tm_node_id *node;

int tm_rescinfo(node, resource, len, event)
tm_node_id node;
char *resource;
int len;
tm_event_t event;

int tm_publish(name, info, len, event)
char *name;
void *info;
int len;
tm_event_t event;

int tm_subscribe(tid, name, info, len, info_len, event)
tm_task_id tid;
char *name;
void *info;
int len;
int *info_len;
tm_event_t event;

int tm_finalize()

DESCRIPTION

These functions provide a partial implementation of the task management interface part of the PSCHED API. In PBS, MOM provides the task manager functions. This library opens a tcp socket to the MOM running on the local host and sends and receives messages.

The PSCHED Task Management API description used to create this library was commited to paper on Novermber 15, 1996 and was given the version number 0.1. Changes may have taken place since that time which are not reflected in this library.

The API description uses several data types that it purposefully does not define. This was done so an implementaion would not be confined in the way it was written. For this specific work, the definitions follow:

typedef int                     tm_node_id;     /* job-relative node id */
#define TM_ERROR_NODE   ((tm_node_id)-1)

typedef int                     tm_event_t;     /* event handle, > 0 for real events */
#define TM_NULL_EVENT   ((tm_event_t)0)
#define TM_ERROR_EVENT  ((tm_event_t)-1)

typedef unsigned long   tm_task_id;
#define TM_NULL_TASK    (tm_task_id)0

There are a number of error values defined as well: TM_SUCCESS, TM_ESYSTEM, TM_ENOEVENT, TM_ENOTCONNECTED, TM_EUNKNOWNCMD, TM_ENOTIMPLEMENTED, TM_EBADENVIRONMENT, TM_ENOTFOUND.

tm_init() initializes the library by opening a socket to the MOM on the local host and sending a TM_INIT message, then waiting for the reply. The info paramenter has no use and is included to conform with the PSCHED document. The roots pointer will contain valid data after the function returns and has the following structure:

struct  tm_roots {
        tm_task_id      tm_me;
        tm_task_id      tm_parent;
        int             tm_nnodes;
        int             tm_ntasks;
        int             tm_taskpoolid;
        tm_task_id      *tm_tasklist;
};

tm_me

The task id of this calling task.

tm_parent

The task id of the task which spawned this task or TM_NULL_TASK if the calling task is the initial task started by PBS.

tm_nnodes

The number of nodes allocated to the job.

tm_ntasks

This will always be 0 for PBS.

tm_taskpoolid

PBS does not support task pools so this will always be -1.

tm_tasklist

This will be NULL for PBS.

The tm_ntasks, tm_taskpoolid and tm_tasklist fields are not filled with data specified by the PSCHED document. PBS does not support task pools and, at this time, does not return information about current running tasks from tm_init. There is a separate call to get information for current running tasks called tm_taskinfo which is described below. The return value from tm_init be TM_SUCCESS if the library initialization was successful, or an error return otherwise.

tm_nodeinfo() places a pointer to a malloc'ed array of tm_node_id's in the pointer pointed at by list. The order of the tm_node_id's in list is the same as that specified to MOM in the "exec_host" attribute. The int pointed to by nnodes contains the number of nodes allocated to the job. This is information that is returned during initialization and does not require communication with MOM. If tm_init has not been called, TM_ESYSTEM is returned, otherwise TM_SUCCESS is returned.

tm_poll() is the function which will retrieve information about the task management system to locations specified when other routines request an action take place. The bookkeeping for this is done by generating an event for each action. When the task manager (MOM) sends a message that an action is complete, the event is reported by tm_poll and information is placed where the caller requested it. The argument poll_event is meant to be used to request a specific event. This implementation does not use it and it must be set to TM_NULL_EVENT or an error is returned. Upon return, the argument result_event will contain a valid event number or TM_ERROR_EVENT on error. If wait is zero and there are no events to report, result_event is set to TM_NULL_EVENT. If wait is non-zero an there are no events to report, the function will block waiting for an event. If no local error takes place, TM_SUCCESS is returned. If an error is reported by MOM for an event, then the argument tm_errno will be set to an error code.

tm_notify() is described in the PSCHED documentation, but is not implemented for PBS yet. It will return TM_ENOTIMPLEMENTED.

tm_spawn() sends a message to MOM to start a new task. The node id of the host to run the task is given by where. The parameters argc, argv and envp specify the program to run and its arguments and environment very much like exec(). The full path of the program executable must be given by argv[0] and the number of elements in the argv array is given by argc. The array envp is NULL terminated. The argument event points to a tm_event_t variable which is filled in with an event number. When this event is returned by tm_poll , the tm_task_id pointed to by tid will contain the task id of the newly created task. In addition, the tid is available to the process in the PBS_TASKNUM environment variable. Similarly, the node number is in the PBS_NODENUM variable and the cpu number is in the PBS_VNODENUM variable.

tm_kill() sends a signal specified by sig to the task tid and puts an event number in the tm_event_t pointed to by event.

tm_obit() creates an event which will be reported when the task tid exits. The int pointed to by obitval will contain the exit value of the task when the event is reported.

tm_taskinfo() returns the list of tasks running on the node specified by node. The PSCHED documentation mentions a special ability to retrieve all tasks running in the job. This is not supported by PBS. The argument tid_list points to an array of tm_task_id's which contains list_size elements. Upon return, event will contain an event number. When this event is polled, the int pointed to by ntasks will contain the number of tasks running on the node and the array will be filled in with tm_task_id's. If ntasks is greater than list_size, only list_size tasks will be returned.

tm_atnode() will place the node id where the task tid exists in the tm_node_id pointed to by node.

tm_rescinfo() makes a request for a string specifying the resources available on a node given by the argument node. The string is returned in the buffer pointed to by resource and is terminated by a NUL character unless the number of characters of information is greater than specified by len. The resource string PBS returns is formated as follows:

A space separated set of strings from the uname system call followed by a colon (:). The order of the strings is sysname, nodename, release, version, machine.

A comma spearated set of strings giving the components of the "Resource_List" attribute of the job. Each component has the resource name, an equal sign, and the limit value.

For example, a return for a task running on an SGI workstation might look like:

IRIX golum 6.2 03131015 IP22:cput=20:00,mem=400kb

tm_publish() causes len bytes of information pointed at by info to be sent to the local MOM to be saved under the name given by name.

tm_subscribe() returns a copy of the information named by name for the task given by tid. The argument info points to a buffer of size len where the information will be returned. The argument info_len will be set with the size of the published data. If this is larger than the supplied buffer, the data will have been truncated.

tm_finalize() may be called to free any memory in use by the library and close the connection to MOM.