Debian Codegraph @

README

raw
1 NAME
2
3 IO::Async - Asynchronous event-driven programming
4
5 SYNOPSIS
6
7 use IO::Async::Stream;
8 use IO::Async::Loop;
9
10 my $loop = IO::Async::Loop->new;
11
12 $loop->connect(
13 host => "some.other.host",
14 service => 12345,
15 socktype => 'stream',
16
17 on_stream => sub {
18 my ( $stream ) = @_;
19
20 $stream->configure(
21 on_read => sub {
22 my ( $self, $buffref, $eof ) = @_;
23
24 while( $$buffref =~ s/^(.*\n)// ) {
25 print "Received a line $1";
26 }
27
28 return 0;
29 }
30 );
31
32 $stream->write( "An initial line here\n" );
33
34 $loop->add( $stream );
35 },
36
37 on_resolve_error => sub { die "Cannot resolve - $_[-1]\n"; },
38 on_connect_error => sub { die "Cannot connect - $_[0] failed $_[-1]\n"; },
39 );
40
41 $loop->run;
42
43 DESCRIPTION
44
45 This collection of modules allows programs to be written that perform
46 asynchronous filehandle IO operations. A typical program using them
47 would consist of a single subclass of IO::Async::Loop to act as a
48 container of other objects, which perform the actual IO work required
49 by the program. As well as IO handles, the loop also supports timers
50 and signal handlers, and includes more higher-level functionality built
51 on top of these basic parts.
52
53 Because there are a lot of classes in this collection, the following
54 overview gives a brief description of each.
55
56 Notifiers
57
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
68 An IO::Async::Handle object is a Notifier that represents a single IO
69 handle being managed. While in most cases it will represent a single
70 filehandle, such as a socket (for example, an IO::Socket::INET
71 connection), it is possible to have separate reading and writing
72 handles (most likely for a program's STDIN and STDOUT streams, or a
73 pair of pipes connected to a child process).
74
75 The IO::Async::Stream class is a subclass of IO::Async::Handle which
76 maintains internal incoming and outgoing data buffers. In this way, it
77 implements bidirectional buffering of a byte stream, such as a TCP
78 socket. The class automatically handles reading of incoming data into
79 the incoming buffer, and writing of the outgoing buffer. Methods or
80 callbacks are used to inform when new incoming data is available, or
81 when the outgoing buffer is empty.
82
83 While stream-based sockets can be handled using using
84 IO::Async::Stream, datagram or raw sockets do not provide a bytestream.
85 For these, the IO::Async::Socket class is another subclass of
86 IO::Async::Handle which maintains an outgoing packet queue, and informs
87 of packet receipt using a callback or method.
88
89 The IO::Async::Listener class is another subclass of IO::Async::Handle
90 which facilitates the use of listen(2)-mode sockets. When a new
91 connection is available on the socket it will accept(2) it and pass the
92 new client socket to its callback function.
93
94 Timers
95
96 An IO::Async::Timer::Absolute object represents a timer that expires at
97 a given absolute time in the future.
98
99 An IO::Async::Timer::Countdown object represents a count time timer,
100 which will invoke a callback after a given delay. It can be stopped and
101 restarted.
102
103 An IO::Async::Timer::Periodic object invokes a callback at regular
104 intervals from its initial start time. It is reliable and will not
105 drift due to the time taken to run the callback.
106
107 The IO::Async::Loop also supports methods for managing timed events on
108 a lower level. Events may be absolute, or relative in time to the time
109 they are installed.
110
111 Signals
112
113 An IO::Async::Signal object represents a POSIX signal, which will
114 invoke a callback when the given signal is received by the process.
115 Multiple objects watching the same signal can be used; they will all
116 invoke in no particular order.
117
118 Processes Management
119
120 An IO::Async::PID object invokes its event when a given child process
121 exits. An IO::Async::Process object can start a new child process
122 running either a given block of code, or executing a given command, set
123 up pipes on its filehandles, write to or read from these pipes, and
124 invoke its event when the child process exits.
125
126 Loops
127
128 The IO::Async::Loop object class represents an abstract collection of
129 IO::Async::Notifier objects, and manages the actual filehandle IO
130 watchers, timers, signal handlers, and other functionality. It performs
131 all of the abstract collection management tasks, and leaves the actual
132 OS interactions to a particular subclass for the purpose.
133
134 IO::Async::Loop::Poll uses an IO::Poll object for this test.
135
136 IO::Async::Loop::Select uses the select(2) syscall.
137
138 Other subclasses of loop may appear on CPAN under their own dists; see
139 the "SEE ALSO" section below for more detail.
140
141 As well as these general-purpose classes, the IO::Async::Loop
142 constructor also supports looking for OS-specific subclasses, in case a
143 more efficient implementation exists for the specific OS it runs on.
144
145 Child Processes
146
147 The IO::Async::Loop object provides a number of methods to facilitate
148 the running of child processes. spawn_child is primarily a wrapper
149 around the typical fork(2)/exec(2) style of starting child processes,
150 and run_child provide a method similar to perl's readpipe (which is
151 used to implement backticks ``).
152
153 File Change Watches
154
155 The IO::Async::File object observes changes to stat(2) properties of a
156 file, directory, or other filesystem object. It invokes callbacks when
157 properties change. This is used by IO::Async::FileStream which presents
158 the same events as a IO::Async::Stream but operates on a regular file
159 on the filesystem, observing it for updates.
160
161 Asynchronous Co-routines and Functions
162
163 The IO::Async framework generally provides mechanisms for multiplexing
164 IO tasks between different handles, so there aren't many occasions when
165 it is necessary to run code in another thread or process. Two cases
166 where this does become useful are when:
167
168 * A large amount of computationally-intensive work needs to be
169 performed.
170
171 * An OS or library-level function needs to be called, that will
172 block, and no asynchronous version is supplied.
173
174 For these cases, an instance of IO::Async::Function can be used around
175 a code block, to execute it in a worker child process or set of
176 processes. The code in the sub-process runs isolated from the main
177 program, communicating only by function call arguments and return
178 values. This can be used to solve problems involving state-less library
179 functions.
180
181 An IO::Async::Routine object wraps a code block running in a separate
182 process to form a kind of co-routine. Communication with it happens via
183 IO::Async::Channel objects. It can be used to solve any sort of problem
184 involving keeping a possibly-stateful co-routine running alongside the
185 rest of an asynchronous program.
186
187 Futures
188
189 An IO::Async::Future object represents a single outstanding action that
190 is yet to complete, such as a name resolution operation or a socket
191 connection. It stands in contrast to a IO::Async::Notifier, which is an
192 object that represents an ongoing source of activity, such as a
193 readable filehandle of bytes or a POSIX signal.
194
195 Futures are a recent addition to the IO::Async API and details are
196 still subject to change and experimentation.
197
198 In general, methods that support Futures return a new Future object to
199 represent the outstanding operation. If callback functions are supplied
200 as well, these will be fired in addition to the Future object becoming
201 ready. Any failures that are reported will, in general, use the same
202 conventions for the Future's fail arguments to relate it to the legacy
203 on_error-style callbacks.
204
205 $on_NAME_error->( $message, @argmuents )
206
207 $f->fail( $message, NAME, @arguments )
208
209 where $message is a message intended for humans to read (so that this
210 is the message displayed by $f->get if the failure is not otherwise
211 caught), NAME is the name of the failing operation. If the failure is
212 due to a failed system call, the value of $! will be the final
213 argument. The message should not end with a linefeed.
214
215 Networking
216
217 The IO::Async::Loop provides several methods for performing
218 network-based tasks. Primarily, the connect and listen methods allow
219 the creation of client or server network sockets. Additionally, the
220 resolve method allows the use of the system's name resolvers in an
221 asynchronous way, to resolve names into addresses, or vice versa. These
222 methods are fully IPv6-capable if the underlying operating system is.
223
224 Protocols
225
226 The IO::Async::Protocol class provides storage for a IO::Async::Handle
227 object, to act as a transport for some protocol. It allows a level of
228 independence from the actual transport being for that protocol,
229 allowing it to be easily reused. The IO::Async::Protocol::Stream
230 subclass provides further support for protocols based on stream
231 connections, such as TCP sockets.
232
233 TODO
234
235 This collection of modules is still very much in development. As a
236 result, some of the potentially-useful parts or features currently
237 missing are:
238
239 * Consider further ideas on Solaris' ports, BSD's Kevents and
240 anything that might be useful on Win32.
241
242 * Consider some form of persistent object wrapper in the form of an
243 IO::Async::Object, based on IO::Async::Routine.
244
245 * IO::Async::Protocol::Datagram
246
247 * Support for watching filesystem entries for change. Extract logic
248 from IO::Async::File and define a Loop watch/unwatch method pair.
249
250 * Define more Future-returning methods. Consider also one-shot
251 Futures on things like IO::Async::Process exits, or IO::Async::Handle
252 close.
253
254 SUPPORT
255
256 Bugs may be reported via RT at
257
258 https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Async
259
260 Support by IRC may also be found on irc.perl.org in the #io-async
261 channel.
262
263 SEE ALSO
264
265 As well as the two loops supplied in this distribution, many more exist
266 on CPAN. At the time of writing this includes:
267
268 * IO::Async::Loop::AnyEvent - use IO::Async with AnyEvent
269
270 * IO::Async::Loop::Epoll - use IO::Async with epoll on Linux
271
272 * IO::Async::Loop::Event - use IO::Async with Event
273
274 * IO::Async::Loop::EV - use IO::Async with EV
275
276 * IO::Async::Loop::Glib - use IO::Async with Glib or GTK
277
278 * IO::Async::Loop::KQueue - use IO::Async with kqueue
279
280 * IO::Async::Loop::Mojo - use IO::Async with Mojolicious
281
282 * IO::Async::Loop::POE - use IO::Async with POE
283
284 * IO::Async::Loop::Ppoll - use IO::Async with ppoll(2)
285
286 Additionally, some other event loops or modules also support being run
287 on top of IO::Async:
288
289 * AnyEvent::Impl::IOAsync - AnyEvent adapter for IO::Async
290
291 * Gungho::Engine::IO::Async - IO::Async Engine
292
293 * POE::Loop::IO_Async - IO::Async event loop support for POE
294
295 AUTHOR
296
297 Paul Evans <[email protected]>
298