com.sun.grid.drmaa.SessionImpl
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
The SessionImpl provides a DRMAA interface to Grid Engine. This interface is built on top of the DRMAA C binding using JNI. In order to keep the native code as localized as possible, this class also provides native DRMAA services to other classes, such as the JobTemplateImpl.
This class relies on the drmaa shared library.
Session,
JobTemplateImpl,
Grid Engine Man Pages| Field Summary |
| Fields inherited from interface org.ggf.drmaa.Session |
DONE, 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 |
| Method Summary | |
void |
control(java.lang.String jobId,
int action)
Hold, release, suspend, resume, or kill the job identified by jobId. |
JobTemplate |
createJobTemplate()
Get a new job template. |
void |
deleteJobTemplate(JobTemplate jt)
The deleteJobTemplate() method releases all resources associated with the DRMAA JobTemplate. |
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 program status of the job identified by jobId. |
Version |
getVersion()
The getVersion() method returns a Version object 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)
The synchronize() method blocks the calling thread until all jobs specified in jobIds have failed or finished execution. |
JobInfo |
wait(java.lang.String jobId,
long timeout)
The wait() function blocks the calling thread until a job fails or finishes execution. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
public void control(java.lang.String jobId,
int action)
throws DrmaaException
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 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.
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 routine returns once the action has been acknowledged by the DRM system, but does not necessarily wait until the action has been completed.
The DRMAA suspend/resume operations are equivalent to the use of
`-s
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 SessionjobId - The id of the job to controlaction - the control action to be taken
DrmaaException - May be one of the following:
public void exit()
throws DrmaaException
The exit() method closes the DRMAA session for all threads and must be called before process termination. The exit() method may be called only once by a single thread in the process and may only be called after the init() function has completed. Any call to exit() before init() returns or after exit() has already been called will result in a NoActiveSessionException.
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 SessionDrmaaException - May be one of the following:
public 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. In the current implemention, however, the getContact() function returns an empty string, and the contact parameter has no effect on the init() method.
The getContact() method returns the same value before and after init() is called.
getContact in interface Sessionpublic java.lang.String getDrmSystem()
getDrmSystem in interface Session
public int getJobProgramStatus(java.lang.String jobId)
throws DrmaaException
Get the program status of the job identified by jobId. The possible return values and their meanings 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.DRMAA always gets the status of jobId from DRM system. No caching of job state is done.
Jobs' user hold and user suspend states can be controled via control(). For affecting system hold and system suspend states the appropriate DRM interfaces must be used.
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 SessionjobId - the id of the job whose status is to be retrieved
DrmaaException - May be one of the following:
public JobTemplate createJobTemplate()
throws DrmaaException
createJobTemplate in interface SessionDrmaaException - May be one of the following:
JobTemplate
public void deleteJobTemplate(JobTemplate jt)
throws DrmaaException
deleteJobTemplate in interface Sessionjt - the job template to delete
DrmaaException - May be one of the following:
public Version getVersion()
getVersion in interface SessionVersion
public void init(java.lang.String contact)
throws DrmaaException
The init() method initializes the Grid Engine DRMAA API library for all threads of the process and creates a new DRMAA Session. This routine must be called once before any other DRMAA call, except for getDRMSystem(), getContact(), and getDRMAAImplementation().
contact is an implementation dependent string which may be used to specify which Grid Engine cell to use. If contact is null or empty, the default Grid Engine cell will be used. In the current implementation setting contact has no effect.
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 Sessioncontact - implementation-dependent string that may be used to specify
which DRM system to use. If null, will select the default DRM if there
is only one DRM implementation available. Ignored in the current
implementation.
DrmaaException - Maybe be one of the following:
public java.util.List runBulkJobs(JobTemplate jt,
int start,
int end,
int incr)
throws DrmaaException
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. The same constraints regarding qsub -t value ranges also apply to the parameters start, end, and incr. See the qsub(1) man page for more information.
On success a String array containing job identifiers for each array job task is returned.
runBulkJobs in interface Sessionstart - 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 job
DrmaaException - May be one of the following:
public java.lang.String runJob(JobTemplate jt)
throws DrmaaException
runJob in interface Sessionjt - the job template to be used to create the job
DrmaaException - May be one of the following:
public void synchronize(java.util.List jobIds,
long timeout,
boolean dispose)
throws DrmaaException
The synchronize() method blocks the calling thread until all jobs
specified in jobIds have failed or finished execution. If
jobIds contains JOB_IDS_SESSION_ALL, then this method waits for
all jobs submitted during this DRMAA session.
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, all the specified jobs have completed or
the calling thread received an interrupt. In both cases, the method will
throw an ExitTimeoutException.
The dispose parameter specifies how to treat reaping information. If false is passed to this paramter, job finish information will still be available if wait() is called. If true is passed, wait() will be unable to access this job's finish information.
synchronize in interface SessionjobIds - the ids of the jobs to synchronizetimeout - the maximum number of seconds to waitdispose - specifies how to treat reaping information
DrmaaException - May be one of the following:
Session.wait(java.lang.String, long)
public JobInfo wait(java.lang.String jobId,
long timeout)
throws DrmaaException
The wait() function blocks the calling thread until a job fails or
finishes execution. This routine is modeled on the UNIX wait4(3) routine.
If the special string JOB_IDS_SESSION_ANY is passed as jobId,
this routine will wait for any job from the session. Otherwise the
jobId 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 TIMEOUT_WAIT_FOREVER
can be uesd to wait indefinitely for a result. The special value
TIMEOUT_NO_WAIT can be used to return immediately. If the call
exits before timeout, all the specified jobs have completed or the
calling thread received an interrupt. In both cases, the method will
throw an ExitTimeoutException.
The routine reaps jobs on a successful call, so any subsequent calls to wait() will fail, throwing an InvalidJobException, meaning that the job has already been reaped. This exception 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 that case it is possible to issue wait() multiple times for the same jobId.
The wait() method will return a JobInfo object. The JobInfo object
contains information about the job execution. In particular, the JobInfo
object will contain the job id of the failed or finished job. This is useful
when JOB_IDS_SESSION_ANY is passed as the jobId.
wait in interface SessionjobId - the id of the job for which to waittimeout - the maximum number of seconds to wait
DrmaaException - May be one of the following:
public java.lang.String getDrmaaImplementation()
getDrmaaImplementation in interface Session
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||