NAME
Mojo::IOLoop::Delay - Manage callbacks and control the flow of events
SYNOPSIS
use Mojo::IOLoop::Delay;
# Synchronize multiple non-blocking operations
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 non-blocking operations
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.
use Mojo::IOLoop;
# These deep nested closures are often referred to as "Callback Hell"
Mojo::IOLoop->timer(3 => sub {
my loop = shift;
say '3 seconds';
Mojo::IOLoop->timer(3 => sub {
my $loop = shift;
say '6 seconds';
Mojo::IOLoop->timer(3 => sub {
my $loop = shift;
say '9 seconds';
Mojo::IOLoop->stop;
});
});
});
Mojo::IOLoop->start;The idea behind Mojo::IOLoop::Delay is to turn the nested closures above into a flat series of closures. In the example below, the call to "begin" creates a code reference that we can pass to "timer" in Mojo::IOLoop as a callback, and that leads to the next closure in the series when executed.
use Mojo::IOLoop;
# Instead of nested closures we now have a simple chain
my $delay = Mojo::IOloop->delay(
sub {
my $delay = shift;
Mojo::IOLoop->timer(3 => $delay->begin);
},
sub {
my $delay = shift;
say '3 seconds';
Mojo::IOLoop->timer(3 => $delay->begin);
},
sub {
my $delay = shift;
say '6 seconds';
Mojo::IOLoop->timer(3 => $delay->begin);
},
sub {
my $delay = shift;
say '9 seconds';
}
);
$delay->wait;Another positive side effect of this pattern is that we do not need to call "start" in Mojo::IOLoop and "stop" in Mojo::IOLoop manually, because we know exactly when our series of closures has reached the end. So "wait" can stop the event loop automatically if it had to be started at all in the first place.
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 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([sub {...}]);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 event counter, the returned code reference can be used as a callback, and needs to be executed when the event has completed to decrement the event counter again. When all code references generated by this method have been executed and the event counter has 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 code reference 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', baz => 23});
$delay = $delay->data(foo => 'bar', baz => 23);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 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 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 event counter. This chain will continue until there are no "remaining" callbacks, a callback does not increment the 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.