oracular (3) CPS::Governor.3pm.gz

NAME

       "CPS::Governor" - control the iteration of the "CPS" functions

DESCRIPTION

       Objects based on this abstract class are used by the "gk*" variants of the CPS functions, to control
       their behavior. These objects are expected to provide a method, "again", which the functions will use to
       re-invoke iterations of loops, and so on. By providing a different implementation of this method,
       governor objects can provide such behaviours as rate-limiting, asynchronisation or parallelism, and
       integration with event-based IO frameworks.

CONSTRUCTOR

   $gov = CPS::Governor->new
       Must be called on a subclass which implements the "again" method. Returns a new instance of a governor
       object in that class.

SUBCLASS METHODS

       Because this is an abstract class, instances of it can only be constructed on a subclass which implements
       the following methods:

   $gov->again( $code, @args )
       Execute the function given in the "CODE" reference $code, passing in the arguments @args. If this is
       going to be executed immediately, it should be invoked using a tail-call directly by the "again" method,
       so that the stack does not grow arbitrarily. This can be achieved by, for example:

        @_ = @args;
        goto &$code;

       Alternatively, the Sub::Call::Tail may be used to apply syntactic sugar, allowing you to write instead:

        use Sub::Call::Tail;
        ...
        tail $code->( @args );

EXAMPLES

   A Governor With A Time Delay
       Consider the following subclass, which implements a "CPS::Governor" subclass that calls "sleep()" between
       every invocation.

        package Governor::Sleep

        use base qw( CPS::Governor );

        sub new
        {
           my $class = shift;
           my ( $delay ) = @_;

           my $self = $class->SUPER::new;
           $self->{delay} = $delay;

           return $self;
        }

        sub again
        {
           my $self = shift;
           my $code = shift;

           sleep $self->{delay};

           # @args are still in @_
           goto &$code;
        }

SEE ALSO

       •   Sub::Call::Tail - Tail calls for subroutines and methods

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>