jb_execv_status

Name

jb_execv_status - polls the state of an IO node process spawned via jb_execv().

Synopsis

#include <mpi.h>
#include "jbcnl.h"

int jb_execv_status( int tag, int* status);

Include with -I/bgsys/local/bgas/jbrt/jbcn/include, link with -L/bgsys/local/bgas/jbrt/jbcn/lib -ljbcn.

Description

If one views jb_execv() as the JBRT analogue of a fork-exec operation, then jb_execv_status() is the JBRT analogue to a

waitpid( pid, &status, WNOHANG);

call with positive first argument. In other words, jb_execv_status() polls the state of an IO node process spawned via jb_execv(). The "tag" argument must be an integer between 1 and 8 and specifies a particular IO node process among the IO node processes spawned by the calling MPI task; therefore it should correspond to the return value of a previous jb_execv() call (see also jb_execv()).

Furthermore, if termination (either by normal exiting or by signal) of the specified process has occurred, jb_execv_status() frees the tag, i.e. "reaps" the associated IO node process. To be precise, the actual reaping of the process, i.e. the releasing of its associated IO node kernel resources, is done by the JBSD independently of any calls to jb_execv_status(); jb_execv_status() only frees its associated compute node resources; therefore not calling jb_execv_status() does not cause the existence of zombie processes on the IO node, it only bars the compute node from spawning additional IO node processes. Note that, unlike waitpid(), jb_execv_status() ignores non-terminating state changes of the specified process (that is, stop or continue signals).

If termination has occurred, "*status" is set to an integer between 0 and 65535 (0xffff) which represents the new IO node process state. This integer can be inspected using the WIFEXITED, WEXITSTATUS and WIFSIGNALED macros, among others. For details, see the manpage for waitpid(); note that usage of any of those macros requires the user to include "sys/wait.h"

Return value

If the specified process has terminated, jb_execv_status() returns the "tag" argument and "*status" is set to a positive integer between 0 and 65535.

If the specified process has not terminated, jb_execv_status() returns 0.

On error, jb_execv_status() returns -1 and "errno" is set.

Errors

ECHILD

The "tag" argument corresponds to a tag which has not been assigned by a prior jb_execv() call.

EINVAL

The "tag" argument does not correspond to a valid tag (i.e. is not an integer between 1 and 8).

Thread safety

jb_execv_status() may be called safely from inside a (POSIX or OpenMP) threaded region. Note that a given tag argument, when used by different threads of the same MPI task, refers to the same job, while a given tag used by different MPI tasks does not. Thus, jb_execv_status() should not be called with the same argument by multiple threads of the same task, and doing so will cause all but one of the jb_execv_status() to fail with ECHILD.