IO::Async(3pm)

1IO::Async(3)          User Contributed Perl Documentation         IO::Async(3)
2
3
4

NAME

6       "IO::Async" - Asynchronous event-driven programming
7

SYNOPSIS

9          use IO::Async::Stream;
10          use IO::Async::Loop;
11
12          my $loop = IO::Async::Loop->new;
13
14          $loop->connect(
15             host     => "some.other.host",
16             service  => 12345,
17             socktype => 'stream',
18
19             on_stream => sub {
20                my ( $stream ) = @_;
21
22                $stream->configure(
23                   on_read => sub {
24                      my ( $self, $buffref, $eof ) = @_;
25
26                      while( $$buffref =~ s/^(.*\n)// ) {
27                         print "Received a line $1";
28                      }
29
30                      return 0;
31                   }
32                );
33
34                $stream->write( "An initial line here\n" );
35
36                $loop->add( $stream );
37             },
38
39             on_resolve_error => sub { die "Cannot resolve - $_[-1]\n"; },
40             on_connect_error => sub { die "Cannot connect - $_[0] failed $_[-1]\n"; },
41          );
42
43          $loop->run;
44

DESCRIPTION

46       This collection of modules allows programs to be written that perform
47       asynchronous filehandle IO operations. A typical program using them
48       would consist of a single subclass of IO::Async::Loop to act as a
49       container of other objects, which perform the actual IO work required
50       by the program. As well as IO handles, the loop also supports timers
51       and signal handlers, and includes more higher-level functionality built
52       on top of these basic parts.
53
54       Because there are a lot of classes in this collection, the following
55       overview gives a brief description of each.
56
57   Notifiers
58       The base class of all the event handling subclasses is
59       IO::Async::Notifier.  It does not perform any IO operations itself, but
60       instead acts as a base class to build the specific IO functionality
61       upon. It can also coordinate a collection of other Notifiers contained
62       within it, forming a tree structure.
63
64       The following sections describe particular types of Notifier.
65
66   File Handle IO
67       An IO::Async::Handle object is a Notifier that represents a single IO
68       handle being managed. While in most cases it will represent a single
69       filehandle, such as a socket (for example, an IO::Socket::INET
70       connection), it is possible to have separate reading and writing
71       handles (most likely for a program's "STDIN" and "STDOUT" streams, or a
72       pair of pipes connected to a child process).
73
74       The IO::Async::Stream class is a subclass of IO::Async::Handle which
75       maintains internal incoming and outgoing data buffers. In this way, it
76       implements bidirectional buffering of a byte stream, such as a TCP
77       socket. The class automatically handles reading of incoming data into
78       the incoming buffer, and writing of the outgoing buffer. Methods or
79       callbacks are used to inform when new incoming data is available, or
80       when the outgoing buffer is empty.
81
82       While stream-based sockets can be handled using using
83       IO::Async::Stream, datagram or raw sockets do not provide a bytestream.
84       For these, the IO::Async::Socket class is another subclass of
85       IO::Async::Handle which maintains an outgoing packet queue, and informs
86       of packet receipt using a callback or method.
87
88       The IO::Async::Listener class is another subclass of IO::Async::Handle
89       which facilitates the use of listen(2)-mode sockets. When a new
90       connection is available on the socket it will accept(2) it and pass the
91       new client socket to its callback function.
92
93   Timers
94       An IO::Async::Timer::Absolute object represents a timer that expires at
95       a given absolute time in the future.
96
97       An IO::Async::Timer::Countdown object represents a count time timer,
98       which will invoke a callback after a given delay. It can be stopped and
99       restarted.
100
101       An IO::Async::Timer::Periodic object invokes a callback at regular
102       intervals from its initial start time. It is reliable and will not
103       drift due to the time taken to run the callback.
104
105       The IO::Async::Loop also supports methods for managing timed events on
106       a lower level. Events may be absolute, or relative in time to the time
107       they are installed.
108
109   Signals
110       An IO::Async::Signal object represents a POSIX signal, which will
111       invoke a callback when the given signal is received by the process.
112       Multiple objects watching the same signal can be used; they will all
113       invoke in no particular order.
114
115   Processes Management
116       An IO::Async::PID object invokes its event when a given child process
117       exits. An IO::Async::Process object can start a new child process
118       running either a given block of code, or executing a given command, set
119       up pipes on its filehandles, write to or read from these pipes, and
120       invoke its event when the child process exits.
121
122   Loops
123       The IO::Async::Loop object class represents an abstract collection of
124       IO::Async::Notifier objects, and manages the actual filehandle IO
125       watchers, timers, signal handlers, and other functionality. It performs
126       all of the abstract collection management tasks, and leaves the actual
127       OS interactions to a particular subclass for the purpose.
128
129       IO::Async::Loop::Poll uses an IO::Poll object for this test.
130
131       IO::Async::Loop::Select uses the select(2) syscall.
132
133       Other subclasses of loop may appear on CPAN under their own dists; see
134       the "SEE ALSO" section below for more detail.
135
136       As well as these general-purpose classes, the IO::Async::Loop
137       constructor also supports looking for OS-specific subclasses, in case a
138       more efficient implementation exists for the specific OS it runs on.
139
140   Child Processes
141       The IO::Async::Loop object provides a number of methods to facilitate
142       the running of child processes. "spawn_child" is primarily a wrapper
143       around the typical fork(2)/exec(2) style of starting child processes,
144       and "run_child" provide a method similar to perl's "readpipe" (which is
145       used to implement backticks ``).
146
147   File Change Watches
148       The IO::Async::File object observes changes to stat(2) properties of a
149       file, directory, or other filesystem object. It invokes callbacks when
150       properties change. This is used by IO::Async::FileStream which presents
151       the same events as a IO::Async::Stream but operates on a regular file
152       on the filesystem, observing it for updates.
153
154   Asynchronous Co-routines and Functions
155       The "IO::Async" framework generally provides mechanisms for
156       multiplexing IO tasks between different handles, so there aren't many
157       occasions when it is necessary to run code in another thread or
158       process. Two cases where this does become useful are when:
159
160       •   A large amount of computationally-intensive work needs to be
161           performed.
162
163       •   An OS or library-level function needs to be called, that will
164           block, and no asynchronous version is supplied.
165
166       For these cases, an instance of IO::Async::Function can be used around
167       a code block, to execute it in a worker child process or set of
168       processes.  The code in the sub-process runs isolated from the main
169       program, communicating only by function call arguments and return
170       values. This can be used to solve problems involving state-less library
171       functions.
172
173       An IO::Async::Routine object wraps a code block running in a separate
174       process to form a kind of co-routine. Communication with it happens via
175       IO::Async::Channel objects. It can be used to solve any sort of problem
176       involving keeping a possibly-stateful co-routine running alongside the
177       rest of an asynchronous program.
178
179   Futures
180       An IO::Async::Future object represents a single outstanding action that
181       is yet to complete, such as a name resolution operation or a socket
182       connection.  It stands in contrast to a IO::Async::Notifier, which is
183       an object that represents an ongoing source of activity, such as a
184       readable filehandle of bytes or a POSIX signal.
185
186       Futures are a recent addition to the "IO::Async" API and details are
187       still subject to change and experimentation.
188
189       In general, methods that support Futures return a new Future object to
190       represent the outstanding operation. If callback functions are supplied
191       as well, these will be fired in addition to the Future object becoming
192       ready. Any failures that are reported will, in general, use the same
193       conventions for the Future's "fail" arguments to relate it to the
194       legacy "on_error"-style callbacks.
195
196          $on_NAME_error->( $message, @argmuents )
197
198          $f->fail( $message, NAME, @arguments )
199
200       where $message is a message intended for humans to read (so that this
201       is the message displayed by "$f->get" if the failure is not otherwise
202       caught), "NAME" is the name of the failing operation. If the failure is
203       due to a failed system call, the value of $! will be the final
204       argument. The message should not end with a linefeed.
205
206   Networking
207       The IO::Async::Loop provides several methods for performing network-
208       based tasks. Primarily, the "connect" and "listen" methods allow the
209       creation of client or server network sockets. Additionally, the
210       "resolve" method allows the use of the system's name resolvers in an
211       asynchronous way, to resolve names into addresses, or vice versa. These
212       methods are fully IPv6-capable if the underlying operating system is.
213
214   Protocols
215       The IO::Async::Protocol class provides storage for a IO::Async::Handle
216       object, to act as a transport for some protocol. It allows a level of
217       independence from the actual transport being for that protocol,
218       allowing it to be easily reused. The IO::Async::Protocol::Stream
219       subclass provides further support for protocols based on stream
220       connections, such as TCP sockets.
221

TODO

223       This collection of modules is still very much in development. As a
224       result, some of the potentially-useful parts or features currently
225       missing are:
226
227       •   Consider further ideas on Solaris' ports, BSD's Kevents and
228           anything that might be useful on Win32.
229
230       •   Consider some form of persistent object wrapper in the form of an
231           "IO::Async::Object", based on IO::Async::Routine.
232
233       •   "IO::Async::Protocol::Datagram"
234
235       •   Support for watching filesystem entries for change. Extract logic
236           from IO::Async::File and define a Loop watch/unwatch method pair.
237
238       •   Define more Future-returning methods. Consider also one-shot
239           Futures on things like IO::Async::Process exits, or
240           IO::Async::Handle close.
241

SUPPORT

243       Bugs may be reported via RT at
244
245          https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Async
246
247       Support by IRC may also be found on irc.perl.org in the #io-async
248       channel.
249

AUTHOR

282       Paul Evans <leonerd@leonerd.org.uk>
283
284
285
286perl v5.36.0                      2023-01-20                      IO::Async(3)