Launcher::Cascade::Base - a base class for a Launcher. Provides everything but the launch() and test()
use base qw( Launch::Cascade::Base ); sub launch { my $self = shift; # implement the launcher } sub test { my $self = shift; # implement the test ... return 1 if $success; return 0 if $error; return undef; # don't know }
This is a base class for a process launcher. It implements a mechanism to handle dependencies between process (i.e., processes that require other processes to be successfully finished before they can start).
Subclasses must overload the launch() and test() methods to define what to launch, and how to test whether is succeeded or failed.
The run() method will invoke the launch() method, but only if:
The launcher has not run yet.
All its dependencies, if any, have been run successfully.
It has already run and failed, but hasn't reached its maximum number of retries.
Attributes are accessed through accessor methods. These methods, when called without an argument, will return the attribute's value. With an argument, they will set the attribute's value to that argument, and return the former value.
A simple string used only for printing hopefully useful messages. This should be set to something meaningfully.
The status of the the launcher. Its value should not be accessed directly but through set_success(), set_failure(), is_ready(), has_run(), is_success(), is_failure() methods.
The possible values are:
Not run yet
Running, but it is still unknown whether it has succeeded or failed.
Success
Failure
Number of retries so far (0 at the first attempt).
Number of failed attempts after which to consider the process as failed. 0 will try only once. -1 will not try forever (you don't want your launcher to last forever do you?).
How long to wait between retries, in seconds. The program will not block during this time.
A Launcher::Cascade::ListOfStrings::Errors object, containing a series of error messages, as pushed by the add_error() method.
Launcher::Cascade::ListOfStrings::Errors
Returns the list of Launcher::Cascade::Base objects that this one depends upon (i.e., they must have successfully been run before this one runs).
Launcher::Cascade::Base
When called with a LIST of arguments, this methods also sets the list of dependencies to LIST. The argument can also be an ARRAYREF, in which case it will automatically be dereferenced.
All elements in LIST or ARRAYREF should be instances of Launcher::Cascade::Base or one of its subclasses.
Pushes a dependency to the list of dependencies. All elements in LIST should be instances of Launcher::Cascade::Base or one of its subclasses.
Sets the status() attribute to the value corresponding to a success, resp. failure.
Checks whether the object is ready to run. Several conditions must be met for this to happen:
status() must be 0, otherwise is_ready() yields undef.
undef
all dependencies must be successful, otherwise is_ready() yields 0.
Returns 1 in all other cases.
Performs the real action. This method should be overridden in subclasses of Launcher::Cascade::Base.
Performs the test to decide whether the process succeeded or failed. This method should be overridden in subclasses of Launcher::Cascade::Base. It must return:
undef if it cannot be determined whether the process has succeeded or failed (e.g., the process is still in its starting phase)
a true status if the process has succeeded.
a false status if the process has failed.
Invokes method launch() if the object is_ready(), and sets its status accordingly.
Performs the test() and sets the status according to its result. Will not run test() until the number of seconds specified by time_between_retries() has elapsed since the last test.
This methods query the object's current status, and return a true status if, respectively, the object has run successfully, or the object has run and failed, or if the object has run (whether it succeeded or failed).
Reset the object's status so that it can be run again.
Returns a string representing the object (its name()). This method is invoked when the object is interpolated in a double quoted string.
Pushes MESSAGE to the list of messages hold by the the Launcher::Cascade::ListOfStrings::Errors object in the errors() attribute. MESSAGE should be either a string or a Launcher::Cascade::Printable object, or any object that can be stringified.
Launcher::Cascade::Printable
Subclasses can use theses "constant" methods within their test() methods, to report either success, failure or the undetermined state of a test.
sub test { my $self = shift; if ( ... ) { return $self->SUCCESS; } elsif ( ... ) { return $self->FAILURE; } else { return $self->UNDEFINED; } }
Launcher::Cascade, Launcher::Cascade::Printable, Launcher::Cascade::ListOfStrings::Errors.
Cédric Bouvier <cbouvi@cpan.org>
<cbouvi@cpan.org>
Copyright (C) 2006 Cédric Bouvier, All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'Cédric'. Assuming CP1252
To install Launcher::Cascade, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Launcher::Cascade
CPAN shell
perl -MCPAN -e shell install Launcher::Cascade
For more information on module installation, please visit the detailed CPAN module installation guide.