DOKK / manpages / debian 12 / libfuture-io-perl / Future::IO::System.3pm.en
Future::IO::System(3pm) User Contributed Perl Documentation Future::IO::System(3pm)

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

   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

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().

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.

   ( $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

An array reference containing the path and arguments to pass to "exec()" in the child process.
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.
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.
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.

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

   ( $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.

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

Paul Evans <leonerd@leonerd.org.uk>

2023-02-21 perl v5.36.0