Scroll to navigation

Future::IO(3pm) User Contributed Perl Documentation Future::IO(3pm)

NAME

"Future::IO" - Future-returning IO methods

SYNOPSIS

   use Future::IO;
   my $delay = Future::IO->sleep( 5 );
   # $delay will become done in 5 seconds time
   my $input = Future::IO->sysread( \*STDIN, 4096 );
   # $input will yield some input from the STDIN IO handle

DESCRIPTION

This package provides a few basic methods that behave similarly to thesame-named core perl functions relating to IO operations, but yield theirresults asynchronously via Future instances.

This is provided primarily as a decoupling mechanism, to allow modules to bewritten that perform IO in an asynchronous manner to depend directly on this,while allowing asynchronous event systems to provide an implementation ofthese 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 "sysread" or "syswrite" 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 suchmodules 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 involvedIO operations, a real implementation based on an actual event loop should beprovided. The following are known to exist; CPAN may provide others:

  • Future::IO::Impl::Glib
  • Future::IO::Impl::IOAsync
  • Future::IO::Impl::UV

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 ormocking object, a unit test can check that the appropriate IO operationshappen as part of the test.

A testing module which does this is provided by Test::Future::IO.

METHODS

accept

   $socketfh = await Future::IO->accept( $fh );

Since version 0.11.

Returns a Future that will become done when a new connection has beenaccepted 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.

sleep

   await Future::IO->sleep( $secs );

Returns a Future that will become done a fixed delay from now, given inseconds. This value may be fractional.

sysread

   $bytes = await Future::IO->sysread( $fh, $length );

Returns a Future that will become done when at least one byte can be readfrom 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.

sysread_exactly

   $bytes = await Future::IO->sysread_exactly( $fh, $length );

Since version 0.03.

Returns a Future that will become done when exactly the given number ofbytes 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.

sysread_until_eof

   $f = Future::IO->sysread_until_eof( $fh );

Since version 0.12.

Returns a Future that will become done when the given filehandle reachesthe EOF condition. The returned future will yield all of the bytes read upuntil that point.

syswrite

   $written_len = await Future::IO->syswrite( $fh, $bytes );

Since version 0.04.

Returns a Future that will become done when at least one byte has beenwritten to the given filehandle. It may write up to all of the bytes. On anyerror (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.

syswrite_exactly

   $written_len = await Future::IO->syswrite_exactly( $fh, $bytes );

Since version 0.04.

Returns a Future that will become done when exactly the given bytes havebeen 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.

waitpid

   $wstatus = await Future::IO->waitpid( $pid );

Since version 0.09.

Returns a Future that will become done when the given child processterminates. 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";
   }

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 directlydepending 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 aspossible 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 themattempting to load each one until a suitable module is found. Any errorsencountered while loading each are ignored. If no module is found to besuitable, 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 containingprogram. Since it sets the implementation, it would generally be consideredinappropriate to invoke this method from some additional module that might beloaded by a containing program.

HAVE_MULTIPLE_FILEHANDLES

   $has = Future::IO->HAVE_MULTIPLE_FILEHANDLES;

Since version 0.11.

Returns true if the underlying IO implementation actually supports multiplefilehandles. Most real support modules will return true here, but this returnsfalse 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 notthrow an exception if failed.

THE $IMPL VARIABLE

Since version 0.02.

As an alternative to setting an implementation by using override_impl, apackage variable is also available that allows modules such as event systemsto opportunistically provide an implementation without needing to depend onthe 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>

2024-09-21 perl v5.38.2