1IO::Async::Process(3pm)User Contributed Perl DocumentatioInO::Async::Process(3pm)
2
6 "IO::Async::Process" - start and manage a child process
7
9 use IO::Async::Process;
10 use IO::Async::Loop;
12 my $loop = IO::Async::Loop->new;
13 my $process = IO::Async::Process->new(
15 command => [ "tr", "a-z", "n-za-m" ],
16 stdin => {
17 from => "hello world\n",
18 },
19 stdout => {
20 on_read => sub {
21 my ( $stream, $buffref ) = @_;
22 while( $$buffref =~ s/^(.*)\n// ) {
23 print "Rot13 of 'hello world' is '$1'\n";
24 }
25 return 0;
27 },
28 },
29 on_finish => sub {
31 $loop->stop;
32 },
33 );
34 $loop->add( $process );
36 $loop->run;
38 Also accessible via the "open_process" in IO::Async::Loop method:
40 $loop->open_process(
42 command => [ "/bin/ping", "-c4", "some.host" ],
43 stdout => {
45 on_read => sub {
46 my ( $stream, $buffref, $eof ) = @_;
47 while( $$buffref =~ s/^(.*)\n// ) {
48 print "PING wrote: $1\n";
49 }
50 return 0;
51 },
52 },
53 on_finish => sub {
55 my $process = shift;
56 my ( $exitcode ) = @_;
57 my $status = ( $exitcode >> 8 );
58 ...
59 },
60 );
61
63 This subclass of IO::Async::Notifier starts a child process, and
64 invokes a callback when it exits. The child process can either execute
65 a given block of code (via fork(2)), or a command.
66
68 The following events are invoked, either using subclass methods or CODE
69 references in parameters:
70 on_finish $exitcode
72 Invoked after the process has exited by normal means (i.e. an exit(2)
73 syscall from a process, or "return"ing from the code block), and has
74 closed all its file descriptors.
75 on_exception $exception, $errno, $exitcode
77 Invoked when the process exits by an exception from "code", or by
78 failing to exec(2) the given command. $errno will be a dualvar,
79 containing both number and string values. After a successful exec()
80 call, this condition can no longer happen.
81 Note that this has a different name and a different argument order from
83 "Loop->open_process"'s "on_error".
84 If this is not provided and the process exits with an exception, then
86 "on_finish" is invoked instead, being passed just the exit code.
87 Since this is just the results of the underlying "$loop->spawn_child"
89 "on_exit" handler in a different order it is possible that the
90 $exception field will be an empty string. It will however always be
91 defined. This can be used to distinguish the two cases:
92 on_exception => sub {
94 my $self = shift;
95 my ( $exception, $errno, $exitcode ) = @_;
96 if( length $exception ) {
98 print STDERR "The process died with the exception $exception " .
99 "(errno was $errno)\n";
100 }
101 elsif( ( my $status = W_EXITSTATUS($exitcode) ) == 255 ) {
102 print STDERR "The process failed to exec() - $errno\n";
103 }
104 else {
105 print STDERR "The process exited with exit status $status\n";
106 }
107 }
108
110 new
111 $process = IO::Async::Process->new( %args )
112 Constructs a new "IO::Async::Process" object and returns it.
114 Once constructed, the "Process" will need to be added to the "Loop"
116 before the child process is started.
117
119 The following named parameters may be passed to "new" or "configure":
120 on_finish => CODE
122 on_exception => CODE
123 CODE reference for the event handlers.
124 Once the "on_finish" continuation has been invoked, the
126 "IO::Async::Process" object is removed from the containing
127 IO::Async::Loop object.
128 The following parameters may be passed to "new", or to "configure"
130 before the process has been started (i.e. before it has been added to
131 the "Loop"). Once the process is running these cannot be changed.
132 command => ARRAY or STRING
134 Either a reference to an array containing the command and its
135 arguments, or a plain string containing the command. This value is
136 passed into perl's exec(2) function.
137 code => CODE
139 A block of code to execute in the child process. It will be called in
140 scalar context inside an "eval" block.
141 setup => ARRAY
143 Optional reference to an array to pass to the underlying "Loop"
144 "spawn_child" method.
145 fdn => HASH
147 A hash describing how to set up file descriptor n. The hash may contain
148 the following keys:
149 via => STRING
151 Configures how this file descriptor will be configured for the
152 child process. Must be given one of the following mode names:
153 pipe_read
155 The child will be given the writing end of a pipe(2); the
156 parent may read from the other.
157 pipe_write
159 The child will be given the reading end of a pipe(2); the
160 parent may write to the other. Since an EOF condition of this
161 kind of handle cannot reliably be detected, "on_finish" will
162 not wait for this type of pipe to be closed.
163 pipe_rdwr
165 Only valid on the "stdio" filehandle. The child will be given
166 the reading end of one pipe(2) on STDIN and the writing end of
167 another on STDOUT. A single Stream object will be created in
168 the parent configured for both filehandles.
169 socketpair
171 The child will be given one end of a socketpair(2); the parent
172 will be given the other. The family of this socket may be given
173 by the extra key called "family"; defaulting to "unix". The
174 socktype of this socket may be given by the extra key called
175 "socktype"; defaulting to "stream". If the type is not
176 "SOCK_STREAM" then a IO::Async::Socket object will be
177 constructed for the parent side of the handle, rather than
178 IO::Async::Stream.
179 Once the filehandle is set up, the "fd" method (or its shortcuts of
181 "stdin", "stdout" or "stderr") may be used to access the
182 IO::Async::Handle-subclassed object wrapped around it.
183 The value of this argument is implied by any of the following
185 alternatives.
186 on_read => CODE
188 The child will be given the writing end of a pipe. The reading end
189 will be wrapped by an IO::Async::Stream using this "on_read"
190 callback function.
191 into => SCALAR
193 The child will be given the writing end of a pipe. The referenced
194 scalar will be filled by data read from the child process. This
195 data may not be available until the pipe has been closed by the
196 child.
197 from => STRING
199 The child will be given the reading end of a pipe. The string given
200 by the "from" parameter will be written to the child. When all of
201 the data has been written the pipe will be closed.
202 prefork => CODE
204 Only valid for handles with a "via" of "socketpair". The code block
205 runs after the socketpair(2) is created, but before the child is
206 forked. This is handy for when you adjust both ends of the created
207 socket (for example, to use setsockopt(3)) from the controlling
208 parent, before the child code runs. The arguments passed in are
209 the IO::Socket objects for the parent and child ends of the socket.
210 $prefork->( $localfd, $childfd )
212 stdin => ...
214 stdout => ...
215 stderr => ...
216 Shortcuts for "fd0", "fd1" and "fd2" respectively.
217 stdio => ...
219 Special filehandle to affect STDIN and STDOUT at the same time. This
220 filehandle supports being configured for both reading and writing at
221 the same time.
222
224 finish_future
225 $f = $process->finish_future
226 Since version 0.75.
228 Returns a Future that completes when the process finishes. It will
230 yield the exit code from the process.
231 pid
233 $pid = $process->pid
234 Returns the process ID of the process, if it has been started, or
236 "undef" if not. Its value is preserved after the process exits, so it
237 may be inspected during the "on_finish" or "on_exception" events.
238 kill
240 $process->kill( $signal )
241 Sends a signal to the process
243 is_running
245 $running = $process->is_running
246 Returns true if the Process has been started, and has not yet finished.
248 is_exited
250 $exited = $process->is_exited
251 Returns true if the Process has finished running, and finished due to
253 normal exit(2).
254 exitstatus
256 $status = $process->exitstatus
257 If the process exited due to normal exit(2), returns the value that was
259 passed to exit(2). Otherwise, returns "undef".
260 exception
262 $exception = $process->exception
263 If the process exited due to an exception, returns the exception that
265 was thrown. Otherwise, returns "undef".
266 errno
268 $errno = $process->errno
269 If the process exited due to an exception, returns the numerical value
271 of $! at the time the exception was thrown. Otherwise, returns "undef".
272 errstr
274 $errstr = $process->errstr
275 If the process exited due to an exception, returns the string value of
277 $! at the time the exception was thrown. Otherwise, returns "undef".
278 fd
280 $stream = $process->fd( $fd )
281 Returns the IO::Async::Stream or IO::Async::Socket associated with the
283 given FD number. This must have been set up by a "configure" argument
284 prior to adding the "Process" object to the "Loop".
285 The returned object have its read or write handle set to the other end
287 of a pipe or socket connected to that FD number in the child process.
288 Typically, this will be used to call the "write" method on, to write
289 more data into the child, or to set an "on_read" handler to read data
290 out of the child.
291 The "on_closed" event for these streams must not be changed, or it will
293 break the close detection used by the "Process" object and the
294 "on_finish" event will not be invoked.
295 stdin
297 stdout
298 stderr
299 stdio
300 $stream = $process->stdin
301 $stream = $process->stdout
303 $stream = $process->stderr
305 $stream = $process->stdio
307 Shortcuts for calling "fd" with 0, 1, 2 or "io" respectively, to obtain
309 the IO::Async::Stream representing the standard input, output, error,
310 or combined input/output streams of the child process.
311
313 Capturing the STDOUT stream of a process
314 By configuring the "stdout" filehandle of the process using the "into"
315 key, data written by the process can be captured.
316 my $stdout;
318 my $process = IO::Async::Process->new(
319 command => [ "writing-program", "arguments" ],
320 stdout => { into => \$stdout },
321 on_finish => sub {
322 my $process = shift;
323 my ( $exitcode ) = @_;
324 print "Process has exited with code $exitcode, and wrote:\n";
325 print $stdout;
326 }
327 );
328 $loop->add( $process );
330 Note that until "on_finish" is invoked, no guarantees are made about
332 how much of the data actually written by the process is yet in the
333 $stdout scalar.
334 See also the "run_child" method of IO::Async::Loop.
336 To handle data more interactively as it arrives, the "on_read" key can
338 instead be used, to provide a callback function to invoke whenever more
339 data is available from the process.
340 my $process = IO::Async::Process->new(
342 command => [ "writing-program", "arguments" ],
343 stdout => {
344 on_read => sub {
345 my ( $stream, $buffref ) = @_;
346 while( $$buffref =~ s/^(.*)\n// ) {
347 print "The process wrote a line: $1\n";
348 }
349 return 0;
351 },
352 },
353 on_finish => sub {
354 print "The process has finished\n";
355 }
356 );
357 $loop->add( $process );
359 If the code to handle data read from the process isn't available yet
361 when the object is constructed, it can be supplied later by using the
362 "configure" method on the "stdout" filestream at some point before it
363 gets added to the Loop. In this case, "stdin" should be configured
364 using "pipe_read" in the "via" key.
365 my $process = IO::Async::Process->new(
367 command => [ "writing-program", "arguments" ],
368 stdout => { via => "pipe_read" },
369 on_finish => sub {
370 print "The process has finished\n";
371 }
372 );
373 $process->stdout->configure(
375 on_read => sub {
376 my ( $stream, $buffref ) = @_;
377 while( $$buffref =~ s/^(.*)\n// ) {
378 print "The process wrote a line: $1\n";
379 }
380 return 0;
382 },
383 );
384 $loop->add( $process );
386 Sending data to STDIN of a process
388 By configuring the "stdin" filehandle of the process using the "from"
389 key, data can be written into the "STDIN" stream of the process.
390 my $process = IO::Async::Process->new(
392 command => [ "reading-program", "arguments" ],
393 stdin => { from => "Here is the data to send\n" },
394 on_finish => sub {
395 print "The process has finished\n";
396 }
397 );
398 $loop->add( $process );
400 The data in this scalar will be written until it is all consumed, then
402 the handle will be closed. This may be useful if the program waits for
403 EOF on "STDIN" before it exits.
404 To have the ability to write more data into the process once it has
406 started. the "write" method on the "stdin" stream can be used, when it
407 is configured using the "pipe_write" value for "via":
408 my $process = IO::Async::Process->new(
410 command => [ "reading-program", "arguments" ],
411 stdin => { via => "pipe_write" },
412 on_finish => sub {
413 print "The process has finished\n";
414 }
415 );
416 $loop->add( $process );
418 $process->stdin->write( "Here is some more data\n" );
420 Setting socket options
422 By using the "prefork" code block you can change the socket receive
423 buffer size at both ends of the socket before the child is forked (at
424 which point it would be too late for the parent to be able to change
425 the child end of the socket).
426 use Socket qw( SOL_SOCKET SO_RCVBUF );
428 my $process = IO::Async::Process->new(
430 command => [ "command-to-read-from-and-write-to", "arguments" ],
431 stdio => {
432 via => "socketpair",
433 prefork => sub {
434 my ( $parentfd, $childfd ) = @_;
435 # Set parent end of socket receive buffer to 3 MB
437 $parentfd->setsockopt(SOL_SOCKET, SO_RCVBUF, 3 * 1024 * 1024);
438 # Set child end of socket receive buffer to 3 MB
439 $childfd ->setsockopt(SOL_SOCKET, SO_RCVBUF, 3 * 1024 * 1024);
440 },
441 },
442 );
443 $loop->add( $process );
445
447 Paul Evans <leonerd@leonerd.org.uk>
448perl v5.36.1 2023-05-14 IO::Async::Process(3pm)