NAME

Launcher::Cascade::Base - a base class for a Launcher. Provides everything but the launch() and test()

SYNOPSIS

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
}

DESCRIPTION

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

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.

name

A simple string used only for printing hopefully useful messages. This should be set to something meaningfully.

status

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:

0

Not run yet

1

Running, but it is still unknown whether it has succeeded or failed.

2

Success

3

Failure

retries

Number of retries so far (0 at the first attempt).

max_retries

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?).

time_between_retries

How long to wait between retries, in seconds. The program will not block during this time.

errors

A Launcher::Cascade::ListOfStrings::Errors object, containing a series of error messages, as pushed by the add_error() method.

Methods

dependencies

dependencies LIST

dependencies ARRAYREF

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).

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.

add_dependencies LIST

Pushes a dependency to the list of dependencies. All elements in LIST should be instances of Launcher::Cascade::Base or one of its subclasses.

set_success

set_failure

Sets the status() attribute to the value corresponding to a success, resp. failure.

is_ready

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.

• all dependencies must be successful, otherwise is_ready() yields 0.

Returns 1 in all other cases.

launch

Performs the real action. This method should be overridden in subclasses of Launcher::Cascade::Base.

test

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.

run

Invokes method launch() if the object is_ready(), and sets its status accordingly.

check_status

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.

is_success

is_failure

has_run

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

Reset the object's status so that it can be run again.

as_string

Returns a string representing the object (its name()). This method is invoked when the object is interpolated in a double quoted string.

add_error MESSAGE

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.

Constants

SUCCESS

FAILURE

UNDEFINED

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;
    }
}

SEE ALSO

Launcher::Cascade, Launcher::Cascade::Printable, Launcher::Cascade::ListOfStrings::Errors.

AUTHOR

Cédric Bouvier <cbouvi@cpan.org>

COPYRIGHT & LICENSE

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.