public class SessionImpl extends java.lang.Object implements Session
This class relies on the version 1.0 drmaa shared library.
Session
,
JobTemplateImpl
,
Grid Engine Man PagesDONE, FAILED, HOLD, JOB_IDS_SESSION_ALL, JOB_IDS_SESSION_ANY, QUEUED_ACTIVE, RELEASE, RESUME, RUNNING, SUSPEND, SYSTEM_ON_HOLD, SYSTEM_SUSPENDED, TERMINATE, TIMEOUT_NO_WAIT, TIMEOUT_WAIT_FOREVER, UNDETERMINED, USER_ON_HOLD, USER_SUSPENDED, USER_SYSTEM_ON_HOLD, USER_SYSTEM_SUSPENDED
Modifier and Type | Method and Description |
---|---|
void |
control(java.lang.String jobId,
int action)
Controls a jobs.
|
JobTemplate |
createJobTemplate()
Get a new job template.
|
void |
deleteJobTemplate(JobTemplate jt)
Deallocate a job template.
|
void |
exit()
The exit() method closes the DRMAA session for all threads and must be
called before process termination.
|
java.lang.String |
getContact()
getContact() returns an opaque string containing contact information
related to the current DRMAA session to be used with the init() method.
|
java.lang.String |
getDrmaaImplementation()
The getDrmaaImplementation() method returns a string containing the DRMAA
Java language binding implementation version information.
|
java.lang.String |
getDrmSystem()
The getDRMSystem() method returns a string containing the DRM product and
version information.
|
int |
getJobProgramStatus(java.lang.String jobId)
Get the job programm status.
|
Version |
getVersion()
Returns a Version instance containing the major and minor version numbers
of the DRMAA library.
|
void |
init(java.lang.String contact)
The init() method initializes the Grid Engine DRMAA API library for
all threads of the process and creates a new DRMAA Session.
|
java.util.List |
runBulkJobs(JobTemplate jt,
int start,
int end,
int incr)
The runBulkJobs() method submits a Grid Engine array job very much as
if the qsub option `-t start-end:incr' had been used
with the corresponding attributes defined in the DRMAA JobTemplate,
jt.
|
java.lang.String |
runJob(JobTemplate jt)
The runJob() method submits a Grid Engine job with attributes defined in
the DRMAA JobTemplate jt.
|
void |
synchronize(java.util.List jobIds,
long timeout,
boolean dispose)
Wait until all jobs specified by jobIds have finished
execution.
|
JobInfo |
wait(java.lang.String jobId,
long timeout)
This method will wait for a job with jobId to finish execution
or fail.
|
public void control(java.lang.String jobId, int action) throws DrmaaException
Controls a jobs.
Hold, release, suspend, resume, or kill the job identified by
jobId. If jobId is JOB_IDS_SESSION_ALL
, then
this routine acts on all jobs submitted during this DRMAA session
up to the moment control() is called. To avoid thread races conditions
in multithreaded applications, the DRMAA implementation user should
explicitly synchronize this call with any other job submission or control
calls that may change the number of remote jobs.
The legal values for action and their meanings are:
SUSPEND
: stop the job,RESUME
: (re)start the job,HOLD
: put the job on-hold,RELEASE
: release the hold on the job, andTERMINATE
: kill the job.This method returns once the action has been acknowledged by the DRM system, but it 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 sessions or jobs submitted via native utilities.
If jobId is JOB_IDS_SESSION_ALL
and the control
action fails for one or more jobs, and InternalException will be thrown,
and the state of the jobs in the session will be undefined.
The DRMAA suspend/resume operations are equivalent to the use of the `-s jobid' and `-us jobid' options with qmod. (See the qmod(1) man page.)
The DRMAA hold/release operations are equivalent to the use of qhold and qrls. (See the qhold(1) and qrls(1) man pages.)
The DRMAA terminate operation is equivalent to the use of qdel. (See the qdel(1) man page.)
Only user hold and user suspend can be controled via control(). For affecting system hold and system suspend states the appropriate DRM interfaces must be used.
control
in interface Session
jobId
- The id of the job to controlaction
- the control action to be takenDrmaaException
- May be one of the following:
public void exit() throws DrmaaException
The exit() method does neccessary clean up of the DRMAA session state, including unregistering from the qmaster. If the exit() method is not called, the qmaster will store events for the DRMAA client until the connection times out, causing extra work for the qmaster and comsuming system resources.
Submitted jobs are not affected by the exit() method.
exit
in interface Session
DrmaaException
- May be one of the following:
public java.lang.String getContact()
[name=value[;name=value]*]
,
where name and value are both strings, and the supported
values of name are:
session
- if used, indicates to which session id
to reconnect.Before the init() method has been called, this method will always
return an empty string. After the init() method has been called, this
method will return the set of name=value pairs which represent the
currently active session. The value returned for session
can be used with the init() method to reconnect to the current session
after exit() has been called.
getContact
in interface Session
init(String)
public java.lang.String getDrmSystem()
getDrmSystem
in interface Session
init(String)
public java.lang.String getDrmaaImplementation()
getDrmaaImplementation
in interface Session
init(String)
public int getJobProgramStatus(java.lang.String jobId) throws DrmaaException
Get the job programm status.
Get the program status of the job identified by jobId. The possible values returned from this method are:UNDETERMINED
: process status cannot be determinedQUEUED_ACTIVE
: job is queued and activeSYSTEM_ON_HOLD
: job is queued and in system holdUSER_ON_HOLD
: job is queued and in user holdUSER_SYSTEM_ON_HOLD
: job is queued and in user and
system holdRUNNING
: job is runningSYSTEM_SUSPENDED
: job is system suspendedUSER_SUSPENDED
: job is user suspendedUSER_SYSTEM_SUSPENDED
: job is user and system
suspendedDONE
: job finished normallyFAILED
: job finished, but failed.The DRMAA implementation must always get the status of jobId from 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.
The control method can be used to control job submitted outside of the scope of the DRMAA session as long as the job identifier for the job is known.
getJobProgramStatus
in interface Session
jobId
- the id of the job whose status is to be retrievedDrmaaException
- May be one of the following:
public JobTemplate createJobTemplate() throws DrmaaException
createJobTemplate
in interface Session
DrmaaException
- May be one of the following:
JobTemplate
public void deleteJobTemplate(JobTemplate jt) throws DrmaaException
deleteJobTemplate
in interface Session
jt
- the JobTemplate to deleteDrmaaException
- May be one of the following:
public Version getVersion()
getVersion
in interface Session
Version
public void init(java.lang.String contact) throws DrmaaException
contact is an implementation dependent string which may be used to specify which Grid Engine cell to use. The contact string is composed of a series of name=value pairs separated by semicolons. The supported name=value pairs are:
session
: the id of the session to which to reconnect
If contact is null or empty, the default Grid Engine cell will be used.
Except for the above listed methods, no DRMAA methods may be called before the init() function completes. Any DRMAA method which is called before the init() method completes will throw a NoActiveSessionException. Any additional call to init() by any thread will throw a SessionAlreadyActiveException.
Once init() has been called, it is the responsibility of the developer to ensure that the exit() will be called before the program terminates.
init
in interface Session
contact
- implementation-dependent string that may be used to
specify which DRM system to use.DrmaaException
- May be be one of the following:
getContact()
,
exit()
public java.util.List runBulkJobs(JobTemplate jt, int start, int end, int incr) throws DrmaaException
On success a String array containing job identifiers for each array job task is returned.
runBulkJobs
in interface Session
start
- the starting value for the loop indexend
- the terminating value for the loop indexincr
- the value by which to increment the loop index each iterationjt
- the job template to be used to create the jobDrmaaException
- May be one of the following:
public java.lang.String runJob(JobTemplate jt) throws DrmaaException
runJob
in interface Session
jt
- the job template to be used to create the jobDrmaaException
- May be one of the following:
public void synchronize(java.util.List jobIds, long timeout, boolean dispose) throws DrmaaException
JOB_IDS_SESSION_ALL
,
then this method waits for all jobs submitted during this DRMAA
session up to the moment synchronize() is called. To avoid thread race
conditions in multithreaded applications, the DRMAA implementation user
should explicitly synchronize this call with any other job submission
or control calls that may change the number of remote jobs.
To prevent blocking indefinitely in this call, the caller may use a
timeout specifying how many seconds to block in this call. The value
TIMEOUT_WAIT_FOREVER
may be specified to wait indefinitely
for a result. The value TIMEOUT_NO_WAIT
may be specified to
return immediately if no result is available. 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 ExitTimeException is
thrown. The caller should check system time before and after this call
in order to be sure of how much time has passed.
The dispose parameter specifies how to treat the reaping of the
remote jobs' internal data records, which includes a record of the jobs'
consumption of system resources during their execution and other
statistical information. If this parameter is set to true
,
the DRM will dispose of the jobs' data records at the end of
the synchroniize() call. If set to false
, the data records
will be left for future access via the wait() method.
synchronize
in interface Session
jobIds
- the ids of the jobs to synchronizetimeout
- the maximum number of seconds to waitdispose
- specifies how to treat reaping informationDrmaaException
- May be one of the following:
Session.wait(java.lang.String, long)
public JobInfo wait(java.lang.String jobId, long timeout) throws DrmaaException
JOB_IDS_SESSION_ANY
, is
provided as the jobId, this routine will wait for any job from the
session. This routine is modeled on the wait3 POSIX routine.
The timeout value is used to specify the desired behavior when
a result is not immediately available. The value,
TIMEOUT_WAIT_FOREVER
, may be specified to wait indefinitely
for a result. The value, 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.
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(), synchronize(), control(), or getJobProgramStatus() 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.)
When successful, the resource usage information for the job is
provided as a Map of usage parameter names and their values in the
JobInfo object. The values contain the amount of resources consumed by
the job and are implementation defined. If no resource usage
information is available for the finished job, the resourceUsage
property of the returned JobInfo instance will be null
.
In the 0.5 version of this method, a NoResourceUsageException would be thrown if the target job finished with no resource usage information. In the current implementation, no exception is thrown in that case. Instead, the JobInfo.getResourceUsage() method will return null.
wait
in interface Session
jobId
- the id of the job for which to waittimeout
- the maximum number of seconds to waitDrmaaException
- May be one of the following:
JobInfo
The contents of this file are licensed under the Sun Industry Standards Source License version 1.2.
Copyright 2008, Sun Microsystems, Inc.