NAME

       "CPS::Governor::Deferred" - iterate at some later point

SYNOPSIS

        use CPS qw( gkforeach );
        use CPS::Governor::Deferred;

        my $gov = CPS::Governor::Deferred->new;

        gkforeach( $gov, [ 1 .. 10 ],
           sub {
              my ( $item, $knext ) = @_;

              print "A$item ";
              goto &$knext;
           },
           sub {},
        );

        gkforeach( $gov, [ 1 .. 10 ],
           sub {
              my ( $item, $knext ) = @_;

              print "B$item ";
              goto &$knext;
           },
           sub {},
        );

        $gov->flush;

DESCRIPTION

       This CPS::Governor allows the functions using it to delay their iteration until some later point when the
       containing program invokes it. This allows two main advantages:

       •   CPU-intensive operations may be split apart and mixed with other IO operations

       •   Multiple control functions may be executed in pseudo-parallel, interleaving iterations of each giving
           a kind of concurrency

       These are achieved by having the governor store a list of code references that need to be invoked, rather
       than  invoking  them  immediately.  These  references can then be invoked later, perhaps by using an idle
       watcher in an event framework.

       Because each code reference hasn't yet been invoked by  the  time  the  "again"  method  is  called,  the
       original  caller is free to store more pending references with the governor. This allows multiple control
       functions to be interleaved, as in the "A" and "B" example above.

CONSTRUCTOR

   $gov = CPS::Governor::Deferred->new( %args )
       Returns a new instance of a "CPS::Governor::Deferred" object. Requires no parameters but may take any  of
       the following to adjust its default behaviour:

       defer_after => INT
               If given some positive number, $n then the first "$n-1" invocations of the "again" method will in
               fact  be  executed  immediately.  Thereafter  they will be enqueued in the normal mechanism. This
               gives the effect that longrunning loops will be executed in batches of $n.

               If not supplied then every invocation of "again" will use the queueing mechanism.

METHODS

   $pending = $gov->is_pending
       Returns true if at least one code reference has been stored that hasn't yet been invoked.

   $gov->prod
       Invokes all of the currently-stored code references, in the order they were stored. If any new references
       are stored by these, they will not yet be invoked, but will be available for the next time this method is
       called.

   $gov->flush
       Repeatedly calls "prod" until no more code references are pending.

SUBCLASS METHODS

       The following methods are used internally  to  implement  the  functionality,  which  may  be  useful  to
       implementors of subclasses.

   $gov->later( $code, @args )
       Used to enqueue the $code ref to be invoked later with the given @args, once it is determined this should
       be  deferred  (rather  than  being  invoked  immediately  in  the  case of the first few invocations when
       "defer_after" is set).

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.34.0                                       2022-06-30                       CPS::Governor::Deferred(3pm)