File Coverage

blib/lib/TaskForest/Job.pm
Criterion Covered Total %
statement 37 37 100.0
branch 7 8 87.5
condition 1 3 33.3
subroutine 8 8 100.0
pod 2 2 100.0
total 55 58 94.8


line stmt bran cond sub pod time code
1             ################################################################################
2             #
3             # $Id: Job.pm 280 2010-03-17 02:20:17Z aijaz $
4             #
5             ################################################################################
6              
7             =head1 NAME
8              
9             TaskForest::Job - A representation of a program that can be run by the operating system
10              
11             =head1 SYNOPSIS
12              
13             use TaskForest::Job;
14              
15             $job = TaskForest::Job->new(name => $job_name);
16             # now $job->{status} eq 'Waiting'
17             # and $job->check() == 0
18              
19             =head1 DOCUMENTATION
20              
21             If you're just looking to use the taskforest application, the only
22             documentation you need to read is that for TaskForest. You can do this
23             either of the two ways:
24              
25             perldoc TaskForest
26              
27             OR
28              
29             man TaskForest
30              
31             =head1 DESCRIPTION
32              
33             A job is a program that can be run. It is represented as a file in
34             the files system whose name is the same as the job name. Most of the
35             manipulation of the attributes of jobs is done by objects of type
36             TaskForest::Family.
37              
38             A job name may only contain the characters a-z, A-Z, 0-9, and '_'.
39              
40             When a job is run by the run wrapper (bin/run), two status files are
41             created in the log directory. The first is created when a job starts and
42             has a name of $FamilyName.$JobName.pid. This file contains some
43             attributes of the job. When the job completes, more attributes are
44             written to this file. See the list of attributes below.
45              
46             When the job completes, another file is written to the log directory. The
47             name of this file will be $FamilyName.$JobName.0 if the job ran
48             successfully, and $FamilyName.$JobName.1 if the job failed. In either
49             case, the file will contain the exit code of the job (0 in the case of
50             success and non-zero otherwise).
51              
52             The system tracks the following properties of a job:
53              
54             =over 2
55              
56             =item * Status.
57              
58             Valid status are:
59              
60             =over 2
61              
62             =item * Waiting
63              
64             One or more dependencies of the job have not been met
65              
66             =item * Ready
67              
68             All dependencies have been met; the job will run the next time around.
69              
70             =item * Running
71              
72             The job is currently running
73              
74             =item * Success
75              
76             The job has run successfully
77              
78             =item * Failure
79              
80             The job was run, but the program exited with a non-zero return code
81              
82             =back
83              
84             =item * Return Code
85              
86             The exit code of the program associated with the job. 0 implies success. Anything else implies failure.
87              
88             =item * Time Zone
89              
90             The time zone with which this job's time dependency is tracked.
91              
92             =item * Scheduled Start
93              
94             The scheduled start time of the job, as specified in the family config file. This is to be interpreted with the timezone above.
95              
96             =item * Actual Start
97              
98             The time that the job actually started (in the timezone above).
99              
100             =item * Stop Time
101              
102             The time that the job completed (succeeded or faild).
103              
104             =back
105              
106             =head1 METHODS
107              
108             =cut
109              
110             package TaskForest::Job;
111              
112 93     93   44256 use strict;
  93         191  
  93         3243  
113 93     93   491 use warnings;
  93         135  
  93         2406  
114 93     93   3079 use Data::Dumper;
  93         20806  
  93         5918  
115 93     93   3053 use Carp;
  93         258  
  93         6545  
116              
117             BEGIN {
118 93     93   492 use vars qw($VERSION);
  93         171  
  93         6345  
119 93     93   29007 $VERSION = '1.30';
120             }
121              
122             my $n = 0;
123              
124             # ------------------------------------------------------------------------------
125             =pod
126              
127             =over 4
128              
129             =item new()
130              
131             Usage : my $job = TaskForest::Job->new();
132             Purpose : The Job constructor creates a simple job data
133             structure. Other classes will set and examine status
134             and return code.
135             Returns : Self
136             Argument : None
137             Throws : "No job name specified" if the required parameter "name"
138             is not provided.
139              
140             =back
141              
142             =cut
143              
144             # ------------------------------------------------------------------------------
145             sub new {
146 1299     1299 1 3276 my $arg = shift;
147 1299   33     8779 my $class = (ref $arg) || $arg;
148 1299         3042 my $pid = $$;
149 1299         1915 $n++;
150 1299         7247 my $unique_id = join("_", time, $pid, $n);
151              
152 1299         7944 my $self = {
153             name => '',
154             rc => '', # exit code
155             status => 'Waiting',
156             unique_id => $unique_id,
157            
158             params => '',
159            
160             };
161              
162 1299         4013 my %args = @_;
163              
164             # set up any other parameters that the caller may have passed in
165             #
166 1299         4461 foreach my $key (keys %args) {
167 2231         5970 $self->{$key} = $args{$key};
168             }
169              
170 1299 50       3943 croak "No Job name specified" unless $self->{name};
171              
172 1299         4550 bless $self, $class;
173 1299         5417 return $self;
174             }
175              
176             # ------------------------------------------------------------------------------
177             =pod
178              
179             =over 4
180              
181             =item check()
182              
183             Usage : $job->check();
184             Purpose : Checks to see whether the job succeeded. Implies that
185             it has already run.
186             Returns : 1 if it succeeded. 0 otherwise.
187             Argument : None
188             Throws : Nothing
189              
190             =back
191              
192             =cut
193              
194             # ------------------------------------------------------------------------------
195             sub check {
196 340     340 1 7932 my $self = shift;
197              
198 340 100       1248 if ($self->{family}) {
199            
200             # this is an external dependency
201            
202             # TODO: What time zone should we look at? The time zone of the
203             # family that owns this job? Or the time zone of the family
204             # in which this job is present?
205            
206             # To make matters simpler, I think it should be the time zone
207             # of the family that includes this external dependency. It's
208             # more obvious. Just look for the file in today's log
209             # dir. Period.
210              
211 12         24 my $foreign_status = shift;
212 12 100       62 if ($foreign_status->{$self->{name}}) {
213 8         44 return 1;
214             }
215              
216 4         26 return 0;
217             }
218              
219              
220 328 100       799 if ($self->{status} eq 'Success') {
221 78         85696 return 1;
222             }
223              
224 250         904 return 0;
225             }
226              
227             1;
228              
229             __END__