NAME
Future::IO - Future-returning IO methods
SYNOPSIS
use Future::IO;
Future::IO->load_best_impl;
my $delay = Future::IO->sleep( 5 );
# $delay will become done in 5 seconds time
my $input = Future::IO->read( \*STDIN, 4096 );
# $input will yield some input from the STDIN IO handle
DESCRIPTION
This package provides a few basic methods that behave similarly to the
same-named core perl functions relating to IO operations, but yield
their results asynchronously via Future instances.
This is provided primarily as a decoupling mechanism, to allow modules
to be written that perform IO in an asynchronous manner to depend
directly on this, while allowing asynchronous event systems to provide
an implementation of these operations.
Default Implementation
If the override_impl method is not invoked, a default implementation of
these operations is provided. This implementation allows a single queue
of read or write calls on a single filehandle only, combined with sleep
calls. It does not support waitpid.
It is provided for the simple cases where modules only need one
filehandle (most likely a single network socket or hardware device
handle), allowing such modules to work without needing a better event
system.
If there are both read/write and sleep futures pending, the
implementation will use select() to wait for either. This may be
problematic on MSWin32, depending on what type of filehandle is
involved.
If select() is not being used then the default implementation will
temporarily set filehandles into blocking mode (by switching off the
O_NONBLOCK flag) while performing IO on them.
For cases where multiple filehandles are required, or for doing more
involved IO operations, a real implementation based on an actual event
loop should be loaded. It is recommended to use the "load_best_impl"
method to do this, if there are no other specific requirements. If the
program is already using some other event system, such as UV or
IO::Async, it is best to directly load the relevant implementation
module in the toplevel program.
Unit Testing
The replaceable implementation is also useful for writing unit test
scripts. If the implementation is set to an instance of some sort of
test fixture or mocking object, a unit test can check that the
appropriate IO operations happen as part of the test.
A testing module which does this is provided by Test::Future::IO.
Cancellation
Any Future returned by a Future::IO method should support being
cancelled by the "cancel" in Future method. Doing so should not cause
the program to break overall, nor will it upset the specific
implementation being used.
However, the result of cancelling a future instance that performs some
actual IO work is unspecified. It may cause no work to be performed, or
it may result in a partial (or even complete but as-yet unreported) IO
operation to have already taken place. In particular, operations that
write bytes to, or read bytes from filehandles may have already
transferred some or all of those bytes before the future was cancelled,
and there is now nothing that the program can do to "undo" those
effects. In general it is likely that the only situation where you will
cancel an IO operation on a filehandle is when an entire connection is
being abandoned, filehandles closed, and so on.
That said, it should be safe to cancel "alarm" and "sleep" futures, as
each one will operate entirely independently, and not cause any change
of state to any of the others. This typically allows you to wrap a
"timeout"-like behaviour around any other sort of IO operation by using
"needs_any" in Future or similar. If the real IO operation was
successful, the timeout can be safely cancelled. If the timeout
happens, the IO operation will be cancelled, and at this point the
application will have to discard the filehandle (or otherwise
resynchronse in some application-specific manner).
METHODS
accept
$socketfh = await Future::IO->accept( $fh );
Since version 0.11.
Returns a Future that will become done when a new connection has been
accepted on the given filehandle, which should represent a listen-mode
socket. The returned future will yield the newly-accepted client socket
filehandle.
alarm
await Future::IO->alarm( $epoch );
Since version 0.08.
Returns a Future that will become done at a fixed point in the future,
given as an epoch timestamp (such as returned by time()). This value
may be fractional.
connect
await Future::IO->connect( $fh, $name );
Since version 0.11.
Returns a Future that will become done when a connect() has succeeded
on the given filehandle to the given sockname address.
poll
$revents = await Future::IO->poll( $fh, $events );
Since version 0.19.
Returns a Future that will become done when the indicated IO operations
can be performed on the given filehandle. $events should be a bitfield
of one or more of the POSIX POLL* constants, such as POLLIN, POLLOUT or
POLLPRI. The result of the future will be a similar bitfield,
indicating which operations may now take place. If the POLLHUP, POLLERR
or POLLNVAL events happen, they will always be reported; you do not
need to request these specifically.
Multiple outstanding futures may be enqueued for the same filehandle.
When an event happens, only the first outstanding future that is
interested in it is informed; the rest will remain pending for the next
round of IO events, if the condition still prevails.
Note that, as compared to the real poll(2) system call, this method
only operates on a single filehandle; all futures returned by it are
independent and refer just to that one filehandle each.
Also note that, in general, it is better to use one of the higher-level
methods to perform whatver IO operation is required on the given
filehandle. The poll method is largely intended as a lowest-level
fallback, for example if integrating with some other library or module
that performs its own filehandle IO and just needs to be informed when
such IO operations may be performed.
For convenience, the POLL* constants are exported by this module. They
should be used in preference to the ones from IO::Poll, in case a
platform does not provide the latter module directly.
read
$bytes = await Future::IO->read( $fh, $length );
Since version 0.17. Before this version this method used to be named
sysread, and still available via that alias.
Returns a Future that will become done when at least one byte can be
read from the given filehandle. It may return up to $length bytes. On
EOF, the returned future will yield an empty list (or undef in scalar
context). On any error (other than EAGAIN / EWOULDBLOCK which are
ignored), the future fails with a suitable error message.
Note specifically this may perform only a single sysread() call, and
thus is not guaranteed to actually return the full length.
read_exactly
$bytes = await Future::IO->read_exactly( $fh, $length );
Since version 0.17. Before this version this method used to be named
sysread_exactly, and still available via that alias.
Returns a Future that will become done when exactly the given number of
bytes have been read from the given filehandle. It returns exactly
$length bytes. On EOF, the returned future will yield an empty list (or
undef in scalar context), even if fewer bytes have already been
obtained. These bytes will be lost. On any error (other than EAGAIN /
EWOULDBLOCK which are ignored), the future fails with a suitable error
message.
This may make more than one sysread() call.
read_until_eof
$f = Future::IO->read_until_eof( $fh );
Since version 0.17. Before this version this method used to be named
sysread_until_eof, and still available via that alias.
Returns a Future that will become done when the given filehandle
reaches the EOF condition. The returned future will yield all of the
bytes read up until that point.
recv
recvfrom
$bytes = await Future::IO->recv( $fh, $length );
$bytes = await Future::IO->recv( $fh, $length, $flags );
( $bytes, $from ) = await Future::IO->recvfrom( $fh, $length );
( $bytes, $from ) = await Future::IO->recvfrom( $fh, $length, $flags );
Since version 0.17.
Returns a Future that will become done when at least one byte is
received from the given filehandle (presumably a socket), by using a
recv(2) or recvfrom(2) system call. On any error (other than EAGAIN /
EWOULDBLOCK which are ignored) the future fails with a suitable error
message.
Optionally a flags bitmask in $flags can be passed. If no flags are
required, the value may be zero. The recvfrom method additionally
returns the sender's address as a second result value; this is
primarily used by unconnected datagram sockets.
send
$sent_len = await Future::IO->send( $fh, $bytes );
$sent_len = await Future::IO->send( $fh, $bytes, $flags );
$sent_len = await Future::IO->send( $fh, $bytes, $flags, $to );
Since version 0.17.
Returns a Future that will become done when at least one byte has been
sent to the given filehandle (presumably a socket), by using a send(2)
system call. On any error (other than EAGAIN / EWOULDBLOCK which are
ignored) the future fails with a suitable error message.
Optionally a flags bitmask in $flags or a destination address in $to
can also be passed. If no flags are required, the value may be zero. If
$to is specified then a sendto(2) system call is used instead.
sleep
await Future::IO->sleep( $secs );
Returns a Future that will become done a fixed delay from now, given in
seconds. This value may be fractional.
waitpid
$wstatus = await Future::IO->waitpid( $pid );
Since version 0.09.
Returns a Future that will become done when the given child process
terminates. The future will yield the wait status of the child process.
This can be inspected by the usual bitshifting operations as per $?:
if( my $termsig = ($wstatus & 0x7f) ) {
say "Terminated with signal $termsig";
}
else {
my $exitcode = ($wstatus >> 8);
say "Terminated with exit code $exitcode";
}
write
$written_len = await Future::IO->write( $fh, $bytes );
Since version 0.17. Before this version this method used to be named
syswrite, and still available via that alias.
Returns a Future that will become done when at least one byte has been
written to the given filehandle. It may write up to all of the bytes.
On any error (other than EAGAIN / EWOULDBLOCK which are ignored) the
future fails with a suitable error message.
Note specifically this may perform only a single syswrite() call, and
thus is not guaranteed to actually return the full length.
write_exactly
$written_len = await Future::IO->write_exactly( $fh, $bytes );
Since version 0.17. Before this version this method used to be named
syswrite_exactly, and still available via that alias.
Returns a Future that will become done when exactly the given bytes
have been written to the given filehandle. On any error (other than
EAGAIN / EWOULDBLOCK which are ignored) the future fails with a
suitable error message.
This may make more than one syswrite() call.
override_impl
Future::IO->override_impl( $impl );
Sets a new implementation for Future::IO, replacing the minimal default
internal implementation. This can either be a package name or an object
instance reference, but must provide the methods named above.
This method is intended to be called by event loops and other similar
places, to provide a better integration. Another way, which doesn't
involve directly depending on Future::IO or loading it, is to use the
$IMPL variable; see below.
Can only be called once, and only if the default implementation is not
in use, therefore a module that wishes to override this ought to invoke
it as soon as possible on program startup, before any of the main
Future::IO methods may have been called.
load_impl
Future::IO->load_impl( @names );
Since version 0.16.
Given a list of possible implementation module names, iterates through
them attempting to load each one until a suitable module is found. Any
errors encountered while loading each are ignored. If no module is
found to be suitable, an exception is thrown that likely aborts the
program.
@names should contain a list of Perl module names (which likely live in
the Future::IO::Impl::* prefix). If any name does not contain a ::
separator, it will have that prefix applied to it. This allows a
conveniently short list; e.g.
Future::IO->load_impl( qw( UV Glib IOAsync ) );
This method is intended to be called once, at startup, by the main
containing program. Since it sets the implementation, it would
generally be considered inappropriate to invoke this method from some
additional module that might be loaded by a containing program.
This is now discouraged, in favour of letting Future::IO decide instead
by using "load_best_impl".
load_best_impl
Future::IO->load_best_impl();
Since version 0.18.
Attempt to work out and load an implementation module.
In most situations, most programs don't really care what specific
implementation module they use, if they aren't already committed to
some other event system and also using Future::IO alongside it. This
method allows programs to offload the decision-making about which
specific implementations to try to load, to Future::IO itself.
This method works by attempting a few different strategies to determine
the "best" implementation to use. It maintains a list of the
currently-known CPAN modules which provide implementations, and
attempts them in a given preference order.
The environment variable PERL_FUTURE_IO_IMPL offers further control of
the behaviour of this method. Its value should be a comma-separated
list of implementation names to be attempted, in preference to any of
the others. Names prefixed with a hyphen will be skipped entirely by
any attempt.
1. First, if PERL_FUTURE_IO_IMPL is set, any of the names given are
tried, in order.
2. Then any of the modules that attempt to wrap other event systems
such as UV or Glib are attempted if it is detected that the other
event system is already loaded.
3. If none of these were successful, next it attempts any OS-specific
modules based on the OS name (given by $^O).
4. Finally, a list of other generic modules is attempted, which also
includes any of the wrapper implementations that can be started
independently.
For more details, consult the implementation code in this module to
find the current list of known modules and the order they are attempted
in.
HAVE_MULTIPLE_FILEHANDLES
$has = Future::IO->HAVE_MULTIPLE_FILEHANDLES;
Since version 0.11.
Returns true if the underlying IO implementation actually supports
multiple filehandles. Most real support modules will return true here,
but this returns false for the internal minimal implementation.
await
$f = $f->await;
Since version 0.07.
Blocks until this future is ready (either by success or failure). Does
not throw an exception if failed.
THE $IMPL VARIABLE
Since version 0.02.
As an alternative to setting an implementation by using override_impl,
a package variable is also available that allows modules such as event
systems to opportunistically provide an implementation without needing
to depend on the module, or loading it require. Simply directly set
that package variable to the name of an implementing package or an
object instance.
Additionally, implementors may use a name within the Future::IO::Impl::
namespace, suffixed by the name of their event system.
For example, something like the following code arrangement is
recommended.
package Future::IO::Impl::BananaLoop;
{
no warnings 'once';
( $Future::IO::IMPL //= __PACKAGE__ ) eq __PACKAGE__ or
warn "Unable to set Future::IO implementation to " . __PACKAGE__ .
" as it is already $Future::IO::IMPL\n";
}
sub sleep
{
...
}
sub sysread
{
...
}
sub syswrite
{
...
}
sub waitpid
{
...
}
Optionally, you can also implement "sysread_exactly" and
"syswrite_exactly":
sub sysread_exactly
{
...
}
sub syswrite_exactly
{
...
}
If not, they will be emulated by Future::IO itself, making multiple
calls to the non-_exactly versions.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>