1IO::Async::Loop(3) User Contributed Perl Documentation IO::Async::Loop(3)
2
6 "IO::Async::Loop" - core loop of the "IO::Async" framework
7
9 use IO::Async::Stream;
10 use IO::Async::Timer::Countdown;
11 use IO::Async::Loop;
13 my $loop = IO::Async::Loop->new;
15 $loop->add( IO::Async::Timer::Countdown->new(
17 delay => 10,
18 on_expire => sub { print "10 seconds have passed\n" },
19 )->start );
20 $loop->add( IO::Async::Stream->new_for_stdin(
22 on_read => sub {
23 my ( $self, $buffref, $eof ) = @_;
24 while( $$buffref =~ s/^(.*)\n// ) {
26 print "You typed a line $1\n";
27 }
28 return 0;
30 },
31 ) );
32 $loop->run;
34
36 This module provides an abstract class which implements the core loop
37 of the IO::Async framework. Its primary purpose is to store a set of
38 IO::Async::Notifier objects or subclasses of them. It handles all of
39 the lower-level set manipulation actions, and leaves the actual IO
40 readiness testing/notification to the concrete class that implements
41 it. It also provides other functionality such as signal handling, child
42 process managing, and timers.
43 See also the two bundled Loop subclasses:
45 IO::Async::Loop::Select
47 IO::Async::Loop::Poll
48 Or other subclasses that may appear on CPAN which are not part of the
50 core IO::Async distribution.
51 Ignoring SIGPIPE
53 Since version 0.66 loading this module automatically ignores "SIGPIPE",
54 as it is highly unlikely that the default-terminate action is the best
55 course of action for an IO::Async-based program to take. If at load
56 time the handler disposition is still set as "DEFAULT", it is set to
57 ignore. If already another handler has been placed there by the program
58 code, it will be left undisturbed.
59
61 new
62 $loop = IO::Async::Loop->new
63 This function attempts to find a good subclass to use, then calls its
65 constructor. It works by making a list of likely candidate classes,
66 then trying each one in turn, "require"ing the module then calling its
67 "new" method. If either of these operations fails, the next subclass is
68 tried. If no class was successful, then an exception is thrown.
69 The constructed object is cached, and will be returned again by a
71 subsequent call. The cache will also be set by a constructor on a
72 specific subclass. This behaviour makes it possible to simply use the
73 normal constructor in a module that wishes to interact with the main
74 program's Loop, such as an integration module for another event system.
75 For example, the following two $loop variables will refer to the same
77 object:
78 use IO::Async::Loop;
80 use IO::Async::Loop::Poll;
81 my $loop_poll = IO::Async::Loop::Poll->new;
83 my $loop = IO::Async::Loop->new;
85 While it is not advised to do so under normal circumstances, if the
87 program really wishes to construct more than one Loop object, it can
88 call the constructor "really_new", or invoke one of the subclass-
89 specific constructors directly.
90 The list of candidates is formed from the following choices, in this
92 order:
93 • $ENV{IO_ASYNC_LOOP}
95 If this environment variable is set, it should contain a comma-
97 separated list of subclass names. These names may or may not be
98 fully-qualified; if a name does not contain "::" then it will have
99 "IO::Async::Loop::" prepended to it. This allows the end-user to
100 specify a particular choice to fit the needs of his use of a
101 program using IO::Async.
102 • $IO::Async::Loop::LOOP
104 If this scalar is set, it should contain a comma-separated list of
106 subclass names. These may or may not be fully-qualified, as with
107 the above case. This allows a program author to suggest a loop
108 module to use.
109 In cases where the module subclass is a hard requirement, such as
111 GTK programs using "Glib", it would be better to use the module
112 specifically and invoke its constructor directly.
113 • IO::Async::OS->LOOP_PREFER_CLASSES
115 The IO::Async::OS hints module for the given OS is then consulted
117 to see if it suggests any other module classes specific to the
118 given operating system.
119 • $^O
121 The module called "IO::Async::Loop::$^O" is tried next. This allows
123 specific OSes, such as the ever-tricky "MSWin32", to provide an
124 implementation that might be more efficient than the generic ones,
125 or even work at all.
126 This option is now discouraged in favour of the IO::Async::OS hint
128 instead. At some future point it may be removed entirely, given as
129 currently only "linux" uses it.
130 • Poll and Select
132 Finally, if no other choice has been made by now, the built-in
134 "Poll" module is chosen. This should always work, but in case it
135 doesn't, the "Select" module will be chosen afterwards as a last-
136 case attempt. If this also fails, then the magic constructor itself
137 will throw an exception.
138 If any of the explicitly-requested loop types ($ENV{IO_ASYNC_LOOP} or
140 $IO::Async::Loop::LOOP) fails to load then a warning is printed
141 detailing the error.
142 Implementors of new "IO::Async::Loop" subclasses should see the notes
144 about "API_VERSION" below.
145
147 The following methods manage the collection of IO::Async::Notifier
148 objects.
149 add
151 $loop->add( $notifier )
152 This method adds another notifier object to the stored collection. The
154 object may be a IO::Async::Notifier, or any subclass of it.
155 When a notifier is added, any children it has are also added,
157 recursively. In this way, entire sections of a program may be written
158 within a tree of notifier objects, and added or removed on one piece.
159 remove
161 $loop->remove( $notifier )
162 This method removes a notifier object from the stored collection, and
164 recursively and children notifiers it contains.
165 notifiers
167 @notifiers = $loop->notifiers
168 Returns a list of all the notifier objects currently stored in the
170 Loop.
171
173 The following methods control the actual run cycle of the loop, and
174 hence the program.
175 loop_once
177 $count = $loop->loop_once( $timeout )
178 This method performs a single wait loop using the specific subclass's
180 underlying mechanism. If $timeout is undef, then no timeout is applied,
181 and it will wait until an event occurs. The intention of the return
182 value is to indicate the number of callbacks that this loop executed,
183 though different subclasses vary in how accurately they can report
184 this. See the documentation for this method in the specific subclass
185 for more information.
186 run
188 @result = $loop->run
189 $result = $loop->run
191 Runs the actual IO event loop. This method blocks until the "stop"
193 method is called, and returns the result that was passed to "stop". In
194 scalar context only the first result is returned; the others will be
195 discarded if more than one value was provided. This method may be
196 called recursively.
197 This method is a recent addition and may not be supported by all the
199 "IO::Async::Loop" subclasses currently available on CPAN.
200 stop
202 $loop->stop( @result )
203 Stops the inner-most "run" method currently in progress, causing it to
205 return the given @result.
206 This method is a recent addition and may not be supported by all the
208 "IO::Async::Loop" subclasses currently available on CPAN.
209 loop_forever
211 $loop->loop_forever
212 A synonym for "run", though this method does not return a result.
214 loop_stop
216 $loop->loop_stop
217 A synonym for "stop", though this method does not pass any results.
219 post_fork
221 $loop->post_fork
222 The base implementation of this method does nothing. It is provided in
224 case some Loop subclasses should take special measures after a "fork()"
225 system call if the main body of the program should survive in both
226 running processes.
227 This may be required, for example, in a long-running server daemon that
229 forks multiple copies on startup after opening initial listening
230 sockets. A loop implementation that uses some in-kernel resource that
231 becomes shared after forking (for example, a Linux "epoll" or a BSD
232 "kqueue" filehandle) would need recreating in the new child process
233 before the program can continue.
234
236 The following methods relate to IO::Async::Future objects.
237 new_future
239 $future = $loop->new_future
240 Returns a new IO::Async::Future instance with a reference to the Loop.
242 await
244 $loop->await( $future )
245 Blocks until the given future is ready, as indicated by its "is_ready"
247 method. As a convenience it returns the future, to simplify code:
248 my @result = $loop->await( $future )->get;
250 await_all
252 $loop->await_all( @futures )
253 Blocks until all the given futures are ready, as indicated by the
255 "is_ready" method. Equivalent to calling "await" on a
256 "Future->wait_all" except that it doesn't create the surrounding future
257 object.
258 delay_future
260 $loop->delay_future( %args )->get
261 Returns a new IO::Async::Future instance which will become done at a
263 given point in time. The %args should contain an "at" or "after" key as
264 per the "watch_time" method. The returned future may be cancelled to
265 cancel the timer. At the alloted time the future will succeed with an
266 empty result list.
267 timeout_future
269 $loop->timeout_future( %args )->get
270 Returns a new IO::Async::Future instance which will fail at a given
272 point in time. The %args should contain an "at" or "after" key as per
273 the "watch_time" method. The returned future may be cancelled to cancel
274 the timer. At the alloted time, the future will fail with the string
275 "Timeout".
276
278 Most of the following methods are higher-level wrappers around base
279 functionality provided by the low-level API documented below. They may
280 be used by IO::Async::Notifier subclasses or called directly by the
281 program.
282 The following methods documented with a trailing call to "->get" return
284 Future instances.
285 attach_signal
287 $id = $loop->attach_signal( $signal, $code )
288 This method adds a new signal handler to watch the given signal. The
290 same signal can be attached to multiple times; its callback functions
291 will all be invoked, in no particular order.
292 The returned $id value can be used to identify the signal handler in
294 case it needs to be removed by the "detach_signal" method. Note that
295 this value may be an object reference, so if it is stored, it should be
296 released after it is cancelled, so the object itself can be freed.
297 $signal The name of the signal to attach to. This should be a bare name
299 like "TERM".
300 $code A CODE reference to the handling callback.
302 Attaching to "SIGCHLD" is not recommended because of the way all child
304 processes use it to report their termination. Instead, the
305 "watch_process" method should be used to watch for termination of a
306 given child process. A warning will be printed if "SIGCHLD" is passed
307 here, but in future versions of IO::Async this behaviour may be
308 disallowed altogether.
309 See also POSIX for the "SIGname" constants.
311 For a more flexible way to use signals from within Notifiers, see
313 instead the IO::Async::Signal object.
314 detach_signal
316 $loop->detach_signal( $signal, $id )
317 Removes a previously-attached signal handler.
319 $signal The name of the signal to remove from. This should be a bare
321 name like "TERM".
322 $id The value returned by the "attach_signal" method.
324 later
326 $loop->later( $code )
327 $f = $loop->later
329 Schedules a code reference to be invoked as soon as the current round
331 of IO operations is complete.
332 The code reference is never invoked immediately, though the loop will
334 not perform any blocking operations between when it is installed and
335 when it is invoked. It may call "select", "poll" or equivalent with a
336 zero-second timeout, and process any currently-pending IO conditions
337 before the code is invoked, but it will not block for a non-zero amount
338 of time.
339 This method is implemented using the "watch_idle" method, with the
341 "when" parameter set to "later". It will return an ID value that can be
342 passed to "unwatch_idle" if required.
343 Since version 0.78: If no $code value is passed, a Future will be
345 returned instead. This allows for constructs such as:
346 await $loop->later;
348 spawn_child
350 $loop->spawn_child( %params )
351 This method creates a new child process to run a given code block or
353 command. The %params hash takes the following keys:
354 command => ARRAY or STRING
356 Either a reference to an array containing the command and its
357 arguments, or a plain string containing the command. This value
358 is passed into perl's "exec" function.
359 code => CODE
361 A block of code to execute in the child process. It will be
362 called in scalar context inside an "eval" block.
363 setup => ARRAY
365 A reference to an array which gives file descriptors to set up
366 in the child process before running the code or command. See
367 below.
368 on_exit => CODE
370 A continuation to be called when the child processes exits. It
371 will be invoked in the following way:
372 $on_exit->( $pid, $exitcode, $dollarbang, $dollarat )
374 The second argument is passed the plain perl $? value.
376 Exactly one of the "command" or "code" keys must be specified.
378 If the "command" key is used, the given array or string is executed
380 using the "exec" function.
381 If the "code" key is used, the return value will be used as the exit(2)
383 code from the child if it returns (or 255 if it returned "undef" or
384 thows an exception).
385 Case | ($exitcode >> 8) | $dollarbang | $dollarat
387 --------------+------------------------+-------------+----------
388 exec succeeds | exit code from program | 0 | ""
389 exec fails | 255 | $! | ""
390 $code returns | return value | $! | ""
391 $code dies | 255 | $! | $@
392 It is usually more convenient to use the "open_process" method in
394 simple cases where an external program is being started in order to
395 interact with it via file IO, or even "run_child" when only the final
396 result is required, rather than interaction while it is running.
397 "setup" array
399 This array gives a list of file descriptor operations to perform in the
401 child process after it has been fork(2)ed from the parent, before
402 running the code or command. It consists of name/value pairs which are
403 ordered; the operations are performed in the order given.
404 fdn => ARRAY
406 Gives an operation on file descriptor n. The first element of
407 the array defines the operation to be performed:
408 [ 'close' ]
410 The file descriptor will be closed.
411 [ 'dup', $io ]
413 The file descriptor will be dup2(2)ed from the given IO
414 handle.
415 [ 'open', $mode, $file ]
417 The file descriptor will be opened from the named file in
418 the given mode. The $mode string should be in the form
419 usually given to the "open" function; such as '<' or '>>'.
420 [ 'keep' ]
422 The file descriptor will not be closed; it will be left as-
423 is.
424 A non-reference value may be passed as a shortcut, where it
426 would contain the name of the operation with no arguments (i.e.
427 for the "close" and "keep" operations).
428 IO => ARRAY
430 Shortcut for passing "fdn", where n is the fileno of the IO
431 reference. In this case, the key must be a reference that
432 implements the "fileno" method. This is mostly useful for
433 $handle => 'keep'
435 fdn => IO
437 A shortcut for the "dup" case given above.
438 stdin => ...
440 stdout => ...
441 stderr => ...
442 Shortcuts for "fd0", "fd1" and "fd2" respectively.
443 env => HASH
445 A reference to a hash to set as the child process's
446 environment.
447 Note that this will entirely set a new environment, completely
449 replacing the existing one. If you want to simply add new keys
450 or change the values of some keys without removing the other
451 existing ones, you can simply copy %ENV into the hash before
452 setting new keys:
453 env => {
455 %ENV,
456 ANOTHER => "key here",
457 }
458 nice => INT
460 Change the child process's scheduling priority using
461 "POSIX::nice".
462 chdir => STRING
464 Change the child process's working directory using "chdir".
465 setuid => INT
467 setgid => INT
468 Change the child process's effective UID or GID.
469 setgroups => ARRAY
471 Change the child process's groups list, to those groups whose
472 numbers are given in the ARRAY reference.
473 On most systems, only the privileged superuser change user or
475 group IDs. IO::Async will NOT check before detaching the child
476 process whether this is the case.
477 If setting both the primary GID and the supplementary groups
479 list, it is suggested to set the primary GID first. Moreover,
480 some operating systems may require that the supplementary
481 groups list contains the primary GID.
482 If no directions for what to do with "stdin", "stdout" and "stderr" are
484 given, a default of "keep" is implied. All other file descriptors will
485 be closed, unless a "keep" operation is given for them.
486 If "setuid" is used, be sure to place it after any other operations
488 that might require superuser privileges, such as "setgid" or opening
489 special files.
490 my ( $pipeRd, $pipeWr ) = IO::Async::OS->pipepair;
492 $loop->spawn_child(
493 command => "/usr/bin/my-command",
494 setup => [
496 stdin => [ "open", "<", "/dev/null" ],
497 stdout => $pipeWr,
498 stderr => [ "open", ">>", "/var/log/mycmd.log" ],
499 chdir => "/",
500 ]
501 on_exit => sub {
503 my ( $pid, $exitcode ) = @_;
504 my $status = ( $exitcode >> 8 );
505 print "Command exited with status $status\n";
506 },
507 );
508 $loop->spawn_child(
510 code => sub {
511 do_something; # executes in a child process
512 return 1;
513 },
514 on_exit => sub {
516 my ( $pid, $exitcode, $dollarbang, $dollarat ) = @_;
517 my $status = ( $exitcode >> 8 );
518 print "Child process exited with status $status\n";
519 print " OS error was $dollarbang, exception was $dollarat\n";
520 },
521 );
522 open_process
524 $process = $loop->open_process( %params )
525 Since version 0.72.
527 This creates a new child process to run the given code block or
529 command, and attaches filehandles to it that the parent will watch.
530 This method is a light wrapper around constructing a new
531 IO::Async::Process object, adding it to the loop, and returning it.
532 The %params hash is passed directly to the IO::Async::Process
534 constructor.
535 open_child
537 $pid = $loop->open_child( %params )
538 A back-compatibility wrapper to calling "open_process" and returning
540 the PID of the newly-constructed IO::Async::Process instance. The
541 "on_finish" continuation likewise will be invoked with the PID rather
542 than the process instance.
543 $on_finish->( $pid, $exitcode )
545 Similarly, a "on_error" continuation is accepted, though note its
547 arguments come in a different order to those of the Process's
548 "on_exception":
549 $on_error->( $pid, $exitcode, $errno, $exception )
551 This method should not be used in new code; instead use "open_process"
553 directly.
554 run_process
556 @results = $loop->run_process( %params )->get
557 ( $exitcode, $stdout ) = $loop->run_process( ... )->get # by default
559 Since version 0.73.
561 Creates a new child process to run the given code block or command,
563 optionally capturing its STDOUT and STDERR streams. By default the
564 returned future will yield the exit code and content of the STDOUT
565 stream, but the "capture" argument can be used to alter what is
566 requested and returned.
567 command => ARRAY or STRING
569 code => CODE
570 The command or code to run in the child process (as per the
571 "spawn_child" method)
572 stdin => STRING
574 Optional. String to pass in to the child process's STDIN
575 stream.
576 setup => ARRAY
578 Optional reference to an array to pass to the underlying
579 "spawn" method.
580 capture => ARRAY
582 Optional reference to an array giving a list of names of values
583 which should be returned by resolving future. Values will be
584 returned in the same order as in the list. Valid choices are:
585 "exitcode", "stdout", "stderr".
586 cancel_signal => STRING
588 Optional. Name (or number) of the signal to send to the process
589 if the returned future is cancelled. Defaults to "TERM". Use
590 empty string or zero disable sending a signal on cancellation.
591 fail_on_nonzero => BOOL
593 Optional. If true, the returned future will fail if the process
594 exits with a nonzero status. The failure will contain a
595 message, the "process" category name, and the capture values
596 that were requested.
597 Future->fail( $message, process => @captures )
599 This method is intended mainly as an IO::Async-compatible replacement
601 for the perl "readpipe" function (`backticks`), allowing it to replace
602 my $output = `command here`;
604 with
606 my ( $exitcode, $output ) = $loop->run_process(
608 command => "command here",
609 )->get;
610 my ( $exitcode, $stdout ) = $loop->run_process(
612 command => "/bin/ps",
613 )->get;
614 my $status = ( $exitcode >> 8 );
616 print "ps exited with status $status\n";
617 run_child
619 $pid = $loop->run_child( %params )
620 A back-compatibility wrapper for "run_process", returning the PID and
622 taking an "on_finish" continuation instead of returning a Future.
623 This creates a new child process to run the given code block or
625 command, capturing its STDOUT and STDERR streams. When the process
626 exits, a continuation is invoked being passed the exitcode, and content
627 of the streams.
628 Takes the following named arguments in addition to those taken by
630 "run_process":
631 on_finish => CODE
633 A continuation to be called when the child process exits and
634 closed its STDOUT and STDERR streams. It will be invoked in the
635 following way:
636 $on_finish->( $pid, $exitcode, $stdout, $stderr )
638 The second argument is passed the plain perl $? value.
640 This method should not be used in new code; instead use "run_process"
642 directly.
643 resolver
645 $loop->resolver
646 Returns the internally-stored IO::Async::Resolver object, used for name
648 resolution operations by the "resolve", "connect" and "listen" methods.
649 set_resolver
651 $loop->set_resolver( $resolver )
652 Sets the internally-stored IO::Async::Resolver object. In most cases
654 this method should not be required, but it may be used to provide an
655 alternative resolver for special use-cases.
656 resolve
658 @result = $loop->resolve( %params )->get
659 This method performs a single name resolution operation. It uses an
661 internally-stored IO::Async::Resolver object. For more detail, see the
662 "resolve" method on the IO::Async::Resolver class.
663 connect
665 $handle|$socket = $loop->connect( %params )->get
666 This method performs a non-blocking connection to a given address or
668 set of addresses, returning a IO::Async::Future which represents the
669 operation. On completion, the future will yield the connected socket
670 handle, or the given IO::Async::Handle object.
671 There are two modes of operation. Firstly, a list of addresses can be
673 provided which will be tried in turn. Alternatively as a convenience,
674 if a host and service name are provided instead of a list of addresses,
675 these will be resolved using the underlying loop's "resolve" method
676 into the list of addresses.
677 When attempting to connect to any among a list of addresses, there may
679 be failures among the first attempts, before a valid connection is
680 made. For example, the resolver may have returned some IPv6 addresses,
681 but only IPv4 routes are valid on the system. In this case, the first
682 connect(2) syscall will fail. This isn't yet a fatal error, if there
683 are more addresses to try, perhaps some IPv4 ones.
684 For this reason, it is possible that the operation eventually succeeds
686 even though some system calls initially fail. To be aware of individual
687 failures, the optional "on_fail" callback can be used. This will be
688 invoked on each individual socket(2) or connect(2) failure, which may
689 be useful for debugging or logging.
690 Because this module simply uses the "getaddrinfo" resolver, it will be
692 fully IPv6-aware if the underlying platform's resolver is. This allows
693 programs to be fully IPv6-capable.
694 In plain address mode, the %params hash takes the following keys:
696 addrs => ARRAY
698 Reference to an array of (possibly-multiple) address structures
699 to attempt to connect to. Each should be in the layout
700 described for "addr". Such a layout is returned by the
701 "getaddrinfo" named resolver.
702 addr => HASH or ARRAY
704 Shortcut for passing a single address to connect to; it may be
705 passed directly with this key, instead of in another array on
706 its own. This should be in a format recognised by
707 IO::Async::OS's "extract_addrinfo" method.
708 This example shows how to use the "Socket" functions to
710 construct one for TCP port 8001 on address 10.0.0.1:
711 $loop->connect(
713 addr => {
714 family => "inet",
715 socktype => "stream",
716 port => 8001,
717 ip => "10.0.0.1",
718 },
719 ...
720 );
721 This example shows another way to connect to a UNIX socket at
723 echo.sock.
724 $loop->connect(
726 addr => {
727 family => "unix",
728 socktype => "stream",
729 path => "echo.sock",
730 },
731 ...
732 );
733 peer => IO
735 Shortcut for constructing an address to connect to the given IO
736 handle, which must be a IO::Socket or subclass, and is presumed
737 to be a local listening socket (perhaps on "PF_UNIX" or
738 "PF_INET"). This is convenient for connecting to a local
739 filehandle, for example during a unit test or similar.
740 local_addrs => ARRAY
742 local_addr => HASH or ARRAY
743 Optional. Similar to the "addrs" or "addr" parameters, these
744 specify a local address or set of addresses to bind(2) the
745 socket to before connect(2)ing it.
746 When performing the resolution step too, the "addrs" or "addr" keys are
748 ignored, and instead the following keys are taken:
749 host => STRING
751 service => STRING
752 The hostname and service name to connect to.
753 local_host => STRING
755 local_service => STRING
756 Optional. The hostname and/or service name to bind(2) the
757 socket to locally before connecting to the peer.
758 family => INT
760 socktype => INT
761 protocol => INT
762 flags => INT
763 Optional. Other arguments to pass along with "host" and
764 "service" to the "getaddrinfo" call.
765 socktype => STRING
767 Optionally may instead be one of the values 'stream', 'dgram'
768 or 'raw' to stand for "SOCK_STREAM", "SOCK_DGRAM" or
769 "SOCK_RAW". This utility is provided to allow the caller to
770 avoid a separate "use Socket" only for importing these
771 constants.
772 It is necessary to pass the "socktype" hint to the resolver when
774 resolving the host/service names into an address, as some OS's
775 "getaddrinfo" functions require this hint. A warning is emitted if
776 neither "socktype" nor "protocol" hint is defined when performing a
777 "getaddrinfo" lookup. To avoid this warning while still specifying no
778 particular "socktype" hint (perhaps to invoke some OS-specific
779 behaviour), pass 0 as the "socktype" value.
780 In either case, it also accepts the following arguments:
782 handle => IO::Async::Handle
784 Optional. If given a IO::Async::Handle object or a subclass
785 (such as IO::Async::Stream or IO::Async::Socket its handle will
786 be set to the newly-connected socket on success, and that
787 handle used as the result of the future instead.
788 on_fail => CODE
790 Optional. After an individual socket(2) or connect(2) syscall
791 has failed, this callback is invoked to inform of the error. It
792 is passed the name of the syscall that failed, the arguments
793 that were passed to it, and the error it generated. I.e.
794 $on_fail->( "socket", $family, $socktype, $protocol, $! );
796 $on_fail->( "bind", $sock, $address, $! );
798 $on_fail->( "connect", $sock, $address, $! );
800 Because of the "try all" nature when given a list of multiple
802 addresses, this callback may be invoked multiple times, even
803 before an eventual success.
804 This method accepts an "extensions" parameter; see the "EXTENSIONS"
806 section below.
807 connect (void)
809 $loop->connect( %params )
810 When not returning a future, additional parameters can be given
812 containing the continuations to invoke on success or failure.
813 on_connected => CODE
815 A continuation that is invoked on a successful connect(2) call
816 to a valid socket. It will be passed the connected socket
817 handle, as an "IO::Socket" object.
818 $on_connected->( $handle )
820 on_stream => CODE
822 An alternative to "on_connected", a continuation that is passed
823 an instance of IO::Async::Stream when the socket is connected.
824 This is provided as a convenience for the common case that a
825 Stream object is required as the transport for a Protocol
826 object.
827 $on_stream->( $stream )
829 on_socket => CODE
831 Similar to "on_stream", but constructs an instance of
832 IO::Async::Socket. This is most useful for "SOCK_DGRAM" or
833 "SOCK_RAW" sockets.
834 $on_socket->( $socket )
836 on_connect_error => CODE
838 A continuation that is invoked after all of the addresses have
839 been tried, and none of them succeeded. It will be passed the
840 most significant error that occurred, and the name of the
841 operation it occurred in. Errors from the connect(2) syscall
842 are considered most significant, then bind(2), then finally
843 socket(2).
844 $on_connect_error->( $syscall, $! )
846 on_resolve_error => CODE
848 A continuation that is invoked when the name resolution attempt
849 fails. This is invoked in the same way as the "on_error"
850 continuation for the "resolve" method.
851 listen
853 $listener = $loop->listen( %params )->get
854 This method sets up a listening socket and arranges for an acceptor
856 callback to be invoked each time a new connection is accepted on the
857 socket. Internally it creates an instance of IO::Async::Listener and
858 adds it to the Loop if not given one in the arguments.
859 Addresses may be given directly, or they may be looked up using the
861 system's name resolver, or a socket handle may be given directly.
862 If multiple addresses are given, or resolved from the service and
864 hostname, then each will be attempted in turn until one succeeds.
865 In named resolver mode, the %params hash takes the following keys:
867 service => STRING
869 The service name to listen on.
870 host => STRING
872 The hostname to listen on. Optional. Will listen on all
873 addresses if not supplied.
874 family => INT
876 socktype => INT
877 protocol => INT
878 flags => INT
879 Optional. Other arguments to pass along with "host" and
880 "service" to the "getaddrinfo" call.
881 socktype => STRING
883 Optionally may instead be one of the values 'stream', 'dgram'
884 or 'raw' to stand for "SOCK_STREAM", "SOCK_DGRAM" or
885 "SOCK_RAW". This utility is provided to allow the caller to
886 avoid a separate "use Socket" only for importing these
887 constants.
888 It is necessary to pass the "socktype" hint to the resolver when
890 resolving the host/service names into an address, as some OS's
891 "getaddrinfo" functions require this hint. A warning is emitted if
892 neither "socktype" nor "protocol" hint is defined when performing a
893 "getaddrinfo" lookup. To avoid this warning while still specifying no
894 particular "socktype" hint (perhaps to invoke some OS-specific
895 behaviour), pass 0 as the "socktype" value.
896 In plain address mode, the %params hash takes the following keys:
898 addrs => ARRAY
900 Reference to an array of (possibly-multiple) address structures
901 to attempt to listen on. Each should be in the layout described
902 for "addr". Such a layout is returned by the "getaddrinfo"
903 named resolver.
904 addr => ARRAY
906 Shortcut for passing a single address to listen on; it may be
907 passed directly with this key, instead of in another array of
908 its own. This should be in a format recognised by
909 IO::Async::OS's "extract_addrinfo" method. See also the
910 "EXAMPLES" section.
911 In direct socket handle mode, the following keys are taken:
913 handle => IO
915 The listening socket handle.
916 In either case, the following keys are also taken:
918 on_fail => CODE
920 Optional. A callback that is invoked if a syscall fails while
921 attempting to create a listening sockets. It is passed the name
922 of the syscall that failed, the arguments that were passed to
923 it, and the error generated. I.e.
924 $on_fail->( "socket", $family, $socktype, $protocol, $! );
926 $on_fail->( "sockopt", $sock, $optname, $optval, $! );
928 $on_fail->( "bind", $sock, $address, $! );
930 $on_fail->( "listen", $sock, $queuesize, $! );
932 queuesize => INT
934 Optional. The queue size to pass to the listen(2) calls. If not
935 supplied, then 3 will be given instead.
936 reuseaddr => BOOL
938 Optional. If true or not supplied then the "SO_REUSEADDR"
939 socket option will be set. To prevent this, pass a false value
940 such as 0.
941 v6only => BOOL
943 Optional. If defined, sets or clears the "IPV6_V6ONLY" socket
944 option on "PF_INET6" sockets. This option disables the ability
945 of "PF_INET6" socket to accept connections from "AF_INET"
946 addresses. Not all operating systems allow this option to be
947 disabled.
948 An alternative which gives more control over the listener, is to create
950 the IO::Async::Listener object directly and add it explicitly to the
951 Loop.
952 This method accepts an "extensions" parameter; see the "EXTENSIONS"
954 section below.
955 listen (void)
957 $loop->listen( %params )
958 When not returning a future, additional parameters can be given
960 containing the continuations to invoke on success or failure.
961 on_notifier => CODE
963 Optional. A callback that is invoked when the Listener object
964 is ready to receive connections. The callback is passed the
965 Listener object itself.
966 $on_notifier->( $listener )
968 If this callback is required, it may instead be better to
970 construct the Listener object directly.
971 on_listen => CODE
973 Optional. A callback that is invoked when the listening socket
974 is ready. Typically this would be used in the name resolver
975 case, in order to inspect the socket's sockname address, or
976 otherwise inspect the filehandle.
977 $on_listen->( $socket )
979 on_listen_error => CODE
981 A continuation this is invoked after all of the addresses have
982 been tried, and none of them succeeded. It will be passed the
983 most significant error that occurred, and the name of the
984 operation it occurred in. Errors from the listen(2) syscall are
985 considered most significant, then bind(2), then sockopt(2),
986 then finally socket(2).
987 on_resolve_error => CODE
989 A continuation that is invoked when the name resolution attempt
990 fails. This is invoked in the same way as the "on_error"
991 continuation for the "resolve" method.
992
994 Because the Magic Constructor searches for OS-specific subclasses of
995 the Loop, several abstractions of OS services are provided, in case
996 specific OSes need to give different implementations on that OS.
997 signame2num
999 $signum = $loop->signame2num( $signame )
1000 Legacy wrappers around IO::Async::OS functions.
1002 time
1004 $time = $loop->time
1005 Returns the current UNIX time in fractional seconds. This is currently
1007 equivalent to "Time::HiRes::time" but provided here as a utility for
1008 programs to obtain the time current used by IO::Async for its own
1009 timing purposes.
1010 fork
1012 $pid = $loop->fork( %params )
1013 This method creates a new child process to run a given code block,
1015 returning its process ID.
1016 code => CODE
1018 A block of code to execute in the child process. It will be
1019 called in scalar context inside an "eval" block. The return
1020 value will be used as the exit(2) code from the child if it
1021 returns (or 255 if it returned "undef" or thows an exception).
1022 on_exit => CODE
1024 A optional continuation to be called when the child processes
1025 exits. It will be invoked in the following way:
1026 $on_exit->( $pid, $exitcode )
1028 The second argument is passed the plain perl $? value.
1030 This key is optional; if not supplied, the calling code should
1032 install a handler using the "watch_process" method.
1033 keep_signals => BOOL
1035 Optional boolean. If missing or false, any CODE references in
1036 the %SIG hash will be removed and restored back to "DEFAULT" in
1037 the child process. If true, no adjustment of the %SIG hash will
1038 be performed.
1039 create_thread
1041 $tid = $loop->create_thread( %params )
1042 This method creates a new (non-detached) thread to run the given code
1044 block, returning its thread ID.
1045 code => CODE
1047 A block of code to execute in the thread. It is called in the
1048 context given by the "context" argument, and its return value
1049 will be available to the "on_joined" callback. It is called
1050 inside an "eval" block; if it fails the exception will be
1051 caught.
1052 context => "scalar" | "list" | "void"
1054 Optional. Gives the calling context that "code" is invoked in.
1055 Defaults to "scalar" if not supplied.
1056 on_joined => CODE
1058 Callback to invoke when the thread function returns or throws
1059 an exception. If it returned, this callback will be invoked
1060 with its result
1061 $on_joined->( return => @result )
1063 If it threw an exception the callback is invoked with the value
1065 of $@
1066 $on_joined->( died => $! )
1068
1070 As "IO::Async::Loop" is an abstract base class, specific subclasses of
1071 it are required to implement certain methods that form the base level
1072 of functionality. They are not recommended for applications to use; see
1073 instead the various event objects or higher level methods listed above.
1074 These methods should be considered as part of the interface contract
1076 required to implement a "IO::Async::Loop" subclass.
1077 API_VERSION
1079 IO::Async::Loop->API_VERSION
1080 This method will be called by the magic constructor on the class before
1082 it is constructed, to ensure that the specific implementation will
1083 support the required API. This method should return the API version
1084 that the loop implementation supports. The magic constructor will use
1085 that class, provided it declares a version at least as new as the
1086 version documented here.
1087 The current API version is 0.49.
1089 This method may be implemented using "constant"; e.g
1091 use constant API_VERSION => '0.49';
1093 watch_io
1095 $loop->watch_io( %params )
1096 This method installs callback functions which will be invoked when the
1098 given IO handle becomes read- or write-ready.
1099 The %params hash takes the following keys:
1101 handle => IO
1103 The IO handle to watch.
1104 on_read_ready => CODE
1106 Optional. A CODE reference to call when the handle becomes
1107 read-ready.
1108 on_write_ready => CODE
1110 Optional. A CODE reference to call when the handle becomes
1111 write-ready.
1112 There can only be one filehandle of any given fileno registered at any
1114 one time. For any one filehandle, there can only be one read-readiness
1115 and/or one write-readiness callback at any one time. Registering a new
1116 one will remove an existing one of that type. It is not required that
1117 both are provided.
1118 Applications should use a IO::Async::Handle or IO::Async::Stream
1120 instead of using this method.
1121 If the filehandle does not yet have the "O_NONBLOCK" flag set, it will
1123 be enabled by this method. This will ensure that any subsequent
1124 "sysread", "syswrite", or similar will not block on the filehandle.
1125 unwatch_io
1127 $loop->unwatch_io( %params )
1128 This method removes a watch on an IO handle which was previously
1130 installed by "watch_io".
1131 The %params hash takes the following keys:
1133 handle => IO
1135 The IO handle to remove the watch for.
1136 on_read_ready => BOOL
1138 If true, remove the watch for read-readiness.
1139 on_write_ready => BOOL
1141 If true, remove the watch for write-readiness.
1142 Either or both callbacks may be removed at once. It is not an error to
1144 attempt to remove a callback that is not present. If both callbacks
1145 were provided to the "watch_io" method and only one is removed by this
1146 method, the other shall remain.
1147 watch_signal
1149 $loop->watch_signal( $signal, $code )
1150 This method adds a new signal handler to watch the given signal.
1152 $signal The name of the signal to watch to. This should be a bare name
1154 like "TERM".
1155 $code A CODE reference to the handling callback.
1157 There can only be one callback per signal name. Registering a new one
1159 will remove an existing one.
1160 Applications should use a IO::Async::Signal object, or call
1162 "attach_signal" instead of using this method.
1163 This and "unwatch_signal" are optional; a subclass may implement
1165 neither, or both. If it implements neither then signal handling will be
1166 performed by the base class using a self-connected pipe to interrupt
1167 the main IO blocking.
1168 unwatch_signal
1170 $loop->unwatch_signal( $signal )
1171 This method removes the signal callback for the given signal.
1173 $signal The name of the signal to watch to. This should be a bare name
1175 like "TERM".
1176 watch_time
1178 $id = $loop->watch_time( %args )
1179 This method installs a callback which will be called at the specified
1181 time. The time may either be specified as an absolute value (the "at"
1182 key), or as a delay from the time it is installed (the "after" key).
1183 The returned $id value can be used to identify the timer in case it
1185 needs to be cancelled by the "unwatch_time" method. Note that this
1186 value may be an object reference, so if it is stored, it should be
1187 released after it has been fired or cancelled, so the object itself can
1188 be freed.
1189 The %params hash takes the following keys:
1191 at => NUM
1193 The absolute system timestamp to run the event.
1194 after => NUM
1196 The delay after now at which to run the event, if "at" is not
1197 supplied. A zero or negative delayed timer should be executed
1198 as soon as possible; the next time the "loop_once" method is
1199 invoked.
1200 now => NUM
1202 The time to consider as now if calculating an absolute time
1203 based on "after"; defaults to "time()" if not specified.
1204 code => CODE
1206 CODE reference to the continuation to run at the allotted time.
1207 Either one of "at" or "after" is required.
1209 For more powerful timer functionality as a IO::Async::Notifier (so it
1211 can be used as a child within another Notifier), see instead the
1212 IO::Async::Timer object and its subclasses.
1213 These *_time methods are optional; a subclass may implement neither or
1215 both of them. If it implements neither, then the base class will manage
1216 a queue of timer events. This queue should be handled by the
1217 "loop_once" method implemented by the subclass, using the
1218 "_adjust_timeout" and "_manage_queues" methods.
1219 This is the newer version of the API, replacing "enqueue_timer". It is
1221 unspecified how this method pair interacts with the older
1222 "enqueue/requeue/cancel_timer" triplet.
1223 unwatch_time
1225 $loop->unwatch_time( $id )
1226 Removes a timer callback previously created by "watch_time".
1228 This is the newer version of the API, replacing "cancel_timer". It is
1230 unspecified how this method pair interacts with the older
1231 "enqueue/requeue/cancel_timer" triplet.
1232 enqueue_timer
1234 $id = $loop->enqueue_timer( %params )
1235 An older version of "watch_time". This method should not be used in new
1237 code but is retained for legacy purposes. For simple watch/unwatch
1238 behaviour use instead the new "watch_time" method; though note it has
1239 differently-named arguments. For requeueable timers, consider using an
1240 IO::Async::Timer::Countdown or IO::Async::Timer::Absolute instead.
1241 cancel_timer
1243 $loop->cancel_timer( $id )
1244 An older version of "unwatch_time". This method should not be used in
1246 new code but is retained for legacy purposes.
1247 requeue_timer
1249 $newid = $loop->requeue_timer( $id, %params )
1250 Reschedule an existing timer, moving it to a new time. The old timer is
1252 removed and will not be invoked.
1253 The %params hash takes the same keys as "enqueue_timer", except for the
1255 "code" argument.
1256 The requeue operation may be implemented as a cancel + enqueue, which
1258 may mean the ID changes. Be sure to store the returned $newid value if
1259 it is required.
1260 This method should not be used in new code but is retained for legacy
1262 purposes. For requeueable, consider using an
1263 IO::Async::Timer::Countdown or IO::Async::Timer::Absolute instead.
1264 watch_idle
1266 $id = $loop->watch_idle( %params )
1267 This method installs a callback which will be called at some point in
1269 the near future.
1270 The %params hash takes the following keys:
1272 when => STRING
1274 Specifies the time at which the callback will be invoked. See
1275 below.
1276 code => CODE
1278 CODE reference to the continuation to run at the allotted time.
1279 The "when" parameter defines the time at which the callback will later
1281 be invoked. Must be one of the following values:
1282 later Callback is invoked after the current round of IO events have
1284 been processed by the loop's underlying "loop_once" method.
1285 If a new idle watch is installed from within a "later"
1287 callback, the installed one will not be invoked during this
1288 round. It will be deferred for the next time "loop_once" is
1289 called, after any IO events have been handled.
1290 If there are pending idle handlers, then the "loop_once" method will
1292 use a zero timeout; it will return immediately, having processed any IO
1293 events and idle handlers.
1294 The returned $id value can be used to identify the idle handler in case
1296 it needs to be removed, by calling the "unwatch_idle" method. Note this
1297 value may be a reference, so if it is stored it should be released
1298 after the callback has been invoked or cancled, so the referrant itself
1299 can be freed.
1300 This and "unwatch_idle" are optional; a subclass may implement neither,
1302 or both. If it implements neither then idle handling will be performed
1303 by the base class, using the "_adjust_timeout" and "_manage_queues"
1304 methods.
1305 unwatch_idle
1307 $loop->unwatch_idle( $id )
1308 Cancels a previously-installed idle handler.
1310 watch_process
1312 $loop->watch_process( $pid, $code )
1313 This method adds a new handler for the termination of the given child
1315 process PID, or all child processes.
1316 $pid The PID to watch. Will report on all child processes if this is
1318 0.
1319 $code A CODE reference to the exit handler. It will be invoked as
1321 $code->( $pid, $? )
1323 The second argument is passed the plain perl $? value.
1325 After invocation, the handler for a PID-specific watch is automatically
1327 removed. The all-child watch will remain until it is removed by
1328 "unwatch_process".
1329 This and "unwatch_process" are optional; a subclass may implement
1331 neither, or both. If it implements neither then child watching will be
1332 performed by using "watch_signal" to install a "SIGCHLD" handler, which
1333 will use "waitpid" to look for exited child processes.
1334 If both a PID-specific and an all-process watch are installed, there is
1336 no ordering guarantee as to which will be called first.
1337 NOTE that not all loop classes may be able to support the all-child
1339 watch. The basic Select and Poll-based classes provided by this
1340 distribution do, and those built on top of similar OS-specific
1341 mechanisms such as Linux's Epoll probably will, but typically those
1342 built on top of other event systems such as glib or libuv may not be
1343 able, as the underlying event system may not provide the necessary
1344 hooks to support it.
1345 unwatch_process
1347 $loop->unwatch_process( $pid )
1348 This method removes a watch on an existing child process PID.
1350
1352 The following methods are provided to access internal features which
1353 are required by specific subclasses to implement the loop
1354 functionality. The use cases of each will be documented in the above
1355 section.
1356 _adjust_timeout
1358 $loop->_adjust_timeout( \$timeout )
1359 Shortens the timeout value passed in the scalar reference if it is
1361 longer in seconds than the time until the next queued event on the
1362 timer queue. If there are pending idle handlers, the timeout is reduced
1363 to zero.
1364 _manage_queues
1366 $loop->_manage_queues
1367 Checks the timer queue for callbacks that should have been invoked by
1369 now, and runs them all, removing them from the queue. It also invokes
1370 all of the pending idle handlers. Any new idle handlers installed by
1371 these are not invoked yet; they will wait for the next time this method
1372 is called.
1373
1375 An Extension is a Perl module that provides extra methods in the
1376 "IO::Async::Loop" or other packages. They are intended to provide extra
1377 functionality that easily integrates with the rest of the code.
1378 Certain base methods take an "extensions" parameter; an ARRAY reference
1380 containing a list of extension names. If such a list is passed to a
1381 method, it will immediately call a method whose name is that of the
1382 base method, prefixed by the first extension name in the list,
1383 separated by "_". If the "extensions" list contains more extension
1384 names, it will be passed the remaining ones in another "extensions"
1385 parameter.
1386 For example,
1388 $loop->connect(
1390 extensions => [qw( FOO BAR )],
1391 %args
1392 )
1393 will become
1395 $loop->FOO_connect(
1397 extensions => [qw( BAR )],
1398 %args
1399 )
1400 This is provided so that extension modules, such as IO::Async::SSL can
1402 easily be invoked indirectly, by passing extra arguments to "connect"
1403 methods or similar, without needing every module to be aware of the
1404 "SSL" extension. This functionality is generic and not limited to
1405 "SSL"; other extensions may also use it.
1406 The following methods take an "extensions" parameter:
1408 $loop->connect
1410 $loop->listen
1411 If an extension "listen" method is invoked, it will be passed a
1413 "listener" parameter even if one was not provided to the original
1414 "$loop->listen" call, and it will not receive any of the "on_*" event
1415 callbacks. It should use the "acceptor" parameter on the "listener"
1416 object.
1417
1419 A well-behaved IO::Async program should spend almost all of its time
1420 blocked on input using the underlying "IO::Async::Loop" instance. The
1421 stall watchdog is an optional debugging feature to help detect CPU
1422 spinlocks and other bugs, where control is not returned to the loop
1423 every so often.
1424 If the watchdog is enabled and an event handler consumes more than a
1426 given amount of real time before returning to the event loop, it will
1427 be interrupted by printing a stack trace and terminating the program.
1428 The watchdog is only in effect while the loop itself is not blocking;
1429 it won't fail simply because the loop instance is waiting for input or
1430 timers.
1431 It is implemented using "SIGALRM", so if enabled, this signal will no
1433 longer be available to user code. (Though in any case, most uses of
1434 "alarm()" and "SIGALRM" are better served by one of the
1435 IO::Async::Timer subclasses).
1436 The following environment variables control its behaviour.
1438 IO_ASYNC_WATCHDOG => BOOL
1440 Enables the stall watchdog if set to a non-zero value.
1441 IO_ASYNC_WATCHDOG_INTERVAL => INT
1443 Watchdog interval, in seconds, to pass to the alarm(2) call.
1444 Defaults to 10 seconds.
1445 IO_ASYNC_WATCHDOG_SIGABRT => BOOL
1447 If enabled, the watchdog signal handler will raise a "SIGABRT",
1448 which usually has the effect of breaking out of a running program
1449 in debuggers such as gdb. If not set then the process is terminated
1450 by throwing an exception with "die".
1451
1453 Paul Evans <leonerd@leonerd.org.uk>
1454perl v5.34.0 2021-08-08 IO::Async::Loop(3)