NAME
    `IO::Async' - Asynchronous event-driven programming

SYNOPSIS
     use IO::Async::Stream;
     use IO::Async::Loop;

     my $loop = IO::Async::Loop->new;

     $loop->connect(
        host     => "some.other.host",
        service  => 12345,
        socktype => 'stream',

        on_stream => sub {
           my ( $stream ) = @_;

           $stream->configure(
              on_read => sub {
                 my ( $self, $buffref, $eof ) = @_;

                 while( $$buffref =~ s/^(.*\n)// ) {
                    print "Received a line $1";
                 }

                 return 0;
              }
           );

           $stream->write( "An initial line here\n" );

           $loop->add( $stream );
        },

        on_resolve_error => sub { die "Cannot resolve - $_[-1]\n"; },
        on_connect_error => sub { die "Cannot connect - $_[0] failed $_[-1]\n"; },
     );

     $loop->run;

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 of other objects, which perform the actual IO work required by
    the program. As well as IO handles, the loop also supports timers and
    signal handlers, and includes more higher-level functionality 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.

  Notifiers
    The base class of all the event handling subclasses is
    IO::Async::Notifier. It does not perform any IO operations itself, but
    instead acts as a base class to build the specific IO functionality
    upon. It can also coordinate a collection of other Notifiers contained
    within it, forming a tree structure.

    The following sections describe particular types of Notifier.

  File Handle IO
    An IO::Async::Handle object is a Notifier that represents a single IO
    handle 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::Handle 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.

    While stream-based sockets can be handled using using
    `IO::Async::Stream', datagram or raw sockets do not provide a
    bytestream. For these, the IO::Async::Socket class is another subclass
    of IO::Async::Handle which maintains an outgoing packet queue, and
    informs of packet receipt using a callback or method.

    The IO::Async::Listener class is another subclass of IO::Async::Handle
    which facilitates the use of `listen(2)'-mode sockets. When a new
    connection is available on the socket it will `accept(2)' it and pass
    the new client socket to its callback function.

  Timers
    An IO::Async::Timer::Absolute object represents a timer that expires at
    a given absolute time in the future.

    An IO::Async::Timer::Countdown object represents a count time timer,
    which will invoke a callback after a given delay. It can be stopped and
    restarted.

    An IO::Async::Timer::Periodic object invokes a callback at regular
    intervals from its initial start time. It is reliable and will not drift
    due to the time taken to run the callback.

    The IO::Async::Loop also supports methods for managing timed events on a
    lower level. Events may be absolute, or relative in time to the time
    they are installed.

  Signals
    An IO::Async::Signal object represents a POSIX signal, which will invoke
    a callback when the given signal is received by the process. Multiple
    objects watching the same signal can be used; they will all invoke in no
    particular order.

  Processes Management
    An IO::Async::PID object invokes its event when a given child process
    exits. An IO::Async::Process object can start a new child process
    running either a given block of code, or executing a given command, set
    up pipes on its filehandles, write to or read from these pipes, and
    invoke its event when the child process exits.

  Loops
    The IO::Async::Loop object class represents an abstract collection of
    IO::Async::Notifier objects, and manages the actual filehandle IO
    watchers, timers, signal handlers, and other functionality. 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::Poll uses an IO::Poll object for this test.

    IO::Async::Loop::Select uses the `select(2)' syscall.

    Other subclasses of loop may appear on CPAN under their own dists; see
    the SEE ALSO section below for more detail.

    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(2)'/`exec(2)' style of starting child
    processes, and `run_child' provide a method similar to perl's `readpipe'
    (which is used to implement backticks ```').

  File Change Watches
    The IO::Async::File object observes changes to `stat(2)' properties of a
    file, directory, or other filesystem object. It invokes callbacks when
    properties change. This is used by IO::Async::FileStream which presents
    the same events as a `IO::Async::Stream' but operates on a regular file
    on the filesystem, observing it for updates.

  Asynchronous Co-routines and Functions
    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::Function can be used around a
    code block, to execute it in a worker child process or set of processes.
    The code in the sub-process runs isolated from the main program,
    communicating only by function call arguments and return values. This
    can be used to solve problems involving state-less library functions.

    An IO::Async::Routine object wraps a code block running in a separate
    process to form a kind of co-routine. Communication with it happens via
    IO::Async::Channel objects. It can be used to solve any sort of problem
    involving keeping a possibly-stateful co-routine running alongside the
    rest of an asynchronous program.

  Tasks
    A Task object represents a single outstanding action that is yet to
    complete, such as a name resolution operation or a socket connection. It
    stands in contrast to a `IO::Async::Notifier', which is an object that
    represents an ongoing source of activity, such as a readable filehandle
    of bytes or a POSIX signal.

    Tasks are a recent addition to the `IO::Async' API and details are still
    subject to change and experimentation. Currently a Task object is an
    instance of CPS::Future, but it is possible this may change in future
    (pardon the pun ;) ) to being some class within the `IO::Async::'
    namespace, and having a reference to the containing Loop object.

    In general, methods that support Tasks return a new Task object to
    represent the outstanding operation. If callback functions are supplied
    as well, these will be fired in addition to the Task object becoming
    ready.

  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. These
    methods are fully IPv6-capable if the underlying operating system is.

  Protocols
    The IO::Async::Protocol class provides storage for a IO::Async::Handle
    object, to act as a transport for some protocol. It allows a level of
    independence from the actual transport being for that protocol, allowing
    it to be easily reused. The IO::Async::Protocol::Stream subclass
    provides further support for protocols based on stream connections, such
    as TCP sockets.

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:

    *   An IO::Async::Loop subclass 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
        generic `IO::Async::Function' approach. This should be easier to
        implement now that the IO::Async::Loop magic constructor looks for
        OS-specific subclasses first.

    *   Consider some form of persistent object wrapper in the form of an
        `IO::Async::Object', based on `IO::Async::Routine'.

    *   Build some sort of future-like system, possibly called
        `IO::Async::Task' to represent one-shot events like name resolver
        lookups, socket connects, etc.. Replace uses of `Async::MergePoint'
        with it, removing a dependency. Use `CPS::Future'.

    *   `IO::Async::Protocol::Datagram'

    *   Support for watching filesystem entries for change. Extract logic
        from `IO::Async::FileStream'. Define Loop watch/unwatch method pair.

SUPPORT
    Bugs may be reported via RT at

     https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Async

    Support by IRC may also be found on irc.perl.org in the #io-async
    channel.

SEE ALSO
    As well as the two loops supplied in this distribution, many more exist
    on CPAN. At the time of writing this includes:

    *   IO::Async::Loop::AnyEvent - use IO::Async with AnyEvent

    *   IO::Async::Loop::Epoll - use IO::Async with epoll on Linux

    *   IO::Async::Loop::EV - use IO::Async with EV

    *   IO::Async::Loop::Glib - use IO::Async with Glib or GTK

    *   IO::Async::Loop::KQueue - use IO::Async with kqueue

    *   IO::Async::Loop::Mojo - use IO::Async with Mojolicious

    *   IO::Async::Loop::POE - use IO::Async with POE

    *   IO::Async::Loop::Ppoll - use IO::Async with ppoll(2)

    Additionally, some other event loops or modules also support being run
    on top of `IO::Async':

    *   AnyEvent::Impl::IOAsync - AnyEvent adapter for IO::Async

    *   Gungho::Engine::IO::Async - IO::Async Engine

    *   POE::Loop::IO_Async - IO::Async event loop support for POE

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

