Mojo::IOLoop(3pm)

1Mojo::IOLoop(3)       User Contributed Perl Documentation      Mojo::IOLoop(3)
2
3
4

NAME

6       Mojo::IOLoop - Minimalistic event loop
7

SYNOPSIS

9         use Mojo::IOLoop;
10
11         # Listen on port 3000
12         Mojo::IOLoop->server({port => 3000} => sub ($loop, $stream) {
13           $stream->on(read => sub ($stream, $bytes) {
14             # Process input chunk
15             say $bytes;
16
17             # Write response
18             $stream->write('HTTP/1.1 200 OK');
19           });
20         });
21
22         # Connect to port 3000
23         my $id = Mojo::IOLoop->client({port => 3000} => sub ($loop, $err, $stream) {
24           $stream->on(read => sub ($stream, $bytes) {
25             # Process input
26             say "Input: $bytes";
27           });
28
29           # Write request
30           $stream->write("GET / HTTP/1.1\x0d\x0a\x0d\x0a");
31         });
32
33         # Add a timer
34         Mojo::IOLoop->timer(5 => sub ($loop) { $loop->remove($id) });
35
36         # Start event loop if necessary
37         Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
38

DESCRIPTION

40       Mojo::IOLoop is a very minimalistic event loop based on Mojo::Reactor,
41       it has been reduced to the absolute minimal feature set required to
42       build solid and scalable non-blocking clients and servers.
43
44       Depending on operating system, the default per-process and system-wide
45       file descriptor limits are often very low and need to be tuned for
46       better scalability. The "LIBEV_FLAGS" environment variable should also
47       be used to select the best possible EV backend, which usually defaults
48       to the not very scalable "select".
49
50         LIBEV_FLAGS=1    # select
51         LIBEV_FLAGS=2    # poll
52         LIBEV_FLAGS=4    # epoll (Linux)
53         LIBEV_FLAGS=8    # kqueue (*BSD, OS X)
54         LIBEV_FLAGS=64   # Linux AIO
55
56       The event loop will be resilient to time jumps if a monotonic clock is
57       available through Time::HiRes. A TLS certificate and key are also built
58       right in, to make writing test servers as easy as possible. Also note
59       that for convenience the "PIPE" signal will be set to "IGNORE" when
60       Mojo::IOLoop is loaded.
61
62       For better scalability (epoll, kqueue) and to provide non-blocking name
63       resolution, SOCKS5 as well as TLS support, the optional modules EV
64       (4.32+), Net::DNS::Native (0.15+), IO::Socket::Socks (0.64+) and
65       IO::Socket::SSL (2.009+) will be used automatically if possible.
66       Individual features can also be disabled with the "MOJO_NO_NNR",
67       "MOJO_NO_SOCKS" and "MOJO_NO_TLS" environment variables.
68
69       See "REAL-TIME WEB" in Mojolicious::Guides::Cookbook for more.
70

EVENTS

72       Mojo::IOLoop inherits all events from Mojo::EventEmitter and can emit
73       the following new ones.
74
75   finish
76         $loop->on(finish => sub ($loop) {...});
77
78       Emitted when the event loop wants to shut down gracefully and is just
79       waiting for all existing connections to be closed.
80
81   reset
82         $loop->on(reset => sub ($loop) {...});
83
84       Emitted when the event loop is reset, this usually happens after the
85       process is forked to clean up resources that cannot be shared.
86

ATTRIBUTES

88       Mojo::IOLoop implements the following attributes.
89
90   max_accepts
91         my $max = $loop->max_accepts;
92         $loop   = $loop->max_accepts(1000);
93
94       The maximum number of connections this event loop is allowed to accept,
95       before shutting down gracefully without interrupting existing
96       connections, defaults to 0. Setting the value to 0 will allow this
97       event loop to accept new connections indefinitely. Note that up to half
98       of this value can be subtracted randomly to improve load balancing
99       between multiple server processes, and to make sure that not all of
100       them restart at the same time.
101
102   max_connections
103         my $max = $loop->max_connections;
104         $loop   = $loop->max_connections(100);
105
106       The maximum number of accepted connections this event loop is allowed
107       to handle concurrently, before stopping to accept new incoming
108       connections, defaults to 1000.
109
110   reactor
111         my $reactor = $loop->reactor;
112         $loop       = $loop->reactor(Mojo::Reactor->new);
113
114       Low-level event reactor, usually a Mojo::Reactor::Poll or
115       Mojo::Reactor::EV object with a default subscriber to the event "error"
116       in Mojo::Reactor.
117
118         # Watch if handle becomes readable or writable
119         Mojo::IOLoop->singleton->reactor->io($handle => sub ($reactor, $writable) {
120           say $writable ? 'Handle is writable' : 'Handle is readable';
121         });
122
123         # Change to watching only if handle becomes writable
124         Mojo::IOLoop->singleton->reactor->watch($handle, 0, 1);
125
126         # Remove handle again
127         Mojo::IOLoop->singleton->reactor->remove($handle);
128

METHODS

130       Mojo::IOLoop inherits all methods from Mojo::EventEmitter and
131       implements the following new ones.
132
133   acceptor
134         my $server = Mojo::IOLoop->acceptor($id);
135         my $server = $loop->acceptor($id);
136         my $id     = $loop->acceptor(Mojo::IOLoop::Server->new);
137
138       Get Mojo::IOLoop::Server object for id or turn object into an acceptor.
139
140   client
141         my $id = Mojo::IOLoop->client(address => '127.0.0.1', port => 3000, sub {...});
142         my $id = $loop->client(address => '127.0.0.1', port => 3000, sub {...});
143         my $id = $loop->client({address => '127.0.0.1', port => 3000} => sub {...});
144
145       Open a TCP/IP or UNIX domain socket connection with
146       Mojo::IOLoop::Client and create a stream object (usually
147       Mojo::IOLoop::Stream), takes the same arguments as "connect" in
148       Mojo::IOLoop::Client.
149
150   delay
151         my $delay = Mojo::IOLoop->delay;
152         my $delay = $loop->delay;
153         my $delay = $loop->delay(sub {...});
154         my $delay = $loop->delay(sub {...}, sub {...});
155
156       Build Mojo::IOLoop::Delay object to use as a promise and/or for flow-
157       control. Callbacks will be passed along to "steps" in
158       Mojo::IOLoop::Delay.
159
160         # Wrap continuation-passing style APIs with promises
161         my $ua = Mojo::UserAgent->new;
162         sub get {
163           my $promise = Mojo::IOLoop->delay;
164           $ua->get(@_ => sub ($ua, $tx) {
165             my $err = $tx->error;
166             if   (!$err || $err->{code}) { $promise->resolve($tx) }
167             else                         { $promise->reject($err->{message}) }
168           });
169           return $promise;
170         }
171         my $mojo = get('https://mojolicious.org');
172         my $cpan = get('https://metacpan.org');
173         Mojo::Promise->race($mojo, $cpan)->then(sub ($tx) { say $tx->req->url })->wait;
174
175         # Synchronize multiple non-blocking operations
176         my $delay = Mojo::IOLoop->delay(sub { say 'BOOM!' });
177         for my $i (1 .. 10) {
178           my $end = $delay->begin;
179           Mojo::IOLoop->timer($i => sub {
180             say 10 - $i;
181             $end->();
182           });
183         }
184         $delay->wait;
185
186         # Sequentialize multiple non-blocking operations
187         Mojo::IOLoop->delay(
188
189           # First step (simple timer)
190           sub ($delay) {
191             Mojo::IOLoop->timer(2 => $delay->begin);
192             say 'Second step in 2 seconds.';
193           },
194
195           # Second step (concurrent timers)
196           sub ($delay) {
197             Mojo::IOLoop->timer(1 => $delay->begin);
198             Mojo::IOLoop->timer(3 => $delay->begin);
199             say 'Third step in 3 seconds.';
200           },
201
202           # Third step (the end)
203           sub { say 'And done after 5 seconds total.' }
204         )->wait;
205
206   is_running
207         my $bool = Mojo::IOLoop->is_running;
208         my $bool = $loop->is_running;
209
210       Check if event loop is running.
211
212   next_tick
213         my $undef = Mojo::IOLoop->next_tick(sub ($loop) {...});
214         my $undef = $loop->next_tick(sub ($loop) {...});
215
216       Execute callback as soon as possible, but not before returning or other
217       callbacks that have been registered with this method, always returns
218       "undef".
219
220         # Perform operation on next reactor tick
221         Mojo::IOLoop->next_tick(sub ($loop) {...});
222
223   one_tick
224         Mojo::IOLoop->one_tick;
225         $loop->one_tick;
226
227       Run event loop until an event occurs.
228
229         # Don't block longer than 0.5 seconds
230         my $id = Mojo::IOLoop->timer(0.5 => sub ($loop) {});
231         Mojo::IOLoop->one_tick;
232         Mojo::IOLoop->remove($id);
233
234   recurring
235         my $id = Mojo::IOLoop->recurring(3 => sub ($loop) {...});
236         my $id = $loop->recurring(0 => sub ($loop) {...});
237         my $id = $loop->recurring(0.25 => sub ($loop) {...});
238
239       Create a new recurring timer, invoking the callback repeatedly after a
240       given amount of time in seconds.
241
242         # Perform operation every 5 seconds
243         Mojo::IOLoop->recurring(5 => sub ($loop) {...});
244
245   remove
246         Mojo::IOLoop->remove($id);
247         $loop->remove($id);
248
249       Remove anything with an id, connections will be dropped gracefully by
250       allowing them to finish writing all data in their write buffers.
251
252   reset
253         Mojo::IOLoop->reset;
254         $loop->reset;
255         $loop->reset({freeze => 1});
256
257       Remove everything and stop the event loop.
258
259       These options are currently available:
260
261       freeze
262           freeze => 1
263
264         Freeze the current state of the event loop in time before resetting
265         it. This will prevent active connections from getting closed
266         immediately, which can help with many unintended side effects when
267         processes are forked. Note that this option is EXPERIMENTAL and might
268         change without warning!
269
270   server
271         my $id = Mojo::IOLoop->server(port => 3000, sub {...});
272         my $id = $loop->server(port => 3000, sub {...});
273         my $id = $loop->server({port => 3000} => sub {...});
274
275       Accept TCP/IP and UNIX domain socket connections with
276       Mojo::IOLoop::Server and create stream objects (usually
277       Mojo::IOLoop::Stream, takes the same arguments as "listen" in
278       Mojo::IOLoop::Server.
279
280         # Listen on random port
281         my $id = Mojo::IOLoop->server({address => '127.0.0.1'} => sub ($loop, $stream, $id) {...});
282         my $port = Mojo::IOLoop->acceptor($id)->port;
283
284   singleton
285         my $loop = Mojo::IOLoop->singleton;
286
287       The global Mojo::IOLoop singleton, used to access a single shared event
288       loop object from everywhere inside the process.
289
290         # Many methods also allow you to take shortcuts
291         Mojo::IOLoop->timer(2 => sub { Mojo::IOLoop->stop });
292         Mojo::IOLoop->start;
293
294         # Restart active timer
295         my $id = Mojo::IOLoop->timer(3 => sub { say 'Timeout!' });
296         Mojo::IOLoop->singleton->reactor->again($id);
297
298         # Turn file descriptor into handle and watch if it becomes readable
299         my $handle = IO::Handle->new_from_fd($fd, 'r');
300         Mojo::IOLoop->singleton->reactor->io($handle => sub ($reactor, $writable) {
301           say $writable ? 'Handle is writable' : 'Handle is readable';
302         })->watch($handle, 1, 0);
303
304   start
305         Mojo::IOLoop->start;
306         $loop->start;
307
308       Start the event loop, this will block until "stop" is called. Note that
309       some reactors stop automatically if there are no events being watched
310       anymore.
311
312         # Start event loop only if it is not running already
313         Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
314
315   stop
316         Mojo::IOLoop->stop;
317         $loop->stop;
318
319       Stop the event loop, this will not interrupt any existing connections
320       and the event loop can be restarted by running "start" again.
321
322   stop_gracefully
323         Mojo::IOLoop->stop_gracefully;
324         $loop->stop_gracefully;
325
326       Stop accepting new connections and wait for already accepted
327       connections to be closed, before stopping the event loop.
328
329   stream
330         my $stream = Mojo::IOLoop->stream($id);
331         my $stream = $loop->stream($id);
332         my $id     = $loop->stream(Mojo::IOLoop::Stream->new);
333
334       Get Mojo::IOLoop::Stream object for id or turn object into a
335       connection.
336
337         # Increase inactivity timeout for connection to 300 seconds
338         Mojo::IOLoop->stream($id)->timeout(300);
339
340   subprocess
341         my $subprocess = Mojo::IOLoop->subprocess;
342         my $subprocess = $loop->subprocess;
343         my $subprocess = $loop->subprocess(sub ($subprocess) {...}, sub ($subprocess, $err, @results) {...});
344
345       Build Mojo::IOLoop::Subprocess object to perform computationally
346       expensive operations in subprocesses, without blocking the event loop.
347       Callbacks will be passed along to "run" in Mojo::IOLoop::Subprocess.
348
349         # Operation that would block the event loop for 5 seconds
350         Mojo::IOLoop->subprocess->run_p(sub {
351           sleep 5;
352           return '♥', 'Mojolicious';
353         })->then(sub (@results) {
354           say "I $results[0] $results[1]!";
355         })->catch(sub ($err) {
356           say "Subprocess error: $err";
357         });
358
359   timer
360         my $id = Mojo::IOLoop->timer(3 => sub ($loop) {...});
361         my $id = $loop->timer(0 => sub ($loop) {...});
362         my $id = $loop->timer(0.25 => sub ($loop) {...});
363
364       Create a new timer, invoking the callback after a given amount of time
365       in seconds.
366
367         # Perform operation in 5 seconds
368         Mojo::IOLoop->timer(5 => sub ($loop) {...});
369

DEBUGGING

371       You can set the "MOJO_IOLOOP_DEBUG" environment variable to get some
372       advanced diagnostics information printed to "STDERR".
373
374         MOJO_IOLOOP_DEBUG=1
375