NAME

IO::Async - a collection of modules that implement asynchronous filehandle IO

SYNOPSIS

 use IO::Async::Stream;
 use IO::Async::Loop::IO_Poll;

 use Socket qw( SOCK_STREAM );

 my $loop = IO::Async::Loop::IO_Poll->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 for a number of IO::Async::Notifier objects (or subclasses thereof). The loop itself is responsible for checking read- or write-readiness, and informing the notifiers of these conditions. The notifiers then perform whatever work is required on these conditions, by using subclass methods or callback functions.

Notifiers

A IO::Async::Notifier object represents a single IO stream 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). Subclass methods or callback functions are then used by the containing IO::Async::Loop object, to inform the notifier when the handles are read- or write-ready.

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 whenever it is notified as being read-ready, and writing of the outgoing buffer when it is notified as write-ready. 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. It performs all of the low-level set management tasks, and leaves the actual determination of read- or write- readiness of filehandles to a particular subclass for the purpose.

IO::Async::Loop::IO_Poll uses an IO::Poll object for this test.

IO::Async::Loop::Select provides methods to prepare and test three bitvectors for a 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.

Detached Code

The IO::Async framework generally provides mechanisms for multiplexing IO tasks between different handles, so there aren't many occasions when such detached code is necessary. Two cases where this does become useful are when a large amount of computationally-intensive work needs to be performed, or when 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.

Timers

Each of the IO::Async::Loop subclasses supports a pair of methods for installing and cancelling timers. These are callbacks invoked at some fixed future time. Once installed, a timer will be called at or after its expiry time, which may be absolute, or relative to the time it was installed. An installed timer which has not yet expired may be cancelled.

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.

Resolver

The IO::Async::Resolver extension to the IO::Async::Loop allows asynchronous use of any name resolvers the system provides; such as getaddrinfo for resolving host/service names into connectable addresses.

Connector

The IO::Async::Connector extension allows socket connections to be established asynchronously, perhaps via the use of the resolver to first resolve names into addresses.

MOTIVATION

The purpose of this distribution is two-fold.

The first reason is to allow programs to be written that perform multiplexed asynchronous IO from within one thread. This is a useful programming model because it avoids a lot of the problems created by multi-threading or other techniques, such as the potential for race conditions or deadlocks. The downside to this approach is the extra complexity in dealing with events asynchronously, handling incoming data as it arrives, even if it is as-yet incomplete. This distribution aims to provide abstractions that minimise the effort required here, through such objects as IO::Async::Stream.

The second reason is to act as a base-layer API, that can be extended while still remaining generic. The split between notifiers and sets allows new subclasses of notifer to be derived from the IO::Async::Notifier or IO::Async::Stream classes without regard for how they will interact with the actual looping constructs emplyed by the containing program. Similarly, new subclasses of IO::Async::Loop can be developed to interact with existing programs written for other styles of asynchronous IO loop, without requiring detailed knowledge of the way the notifiers work.

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::Loop subclass to perform integration with Event. Consider further ideas on Linux's epoll, 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 generic DetachedCode approach.

• A consideration of whether it is useful and possible to provide integration with POE.

SEE ALSO

• Event - Event loop processing

• POE - portable multitasking and networking framework for Perl

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm IO::Async

perl -MCPAN -e shell
install IO::Async