README
1NAME
2
3 Mojo::IOLoop::Delay - (DISCOURAGED) Promises/A+ and flow-control
4 helpers
5
6SYNOPSIS
7
8 use Mojo::IOLoop::Delay;
9
10 # Synchronize multiple non-blocking operations
11 my $delay = Mojo::IOLoop::Delay->new;
12 $delay->steps(sub { say 'BOOM!' });
13 for my $i (1 .. 10) {
14 my $end = $delay->begin;
15 Mojo::IOLoop->timer($i => sub {
16 say 10 - $i;
17 $end->();
18 });
19 }
20 $delay->wait;
21
22 # Sequentialize multiple non-blocking operations
23 Mojo::IOLoop::Delay->new->steps(
24
25 # First step (simple timer)
26 sub ($delay) {
27 Mojo::IOLoop->timer(2 => $delay->begin);
28 say 'Second step in 2 seconds.';
29 },
30
31 # Second step (concurrent timers)
32 sub ($delay, @args) {
33 Mojo::IOLoop->timer(1 => $delay->begin);
34 Mojo::IOLoop->timer(3 => $delay->begin);
35 say 'Third step in 3 seconds.';
36 },
37
38 # Third step (the end)
39 sub ($delay, @args) {
40 say 'And done after 5 seconds total.';
41 }
42 )->wait;
43
44DESCRIPTION
45
46 Mojo::IOLoop::Delay adds flow-control helpers to Mojo::Promise, which
47 can help you avoid deep nested closures that often result from
48 continuation-passing style.
49
50 use Mojo::IOLoop;
51
52 # These deep nested closures are often referred to as "Callback Hell"
53 Mojo::IOLoop->timer(3 => sub ($loop) {
54
55 say '3 seconds';
56 Mojo::IOLoop->timer(3 => sub ($loop) {
57
58 say '6 seconds';
59 Mojo::IOLoop->timer(3 => sub ($loop) {
60
61 say '9 seconds';
62 Mojo::IOLoop->stop;
63 });
64 });
65 });
66
67 Mojo::IOLoop->start;
68
69 The idea behind Mojo::IOLoop::Delay is to turn the nested closures
70 above into a flat series of closures. In the example below, the call to
71 "begin" creates a code reference that we can pass to "timer" in
72 Mojo::IOLoop as a callback, and that leads to the next closure in the
73 series when executed.
74
75 use Mojo::IOLoop;
76 use Mojo::IOLoop::Delay; # adds Mojo::IOLoop->delay
77
78 # Instead of nested closures we now have a simple chain of steps
79 my $delay = Mojo::IOLoop->delay(
80 sub ($delay) { Mojo::IOLoop->timer(3 => $delay->begin) },
81 sub ($delay) {
82 say '3 seconds';
83 Mojo::IOLoop->timer(3 => $delay->begin);
84 },
85 sub ($delay) {
86 say '6 seconds';
87 Mojo::IOLoop->timer(3 => $delay->begin);
88 },
89 sub ($delay) { say '9 seconds' }
90 );
91 $delay->wait;
92
93 Another positive side effect of this pattern is that we do not need to
94 call "start" in Mojo::IOLoop and "stop" in Mojo::IOLoop manually,
95 because we know exactly when our chain of "steps" has reached the end.
96 So "wait" in Mojo::Promise can stop the event loop automatically if it
97 had to be started at all in the first place.
98
99DISCOURAGED! WARNING!
100
101 This module has been extracted from Mojolicious and was removed from it
102 at the 9.0 release. It is kept here for backwards compatibility
103 purposes but there is no intention to maintain it further and it should
104 be migrated away from as your earliest convenience.
105
106 Though there is no intention of removing it from CPAN in the future it
107 should be treated as deprecated and the metadata will mark it as such.
108 It will receive no no-security-related changes going forward.
109
110MOJO::IOLOOP CLASS METHOD CONSTRUCTOR
111
112 As of Mojolicious 9.0, the package Mojo::IOLoop no longer provides a
113 class constructor for delays. If you want to use Mojo::IOLoop->delay
114 you must first load this class explicitly which will add it back. You
115 can also use -MMojo::IOLoop::Delay at the command line to do so.
116
117ATTRIBUTES
118
119 Mojo::IOLoop::Delay inherits all attributes from Mojo::Promise.
120
121METHODS
122
123 Mojo::IOLoop::Delay inherits all methods from Mojo::Promise and
124 implements the following new ones.
125
126 begin
127
128 my $cb = $delay->begin;
129 my $cb = $delay->begin($offset);
130 my $cb = $delay->begin($offset, $len);
131
132 Indicate an active event by incrementing the event counter, the
133 returned code reference can be used as a callback, and needs to be
134 executed when the event has completed to decrement the event counter
135 again. When all code references generated by this method have been
136 executed and the event counter has reached zero, "steps" will continue.
137
138 # Capture all arguments except for the first one (invocant)
139 my $delay = Mojo::IOLoop->delay(sub ($delay, $err, $stream) { ... });
140 Mojo::IOLoop->client({port => 3000} => $delay->begin);
141 $delay->wait;
142
143 Arguments passed to the returned code reference are spliced with the
144 given offset and length, defaulting to an offset of 1 with no default
145 length. The arguments are then combined in the same order "begin" was
146 called, and passed together to the next step.
147
148 # Capture all arguments
149 my $delay = Mojo::IOLoop->delay(sub ($delay, $loop, $err, $stream) { ... });
150 Mojo::IOLoop->client({port => 3000} => $delay->begin(0));
151 $delay->wait;
152
153 # Capture only the second argument
154 my $delay = Mojo::IOLoop->delay(sub ($delay, $err) { ... });
155 Mojo::IOLoop->client({port => 3000} => $delay->begin(1, 1));
156 $delay->wait;
157
158 # Capture and combine arguments
159 my $delay = Mojo::IOLoop->delay(sub ($delay, $three_err, $three_stream, $four_err, $four_stream) { ... });
160 Mojo::IOLoop->client({port => 3000} => $delay->begin);
161 Mojo::IOLoop->client({port => 4000} => $delay->begin);
162 $delay->wait;
163
164 pass
165
166 $delay = $delay->pass;
167 $delay = $delay->pass(@args);
168
169 Shortcut for passing values between "steps".
170
171 # Longer version
172 $delay->begin(0)->(@args);
173
174 steps
175
176 $delay = $delay->steps(sub {...}, sub {...});
177
178 Sequentialize multiple events, every time the event counter reaches
179 zero a callback will run, the first one automatically runs during the
180 next reactor tick unless it is delayed by incrementing the event
181 counter. This chain will continue until there are no remaining
182 callbacks, a callback does not increment the event counter or an
183 exception gets thrown in a callback. Finishing the chain will also
184 result in the promise being fulfilled, or if an exception got thrown it
185 will be rejected.
186
187SEE ALSO
188
189 Mojolicious, Mojolicious::Guides, https://mojolicious.org.
190
191AUTHORS
192
193 The "AUTHORS" in Mojolicious
194
195CONTACT
196
197 While this module is no longer receiving non-security related
198 maintenance, if you must contact someone about it please contact Joel
199 Berger <jberger@cpan.org> or as a last resort contact the Mojolicious
200 Core Team.
201
202COPYRIGHT AND LICENSE
203
204 Copyright (C) 2008-2021, Sebastian Riedel and others.
205
206 This program is free software, you can redistribute it and/or modify it
207 under the terms of the Artistic License version 2.0.
208
209