Mojo::IOLoop(3pm)

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

NAME

6       Mojo::IOLoop - Minimalistic Reactor For TCP Clients And Servers
7

SYNOPSIS

9           use Mojo::IOLoop;
10
11           # Create loop
12           my $loop = Mojo::IOLoop->new;
13
14           # Listen on port 3000
15           $loop->listen(
16               port => 3000,
17               read_cb => sub {
18                   my ($self, $id, $chunk) = @_;
19
20                   # Process input
21                   print $chunk;
22
23                   # Got some data, time to write
24                   $self->write($id, 'HTTP/1.1 200 OK');
25               }
26           );
27
28           # Connect to port 3000 with TLS activated
29           my $id = $loop->connect(
30               address => 'localhost',
31               port => 3000,
32               tls => 1,
33               connect_cb => sub {
34                   my ($self, $id) = @_;
35
36                   # Write request
37                   $self->write($id, "GET / HTTP/1.1\r\n\r\n");
38               },
39               read_cb => sub {
40                   my ($self, $id, $chunk) = @_;
41
42                   # Process input
43                   print $chunk;
44               }
45           );
46
47           # Add a timer
48           $loop->timer(5 => sub {
49               my $self = shift;
50               $self->drop($id);
51           });
52
53           # Start and stop loop
54           $loop->start;
55           $loop->stop;
56

DESCRIPTION

58       Mojo::IOLoop is a very minimalistic reactor that has been reduced to
59       the absolute minimal feature set required to build solid and scalable
60       TCP clients and servers.
61
62       Optional modules IO::KQueue, IO::Epoll, IO::Socket::INET6 and
63       IO::Socket::SSL are supported transparently and used if installed.
64
65       A TLS certificate and key are also built right in to make writing test
66       servers as easy as possible.
67

ATTRIBUTES

69       Mojo::IOLoop implements the following attributes.
70
71   "accept_timeout"
72           my $timeout = $loop->accept_timeout;
73           $loop       = $loop->accept_timeout(5);
74
75       Maximum time in seconds a connection can take to be accepted before
76       being dropped, defaults to 5.
77
78   "connect_timeout"
79           my $timeout = $loop->connect_timeout;
80           $loop       = $loop->connect_timeout(5);
81
82       Maximum time in seconds a conenction can take to be connected before
83       being dropped, defaults to 5.
84
85   "idle_cb"
86           my $cb = $loop->idle_cb;
87           $loop  = $loop->idle_cb(sub {...});
88
89       Callback to be invoked on every reactor tick if no events occurred.
90       Note that this attribute is EXPERIMENTAL and might change without
91       warning!
92
93   "lock_cb"
94           my $cb = $loop->lock_cb;
95           $loop  = $loop->lock_cb(sub {...});
96
97       A locking callback that decides if this loop is allowed to accept new
98       incoming connections, used to sync multiple server processes.  The
99       callback should return true or false.  Note that exceptions in this
100       callback are not captured.
101
102           $loop->lock_cb(sub {
103               my ($loop, $blocking) = @_;
104
105               # Got the lock, listen for new connections
106               return 1;
107           });
108
109   "max_connections"
110           my $max = $loop->max_connections;
111           $loop   = $loop->max_connections(1000);
112
113       The maximum number of connections this loop is allowed to handle before
114       stopping to accept new incoming connections, defaults to 1000.  Setting
115       the value to 0 will make this loop stop accepting new connections and
116       allow it to shutdown gracefully without interrupting existing
117       connections.
118
119   "tick_cb"
120           my $cb = $loop->tick_cb;
121           $loop  = $loop->tick_cb(sub {...});
122
123       Callback to be invoked on every reactor tick, this for example allows
124       you to run multiple reactors next to each other.
125
126           my $loop2 = Mojo::IOLoop->new(timeout => 0);
127           Mojo::IOLoop->singleton->tick_cb(sub { $loop2->one_tick });
128
129       Note that the loop timeout can be changed dynamically at any time to
130       adjust responsiveness.
131
132   "timeout"
133           my $timeout = $loop->timeout;
134           $loop       = $loop->timeout(5);
135
136       Maximum time in seconds our loop waits for new events to happen,
137       defaults to 0.25.  Note that a value of 0 would make the loop non
138       blocking.
139
140   "unlock_cb"
141           my $cb = $loop->unlock_cb;
142           $loop  = $loop->unlock_cb(sub {...});
143
144       A callback to free the accept lock, used to sync multiple server
145       processes.  Note that exceptions in this callback are not captured.
146

METHODS

148       Mojo::IOLoop inherits all methods from Mojo::Base and implements the
149       following new ones.
150
151   "new"
152           my $loop = Mojo::IOLoop->new;
153
154       Construct a new Mojo::IOLoop object.  Multiple of these will block each
155       other, so use "singleton" instead if possible.
156
157   "connect"
158           my $id = $loop->connect(
159               address => '127.0.0.1',
160               port    => 3000
161           );
162           my $id = $loop->connect({
163               address => '[::1]',
164               port    => 443,
165               tls     => 1
166           });
167
168       Open a TCP connection to a remote host, IPv6 will be used automatically
169       if available.  Note that IPv6 support depends on IO::Socket::INET6 and
170       TLS support on IO::Socket::SSL.
171
172       These options are currently available.
173
174       "address"
175           Address or host name of the peer to connect to.
176
177       "connect_cb"
178           Callback to be invoked once the connection is established.
179
180       "error_cb"
181           Callback to be invoked if an error event happens on the connection.
182
183       "hup_cb"
184           Callback to be invoked if the connection gets closed.
185
186       "port"
187           Port to connect to.
188
189       "read_cb"
190           Callback to be invoked if new data arrives on the connection.
191
192       "socket"
193           Use an already prepared socket handle.
194
195       "tls"
196           Enable TLS.
197
198       "tls_ca_file"
199           CA file to use for TLS.
200
201       "tls_verify_cb"
202           Callback to invoke for TLS verification.
203
204   "connection_timeout"
205           my $timeout = $loop->connection_timeout($id);
206           $loop       = $loop->connection_timeout($id => 45);
207
208       Maximum amount of time in seconds a connection can be inactive before
209       being dropped.
210
211   "drop"
212           $loop = $loop->drop($id);
213
214       Drop a connection, listen socket or timer.  Connections will be dropped
215       gracefully by allowing them to finish writing all data in it's write
216       buffer.
217
218   "error_cb"
219           $loop = $loop->error_cb($id => sub {...});
220
221       Callback to be invoked if an error event happens on the connection.
222
223   "generate_port"
224           my $port = $loop->generate_port;
225
226       Find a free TCP port, this is a utility function primarily used for
227       tests.
228
229   "hup_cb"
230           $loop = $loop->hup_cb($id => sub {...});
231
232       Callback to be invoked if the connection gets closed.
233
234   "is_running"
235           my $running = $loop->is_running;
236
237       Check if loop is running.
238
239           exit unless Mojo::IOLoop->singleton->is_running;
240
241   "listen"
242           my $id = $loop->listen(port => 3000);
243           my $id = $loop->listen({port => 3000});
244           my $id = $loop->listen(file => '/foo/myapp.sock');
245           my $id = $loop->listen(
246               port     => 443,
247               tls      => 1,
248               tls_cert => '/foo/server.cert',
249               tls_key  => '/foo/server.key'
250           );
251
252       Create a new listen socket, IPv6 will be used automatically if
253       available.  Note that IPv6 support depends on IO::Socket::INET6 and TLS
254       support on IO::Socket::SSL.
255
256       These options are currently available.
257
258       "address"
259           Local address to listen on, defaults to all.
260
261       "accept_cb"
262           Callback to invoke for each accepted connection.
263
264       "error_cb"
265           Callback to be invoked if an error event happens on the connection.
266
267       "file"
268           A unix domain socket to listen on.
269
270       "hup_cb"
271           Callback to be invoked if the connection gets closed.
272
273       "port"
274           Port to listen on.
275
276       "queue_size"
277           Maximum queue size, defaults to "SOMAXCONN".
278
279       "read_cb"
280           Callback to be invoked if new data arrives on the connection.
281
282       "tls"
283           Enable TLS.
284
285       "tls_cert"
286           Path to the TLS cert file, defaulting to a built in test
287           certificate.
288
289       "tls_key"
290           Path to the TLS key file, defaulting to a built in test key.
291
292   "local_info"
293           my $info = $loop->local_info($id);
294
295       Get local information about a connection.
296
297           my $address = $info->{address};
298
299       These values are to be expected in the returned hash reference.
300
301       "address"
302           The local address.
303
304       "port"
305           The local port.
306
307   "one_tick"
308           $loop->one_tick;
309           $loop->one_tick('0.25');
310           $loop->one_tick(0);
311
312       Run reactor for exactly one tick.
313
314   "read_cb"
315           $loop = $loop->read_cb($id => sub {...});
316
317       Callback to be invoked if new data arrives on the connection.
318
319           $loop->read_cb($id => sub {
320               my ($loop, $id, $chunk) = @_;
321
322               # Process chunk
323           });
324
325   "remote_info"
326           my $info = $loop->remote_info($id);
327
328       Get remote information about a connection.
329
330           my $address = $info->{address};
331
332       These values are to be expected in the returned hash reference.
333
334       "address"
335           The remote address.
336
337       "port"
338           The remote port.
339
340   "singleton"
341           my $loop = Mojo::IOLoop->singleton;
342
343       The global loop object, used to access a single shared loop instance
344       from everywhere inside the process.
345
346   "start"
347           $loop->start;
348
349       Start the loop, this will block until "stop" is called or return
350       immediately if the loop is already running.
351
352   "start_tls"
353           my $id = $loop->start_tls($id);
354           my $id = $loop->start_tls($id => {tls_ca_file => '/etc/tls/cacerts.pem'});
355
356       Start new TLS connection inside old connection.  Note that TLS support
357       depends on IO::Socket::SSL.
358
359       These options are currently available.
360
361       "tls_ca_file"
362           CA file to use for TLS.
363
364       "tls_verify_cb"
365           Callback to invoke for TLS verification.
366
367   "stop"
368           $loop->stop;
369
370       Stop the loop immediately, this will not interrupt any existing
371       connections and the loop can be restarted by running "start" again.
372
373   "timer"
374           my $id = $loop->timer(5 => sub {...});
375           my $id = $loop->timer(0.25 => sub {...});
376
377       Create a new timer, invoking the callback afer a given amount of
378       seconds.
379
380   "write"
381           $loop->write($id => 'Hello!');
382           $loop->write($id => 'Hello!', sub {...});
383
384       Write data to connection, the optional drain callback will be invoked
385       once all data has been written.
386

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

SEE ALSO