Cascade/Base.pm

filter: Statementstmt 100% 91 / 91 Branchbran 100% 24 / 24 Conditioncond 80.0% 8 / 10 MC/DCmcdc 50.0% 3 / 6 Subroutinesub 91.6% 22 / 24 Podpod 100% 18 / 18 totaltotal 95.9% 166 / 173 CC 18 SCAR 11.5
CC
18
Cov
98%
check_status
8.0
dependencies
4.0
is_ready
4.0
CRAP 3.1
« Cascade/Simple.pm ↑ Summary Cascade/FileReader/Seekable.pm »
1 package Launcher::Cascade::Base;
2  
3 =head1 NAME
4  
5 Launcher::Cascade::Base - a base class for a Launcher. Provides everything but the launch() and test()
6  
7 =head1 SYNOPSIS
8  
9 use base qw( Launch::Cascade::Base );
10  
11 sub launch {
12 my $self = shift;
13 # implement the launcher
14 }
15  
16 sub test {
17 my $self = shift;
18 # implement the test
19 ...
20 return 1 if $success;
21 return 0 if $error;
22 return undef; # don't know
23 }
24  
25 =head1 DESCRIPTION
26  
27 This is a base class for a process launcher. It implements a mechanism to
28 handle dependencies between process (i.e., processes that require other
29 processes to be successfully finished before they can start).
30  
31 Subclasses must overload the launch() and test() methods to define what to
32 launch, and how to test whether is succeeded or failed.
33  
34 The run() method will invoke the launch() method, but only if:
35  
36 =over 4
37  
38 =item *
39  
40 The launcher has not run yet.
41  
42 =item *
43  
44 All its dependencies, if any, have been run successfully.
45  
46 =item *
47  
48 It has already run and failed, but hasn't reached its maximum number of
49 retries.
50  
51 =back
52  
53 =cut
54  
55 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
56 10 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
57  
58 10 ▶use base qw( Launcher::Cascade );
Subroutine BEGIN: called CC=1 SCAR=0.0
59 10 ▶use overload '""' => \&as_string;
Subroutine BEGIN: called CC=1 SCAR=0.0
60  
61 10 ▶use Log::Log4perl qw( get_logger );
Subroutine BEGIN: called CC=1 SCAR=0.0
62 10 ▶use Launcher::Cascade::ListOfStrings::Errors;
Subroutine BEGIN: called CC=1 SCAR=0.0
63  
64 =head2 Attributes
65  
66 Attributes are accessed through accessor methods. These methods, when called
67 without an argument, will return the attribute's value. With an argument, they
68 will set the attribute's value to that argument, and return the former value.
69  
70 =over 4
71  
72 =item B<name>
73  
74 A simple string used only for printing hopefully useful messages. This should
75 be set to something meaningfully.
76  
77 =item B<status>
78  
79 The status of the the launcher. Its value should not be accessed directly but
80 through set_success(), set_failure(), is_ready(), has_run(), is_success(),
81 is_failure() methods.
82  
83 The possible values are:
84  
85 =over 5
86  
87 =item B<0>
88  
89 Not run yet
90  
91 =item B<1>
92  
93 Running, but it is still unknown whether it has succeeded or failed.
94  
95 =item B<2>
96  
97 Success
98  
99 =item B<3>
100  
101 Failure
102  
103 =back
104  
105 =cut
106  
107 =item B<retries>
108  
109 Number of retries so far (0 at the first attempt).
110  
111 =item B<max_retries>
112  
113 Number of failed attempts after which to consider the process as failed. 0 will
114 try only once. -1 will B<not> try forever (you don't want your launcher to last
115 forever do you?).
116  
117 =item B<time_between_retries>
118  
119 How long to wait between retries, in seconds. The program will not block during
120 this time.
121  
122 =item B<errors>
123  
124 A C<Launcher::Cascade::ListOfStrings::Errors> object, containing a series of
125 error messages, as pushed by the add_error() method.
126  
127 =cut
128  
129 10 Launcher::Cascade::make_accessors qw( name errors );
130 10 Launcher::Cascade::make_accessors_with_defaults
131 status => 0,
132 retries => 0,
133 max_retries => 0,
134 time_between_retries => 0,
135 _last_retry_at => 0,
136 ;
137  
138 =back
139  
140 =head2 Methods
141  
142 =over 4
143  
144 =item B<dependencies>
145  
146 =item B<dependencies> I<LIST>
147  
148 =item B<dependencies> I<ARRAYREF>
149  
150 Returns the list of C<Launcher::Cascade::Base> objects that this one depends
151 upon (i.e., they must have successfully been run before this one runs).
152  
153 When called with a I<LIST> of arguments, this methods also sets the list of
154 dependencies to I<LIST>. The argument can also be an I<ARRAYREF>, in which case
155 it will automatically be dereferenced.
156  
157 All elements in I<LIST> or I<ARRAYREF> should be instances of
158 C<Launcher::Cascade::Base> or one of its subclasses.
159  
160 =cut
161  
162 33 ▶sub dependencies {
Subroutine dependencies: called CC=4 SCAR=13.9
Pod documented
163  
164 33 my $self = shift;
165 33 ▶ $self->{_dependencies} ||= [];
Condition100%2/2
$self->{"_dependencies"} ||= []
l!l
249
MC/DC100%1/1
$self->{"_dependencies"} ||= []
$self->{"_dependencies"}
Truth table100%2/2
A
A= $self->{"_dependencies"}
Aresult
11
00
166 33 ▶ if ( @_ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 5 28 33
167 5 ▶ if ( UNIVERSAL::isa($_[0], 'ARRAY') ) {
Branch: 1 branch
BranchTrueFalseTotal
if (UNIVERSAL::isa($_[0], 'ARRAY')) { } 3 2 5
168 # Dereference the first arg if it is an arrayref (so that the
169 # method can be called with an arrayref from the constructor).
170 3 $self->{_dependencies} = $_[0];
171 }
172 else {
173 2 $self->{_dependencies} = [ @_ ];
174 }
175 }
176 33 @{$self->{_dependencies}};
177 }
178  
179 =item B<add_dependencies> I<LIST>
180  
181 Pushes a dependency to the list of dependencies. All elements in I<LIST>
182 should be instances of C<Launcher::Cascade::Base> or one of its subclasses.
183  
184 =cut
185  
186 1 ▶sub add_dependencies {
Subroutine add_dependencies: called CC=2 SCAR=7.1
Pod documented
187  
188 1 my $self = shift;
189 1 ▶ push @{$self->{_dependencies} ||= []}, @_;
Condition50%1/2
$self->{"_dependencies"} ||= []
l!l
01
MC/DC0%0/1
$self->{"_dependencies"} ||= []
$self->{"_dependencies"}
Truth table50%1/2
A
A= $self->{"_dependencies"}
Aresult
11
00
190 }
191  
192 =item B<set_success>
193  
194 =item B<set_failure>
195  
196 Sets the status() attribute to the value corresponding to a success, resp. failure.
197  
198 =cut
199  
200 10 ▶sub set_success {
Subroutine set_success: called CC=1 SCAR=0.0
Pod documented
201 10 my $self = shift;
202 10 $self->status(2);
203 }
204  
205 7 ▶sub set_failure {
Subroutine set_failure: called CC=1 SCAR=0.0
Pod documented
206 7 my $self = shift;
207 7 $self->status(3);
208 }
209  
210 =item B<is_ready>
211  
212 Checks whether the object is ready to run. Several conditions must be met for
213 this to happen:
214  
215 =over 5
216  
217 =item *
218  
219 status() must be 0, otherwise is_ready() yields C<undef>.
220  
221 =item *
222  
223 all dependencies must be successful, otherwise is_ready() yields 0.
224  
225 =back
226  
227 Returns 1 in all other cases.
228  
229 =cut
230  
231 145923 ▶sub is_ready {
Subroutine is_ready: called CC=4 SCAR=13.9
Pod documented
232  
233 145923 my $self = shift;
234 145923 ▶ return unless $self->status() == 0;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->status == 0 145899 24 145923
235  
236 24 foreach ( $self->dependencies() ) {
237 11 ▶ return 0 unless $_->is_success();
Branch: 1 branch
BranchTrueFalseTotal
unless $_->is_success 5 6 11
238 }
239 19 return 1;
240 }
241  
242 =item B<launch>
243  
244 Performs the real action. This method should be overridden in subclasses of
245 C<Launcher::Cascade::Base>.
246  
247 =cut
248  
249 0 ▶sub launch {}
Subroutine launch: not called CC=1 SCAR=0.0
Pod documented
250  
251 =item B<test>
252  
253 Performs the test to decide whether the process succeeded or failed. This
254 method should be overridden in subclasses of C<Launcher::Cascade::Base>. It
255 must return:
256  
257 =over 5
258  
259 =item *
260  
261 C<undef> if it cannot be determined whether the process has succeeded or failed
262 (e.g., the process is still in its starting phase)
263  
264 =item *
265  
266 a B<true> status if the process has succeeded.
267  
268 =item *
269  
270 a B<false> status if the process has failed.
271  
272 =back
273  
274 =cut
275  
276 0 ▶sub test {}
Subroutine test: not called CC=1 SCAR=0.0
Pod documented
277  
278 =item B<run>
279  
280 Invokes method launch() if the object is_ready(), and sets its status
281 accordingly.
282  
283 =cut
284  
285 145913 ▶sub run {
Subroutine run: called CC=2 SCAR=6.9
Pod documented
286  
287 145913 my $self = shift;
288 145913 ▶ return unless $self->is_ready();
Branch: 1 branch
BranchTrueFalseTotal
unless $self->is_ready 145896 17 145913
289 17 $self->launch();
290 17 $self->status(1); # Running
291 }
292  
293 =item B<check_status>
294  
295 Performs the test() and sets the status according to its result. Will not run
296 test() until the number of seconds specified by time_between_retries() has
297 elapsed since the last test.
298  
299 =cut
300  
301 145913 ▶sub check_status {
Subroutine check_status: called CC=8 SCAR=20.8
Pod documented
302  
303 145913 my $self = shift;
304 145913 my $logger = get_logger;
305  
306 145913 ▶ return unless $self->status() == 1;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->status == 1 8 145905 145913
307  
308 # Checking whether it is too early for another attempt
309 145905 my $time = time;
310 145905 ▶ return if $self->time_between_retries()
Branch: 1 branch
BranchTrueFalseTotal
if $self->time_between_retries and $time - $self->_last_retry_at < $self->time_between_retries 145866 39 145905
Condition100%3/3
$self->time_between_retries and $time - $self->_last_retry_at < $self->time_between_retries
!ll&&!rl&&r
363145866
MC/DC100%2/2
$self->time_between_retries and $time - $self->_last_retry_at < $self->time_between_retries
$self->time_between_retries $time - $self->_last_retry_at < $self->time_between_retries
Truth table100%3/3
A and B
A= $self->time_between_retriesB= $time - $self->_last_retry_at < $self->time_between_retries
ABresult
0X0
100
111
311 && $time - $self->_last_retry_at() < $self->time_between_retries();
312 39 $self->_last_retry_at($time);
313  
314 39 $logger->debug("Performing the test() for $self");
315 39 my $result = eval {
316 39 $self->test();
317 };
318 39 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 1 38 39
319 1 my $msg = "Test for $self died unexpectedly: $@";
320 1 $logger->error($msg);
321 1 $self->add_error($msg);
322 1 $self->set_failure();
323 1 return;
324 }
325  
326 38 ▶ if ( !defined($result) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $result) { } 26 12 38
elsif ($result > 0) { } 10 2 12
327 26 $logger->debug("Still not sure whether $self succeeded");
328 26 ▶ if ( $self->retries() < $self->max_retries() ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->retries < $self->max_retries) { } 22 4 26
329 22 $self->retries($self->retries() + 1);
330 22 return;
331 }
332 else {
333 4 my $msg = "Maximum number of retries reached";
334 4 $logger->error($msg);
335 4 $self->add_error($msg);
336 4 $self->set_failure();
337 }
338 }
339 elsif ( $result > 0) {
340 10 $logger->info("$self ran successfully");
341 10 $self->set_success();
342 }
343 else {
344 2 $logger->info("$self failed to run successfully");
345 2 $self->set_failure();
346 }
347 }
348  
349 =item B<is_success>
350  
351 =item B<is_failure>
352  
353 =item B<has_run>
354  
355 This methods query the object's current status, and return a true status if,
356 respectively, the object has run successfully, or the object has run and
357 failed, or if the object has run (whether it succeeded or failed).
358  
359 =cut
360  
361 145952 ▶sub is_success {
Subroutine is_success: called CC=1 SCAR=0.0
Pod documented
362 145952 my $self = shift;
363 145952 $self->status() == 2;
364 }
365  
366 145948 ▶sub is_failure {
Subroutine is_failure: called CC=1 SCAR=0.0
Pod documented
367 145948 my $self = shift;
368 145948 $self->status() == 3;
369 }
370  
371 145907 ▶sub has_run {
Subroutine has_run: called CC=2 SCAR=6.9
Pod documented
372  
373 145907 my $self = shift;
374 145907 ▶ $self->is_success() || $self->is_failure();
Branch: 1 branch
BranchTrueFalseTotal
$self->is_success or $self->is_failure 1 145906 145907
375 }
376  
377 =item B<reset>
378  
379 Reset the object's status so that it can be run again.
380  
381 =cut
382  
383 8 ▶sub reset {
Subroutine reset: called CC=1 SCAR=0.0
Pod documented
384  
385 8 my $self = shift;
386 8 $self->retries(0);
387 8 $self->status(0);
388 8 $self->_last_retry_at(0);
389 }
390  
391 =item B<as_string>
392  
393 Returns a string representing the object (its name()). This method is invoked
394 when the object is interpolated in a double quoted string.
395  
396 =cut
397  
398 85 ▶sub as_string {
Subroutine as_string: called CC=1 SCAR=0.0
Pod documented
399  
400 85 my $self = shift;
401  
402 85 return $self->name();
403 }
404  
405 =item B<add_error> I<MESSAGE>
406  
407 Pushes I<MESSAGE> to the list of messages hold by the the
408 C<Launcher::Cascade::ListOfStrings::Errors> object in the errors() attribute.
409 I<MESSAGE> should be either a string or a C<Launcher::Cascade::Printable>
410 object, or any object that can be stringified.
411  
412 =cut
413  
414 8 ▶sub add_error {
Subroutine add_error: called CC=2 SCAR=7.0
Pod documented
415  
416 8 my $self = shift;
417 8 ▶ push @{$self->{_errors} ||= new Launcher::Cascade::ListOfStrings::Errors }, @_;
Condition66%2/3
$self->{"_errors"} ||= "Launcher::Cascade::ListOfStrings::Errors"->new
l!l&&r!l&&!r
350
MC/DC0%0/2
$self->{"_errors"} ||= "Launcher::Cascade::ListOfStrings::Errors"->new
$self->{"_errors"} "Launcher::Cascade::ListOfStrings::Errors"->new
Truth table66%2/3
A ||= B
A= $self->{"_errors"}B= "Launcher::Cascade::ListOfStrings::Errors"->new
ABresult
1X1
011
000
418 }
419  
420 =back
421  
422 =head2 Constants
423  
424 =over 4
425  
426 =item B<SUCCESS>
427  
428 =item B<FAILURE>
429  
430 =item B<UNDEFINED>
431  
432 Subclasses can use theses "constant" methods within their test() methods, to
433 report either success, failure or the undetermined state of a test.
434  
435 sub test {
436  
437 my $self = shift;
438  
439 if ( ... ) {
440 return $self->SUCCESS;
441 }
442 elsif ( ... ) {
443 return $self->FAILURE;
444 }
445 else {
446 return $self->UNDEFINED;
447 }
448 }
449  
450 =back
451  
452 =cut
453  
454 1 ▶sub SUCCESS { 1 }
Subroutine SUCCESS: called CC=1 SCAR=0.0
Pod documented
455  
456 1 ▶sub FAILURE { -1 }
Subroutine FAILURE: called CC=1 SCAR=0.0
Pod documented
457  
458 9 ▶sub UNDEFINED { undef }
Subroutine UNDEFINED: called CC=1 SCAR=0.0
Pod documented
459  
460 =head1 SEE ALSO
461  
462 L<Launcher::Cascade>, L<Launcher::Cascade::Printable>,
463 L<Launcher::Cascade::ListOfStrings::Errors>.
464  
465 =head1 AUTHOR
466  
467 Cédric Bouvier C<< <cbouvi@cpan.org> >>
468  
469 =head1 COPYRIGHT & LICENSE
470  
471 Copyright (C) 2006 Cédric Bouvier, All Rights Reserved.
472  
473 This program is free software; you can redistribute it and/or modify it under
474 the same terms as Perl itself.
475  
476 =cut
477  
478 10 1; # end of Launcher::Cascade::Base
« Cascade/Simple.pm ↑ Summary Cascade/FileReader/Seekable.pm »