Package schrodinger :: Package job :: Module jobcontrol :: Class Job

Class Job

object --+
         |
        Job

A class to access a specific record in the job database.

A Job instance is always a snapshot of the job record at a specific point in time. It is only updated when the readAgain method is explicitly invoked.

Standard scalar attributes that can be accessed from Job objects include:

JobID
Name
Program
Processors
Host
User
Dir
HostsFile
HostEntry
JobHost
JobUser
JobDir
Status
ExitStatus
ExitCode
Command
Env
Home
LaunchTime
StartTime

Standard list attributes that can be accessed from Job objects include:

InputFiles
OutputFiles
LogFiles
MonitorFiles
SubJobs
Envs

Not all of these attributes are always present. Their presence can be checked with hasattr(), and a full list of the available attributes for a specific Job object can be retrieved with the keys() method.

WARNING: To instantiate a Job object, the Job Database in which it is stored must be accessible from the current process. For example, when a Windows workflow is submitted to a Linux machine, any children that it spawns can not access their parent's job record, because the home directory isn't shared.

Instance Methods

[hide private]

__init__(self, job_id, username='', file=None, launch_output=None, launch_error=None, handle=None, manage_handle=True)
Initialize a read-only Job object.

_cleanup(self)
Force a cleanup of mmjob resources at a specific time.

readAgain(self)
Reread the database.

_setAttributes(self)
Explicitly set attributes instead of relying on __getattr__.

keys(self)
Return a list of keys present in the last read of the job control record.

get(self, name, default=None)
Return the last read value of a job control key.

__getattr__(self, name)
Return the last read value of a job control key.

writeFile(self, filename=None)
Writes the job record to a file.

isComplete(self)
Returns True if the job is complete.

isQueued(self)
Returns True if the job a batch queue job or grid job.

succeeded(self)
Returns False if the job was killed, died or fizzled.

setStatusIncorporated(self)
Set the status of the job to "incorporated" if the job has completed.

sendMessage(self, msg)
Send an arbitrary text message to the job's jmonitor process.

kill(self)
Kill the job if it is running.

wait(self, max_interval=60)
Wait for the job to complete; sleeping up to 'interval' seconds between each database check.

__repr__(self)
Returns the formal string representation of the Job object.

summary(self)
Return a string summarizing all current Job attributes.

getDuration(self)
Returns the wallclock time of the job if it is complete.

_getStatus(self)
Get the Status of the job.

_getExitStatus(self)
Get the ExitStatus of the job.

getApplicationHeaderFields(self, default=None)
@return: An OrderedDict of essential jobcontrol keyword:value pairs used to standardize application log files.

getApplicationHeaderString(self, field_sep=' : ')
@return: A string of essential jobcontrol parameters, in a preferred order, with simple formatting.

getInputFiles(self)
Get list of InputFiles and Transfers marked for input

getOutputFiles(self)
Get list of OutputFiles and Transfers marked for output

getProgressAsPercentage(self)
Get the value of backend job progress in terms of percentage.

getProgressAsSteps(self)
Get the value of backend job progress in terms of steps and totalsteps.

getProgressAsString(self)
Get the value of backend job progress in terms of descriptive text.

purgeRecord(self)
Purge the job record for the job from the database.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables

[hide private]

_field_access_function = {'name': mmjob.mmjob_get_str,}

Properties

[hide private]

Status
Get the Status of the job.

ExitStatus
Get the ExitStatus of the job.

InputFiles
Get list of InputFiles and Transfers marked for input

OutputFiles
Get list of OutputFiles and Transfers marked for output

Inherited from object: __class__

Method Details

[hide private]

init(self, job_id, username=`''`, file=None, launch_output=None, launch_error=None, handle=None, manage_handle=True)
(Constructor)


Initialize a read-only Job object.

There are a three ways that a Job object can be created, and the
optional arguments reflect this. The first way is with only a
job_id, e.g. captured from stdout of a launch. This Job object will
rely on the database to find information. If created from a launch,
stderr and stdout of the launch command can be attached.

The second way is with a file specification. This will create a Job
object that is independent of the standard job database.

A final way is to provide an existing mmjob handle.

With the file or mmjob handle initialization methods any job_id
value will be overwritten with the value retrieved from the mmjob
handle. You can simply provide None as a placeholder value.

Parameters

username (str)
    The username is not required and should not generally be
    specified. It is provided mainly for backward compatibility.

launch_output (str)
    The captured stdout from the launch process that created the
    job.

launch_error (str)
    The captured stderr from the launch process that created the
    job.

manage_handle (bool)
    Obsolete.

Overrides: object.__init__

_cleanup(self)

Force a cleanup of mmjob resources at a specific time.

Don't call this unless you know that there isn't another Job instance with the same handle as this one.

readAgain(self)

Reread the database. Calling this routine is necessary to get fresh values.

_setAttributes(self)

Explicitly set attributes instead of relying on __getattr__. (This is nice for tab completion in the interactive prompt.)

get(self, name, default=None)

Return the last read value of a job control key. Returns default if the job does not have the key 'name'.

getattr(self, name)
(Qualification operator)

Return the last read value of a job control key. Raises an AttributeError if the job does not have the key 'name'.

writeFile(self, filename=None)

Writes the job record to a file.

If no filename is given, the filename is the JobId.

isComplete(self)

Returns True if the job is complete.

This method uses a native mmjob logic to determine if the job is complete or not.

succeeded(self)

Returns False if the job was killed, died or fizzled. Returns True if ExitStatus is finished.

Raises an exception if the job isn't completed, so use isComplete() before calling.

sendMessage(self, msg)

Send an arbitrary text message to the job's jmonitor process.

This should not normally be necessary.

wait(self, max_interval=60)

Wait for the job to complete; sleeping up to 'interval' seconds between each database check. (Interval increase gradually from 2 sec up to the maximum.)

NOTE: Do not use if your program is running in Maestro, as this will make Maestro unresponsive while the job is running.

repr(self)
(Representation operator)

Returns the formal string representation of the Job object.

Overrides: object.__repr__

getDuration(self)

Returns the wallclock time of the job if it is complete. StopTime - StartTime. Units are seconds (float). If job is not complete, returns None.

getApplicationHeaderFields(self, default=None)


@return:
    An OrderedDict of essential jobcontrol keyword:value pairs
    used to standardize application log files.

@param default:
    Value assigned to a keyword if the corresponding attribute
    is not defined.
@type default:
    any

Keywords include: 'JobId', 'Name', 'Program', 'MMshareExec',
'Host', 'Dir', 'HostEntry', 'Queue', 'JobHost', 'JobDir',
'JobMMshareExec', 'Commandline', and 'StartTime'.

getApplicationHeaderString(self, field_sep=`'` `:` `'`)


        @return:
            A string of essential jobcontrol parameters, in a
            preferred order, with simple formatting.

        @param field_sep:
            String that delimits the keyword and value.
        @type field_sep:
            str

        @note:
            'Queue' only appears in the header string if it is defined
            in the jobrecord.

        ex:
        jobbe = schrodinger.job.jobcontrol.get_backend()
        if jobbe:
            print jobbe.getJob().getApplicationHeaderString()
-------------------------------------------------------------------------------
JobId          : buffy-0-4de9129b
Name           : mmod_mini
Program        : MacroModel
MMshareExec    : /zone2/releases/suite2011/general_19Apr2011/mmshare-v20109/bin/Linux-x86_64
Host           : buffy.schrodinger.com
Dir            : /scr/scr1/shawn/mmshare_git/mmshare/python/modules/schrodinger/job
HostEntry      : nina
Queue          : SGE
JobHost        : nina-0-90.local
JobDir         : /nfs/working/ddag/users/shawn/schrod_tmp/shawn/mmod_mini
JobMMshareExec : /nfs/working/releases/suite2011/general_19Apr2011/mmshare-v20109/bin/Linux-x86_64
Commandline    : /zone2/releases/suite2011/general_19Apr2011//bmin mmod_mini -HOST nina
StartTime      : 2011-06-03-09:58:11
-------------------------------------------------------------------------------

getProgressAsPercentage(self)

Get the value of backend job progress in terms of percentage. Return 0.0 when a job is not yet in running state.

getProgressAsSteps(self)

Get the value of backend job progress in terms of steps and totalsteps. Return (0,1) when a job is not yet in 'running' state.

getProgressAsString(self)

Get the value of backend job progress in terms of descriptive text. Return "The job has not yet started." when a job is not yet in running state.

Property Details

[hide private]

Status

Get the Status of the job.

Get Method:: _getStatus(self) - Get the Status of the job.

ExitStatus

Get the ExitStatus of the job.

Get Method:: _getExitStatus(self) - Get the ExitStatus of the job.

InputFiles

Get list of InputFiles and Transfers marked for input

Get Method:: getInputFiles(self) - Get list of InputFiles and Transfers marked for input

OutputFiles

Get list of OutputFiles and Transfers marked for output

Get Method:: getOutputFiles(self) - Get list of OutputFiles and Transfers marked for output

Class Job

__init__(self, job_id, username='', file=None, launch_output=None, launch_error=None, handle=None, manage_handle=True) (Constructor)

_cleanup(self)

readAgain(self)

_setAttributes(self)

get(self, name, default=None)

__getattr__(self, name) (Qualification operator)

writeFile(self, filename=None)

isComplete(self)

succeeded(self)

sendMessage(self, msg)

wait(self, max_interval=60)

__repr__(self) (Representation operator)

getDuration(self)

getApplicationHeaderFields(self, default=None)

getApplicationHeaderString(self, field_sep=' : ')

getProgressAsPercentage(self)

getProgressAsSteps(self)

getProgressAsString(self)

Status

ExitStatus

InputFiles

OutputFiles

init(self, job_id, username=`''`, file=None, launch_output=None, launch_error=None, handle=None, manage_handle=True)
(Constructor)

getattr(self, name)
(Qualification operator)

repr(self)
(Representation operator)

getApplicationHeaderString(self, field_sep=`'` `:` `'`)