Knowledge Center         Contents    Previous  Next    
Platform Computing Corp.

ls_rwait()

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

DESCRIPTION

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()).

LSLIB defines some new return status values related to load sharing. These values are returned by ls_rwait(). They include:

STATUS_TIMEOUT

Timeout trying to connect to the remote RES.

STATUS_IOERR

The remote task failed with an I/O error.

STATUS_EXCESS

Too many tasks are currently executing.

STATUS_REX_NOMEM

RES failed to allocate memory

STATUS_REX_FATAL

Fatal error, check RES err log

STATUS_REX_CWD

Cannot change to current working directory

STATUS_REX_PTY

RES cannot allocate a pty

STATUS_REX_SP

RES cannot allocate a socket pair

STATUS_REX_FORK

RES failed to fork the task

STATUS_REX_UNKNOWN

Internal error in RES

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 documented in ls_rfs() 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.

SYNOPSIS

#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

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.

RETURN VALUES

character:remote task ID

The function was successful.

integer:-1

Function failed.

ERRORS

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

SEE ALSO

Related APIs

ls_rwaittid()

ls_rtask()

ls_rtaske()

ls_rfs()

Equivalent line command

none

Files

${LSF_ENVDIR-/etc}/lsf.conf


Platform Computing Inc.
www.platform.com
Knowledge Center         Contents    Previous  Next