.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojo::IOLoop::Delay 3pm"
.TH Mojo::IOLoop::Delay 3pm "2019-02-05" "perl v5.28.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 \- Promises/A+ and flow\-control helpers
.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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojo::IOLoop::Delay adds flow-control helpers to Mojo::Promise, which can
help you avoid deep nested closures that often result from continuation-passing
style.
.PP
.Vb 1
\&  use Mojo::IOLoop;
\&
\&  # These deep nested closures are often referred to as "Callback Hell"
\&  Mojo::IOLoop\->timer(3 => sub {
\&    my loop = shift;
\&
\&    say \*(Aq3 seconds\*(Aq;
\&    Mojo::IOLoop\->timer(3 => sub {
\&      my $loop = shift;
\&
\&      say \*(Aq6 seconds\*(Aq;
\&      Mojo::IOLoop\->timer(3 => sub {
\&        my $loop = shift;
\&
\&        say \*(Aq9 seconds\*(Aq;
\&        Mojo::IOLoop\->stop;
\&      });
\&    });
\&  });
\&
\&  Mojo::IOLoop\->start;
.Ve
.PP
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 \*(L"begin\*(R" creates
a code reference that we can pass to \*(L"timer\*(R" in Mojo::IOLoop as a callback, and
that leads to the next closure in the series when executed.
.PP
.Vb 1
\&  use Mojo::IOLoop;
\&
\&  # Instead of nested closures we now have a simple chain of steps
\&  my $delay = Mojo::IOLoop\->delay(
\&    sub {
\&      my $delay = shift;
\&      Mojo::IOLoop\->timer(3 => $delay\->begin);
\&    },
\&    sub {
\&      my $delay = shift;
\&      say \*(Aq3 seconds\*(Aq;
\&      Mojo::IOLoop\->timer(3 => $delay\->begin);
\&    },
\&    sub {
\&      my $delay = shift;
\&      say \*(Aq6 seconds\*(Aq;
\&      Mojo::IOLoop\->timer(3 => $delay\->begin);
\&    },
\&    sub {
\&      my $delay = shift;
\&      say \*(Aq9 seconds\*(Aq;
\&    }
\&  );
\&  $delay\->wait;
.Ve
.PP
Another positive side effect of this pattern is that we do not need to call
\&\*(L"start\*(R" in Mojo::IOLoop and \*(L"stop\*(R" in Mojo::IOLoop manually, because we know
exactly when our chain of \*(L"steps\*(R" has reached the end. So
\&\*(L"wait\*(R" in Mojo::Promise can stop the event loop automatically if it had to be
started at all in the first place.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Mojo::IOLoop::Delay inherits all attributes from Mojo::Promise.
.SH "METHODS"
.IX Header "METHODS"
Mojo::IOLoop::Delay inherits all methods from Mojo::Promise 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
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, \*(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 code reference 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.
.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 "pass"
.IX Subsection "pass"
.Vb 2
\&  $delay = $delay\->pass;
\&  $delay = $delay\->pass(@args);
.Ve
.PP
Shortcut for passing values between \*(L"steps\*(R".
.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 remaining callbacks, a callback does not increment the event
counter or an exception gets thrown in a callback. Finishing the chain will also
result in the promise being fulfilled, or if an exception got thrown it will be
rejected.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.