NAME

       Mojo::IOLoop::Delay - Manage callbacks and control the flow of events

SYNOPSIS

         use Mojo::IOLoop::Delay;

         # Synchronize multiple events
         my $delay = Mojo::IOLoop::Delay->new;
         $delay->steps(sub { say 'BOOM!' });
         for my $i (1 .. 10) {
           my $end = $delay->begin;
           Mojo::IOLoop->timer($i => sub {
             say 10 - $i;
             $end->();
           });
         }
         $delay->wait;

         # Sequentialize multiple events
         Mojo::IOLoop::Delay->new->steps(

           # First step (simple timer)
           sub {
             my $delay = shift;
             Mojo::IOLoop->timer(2 => $delay->begin);
             say 'Second step in 2 seconds.';
           },

           # Second step (concurrent timers)
           sub {
             my ($delay, @args) = @_;
             Mojo::IOLoop->timer(1 => $delay->begin);
             Mojo::IOLoop->timer(3 => $delay->begin);
             say 'Third step in 3 seconds.';
           },

           # Third step (the end)
           sub {
             my ($delay, @args) = @_;
             say 'And done after 5 seconds total.';
           }
         )->wait;

         # Handle exceptions in all steps
         Mojo::IOLoop::Delay->new->steps(
           sub {
             my $delay = shift;
             die 'Intentional error';
           },
           sub {
             my ($delay, @args) = @_;
             say 'Never actually reached.';
           }
         )->catch(sub {
           my ($delay, $err) = @_;
           say "Something went wrong: $err";
         })->wait;

DESCRIPTION

       Mojo::IOLoop::Delay manages callbacks and controls the flow of events for Mojo::IOLoop,
       which can help you avoid deep nested closures that often result from continuation-passing
       style.

EVENTS

       Mojo::IOLoop::Delay inherits all events from Mojo::EventEmitter and can emit the following
       new ones.

   error
         $delay->on(error => sub {
           my ($delay, $err) = @_;
           ...
         });

       Emitted if an exception gets thrown in one of the steps, breaking the chain, fatal if
       unhandled.

   finish
         $delay->on(finish => sub {
           my ($delay, @args) = @_;
           ...
         });

       Emitted once the active event counter reaches zero and there are no more steps.

ATTRIBUTES

       Mojo::IOLoop::Delay implements the following attributes.

   ioloop
         my $loop = $delay->ioloop;
         $delay   = $delay->ioloop(Mojo::IOLoop->new);

       Event loop object to control, defaults to the global Mojo::IOLoop singleton.

   remaining
         my $remaining = $delay->remaining;
         $delay        = $delay->remaining([]);

       Remaining "steps" in chain.

METHODS

       Mojo::IOLoop::Delay inherits all methods from Mojo::EventEmitter and implements the
       following new ones.

   begin
         my $cb = $delay->begin;
         my $cb = $delay->begin($offset);
         my $cb = $delay->begin($offset, $len);

       Indicate an active event by incrementing the active event counter, the returned callback
       needs to be called when the event has completed, to decrement the active event counter
       again. When all callbacks have been called and the active event counter reached zero,
       "steps" will continue.

         # Capture all arguments except for the first one (invocant)
         my $delay = Mojo::IOLoop->delay(sub {
           my ($delay, $err, $stream) = @_;
           ...
         });
         Mojo::IOLoop->client({port => 3000} => $delay->begin);
         $delay->wait;

       Arguments passed to the returned callback are spliced with the given offset and length,
       defaulting to an offset of 1 with no default length. The arguments are then combined in
       the same order "begin" was called, and passed together to the next step or "finish" event.

         # Capture all arguments
         my $delay = Mojo::IOLoop->delay(sub {
           my ($delay, $loop, $err, $stream) = @_;
           ...
         });
         Mojo::IOLoop->client({port => 3000} => $delay->begin(0));
         $delay->wait;

         # Capture only the second argument
         my $delay = Mojo::IOLoop->delay(sub {
           my ($delay, $err) = @_;
           ...
         });
         Mojo::IOLoop->client({port => 3000} => $delay->begin(1, 1));
         $delay->wait;

         # Capture and combine arguments
         my $delay = Mojo::IOLoop->delay(sub {
           my ($delay, $three_err, $three_stream, $four_err, $four_stream) = @_;
           ...
         });
         Mojo::IOLoop->client({port => 3000} => $delay->begin);
         Mojo::IOLoop->client({port => 4000} => $delay->begin);
         $delay->wait;

   data
         my $hash = $delay->data;
         my $foo  = $delay->data('foo');
         $delay   = $delay->data({foo => 'bar'});
         $delay   = $delay->data(foo => 'bar');

       Data shared between all "steps".

         # Remove value
         my $foo = delete $delay->data->{foo};

         # Assign multiple values at once
         $delay->data(foo => 'test', bar => 23);

   pass
         $delay = $delay->pass;
         $delay = $delay->pass(@args);

       Increment active event counter and decrement it again right away to pass values to the
       next step.

         # Longer version
         $delay->begin(0)->(@args);

   steps
         $delay = $delay->steps(sub {...}, sub {...});

       Sequentialize multiple events, every time the active event counter reaches zero a callback
       will run, the first one automatically runs during the next reactor tick unless it is
       delayed by incrementing the active event counter. This chain will continue until there are
       no "remaining" callbacks, a callback does not increment the active event counter or an
       exception gets thrown in a callback.

   wait
         $delay->wait;

       Start "ioloop" and stop it again once an "error" or "finish" event gets emitted, does
       nothing when "ioloop" is already running.

SEE ALSO

       Mojolicious, Mojolicious::Guides, <http://mojolicio.us>.