ls_rwait

Collects the status of a remote task started by ls_rtask or ls_rtaske.

ls_rwait collects the status of a remote child (task) that has been started by ls_rtask or ls_rtaske. This call is similar to the UNIX wait3() call, except that the child is located on a remote host.

If a remote child's status is successfully obtained, then the remote task ID (which is returned by an earlier ls_rtask or ls_rtaske call) is returned. Also, if status is not NULL, the status of the exited child is stored in the structure pointed to by status. If ru is not NULL, and the remote child's machine supports the rusage structure in its wait3() call, the resource usage information of the exited child is stored in the structure pointed to by ru. Only the ru_utime and ru_stime fields are set in the structure if the remote child's machine does not support the rusage structure in the wait3() call. If the remote child is run on a different platform than the parent, then only the fields in the resource structure that are common between the two platforms are filled in (the rusage structure is not identical across all platforms). If the child runs on a 64-bit machine, and the parent runs on a 32-bit machine, each of the values in the rusage structure that will overflow on a 32-bit machine are set to LONG_MAX.

The ls_rwait call are automatically restarted when the parent receives a signal while awaiting termination of a remote child process, unless the SV_INTERRUPT bit has been set for the signal (see sigaction()).

Use the blocking mode of ls_rwait with care. If there are both local and remote children, ls_rwait take care only of remote children; none of them will return even though a local child has exited. In such cases, you can call wait(), ls_rwait and/or ls_rwaittid via signal handlers (for SIGCHLD and SIGUSR1, respectively) to process local and remote children.

When a remote child terminates, SIGUSR1 is sent to the parent process. Thus, ls_rwait is typically called from inside the SIGUSR1 signal handler of the parent process.

Any program using these routines must call ls_initrex first.

Any program using these routines must be setuid to root if LSF_AUTH is not defined in the lsf.conf file.

The remote file operations make use of a Remote File Server on the remote host. When this RFS shuts down, its status will be reported to its client. The client should ignore this status.

#include <sys/types.h>
#include <sys/wait.h>
#include <sys/time.h>
#include <sys/resource.h>
#include <lsf/lsf.h>

int ls_rwait(LS_WAIT_T *status, int options, struct rusage *ru)

Parameters:

	*status	return_values_waittid
	options	If specified as 0, and there is at least one remote child, then the calling host is blocked until a remote child exits. If options is specified to be WNOHANG, the routine checks for any exited (remote) child and returns immediately. The options parameter may be extended to provide more options in the future.
	*ru	The structure where the resource usage information of the exited child is stored.

Data Structures:

none

Define Statements:

return_values_waittid

Returns:

char:remote task ID
The function was successful.

int:-1
Function failed.

Errors:

If the function fails, lserrno is set to indicate the error.

Equivalent line commands:

none

Files:

${LSF_ENVDIR:-/etc}/lsf.conf

See also:

ls_rwaittid

ls_rtask

ls_rtaske