NAME
IO::Async - a collection of modules that implement asynchronous filehandle IO
SYNOPSIS
use IO::Async::Stream;
use IO::Async::Loop;
use Socket qw( SOCK_STREAM );
my $loop = IO::Async::Loop->new();
$loop->connect(
host => "some.other.host",
service => 12345,
socktype => SOCK_STREAM,
on_connected => sub {
my ( $socket ) = @_;
my $stream = IO::Async::Stream->new(
handle => $socket,
on_read => sub {
my ( $self, $buffref, $closed ) = @_;
return 0 unless( $buffref =~ s/^(.*\n)// );
print "Received a line $1";
return 1;
}
);
$stream->write( "An initial line here\n" );
$loop->add( $stream );
},
...
);
$loop->loop_forever();DESCRIPTION
This collection of modules allows programs to be written that perform asynchronous filehandle IO operations. A typical program using them would consist of a single subclass of IO::Async::Loop to act as a container o other objects, which perform the actual IO work required by the program. As as IO handles, the loop also supports timers and signal handlers, and includes more higher-level functionallity built on top of these basic parts.
Because there are a lot of classes in this collection, the following overview gives a brief description of each.
File Handle IO
A IO::Async::Notifier object represents a single IO handle that is being managed. While in most cases it will represent a single filehandle, such as a socket (for example, an IO::Socket::INET connection), it is possible to have separate reading and writing handles (most likely for a program's STDIN and STDOUT streams, or a pair of pipes connected to a child process).
The IO::Async::Stream class is a subclass of IO::Async::Notifier which maintains internal incoming and outgoing data buffers. In this way, it implements bidirectional buffering of a byte stream, such as a TCP socket. The class automatically handles reading of incoming data into the incoming buffer, and writing of the outgoing buffer. Methods or callbacks are used to inform when new incoming data is available, or when the outgoing buffer is empty.
Loops
The IO::Async::Loop object class represents an abstract collection of IO::Async::Notifier objects, timers, signal handlers, and other functionallity. It performs all of the abstract collection management tasks, and leaves the actual OS interactions to a particular subclass for the purpose.
IO::Async::Loop::IO_Poll uses an IO::Poll object for this test.
IO::Async::Loop::Select uses the select() syscall.
Other subclasses of loop may appear on CPAN under their own dists; such as IO::Async::Loop::Glib which acts as a proxy for the Glib::MainLoop of a Glib-based program, or IO::Async::Loop::IO_Ppoll which uses the IO::Ppoll object to handle signals safely on Linux.
As well as these general-purpose classes, the IO::Async::Loop constructor also supports looking for OS-specific subclasses, in case a more efficient implementation exists for the specific OS it runs on.
Child Processes
The IO::Async::Loop object provides a number of methods to facilitate the running of child processes. spawn_child is primarily a wrapper around the typical fork()/exec() style of starting child processes, open_child builds on this to provide management of child process file handles and streams connected to them, and finally run_child builds on that to provide a method similar to perl's readpipe() (which is used to implement backticks ``).
Detached Code
The IO::Async framework generally provides mechanisms for multiplexing IO tasks between different handles, so there aren't many occasions when it is necessary to run code in another thread or process. Two cases where this does become useful are when:
A large amount of computationally-intensive work needs to be performed.
An OS or library-level function needs to be called, that will block, and no asynchronous version is supplied.
For these cases, an instance of IO::Async::DetachedCode can be used around a code block, to execute it in a detached child process. The code in the sub-process runs isolated from the main program, communicating only by function call arguments and return values.
Timers
The IO::Async::Loop supports methods for managing timers. These are callbacks invoked at some fixed future time. Once installed, a timer will be called at or after its expiry time. This time may be absolute, or relative to the time it was installed. An installed timer which has not yet expired may be cancelled or rescheduled.
Merge Points
The IO::Async::MergePoint object class allows for a program to wait on the completion of multiple seperate subtasks. It allows for each subtask to return some data, which will be collected and given to the callback provided to the merge point, which is called when every subtask has completed.
Networking
The IO::Async::Loop provides several methods for performing network-based tasks. Primarily, the connect and listen methods allow the creation of client or server network sockets. Additionally, the resolve method allows the use of the system's name resolvers in an asynchronous way, to resolve names into addresses, or vice versa.
TODO
This collection of modules is still very much in development. As a result, some of the potentially-useful parts or features currently missing are:
A
IO::Async::Loopsubclass to perform integration with Event. Consider further ideas on Solaris' ports, BSD's Kevents and anything that might be useful on Win32.A consideration on how to provide per-OS versions of the utility classes. For example, Win32 would probably need an extensively-different
ChildManager, or OSes may have specific ways to perform asynchronous name resolution operations better than the genericDetachedCodeapproach. This should be easier to implement now that theIO::Async::Loopmagic constructor looks for OS-specific subclasses first.A consideration of whether it is useful and possible to provide integration with POE or AnyEvent.
SEE ALSO
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>