/ 
TaskForest-1.06
River stage zero No dependents
/ TaskForest::Job

NAME

TaskForest::Job - A representation of a program that can be run by the operating system

SYNOPSIS

use TaskForest::Job;

$job = TaskForest::Job->new(name => $job_name);
# now $job->{status} eq 'Waiting'
# and $job->check() == 0

DOCUMENTATION

If you're just looking to use the taskforest application, the only documentation you need to read is that for TaskForest. You can do this either of the two ways:

perldoc TaskForest

OR

man TaskForest

If you're a developer and you want to understand the code, I would recommend that you read the pods in this order:

  • TaskForest

  • TaskForest::Job

  • TaskForest::Family

  • TaskForest::TimeDependency

  • TaskForest::LogDir

  • TaskForest::Options

  • TaskForest::StringHandleTier

  • TaskForest::StringHandle

Finally, read the documentation in the source. Great efforts have been made to keep it current and relevant.

DESCRIPTION

A job is a program that can be run. It is represented as a file in the files system whose name is the same as the job name. Most of the manipulation of the attributes of jobs is done by objects of type TaskForest::Family.

A job name may only contain the characters a-z, A-Z, 0-9, and '_'.

When a job is run by the run wrapper (bin/run), two status files are created in the log directory. The first is created when a job starts and has a name of $FamilyName.$JobName.pid. This file contains some attributes of the job. When the job completes, more attributes are written to this file. See the list of attributes below.

When the job completes, another file is written to the log directory. The name of this file will be $FamilyName.$JobName.0 if the job ran successfully, and $FamilyName.$JobName.1 if the job failed. In either case, the file will contain the exit code of the job (0 in the case of success and non-zero otherwise).

The system tracks the following properties of a job:

  • Status.

    Valid status are:

    • Waiting

      One or more dependencies of the job have not been met

    • Ready

      All dependencies have been met; the job will run the next time around.

    • Running

      The job is currently running

    • Success

      The job has run successfully

    • Failure

      The job was run, but the program exited with a non-zero return code

  • Return Code

    The exit code of the program associated with the job. 0 implies success. Anything else implies failure.

  • Time Zone

    The time zone with which this job's time dependency is tracked.

  • Scheduled Start

    The scheduled start time of the job, as specified in the family config file. This is to be interpreted with the timezone above.

  • Actual Start

    The time that the job actually started (in the timezone above).

  • Stop Time

    The time that the job completed (succeeded or faild).

METHODS

new()
Usage     : my $job = TaskForest::Job->new();
Purpose   : The Job constructor creates a simple job data
            structure.  Other classes will set and examine status
            and return code. 
Returns   : Self
Argument  : None
Throws    : "No job name specified" if the required parameter "name"
            is not provided.
check()
Usage     : $job->check();
Purpose   : Checks to see whether the job succeeded.  Implies that
            it has already run.
Returns   : 1 if it succeeded.  0 otherwise.
Argument  : None
Throws    : Nothing