drmaa_wait(3)

💖 drmaa_wait(3) — Grid Engine DRMAA 💖

okay bestie, sit down, hydrate, because we're about to talk about waiting for your jobs to finish and honestly? it's giving main character energy. this is the Grid Engine DRMAA family of functions: drmaa_synchronize, drmaa_wait, and the whole little squad of status-decoders that go with them. 🦋

---

✨ NAME ✨

drmaa_synchronize, drmaa_wait, drmaa_wifexited, drmaa_wexitstatus, drmaa_wifsignaled, drmaa_wtermsig, drmaa_wcoredump, drmaa_wifaborted — waiting for jobs to finish. that's it. that's the whole vibe. ⏳

---

🌸 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
);

ngl the drmaa_wait prototype really said error_diagnois_len and we're keeping it exactly as-is. no editing, no cap. 💅

---

🎀 DESCRIPTION 🎀

so drmaa_synchronize() blocks the calling thread until every single job listed in job_ids has either failed or finished running. if job_ids contains 'DRMAA_JOB_IDS_SESSION_ALL', bestie, it's waiting on every job submitted during this DRMAA session. and the job_ids pointer array? it must be NULL terminated. no exceptions. 🙅

to keep you from being stuck there forever (we've all been there), the caller can use timeout — that's how many seconds to wait before this call gives up. the special value DRMAA_TIMEOUT_WAIT_FOREVER means wait forever for a result, and DRMAA_TIMEOUT_NO_WAIT means return immediately. if the call exits before timeout seconds, either all the specified jobs have completed or the calling thread caught an interrupt — and in both cases the return code is DRMAA_ERRNO_EXIT_TIMEOUT.

the dispose parameter decides how reaping info gets treated:

• if '0' is passed, the job finish info 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. gone. poof. 💀

💫 drmaa_wait()

drmaa_wait() blocks the calling thread until a job fails or finishes execution. this routine is modeled on the wait4(3) routine, iykyk. if the special string 'DRMAA_JOB_IDS_SESSION_ANY' is passed as job_id, it waits for any job from the session. otherwise job_id has to be the job identifier of a job or array job task that was submitted during the session.

to stop it from blocking forever, the caller can use timeout — how many seconds to wait before timing out. DRMAA_TIMEOUT_WAIT_FOREVER can be used to wait indefinitely for a result. DRMAA_TIMEOUT_NO_WAIT returns immediately. if the call exits before timeout seconds have passed, either all the specified jobs have completed or the calling thread got an interrupt — both cases give you DRMAA_ERRNO_EXIT_TIMEOUT.

now here's the part where you gotta pay attention 🫶 this routine reaps jobs on a successful call, so any later call to drmaa_wait(3) will fail with a DRMAA_ERRNO_INVALID_JOB error, meaning that job has already been reaped. and that error is the same as if the job were unknown. but if you returned due to an elapsed timeout or an interrupt, the job information is not reaped — which means in that case you can totally issue drmaa_wait(3) multiple times for the same job_id. iconic behavior honestly.

• 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 tells you whether the job failed or finished, plus other info. all that encoded info can be decoded 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 comes back as a DRMAA values string vector. you pull entries out of it with drmaa_get_next_attr_value(3). every string that drmaa_get_next_attr_value(3) hands you is formatted as name=value, where name and value are the name and amount of resources consumed by the job. see accounting(5) for the full explanation of the resource info. 🍓

💫 drmaa_wifaborted()

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

drmaa_wifexited() 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 mean that even though the job terminated normally, an exit status isn't available — or that it's not known whether the job terminated normally. in both of those cases, drmaa_wexitstatus(3) will not provide exit status info. a non-zero value in exited means more detailed diagnosis can come from drmaa_wifsignaled(3), drmaa_wtermsig(3) and drmaa_wcoredump(3). 🔍

💫 drmaa_wifsignaled()

drmaa_wifsignaled() 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 mean that even though the job terminated from a signal, the signal isn't available — or that it's not known whether it terminated from a signal. in both of those cases, drmaa_wtermsig(3) will not provide signal info. a non-zero value in signaled means signal info can be retrieved via drmaa_wtermsig(3). 📡

💫 drmaa_wcoredump()

if drmaa_wifsignaled(3) returned a non-zero value in the signaled parameter, then drmaa_wcoredump() 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, then drmaa_wexitstatus() evaluates into the integer pointed to by exit_code the exit code that the job passed to exit(2), or the value the child process returned from main. 🚪

💫 drmaa_wtermsig()

if drmaa_wifsignaled(3) returned a non-zero value in the signaled parameter, then drmaa_wtermsig() evaluates into signal up to signal_len characters of a string representation of the signal that caused the job's termination. 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 order of precedence):
  1. the name of the cell specified in the environment variable SGE_CELL, if it is set.
  2. the name of the default cell, i.e. default.
• SGE_DEBUG_LEVEL — if set, specifies that debug information should be written to stderr. plus, the level of detail in which debug info is generated is defined by it.
• 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. any other value means error. when that happens, up to error_diag_len characters of error-related diagnosis info are provided in the buffer error_diagnosis. 🩺

---

🔥 ERRORS 🔥

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

• DRMAA_ERRNO_INTERNAL_ERROR — unexpected or internal DRMAA error, like system call failure, etc. 😭
• DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE — could not contact the 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. 💀

and drmaa_synchronize() and drmaa_wait() can also fail with:

• DRMAA_ERRNO_EXIT_TIMEOUT — time-out condition. ⏰
• DRMAA_ERRNO_INVALID_JOB — the job specified by the does not exist.

and drmaa_wait() can also 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).

---

okay that's the whole page bestie, go forth and wait on your jobs with confidence 🫶 this was the SGE 8.1.3pre version of the page, dated $Date: 2004-11-12 15:40:05 $ — yes the date is literally that old and it still ate. mwah. 💋✨