1IO::Async(3) User Contributed Perl Documentation IO::Async(3)
2
6 "IO::Async" - perform asynchronous filehandle IO and other operations
7
9 use IO::Async::Stream;
10 use IO::Async::Loop;
11 my $loop = IO::Async::Loop->new();
13 $loop->connect(
15 host => "some.other.host",
16 service => 12345,
17 socktype => 'stream',
18 on_connected => sub {
20 my ( $socket ) = @_;
21 my $stream = IO::Async::Stream->new(
23 handle => $socket,
24 on_read => sub {
26 my ( $self, $buffref, $closed ) = @_;
27 return 0 unless( $buffref =~ s/^(.*\n)// );
29 print "Received a line $1";
31 return 1;
33 }
34 );
35 $stream->write( "An initial line here\n" );
37 $loop->add( $stream );
39 },
40 ...
42 );
43 $loop->loop_forever();
45
47 This collection of modules allows programs to be written that perform
48 asynchronous filehandle IO operations. A typical program using them
49 would consist of a single subclass of IO::Async::Loop to act as a
50 container of other objects, which perform the actual IO work required
51 by the program. As well as IO handles, the loop also supports timers
52 and signal handlers, and includes more higher-level functionallity
53 built on top of these basic parts.
54 Because there are a lot of classes in this collection, the following
56 overview gives a brief description of each.
57 Notifiers
59 The base class of all the event handling subclasses is
60 IO::Async::Notifier. It does not perform any IO operations itself, but
61 instead acts as a base class to build the specific IO functionallity
62 upon. It can also coordinate a collection of other Notifiers contained
63 within it, forming a tree structure.
64 The following sections describe particular types of Notifier.
66 File Handle IO
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 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 The IO::Async::Listener class is another subclass of IO::Async::Handle
84 which facilitates the use of "listen()"-mode sockets. When a new
85 connection is available on the socket it will "accept()" it and pass
86 the new client socket to its callback function.
87 Timers
89 An IO::Async::Timer::Countdown object represents a count time timer,
90 which will invoke a callback after a given delay. It can be stopped and
91 restarted.
92 An IO::Async::Timer::Periodic object invokes a callback at regular
94 intervals from its initial start time. It is reliable and will not
95 drift due to the time taken to run the callback.
96 The IO::Async::Loop also supports methods for managing timed events on
98 a lower level. Events may be absolute, or relative in time to the time
99 they are installed.
100 Signals
102 An IO::Async::Signal object represents a POSIX signal, which will
103 invoke a callback when the given signal is received by the process.
104 Multiple objects watching the same signal can be used; they will all
105 invoke in no particular order.
106 Merge Points
108 The IO::Async::MergePoint object class allows for a program to wait on
109 the completion of multiple seperate subtasks. It allows for each
110 subtask to return some data, which will be collected and given to the
111 callback provided to the merge point, which is called when every
112 subtask has completed.
113 Loops
115 The IO::Async::Loop object class represents an abstract collection of
116 IO::Async::Notifier objects, and manages the actual filehandle IO
117 watchers, timers, signal handlers, and other functionallity. It
118 performs all of the abstract collection management tasks, and leaves
119 the actual OS interactions to a particular subclass for the purpose.
120 IO::Async::Loop::Poll uses an IO::Poll object for this test.
122 IO::Async::Loop::Select uses the "select()" syscall.
124 Other subclasses of loop may appear on CPAN under their own dists; such
126 as IO::Async::Loop::Glib which acts as a proxy for the "Glib::MainLoop"
127 of a Glib-based program, or IO::Async::Loop::Ppoll which uses the
128 IO::Ppoll object to handle signals safely on Linux.
129 As well as these general-purpose classes, the IO::Async::Loop
131 constructor also supports looking for OS-specific subclasses, in case a
132 more efficient implementation exists for the specific OS it runs on.
133 Child Processes
135 The IO::Async::Loop object provides a number of methods to facilitate
136 the running of child processes. "spawn_child" is primarily a wrapper
137 around the typical "fork()"/"exec()" style of starting child processes,
138 "open_child" builds on this to provide management of child process file
139 handles and streams connected to them, and finally "run_child" builds
140 on that to provide a method similar to perl's "readpipe()" (which is
141 used to implement backticks "``").
142 Detached Code
144 The "IO::Async" framework generally provides mechanisms for
145 multiplexing IO tasks between different handles, so there aren't many
146 occasions when it is necessary to run code in another thread or
147 process. Two cases where this does become useful are when:
148 · A large amount of computationally-intensive work needs to be
150 performed.
151 · An OS or library-level function needs to be called, that will
153 block, and no asynchronous version is supplied.
154 For these cases, an instance of IO::Async::DetachedCode can be used
156 around a code block, to execute it in a detached child process. The
157 code in the sub-process runs isolated from the main program,
158 communicating only by function call arguments and return values.
159 Networking
161 The IO::Async::Loop provides several methods for performing network-
162 based tasks. Primarily, the "connect" and "listen" methods allow the
163 creation of client or server network sockets. Additionally, the
164 "resolve" method allows the use of the system's name resolvers in an
165 asynchronous way, to resolve names into addresses, or vice versa.
166
168 This collection of modules is still very much in development. As a
169 result, some of the potentially-useful parts or features currently
170 missing are:
171 · An IO::Async::Loop subclass to perform integration with Event.
173 Consider further ideas on Solaris' ports, BSD's Kevents and
174 anything that might be useful on Win32.
175 · A consideration on how to provide per-OS versions of the utility
177 classes. For example, Win32 would probably need an extensively-
178 different "ChildManager", or OSes may have specific ways to perform
179 asynchronous name resolution operations better than the generic
180 "DetachedCode" approach. This should be easier to implement now
181 that the IO::Async::Loop magic constructor looks for OS-specific
182 subclasses first.
183 · A consideration of whether it is useful and possible to provide
185 integration with POE or AnyEvent.
186
188 · Event - Event loop processing
189 · POE - portable multitasking and networking framework for Perl
191
193 Paul Evans <leonerd@leonerd.org.uk>
194perl v5.12.1 2010-06-09 IO::Async(3)