1Future::IO::System(3) User Contributed Perl DocumentationFuture::IO::System(3)
2
3
4

NAME

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

SYNOPSIS

9          use Future::IO;
10          use Future::IO::System;
11
12          my $f = Future::IO::System->system( "cmd", "args go", "here" );
13          # $f will become done when the command completes
14
15          my $f = Future::IO::System->system_out( "cmd", "-v" );
16          my ( $status, $out ) = $f->get;
17
18          # $status will contain the exit code and $out will contain what it wrote
19          # to STDOUT
20

DESCRIPTION

22       This package contains a selection of methods that behave like the core
23       system() and related functions, running asynchronously via Future::IO.
24
25       In particular, the "system" behaves somewhat like CORE::system() and
26       "system_out" behaves somewhat like qx().
27
28   Portability
29       In order for this module to work at all, the underlying "Future::IO"
30       implementation must support the "waitpid" in Future::IO method. The
31       default minimal implementation included with the module does not, but
32       most of the additional implementations from CPAN will.
33
34       In addition, the operation of this module uses techniques that only
35       really work on full POSIX systems (such as Linux, Mac OS X, the various
36       BSDs, etc).  It is unlikely to work in places like MSWin32.
37

METHODS

39   run
40          ( $exitcode, ... ) = await Future::IO::System->run(
41             argv => [ $path, @args ],
42             ...
43          );
44
45       Since version 0.12.
46
47       Runs the given $path with the given @args as a sub-process, optionally
48       with some additional filehandles set up as determined by the other
49       arguments.  The returned Future will yield the waitpid() exit code from
50       the process when it terminates, and optionally the bytes read from the
51       other filehandles that were set up.
52
53       Takes the following named arguments
54
55       argv => ARRAY
56           An array reference containing the path and arguments to pass to
57           exec() in the child process.
58
59       in => STRING
60           If defined, create a pipe and assign the reading end to the child
61           process's STDIN filehandle. The given string will then be written
62           to the pipe, after which the pipe will be closed.
63
64       want_out => BOOL
65           If true, create a pipe and assign the writing end to the child
66           process's STDOUT filehandle. The returned future will additionally
67           contain all the bytes read from it until EOF.
68
69       want_err => BOOL
70           If true, create a pipe and assign the writing end to the child
71           process's STDERR filehandle. The returned future will additionally
72           contain all the bytes read from it until EOF.
73
74       The remaining methods in this class are simplified wrappers of this
75       one.
76
77   system
78          $exitcode = await Future::IO::System->system( $path, @args );
79
80       Since version 0.12.
81
82       Runs the given $path with the given @args as a sub-process with no
83       extra filehandles.
84
85   system_out
86          ( $exitcode, $out ) = await Future::IO::System->system_out( $path, @args );
87
88       Since version 0.12.
89
90       Runs the given $path with the given @args as a sub-process with a new
91       pipe as its STDOUT filehandle. The returned Future will additionally
92       yield the bytes read from the STDOUT pipe.
93

TODO

95       •   Add some OS portability guard warnings when loading the module on
96           platforms not known to support it.
97
98       •   Consider what other features of modules like IPC::Run or
99           IO::Async::Process to support here. Try not to go overboard.
100

AUTHOR

102       Paul Evans <leonerd@leonerd.org.uk>
103
104
105
106perl v5.36.0                      2023-02-05             Future::IO::System(3)