def jobStatus(jobId):
"""
returns the program status of the job identified by jobId.
The possible values returned from
this method are:
* `JobState.UNDETERMINED`: process status cannot be determined,
* `JobState.QUEUED_ACTIVE`: job is queued and active,
* `JobState.SYSTEM_ON_HOLD`: job is queued and in system hold,
* `JobState.USER_ON_HOLD`: job is queued and in user hold,
* `JobState.USER_SYSTEM_ON_HOLD`: job is queued and in user and
system hold,
* `JobState.RUNNING`: job is running,
* `JobState.SYSTEM_SUSPENDED`: job is system suspended,
* `JobState.USER_SUSPENDED`: job is user suspended,
* `JobState.DONE`: job finished normally, and
* `JobState.FAILED`: job finished, but failed.
The DRMAA implementation should always get the status of the job from
the DRM system unless the status has already been determined to be
FAILED or DONE and the status has been successfully cached. Terminated
jobs return a FAILED status.
"""
status = c_int()
if isinstance(jobId, str):
jobId = jobId.encode(ENCODING)
c(drmaa_job_ps, jobId, byref(status))
return status_to_string(status.value)
def runJob(jobTemplate):
"""
Submit a job with attributes defined in the job template.
:Parameters:
jobTemplate : JobTemplate
the template representing the job to be run
The returned job identifier is a String identical to that returned
from the underlying DRM system.
"""
jid = create_string_buffer(128)
c(drmaa_run_job, jid, sizeof(jid), jobTemplate)
return jid.value.decode()
def __init__(self, **kwargs):
"""\
Builds a JobTemplate instance.
Attributes can be passed as keyword arguments."""
jt = _ct.pointer(_ct.POINTER(_w.drmaa_job_template_t)())
_h.c(_w.drmaa_allocate_job_template, jt)
self._jt = self._as_parameter_ = jt.contents
try:
for aname in kwargs:
setattr(self, aname, kwargs.get(aname))
except:
self.delete()
raise
def __init__(self, **kwargs):
"""
Builds a JobTemplate instance.
Attributes can be passed as keyword arguments.
"""
jt = pointer(POINTER(drmaa_job_template_t)())
c(drmaa_allocate_job_template, jt)
self._jt = self._as_parameter_ = jt.contents
try:
for aname in kwargs:
setattr(self, aname, kwargs.get(aname))
except:
self.delete()
raise
def synchronize(jobIds, timeout=-1, dispose=False):
"""
Waits until all jobs specified by jobList have finished execution.
:Parameters:
jobIds
If jobIds contains `Session.JOB_IDS_SESSION_ALL`, then this
method waits for all jobs submitted during this DRMAA session up to
the moment synchronize() is called
timeout : int
maximum time (in seconds) to be waited for the completion of a job.
The value `Session.TIMEOUT_WAIT_FOREVER` may be specified to wait
indefinitely for a result. The value `Session.TIMEOUT_NO_WAIT` may
be specified to return immediately if no result is available.
dispose : bool
specifies how to treat the reaping of the remote job's internal
data record, which includes a record of the job's consumption of
system resources during its execution and other statistical
information. If set to True, the DRM will dispose of the job's
data record at the end of the synchronize() call. If set to
False, the data record will be left for future access via the
wait() method. It is the responsibility of the application to
make sure that either `synchronize()` or `wait()`is called for
every job. Not doing so creates a memory leak. Note that calling
synchronize() with dispose set to true flushes all accounting
information for all jobs in the list.
To avoid thread race conditions in multithreaded applications, the
DRMAA implementation user should explicitly synchronize this call with
any other job submission calls or control calls that may change the
number of remote jobs.
If the call exits before the timeout has elapsed, all the jobs have
been waited on or there was an interrupt. If the invocation exits on
timeout, an ExitTimeoutException is thrown. The caller should check
system time before and after this call in order to be sure of how much
time has passed.
"""
if dispose:
d = 1
else:
d = 0
c(drmaa_synchronize, string_vector(jobIds), timeout, d)
def synchronize(jobIds, timeout=-1, dispose=False):
"""
Waits until all jobs specified by jobList have finished execution.
:Parameters:
jobIds
If jobIds contains `Session.JOB_IDS_SESSION_ALL`, then this
method waits for all jobs submitted during this DRMAA session up to
the moment synchronize() is called
timeout : int
maximum time (in seconds) to be waited for the completion of a job.
The value `Session.TIMEOUT_WAIT_FOREVER` may be specified to wait
indefinitely for a result. The value `Session.TIMEOUT_NO_WAIT` may
be specified to return immediately if no result is available.
dispose : bool
specifies how to treat the reaping of the remote job's internal
data record, which includes a record of the job's consumption of
system resources during its execution and other statistical
information. If set to True, the DRM will dispose of the job's
data record at the end of the synchronize() call. If set to
False, the data record will be left for future access via the
wait() method. It is the responsibility of the application to
make sure that either `synchronize()` or `wait()`is called for
every job. Not doing so creates a memory leak. Note that calling
synchronize() with dispose set to true flushes all accounting
information for all jobs in the list.
To avoid thread race conditions in multithreaded applications, the
DRMAA implementation user should explicitly synchronize this call with
any other job submission calls or control calls that may change the
number of remote jobs.
If the call exits before the timeout has elapsed, all the jobs have
been waited on or there was an interrupt. If the invocation exits on
timeout, an ExitTimeoutException is thrown. The caller should check
system time before and after this call in order to be sure of how much
time has passed.
"""
if dispose:
d = 1
else:
d = 0
c(drmaa_synchronize, string_vector(jobIds), timeout, d)
def control(jobId, operation):
"""
Used to hold, release, suspend, resume, or kill the job identified by jobId.
:Parameters:
jobId : string
if jobId is `Session.JOB_IDS_SESSION_ALL` then this routine acts on
all jobs submitted during this DRMAA session up to the moment
control() is called. The legal values for
action and their meanings are
operation : string
possible values are:
`JobControlAction.SUSPEND`
stop the job
`JobControlAction.RESUME`
(re)start the job
`JobControlAction.HOLD`
put the job on-hold
`JobControlAction.RELEASE`
release the hold on the job
`JobControlAction.TERMINATE`
kill the job
To avoid thread races in multithreaded applications, the DRMAA
implementation user should explicitly synchronize this call with
any other job submission calls or control calls that may change
the number of remote jobs.
This method returns once the action has been acknowledged by the DRM
system, but does not necessarily wait until the action has been
completed. Some DRMAA implementations may allow this method to be
used to control jobs submitted external to the DRMAA session, such as
jobs submitted by other DRMAA session in other DRMAA implementations
or jobs submitted via native utilities.
"""
if isinstance(jobId, str):
jobId = jobId.encode(ENCODING)
c(drmaa_control, jobId, string_to_control_action(operation))
def control(jobId, operation):
"""
Used to hold, release, suspend, resume, or kill the job identified by jobId.
:Parameters:
jobId : string
if jobId is `Session.JOB_IDS_SESSION_ALL` then this routine acts on
all jobs submitted during this DRMAA session up to the moment
control() is called. The legal values for
action and their meanings are
operation : string
possible values are:
`JobControlAction.SUSPEND`
stop the job
`JobControlAction.RESUME`
(re)start the job
`JobControlAction.HOLD`
put the job on-hold
`JobControlAction.RELEASE`
release the hold on the job
`JobControlAction.TERMINATE`
kill the job
To avoid thread races in multithreaded applications, the DRMAA
implementation user should explicitly synchronize this call with
any other job submission calls or control calls that may change
the number of remote jobs.
This method returns once the action has been acknowledged by the DRM
system, but does not necessarily wait until the action has been
completed. Some DRMAA implementations may allow this method to be
used to control jobs submitted external to the DRMAA session, such as
jobs submitted by other DRMAA session in other DRMAA implementations
or jobs submitted via native utilities.
"""
if isinstance(jobId, str):
jobId = jobId.encode(ENCODING)
c(drmaa_control, jobId, string_to_control_action(operation))
def wait(jobId, timeout=-1):
"""
Wait for a job with jobId to finish execution or fail.
:Parameters:
`jobId` : str
The job id to wait completion for.
If the special string, `Session.JOB_IDS_SESSION_ANY`, is provided
as the jobId, this routine will wait for any job from the session
`timeout` : float
The timeout value is used to specify the desired behavior when a
result is not immediately available.
The value `Session.TIMEOUT_WAIT_FOREVER` may be specified to wait
indefinitely for a result. The value `Session.TIMEOUT_NO_WAIT` may
be specified to return immediately if no result is
available. Alternatively, a number of seconds may be specified to
indicate how long to wait for a result to become available
This routine is modeled on the wait3 POSIX routine. If the call exits
before timeout, either the job has been waited on successfully or
there was an interrupt. If the invocation exits on timeout, an
`ExitTimeoutException` is thrown. The caller should check system time
before and after this call in order to be sure how much time has
passed. The routine reaps job data records on a successful call, so
any subsequent calls to wait() will fail, throwing an
`InvalidJobException`, meaning that the job's data record has been
already reaped. This exception is the same as if the job were
unknown. (The only case where wait() can be successfully called on a
single job more than once is when the previous call to wait() timed
out before the job finished.)
"""
stat = c_int()
jid_out = create_string_buffer(128)
rusage = pointer(POINTER(drmaa_attr_values_t)())
if isinstance(jobId, str):
jobId = jobId.encode(ENCODING)
c(drmaa_wait, jobId, jid_out, sizeof(jid_out), byref(stat), timeout,
rusage)
res_usage = adapt_rusage(rusage)
exited = c_int()
c(drmaa_wifexited, byref(exited), stat)
aborted = c_int()
c(drmaa_wifaborted, byref(aborted), stat)
signaled = c_int()
c(drmaa_wifsignaled, byref(signaled), stat)
coredumped = c_int()
if exited.value == 0:
c(drmaa_wcoredump, byref(coredumped), stat)
exit_status = c_int()
c(drmaa_wexitstatus, byref(exit_status), stat)
term_signal = create_string_buffer(SIGNAL_BUFFER)
if signaled.value == 1:
c(drmaa_wtermsig, term_signal, sizeof(term_signal), stat)
return JobInfo(jid_out.value.decode(), bool(exited), bool(signaled),
term_signal.value.decode(), bool(coredumped),
bool(aborted), int(exit_status.value), res_usage)
def delete(self):
"""Deallocate the underlying DRMAA job template."""
c(drmaa_delete_job_template, self)
def wait(jobId, timeout=-1):
"""
Wait for a job with jobId to finish execution or fail.
:Parameters:
`jobId` : str
The job id to wait completion for.
If the special string, `Session.JOB_IDS_SESSION_ANY`, is provided
as the jobId, this routine will wait for any job from the session
`timeout` : float
The timeout value is used to specify the desired behavior when a
result is not immediately available.
The value `Session.TIMEOUT_WAIT_FOREVER` may be specified to wait
indefinitely for a result. The value `Session.TIMEOUT_NO_WAIT` may
be specified to return immediately if no result is
available. Alternatively, a number of seconds may be specified to
indicate how long to wait for a result to become available
This routine is modeled on the wait3 POSIX routine. If the call exits
before timeout, either the job has been waited on successfully or
there was an interrupt. If the invocation exits on timeout, an
`ExitTimeoutException` is thrown. The caller should check system time
before and after this call in order to be sure how much time has
passed. The routine reaps job data records on a successful call, so
any subsequent calls to wait() will fail, throwing an
`InvalidJobException`, meaning that the job's data record has been
already reaped. This exception is the same as if the job were
unknown. (The only case where wait() can be successfully called on a
single job more than once is when the previous call to wait() timed
out before the job finished.)
"""
stat = c_int()
jid_out = create_string_buffer(128)
rusage = pointer(POINTER(drmaa_attr_values_t)())
if isinstance(jobId, str):
jobId = jobId.encode(ENCODING)
c(drmaa_wait, jobId, jid_out, sizeof(jid_out), byref(stat), timeout,
rusage)
res_usage = adapt_rusage(rusage)
exited = c_int()
c(drmaa_wifexited, byref(exited), stat)
aborted = c_int()
c(drmaa_wifaborted, byref(aborted), stat)
signaled = c_int()
c(drmaa_wifsignaled, byref(signaled), stat)
coredumped = c_int()
c(drmaa_wcoredump, byref(coredumped), stat)
exit_status = c_int()
c(drmaa_wexitstatus, byref(exit_status), stat)
term_signal = create_string_buffer(SIGNAL_BUFFER)
c(drmaa_wtermsig, term_signal, sizeof(term_signal), stat)
return JobInfo(jid_out.value.decode(), bool(exited), bool(signaled),
term_signal.value.decode(), bool(coredumped),
bool(aborted), int(exit_status.value), res_usage)
def delete(self):
"""Deallocate the underlying DRMAA job template."""
c(drmaa_delete_job_template, self)
