= 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 [wiki:bgas-user:bgas-manpages:jb_execv 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.