.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Mojo::IOLoop::Delay 3pm"
.TH Mojo::IOLoop::Delay 3pm "2017-01-24" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojo::IOLoop::Delay \- Manage callbacks and control the flow of events
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojo::IOLoop::Delay;
\&
\&  # Synchronize multiple non\-blocking operations
\&  my $delay = Mojo::IOLoop::Delay\->new;
\&  $delay\->steps(sub { say \*(AqBOOM!\*(Aq });
\&  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 \*(AqSecond step in 2 seconds.\*(Aq;
\&    },
\&
\&    # Second step (concurrent timers)
\&    sub {
\&      my ($delay, @args) = @_;
\&      Mojo::IOLoop\->timer(1 => $delay\->begin);
\&      Mojo::IOLoop\->timer(3 => $delay\->begin);
\&      say \*(AqThird step in 3 seconds.\*(Aq;
\&    },
\&
\&    # Third step (the end)
\&    sub {
\&      my ($delay, @args) = @_;
\&      say \*(AqAnd done after 5 seconds total.\*(Aq;
\&    }
\&  )\->wait;
\&
\&  # Handle exceptions in all steps
\&  Mojo::IOLoop::Delay\->new\->steps(
\&    sub {
\&      my $delay = shift;
\&      die \*(AqIntentional error\*(Aq;
\&    },
\&    sub {
\&      my ($delay, @args) = @_;
\&      say \*(AqNever actually reached.\*(Aq;
\&    }
\&  )\->catch(sub {
\&    my ($delay, $err) = @_;
\&    say "Something went wrong: $err";
\&  })\->wait;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "EVENTS"
.IX Header "EVENTS"
Mojo::IOLoop::Delay inherits all events from Mojo::EventEmitter and can
emit the following new ones.
.SS "error"
.IX Subsection "error"
.Vb 4
\&  $delay\->on(error => sub {
\&    my ($delay, $err) = @_;
\&    ...
\&  });
.Ve
.PP
Emitted if an exception gets thrown in one of the steps, breaking the chain,
fatal if unhandled.
.SS "finish"
.IX Subsection "finish"
.Vb 4
\&  $delay\->on(finish => sub {
\&    my ($delay, @args) = @_;
\&    ...
\&  });
.Ve
.PP
Emitted once the event counter reaches zero and there are no more steps.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Mojo::IOLoop::Delay implements the following attributes.
.SS "ioloop"
.IX Subsection "ioloop"
.Vb 2
\&  my $loop = $delay\->ioloop;
\&  $delay   = $delay\->ioloop(Mojo::IOLoop\->new);
.Ve
.PP
Event loop object to control, defaults to the global Mojo::IOLoop singleton.
.SS "remaining"
.IX Subsection "remaining"
.Vb 2
\&  my $remaining = $delay\->remaining;
\&  $delay        = $delay\->remaining([sub {...}]);
.Ve
.PP
Remaining \*(L"steps\*(R" in chain.
.SH "METHODS"
.IX Header "METHODS"
Mojo::IOLoop::Delay inherits all methods from Mojo::EventEmitter and
implements the following new ones.
.SS "begin"
.IX Subsection "begin"
.Vb 3
\&  my $cb = $delay\->begin;
\&  my $cb = $delay\->begin($offset);
\&  my $cb = $delay\->begin($offset, $len);
.Ve
.PP
Indicate an active event by incrementing the event counter, the returned
callback needs to be executed when the event has completed, to decrement the
event counter again. When all callbacks have been executed and the event counter
reached zero, \*(L"steps\*(R" will continue.
.PP
.Vb 7
\&  # 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;
.Ve
.PP
Arguments passed to the returned callback are spliced with the given offset and
length, defaulting to an offset of \f(CW1\fR with no default length. The arguments
are then combined in the same order \*(L"begin\*(R" was called, and passed together
to the next step or \*(L"finish\*(R" event.
.PP
.Vb 7
\&  # 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;
.Ve
.SS "data"
.IX Subsection "data"
.Vb 4
\&  my $hash = $delay\->data;
\&  my $foo  = $delay\->data(\*(Aqfoo\*(Aq);
\&  $delay   = $delay\->data({foo => \*(Aqbar\*(Aq, baz => 23});
\&  $delay   = $delay\->data(foo => \*(Aqbar\*(Aq, baz => 23);
.Ve
.PP
Data shared between all \*(L"steps\*(R".
.PP
.Vb 2
\&  # Remove value
\&  my $foo = delete $delay\->data\->{foo};
\&
\&  # Assign multiple values at once
\&  $delay\->data(foo => \*(Aqtest\*(Aq, bar => 23);
.Ve
.SS "pass"
.IX Subsection "pass"
.Vb 2
\&  $delay = $delay\->pass;
\&  $delay = $delay\->pass(@args);
.Ve
.PP
Increment event counter and decrement it again right away to pass values to the
next step.
.PP
.Vb 2
\&  # Longer version
\&  $delay\->begin(0)\->(@args);
.Ve
.SS "steps"
.IX Subsection "steps"
.Vb 1
\&  $delay = $delay\->steps(sub {...}, sub {...});
.Ve
.PP
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 \*(L"remaining\*(R" callbacks, a callback does not increment the
event counter or an exception gets thrown in a callback.
.SS "wait"
.IX Subsection "wait"
.Vb 1
\&  $delay\->wait;
.Ve
.PP
Start \*(L"ioloop\*(R" and stop it again once an \*(L"error\*(R" or \*(L"finish\*(R" event
gets emitted, does nothing when \*(L"ioloop\*(R" is already running.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <http://mojolicious.org>.