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>