Provided by: gridengine-drmaa-dev_8.1.9+dfsg-7build1_amd64 bug

NAME

       drmaa_synchronize,   drmaa_wait,  drmaa_wifexited,  drmaa_wexitstatus,  drmaa_wifsignaled,
       drmaa_wtermsig, drmaa_wcoredump, drmaa_wifaborted - Waiting for jobs to finish

SYNOPSIS

       #include "drmaa.h"

       int drmaa_synchronize(
              const char *job_ids[],
              signed long timeout,
              int dispose,
              char *error_diagnosis,
              size_t error_diag_len
       );

       int drmaa_wait(
              const char *job_id,
              char *job_id_out,
              size_t job_id_out_len,
              int *stat,
              signed long timeout,
              drmaa_attr_values_t **rusage,
              char *error_diagnosis,
              size_t error_diagnois_len
       );

       int drmaa_wifaborted(
              int *aborted,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
       );

       int drmaa_wifexited(
              int *exited,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
       );

       int drmaa_wifsignaled(
              int *signaled,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
       );

       int drmaa_wcoredump(
              int *core_dumped,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
       );

       int drmaa_wexitstatus(
              int *exit_status,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
       );

       int drmaa_wtermsig(
              char *signal,
              size_t signal_len,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
       );

DESCRIPTION

       The drmaa_synchronize() function blocks the calling thread until  all  jobs  specified  in
       job_ids     have     failed     or     finished    execution.    If    job_ids    contains
       'DRMAA_JOB_IDS_SESSION_ALL', then this function waits for all jobs submitted  during  this
       DRMAA session. The job_ids pointer array must be NULL terminated.

       To  prevent blocking indefinitely in this call, the caller may use the timeout, specifying
       how many seconds to wait for this call to complete before timing out.  The  special  value
       DRMAA_TIMEOUT_WAIT_FOREVER  can  be  used  to  wait indefinitely for a result. The special
       value DRMAA_TIMEOUT_NO_WAIT can be used to return immediately.  If the call  exits  before
       timeout  seconds,  all the specified jobs have completed or the calling thread received an
       interrupt.  In both cases, the return code is DRMAA_ERRNO_EXIT_TIMEOUT.

       The dispose parameter specifies how to treat reaping information.  If  '0'  is  passed  to
       this parameter, job finish information will still be available when drmaa_wait(3) is used.
       If '1' is passed, drmaa_wait(3) will be unable to access this job's finish information.

   drmaa_wait()
       The drmaa_wait() function blocks  the  calling  thread  until  a  job  fails  or  finishes
       execution.   This  routine  is  modeled  on  the  wait4(3) routine.  If the special string
       'DRMAA_JOB_IDS_SESSION_ANY' is passed as job_id, this routine will wait for any  job  from
       the  session.  Otherwise  the job_id must be the job identifier of a job or array job task
       that was submitted during the session.

       To prevent blocking indefinitely in this call, the caller may use timeout, specifying  how
       many  seconds  to  wait  for  this  call  to complete before timing out. The special value
       DRMAA_TIMEOUT_WAIT_FOREVER can be to wait indefinitely for a  result.  The  special  value
       DRMAA_TIMEOUT_NO_WAIT can be used to return immediately.  If the call exits before timeout
       seconds have passed, all the specified jobs have completed or the calling thread  received
       an interrupt.  In both cases, the return code is DRMAA_ERRNO_EXIT_TIMEOUT.

       The routine reaps jobs on a successful call, so any subsequent calls to drmaa_wait(3) will
       fail returning a DRMAA_ERRNO_INVALID_JOB error, meaning that  the  job  has  already  been
       reaped.   This  error  is the same as if the job were unknown. Returning due to an elapsed
       timeout or an interrupt does not cause the job information to be reaped.  This means that,
       in this case, it is possible to issue drmaa_wait(3) multiple times for the same job_id.

       If  job_id_out is not a null pointer, then on return from a successful drmaa_wait(3) call,
       up to job_id_out_len characters from the  job  id  of  the  failed  or  finished  job  are
       returned.

       If  stat  is  not a null pointer, then on return from a successful drmaa_wait(3) call, the
       status of the job is stored in the integer pointed to by stat.  stat indicates whether job
       failed or finished and other information. The information encoded in the integer value can
       be   accessed   via   drmaa_wifaborted(3),    drmaa_wifexited(3),    drmaa_wifsignaled(3),
       drmaa_wcoredump(3), drmaa_wexitstatus(3), and drmaa_wtermsig(3).

       If  rusage  is  not a null pointer, then on return from a successful drmaa_wait(3) call, a
       summary of the  resources used by the terminated job  is  returned  in  form  of  a  DRMAA
       values   string   vector.  The  entries in the DRMAA values string vector can be extracted
       using drmaa_get_next_attr_value(3).  Each string returned by  drmaa_get_next_attr_value(3)
       will  be  of  the  format  name=value,  where  name  and  value specify name and amount of
       resources consumed by the job, respectively.  See accounting(5) for an explanation of  the
       resource information.

   drmaa_wifaborted()
       The  drmaa_wifaborted()  function  evaluates into the integer pointed to by aborted a non-
       zero value if stat was returned from a job that ended before entering the running state.

   drmaa_wifexited()
       The drmaa_wifexited() function evaluates into the integer pointed to by exited a  non-zero
       value  if  stat  was  returned  from a job that terminated normally. A zero value can also
       indicate that although the job has terminated normally, an exit status is  not  available,
       or   that   it  is  not  known  whether  the  job  terminated  normally.   In  both  cases
       drmaa_wexitstatus(3) will not provide exit status information. A non-zero  value  returned
       in   exited   indicates   more   detailed   diagnosis   can   be   provided  by  means  of
       drmaa_wifsignaled(3), drmaa_wtermsig(3) and drmaa_wcoredump(3).

   drmaa_wifsignaled()
       The drmaa_wifsignaled() function evaluates into the integer pointed to by signaled a  non-
       zero  value if stat was returned for a job that terminated due to the receipt of a signal.
       A zero value can also indicate that although the job has terminated due to the receipt  of
       a  signal,  the signal is not available, or it is not known whether the job terminated due
       to the receipt of a signal. In  both  cases  drmaa_wtermsig(3)  will  not  provide  signal
       information.  A  non-zero  value  returned in signaled indicates signal information can be
       retrieved by means of drmaa_wtermsig(3).

   drmaa_wcoredump()
       If  drmaa_wifsignaled(3)  returned  a  non-zero  value  in  the  signaled  parameter,  the
       drmaa_wcoredump() function evaluates into the integer pointed to by core_dumped a non-zero
       value if a core image of the terminated job was created.

   drmaa_wexitstatus()
       If  drmaa_wifexited(3)  returned  a  non-zero  value  in   the   exited   parameter,   the
       drmaa_wexitstatus()  function  evaluates into the integer pointed to by exit_code the exit
       code that the job passed to exit(2) or the value that  the  child  process  returned  from
       main.

   drmaa_wtermsig()
       If  drmaa_wifsignaled(3)  returned  a  non-zero  value  in  the  signaled  parameter,  the
       drmaa_wtermsig() function evaluates into signal up to signal_len characters  of  a  string
       representation  of the signal that caused the termination of the job. For signals declared
       by POSIX.1, the symbolic names are returned (e.g.,  SIGABRT,  SIGALRM).  For  signals  not
       declared by POSIX, any other string may be returned.

ENVIRONMENTAL VARIABLES

       SGE_ROOT       Specifies the location of the Grid Engine standard configuration files.

       SGE_CELL       If  set,  specifies  the  default Grid Engine cell to be used. To address a
                      Grid Engine cell Grid Engine uses (in the order of precedence):

                             The name of the cell specified in the environment variable SGE_CELL,
                             if it is set.

                             The name of the default cell, i.e. default.

       SGE_DEBUG_LEVEL
                      If  set,  specifies  that debug information should be written to stderr. In
                      addition the level of detail in which debug  information  is  generated  is
                      defined.

       SGE_QMASTER_PORT
                      If  set,  specifies  the  tcp  port  on which sge_qmaster(8) is expected to
                      listen for communication requests.  Most installations will use a  services
                      map entry instead to define that port.

RETURN VALUES

       Upon     successful     completion,     drmaa_run_job(),     drmaa_run_bulk_jobs(),    and
       drmaa_get_next_job_id() return DRMAA_ERRNO_SUCCESS. Other values indicate an error.  Up to
       error_diag_len  characters  of error related diagnosis information is then provided in the
       buffer error_diagnosis.

ERRORS

       The    drmaa_synchronize(),    drmaa_wait(),    drmaa_wifexited(),    drmaa_wexitstatus(),
       drmaa_wifsignaled(), drmaa_wtermsig(), drmaa_wcoredump(), and drmaa_wifaborted() functions
       can fail with:

       DRMAA_ERRNO_INTERNAL_ERROR
              Unexpected or internal DRMAA error, like system call failure, etc.

       DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
              Could not contact DRM system for this request.

       DRMAA_ERRNO_AUTH_FAILURE
              The specified request is not processed successfully due to authorization failure.

       DRMAA_ERRNO_INVALID_ARGUMENT
              The input value for an argument is invalid.

       DRMAA_ERRNO_NO_ACTIVE_SESSION
              Failed because there is no active session.

       DRMAA_ERRNO_NO_MEMORY
              Failed allocating memory.

       The drmaa_synchronize() and drmaa_wait() functions can fail with:

       DRMAA_ERRNO_EXIT_TIMEOUT
              Time-out condition.

       DRMAA_ERRNO_INVALID_JOB
              The job specified by the does not exist.

       The drmaa_wait() can fail with:

       DRMAA_ERRNO_NO_RUSAGE
              This error code is returned by drmaa_wait() when a job has finished but  no  rusage
              and stat data could be provided.

SEE ALSO

       drmaa_submit(3).