.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mojo::IOLoop::Delay 3pm"
.TH Mojo::IOLoop::Delay 3pm "2014-09-12" "perl v5.20.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 events
\&  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 events
\&  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 and memory
leaks 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 active 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 $ioloop = $delay\->ioloop;
\&  $delay     = $delay\->ioloop(Mojo::IOLoop\->new);
.Ve
.PP
Event loop object to control, defaults to the global Mojo::IOLoop
singleton.
.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
Increment active event counter, the returned callback can be used to decrement
the active event counter again. Arguments passed to the callback are spliced
and queued in the right order for the next step or \*(L"finish\*(R" event and
\&\*(L"wait\*(R" method, the argument offset defaults to \f(CW1\fR with no default
length.
.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;
\&
\&  # 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;
.Ve
.SS "data"
.IX Subsection "data"
.Vb 4
\&  my $hash = $delay\->data;
\&  my $foo  = $delay\->data(\*(Aqfoo\*(Aq);
\&  $delay   = $delay\->data({foo => \*(Aqbar\*(Aq});
\&  $delay   = $delay\->data(foo => \*(Aqbar\*(Aq);
.Ve
.PP
Data shared between all \*(L"steps\*(R".
.PP
.Vb 2
\&  # Remove value
\&  my $foo = delete $delay\->data\->{foo};
.Ve
.SS "pass"
.IX Subsection "pass"
.Vb 2
\&  $delay = $delay\->pass;
\&  $delay = $delay\->pass(@args);
.Ve
.PP
Increment active 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 "remaining"
.IX Subsection "remaining"
.Vb 2
\&  my $remaining = $delay\->remaining;
\&  $delay        = $delay\->remaining([]);
.Ve
.PP
Remaining \*(L"steps\*(R" in chain, stored outside the object to protect from
circular references.
.SS "steps"
.IX Subsection "steps"
.Vb 1
\&  $delay = $delay\->steps(sub {...}, sub {...});
.Ve
.PP
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 more callbacks, a callback does
not increment the active 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://mojolicio.us>.