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

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.40.0                                       2024-09-21                                    Future::IO(3pm)

       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.

   DefaultImplementation
       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 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 provided. The following are known to exist; CPAN
       may provide others:

       •   Future::IO::Impl::Glib

       •   Future::IO::Impl::IOAsync

       •   Future::IO::Impl::UV

   UnitTesting
       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.

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

       Sinceversion0.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 );

       Sinceversion0.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 );

       Sinceversion0.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 in seconds. 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 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.

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

       Sinceversion0.03.

       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.

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

       Sinceversion0.12.

       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.

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

       Sinceversion0.04.

       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.

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

       Sinceversion0.04.

       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.

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

       Sinceversion0.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";
          }

   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 );

       Sinceversion0.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.

   HAVE_MULTIPLE_FILEHANDLES
          $has = Future::IO->HAVE_MULTIPLE_FILEHANDLES;

       Sinceversion0.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;

       Sinceversion0.07.

       Blocks until this future is ready (either by success or failure). Does not throw an exception if failed.

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

          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

Sinceversion0.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.