TaskForest::Family - A collection of jobs
use TaskForest::Family; my $family = TaskForest::Family->new(name => 'Foo'); # the associated job dependencies are read within new(); $family->getCurrent(); # get the status of all jobs, what's failed, etc. $family->cycle(); # runs any jobs that are ready to be run $family->display(); # print to stdout a list of all jobs in the family # and their statuses
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:
Finally, read the documentation in the source. Great efforts have been made to keep it current and relevant.
A family is a group of jobs that share the following characteristics:
For more information about jobs, please look at the documentation for the TaskForest class.
The following are attributes of objects of the family class:
The name is the same as the name of the config file that contains the job dependency information.
The family start time in 'HH:MM' format using the 24-hour clock. e.g.: '17:30' for 5:30 p.m.
The time zone with which the family start time is to be interpreted.
An array reference of days of the week on which this family's jobs may run. Valid days are 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' and 'Sun'. Anything else will be ignored.
A hash reference that contains the values of the options retrieved from the command line or the environment,
A hash reference of all the jobs that are members of this family. The keys of this hash are the names of the jobs. The names of the jobs are in the family configuration file and they're the same as the filenames of the jobs on disk.
A boolean that is set to true after all the details of the family's jobs are read from status files in the log directory. This boolean is set to false when an attempt is made to run any jobs, and when the family config file is first read (before getCurrent() is called).
A temporary hash reference of jobs that are ready to be run - jobs whose dependencies have been met.
A hash reference of dependencies of all jobs (things that the jobs depend ON). The keys of this hash are the job names. The values are array references. Each array reference can contain 1 or more references to objects of type TaskForest::Job or TaskForest::TimeDependency.
All jobs have at least one dependency - a TimeDependency that's set to the start time of the Family. In other words, after the start time of the Family passes, the check() method of the TimeDependency will return 1. Before that, it will return 0.
For convenience, all time dependencies encountered in this family (including that of the family start time) are saved in this array reference. The other types of time dependencies are those that apply to individual jobs.
This is the TaskForest::TimeDependency that refers to the family start time.
These attributes refer to the current day. They're saved within the Family object so that we don't have to call localtime over and over again. I really should have this cached this somewhere else. Oh, well.
The readFromFile function was *really* long, so I refactored it into smaller functions. Since at least two of the functions read from the file, I saved the file handle within the object.
These are temporary attributes that builds dependency lists while parsing the file.
Usage : my $family = TaskForest::Family->new();
Purpose : The Family constructor is passed the family name. It
uses this name along with the location of the family
directory to find the family configuration file and
reads the file. The family object is configured with
the data read in from the file.
Returns : Self
Argument : A hash that has the properties of he family. Of these,
the only required one is the 'name' property.
Throws : "No family name specified" if the name property is
blank.
Usage : $family->display()
Purpose : This method displays the status of all jobs in all
families that are scheduled to run today.
If the --collapse option is given, pending repeat
jobs are not displayed.
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $family->getCurrent()
Purpose : This method reads all the semaphore files in the log
directory and gets the current status of the entire
family. Each run job can have succeeded or failed. As
a result of this, other jobs may be Ready to be run. If
a job's dependencies have not yet been met, it is said
to be in the Waiting state. Once a family is current,
the only thing that makes it 'uncurrent' is if any jobs
are run, or if its configuration file changes.
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $family->cycle()
Purpose : This is the main method that is invoked once in every
loop, to run any jobs that are in a Ready state. It
gets the current status of the family and runs any jobs
that are in the Ready state.
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $family->updateJobStatuses()
Purpose : This method looks at all the semaphore files in the
current day's log directory and updates job statuses
based on those semaphore files.
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $family->runReadyJobs()
Purpose : This method uses the fork and exec model to run all jobs
currently in the Ready state. The script that is
actually exec'ed is the run wrapper. The wrapper takes
a whole bunch of arguments, some of which can be derived
by others. The intent is to make it flexible and make
it easy for others to write custom wrappers. The code
that's executed in the child process before the exec is
rather paranoid and is taken from perldoc perlsec.
Returns : Nothing
Argument : None
Throws : "Can't drop privileges" if the userids cannot be
changed
Usage : $family->checkAllTimeDependencies()
Purpose : Runs td->check() on all time dependencies, to see
whether they have been met or not
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $family->getAllWaitingJobs()
Purpose : This method gets a hash of all jobs that are currently
in the Waiting state
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $family->readFromFile
Purpose : This is the most crucial method of the application. It
reads the Family configuration file and constructs a
data structure that represents all the configuration
parameters of the family.
Returns : Nothing
Argument : None
Throws : "Can't read dir/file" if the config file cannot be read
"No start time specified for Family",
"No time zone specified for Family",
"No run days specified for Family",
if any of the 3 required headers are not present in
the file
Generic croak if the data cannot be extracted after an
eval.
Usage : $family->okToRunToday
Purpose : This method checks whether today is in the list of days
of the week that this family is eligible to run
Returns : 1 if it is, 0 if it's not.
Argument : $wday - the day of the week today
Throws : Nothing
Usage : $self->_intializeDataStructures Purpose : Used in readFrom file, before a file is opened for reading Returns : Nothing Argument : None Throws : Nothing
Usage : $self->_getSections Purpose : Read concurrent sections from the family file Returns : A list of sections, or () if the file is empty Argument : None Throws : Nothing
Usage : $self->_parseHeaderLine()
Purpose : Read the first non-empty line from the family file.
If this family is not scheduled to run today, then just
close the file and return 0. This means that you
could change the days in the header file in the middle
of the day, and add today to the list of valid
days. This would cause the family to now become
eligible to run today, when earlier in the day it was
not.
Returns : 1 if the family is to run today, 0 otherwise.
Argument : None
Throws : Nothing
Usage : $self->_parseLine($line)
Purpose : Get a list of all jobs on the line and parse them,
creating the data structure.
As we process each line, we add to each job's
dependencies the dependencies in
$self->{last_dependency}. We also add each job to the
list of 'current' dependencies. When we're done parsing
the line, we set 'last' to 'current', for the benefit of
the next line.
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $self->_parseJob($job)
Purpose : Parse the job definition, create additional dependencies
if necessary, and create the job. If it's a recurring
job, then create a bunch of 'repeat' jobs that are not
dependent on the original job's predecessors, but on
time dependencies only.
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $self->_createRecurringJobs($job_name, $args)
Purpose : If a job is a recurring job, create new jobs with a
prefix of --Repeat_$n-- where $n specifies the
cardinality of the repeat job.
By default, the newly created jobs are *not* dependent on
each other. They're only dependent on their start times.
If the 'chained=>1' option is given in the family file,
then the jobs are dependent on each other. This is,
arguably, the more sensible behavior.
Returns : Nothing
Argument : None
Throws : Nothing
Usage : $self->_writeSemaphoreFile($file_name) Purpose : Creates a semaphore file. If the file already exists, do nothing. Returns : Nothing Argument : Contents of the file Throws : Nothing
