plucky (3) Future::IO::System.3pm.gz

NAME

       "Future::IO::System" - "system()"-like methods for Future::IO

SYNOPSIS

          use Future::IO;
          use Future::IO::System;

          my $f = Future::IO::System->system( "cmd", "args go", "here" );
          # $f will become done when the command completes

          my $f = Future::IO::System->system_out( "cmd", "-v" );
          my ( $status, $out ) = $f->get;

          # $status will contain the exit code and $out will contain what it wrote
          # to STDOUT

DESCRIPTION

       This package contains a selection of methods that behave like the core system() and related functions,
       running asynchronously via Future::IO.

       In particular, the "system" behaves somewhat like CORE::system() and "system_out" behaves somewhat like
       qx().

   Portability
       In order for this module to work at all, the underlying "Future::IO" implementation must support the
       "waitpid" in Future::IO method. The default minimal implementation included with the module does not, but
       most of the additional implementations from CPAN will.

       In addition, the operation of this module uses techniques that only really work on full POSIX systems
       (such as Linux, Mac OS X, the various BSDs, etc).  It is unlikely to work in places like MSWin32.

METHODS

   run
          ( $exitcode, ... ) = await Future::IO::System->run(
             argv => [ $path, @args ],
             ...
          );

       Since version 0.12.

       Runs the given $path with the given @args as a sub-process, optionally with some additional filehandles
       set up as determined by the other arguments.  The returned Future will yield the waitpid() exit code from
       the process when it terminates, and optionally the bytes read from the other filehandles that were set
       up.

       Takes the following named arguments

       argv => ARRAY
           An array reference containing the path and arguments to pass to exec() in the child process.

       in => STRING
           If defined, create a pipe and assign the reading end to the child process's STDIN filehandle. The
           given string will then be written to the pipe, after which the pipe will be closed.

       want_out => BOOL
           If true, create a pipe and assign the writing end to the child process's STDOUT filehandle. The
           returned future will additionally contain all the bytes read from it until EOF.

       want_err => BOOL
           If true, create a pipe and assign the writing end to the child process's STDERR filehandle. The
           returned future will additionally contain all the bytes read from it until EOF.

       The remaining methods in this class are simplified wrappers of this one.

   system
          $exitcode = await Future::IO::System->system( $path, @args );

       Since version 0.12.

       Runs the given $path with the given @args as a sub-process with no extra filehandles.

   system_out
          ( $exitcode, $out ) = await Future::IO::System->system_out( $path, @args );

       Since version 0.12.

       Runs the given $path with the given @args as a sub-process with a new pipe as its STDOUT filehandle. The
       returned Future will additionally yield the bytes read from the STDOUT pipe.

TODO

       •   Add some OS portability guard warnings when loading the module on platforms not known to support it.

       •   Consider what other features of modules like IPC::Run or IO::Async::Process to support here. Try not
           to go overboard.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>