view release on metacpan or  search on metacpan

local/lib/perl5/IO/Async.pm  view on Meta::CPAN

Futures are a recent addition to the C<IO::Async> API and details are still
subject to change and experimentation.

In general, methods that support Futures return a new Future object to
represent the outstanding operation. If callback functions are supplied as
well, these will be fired in addition to the Future object becoming ready. Any
failures that are reported will, in general, use the same conventions for the
Future's C<fail> arguments to relate it to the legacy C<on_error>-style
callbacks.

 $on_NAME_error->( $message, @argmuents )

 $f->fail( $message, NAME, @arguments )

where C<$message> is a message intended for humans to read (so that this is
the message displayed by C<< $f->get >> if the failure is not otherwise
caught), C<NAME> is the name of the failing operation. If the failure is due
to a failed system call, the value of C<$!> will be the final argument. The
message should not end with a linefeed.

=head2 Networking

The L<IO::Async::Loop> provides several methods for performing network-based
tasks. Primarily, the C<connect> and C<listen> methods allow the creation of
client or server network sockets. Additionally, the C<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.

=head2 Protocols

The L<IO::Async::Protocol> class provides storage for a L<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 L<IO::Async::Protocol::Stream> subclass provides further
support for protocols based on stream connections, such as TCP sockets.

=head1 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:

=over 4

=item *

Consider further ideas on Solaris' I<ports>, BSD's I<Kevents> and anything that
might be useful on Win32.

=item *

Consider some form of persistent object wrapper in the form of an
C<IO::Async::Object>, based on L<IO::Async::Routine>.

=item *

C<IO::Async::Protocol::Datagram>

=item *

Support for watching filesystem entries for change. Extract logic from
L<IO::Async::File> and define a Loop watch/unwatch method pair.

=item *

Define more L<Future>-returning methods. Consider also one-shot Futures on
things like L<IO::Async::Process> exits, or L<IO::Async::Handle> close.

=back

=head1 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 F<irc.perl.org> in the F<#io-async>
channel.

=cut

=head1 SEE ALSO

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

=over 4

=item *

L<IO::Async::Loop::AnyEvent> - use IO::Async with AnyEvent

=item *

L<IO::Async::Loop::Epoll> - use IO::Async with epoll on Linux

=item *

L<IO::Async::Loop::Event> - use IO::Async with Event

=item *

L<IO::Async::Loop::EV> - use IO::Async with EV

=item *

L<IO::Async::Loop::Glib> - use IO::Async with Glib or GTK

=item *

L<IO::Async::Loop::KQueue> - use IO::Async with kqueue

=item *

L<IO::Async::Loop::Mojo> - use IO::Async with Mojolicious

=item *

L<IO::Async::Loop::POE> - use IO::Async with POE

=item *