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>