IO::Async::Process - start and manage a child process
IO::Async::Process
use IO::Async::Process; use IO::Async::Loop; my $loop = IO::Async::Loop->new; my $process = IO::Async::Process->new( command => [ "tr", "a-z", "n-za-m" ], stdin => { from => "hello world\n", }, stdout => { on_read => sub { my ( $stream, $buffref ) = @_; while( $$buffref =~ s/^(.*)\n// ) { print "Rot13 of 'hello world' is '$1'\n"; } return 0; }, }, on_finish => sub { $loop->stop; }, ); $loop->add( $process ); $loop->run;
This subclass of IO::Async::Notifier starts a child process, and invokes a callback when it exits. The child process can either execute a given block of code (via fork(2)), or a command.
fork(2)
The following events are invoked, either using subclass methods or CODE references in parameters:
Invoked after the process has exited by normal means (i.e. an exit(2) syscall from a process, or returning from the code block), and has closed all its file descriptors.
exit(2)
return
Invoked when the process exits by an exception from code, or by failing to exec(2) the given command. $errno will be a dualvar, containing both number and string values. After a successful exec() call, this condition can no longer happen.
code
exec(2)
$errno
exec()
Note that this has a different name and a different argument order from Loop->open_child's on_error.
Loop->open_child
on_error
If this is not provided and the process exits with an exception, then on_finish is invoked instead, being passed just the exit code.
on_finish
Since this is just the results of the underlying $loop->spawn_child on_exit handler in a different order it is possible that the $exception field will be an empty string. It will however always be defined. This can be used to distinguish the two cases:
$loop->spawn_child
on_exit
$exception
on_exception => sub { my ( $self, $exception, $errno, $exitcode ) = @_; if( length $exception ) { print STDERR "The process died with the exception $exception " . "(errno was $errno)\n"; } elsif( ( my $status = W_EXITSTATUS($exitcode) ) == 255 ) { print STDERR "The process failed to exec() - $errno\n"; } else { print STDERR "The process exited with exit status $status\n"; } }
$process = IO::Async::Process->new( %args )
Constructs a new IO::Async::Process object and returns it.
Once constructed, the Process will need to be added to the Loop before the child process is started.
Process
Loop
The following named parameters may be passed to new or configure:
new
configure
CODE reference for the event handlers.
Once the on_finish continuation has been invoked, the IO::Async::Process object is removed from the containing IO::Async::Loop object.
The following parameters may be passed to new, or to configure before the process has been started (i.e. before it has been added to the Loop). Once the process is running these cannot be changed.
Either a reference to an array containing the command and its arguments, or a plain string containing the command. This value is passed into perl's exec(2) function.
A block of code to execute in the child process. It will be called in scalar context inside an eval block.
eval
Optional reference to an array to pass to the underlying Loop spawn_child method.
spawn_child
A hash describing how to set up file descriptor n. The hash may contain the following keys:
Configures how this file descriptor will be configured for the child process. Must be given one of the following mode names:
The child will be given the writing end of a pipe(2); the parent may read from the other.
pipe(2)
The child will be given the reading end of a pipe(2); the parent may write to the other. Since an EOF condition of this kind of handle cannot reliably be detected, on_finish will not wait for this type of pipe to be closed.
Only valid on the stdio filehandle. The child will be given the reading end of one pipe(2) on STDIN and the writing end of another on STDOUT. A single Stream object will be created in the parent configured for both filehandles.
stdio
The child will be given one end of a socketpair(2); the parent will be given the other. The family of this socket may be given by the extra key called family; defaulting to unix. The socktype of this socket may be given by the extra key called socktype; defaulting to stream. If the type is not SOCK_STREAM then a IO::Async::Socket object will be constructed for the parent side of the handle, rather than IO::Async::Stream.
socketpair(2)
family
unix
socktype
stream
SOCK_STREAM
Once the filehandle is set up, the fd method (or its shortcuts of stdin, stdout or stderr) may be used to access the IO::Async::Handle-subclassed object wrapped around it.
fd
stdin
stdout
stderr
The value of this argument is implied by any of the following alternatives.
The child will be given the writing end of a pipe. The reading end will be wrapped by an IO::Async::Stream using this on_read callback function.
on_read
The child will be given the writing end of a pipe. The referenced scalar will be filled by data read from the child process. This data may not be available until the pipe has been closed by the child.
The child will be given the reading end of a pipe. The string given by the from parameter will be written to the child. When all of the data has been written the pipe will be closed.
from
Shortcuts for fd0, fd1 and fd2 respectively.
fd0
fd1
fd2
Special filehandle to affect STDIN and STDOUT at the same time. This filehandle supports being configured for both reading and writing at the same time.
$pid = $process->pid
Returns the process ID of the process, if it has been started, or undef if not. Its value is preserved after the process exits, so it may be inspected during the on_finish or on_exception events.
undef
on_exception
$process->kill( $signal )
Sends a signal to the process
$running = $process->is_running
Returns true if the Process has been started, and has not yet finished.
$exited = $process->is_exited
Returns true if the Process has finished running, and finished due to normal exit(2).
$status = $process->exitstatus
If the process exited due to normal exit(2), returns the value that was passed to exit(2). Otherwise, returns undef.
$exception = $process->exception
If the process exited due to an exception, returns the exception that was thrown. Otherwise, returns undef.
$errno = $process->errno
If the process exited due to an exception, returns the numerical value of $! at the time the exception was thrown. Otherwise, returns undef.
$!
$errstr = $process->errstr
If the process exited due to an exception, returns the string value of $! at the time the exception was thrown. Otherwise, returns undef.
$stream = $process->fd( $fd )
Returns the IO::Async::Stream or IO::Async::Socket associated with the given FD number. This must have been set up by a configure argument prior to adding the Process object to the Loop.
The returned object have its read or write handle set to the other end of a pipe or socket connected to that FD number in the child process. Typically, this will be used to call the write method on, to write more data into the child, or to set an on_read handler to read data out of the child.
write
The on_closed event for these streams must not be changed, or it will break the close detection used by the Process object and the on_finish event will not be invoked.
on_closed
$stream = $process->stdin $stream = $process->stdout $stream = $process->stderr $stream = $process->stdio
Shortcuts for calling fd with 0, 1, 2 or io respectively, to obtain the IO::Async::Stream representing the standard input, output, error, or combined input/output streams of the child process.
io
By configuring the stdout filehandle of the process using the into key, data written by the process can be captured.
into
my $stdout; my $process = IO::Async::Process->new( command => [ "writing-program", "arguments" ], stdout => { into => \$stdout }, on_finish => sub { print "The process has finished, and wrote:\n"; print $stdout; } ); $loop->add( $process );
Note that until on_finish is invoked, no guarantees are made about how much of the data actually written by the process is yet in the $stdout scalar.
$stdout
See also the run_child method of IO::Async::Loop.
run_child
To handle data more interactively as it arrives, the on_read key can instead be used, to provide a callback function to invoke whenever more data is available from the process.
my $process = IO::Async::Process->new( command => [ "writing-program", "arguments" ], stdout => { on_read => sub { my ( $stream, $buffref ) = @_; while( $$buffref =~ s/^(.*)\n// ) { print "The process wrote a line: $1\n"; } return 0; }, }, on_finish => sub { print "The process has finished\n"; } ); $loop->add( $process );
If the code to handle data read from the process isn't available yet when the object is constructed, it can be supplied later by using the configure method on the stdout filestream at some point before it gets added to the Loop. In this case, stdin should be configured using pipe_read in the via key.
pipe_read
via
my $process = IO::Async::Process->new( command => [ "writing-program", "arguments" ], stdout => { via => "pipe_read" }, on_finish => sub { print "The process has finished\n"; } ); $process->stdout->configure( on_read => sub { my ( $stream, $buffref ) = @_; while( $$buffref =~ s/^(.*)\n// ) { print "The process wrote a line: $1\n"; } return 0; }, ); $loop->add( $process );
By configuring the stdin filehandle of the process using the from key, data can be written into the STDIN stream of the process.
STDIN
my $process = IO::Async::Process->new( command => [ "reading-program", "arguments" ], stdin => { from => "Here is the data to send\n" }, on_finish => sub { print "The process has finished\n"; } ); $loop->add( $process );
The data in this scalar will be written until it is all consumed, then the handle will be closed. This may be useful if the program waits for EOF on STDIN before it exits.
To have the ability to write more data into the process once it has started. the write method on the stdin stream can be used, when it is configured using the pipe_write value for via:
pipe_write
my $process = IO::Async::Process->new( command => [ "reading-program", "arguments" ], stdin => { via => "pipe_write" }, on_finish => sub { print "The process has finished\n"; } ); $loop->add( $process ); $process->stdin->write( "Here is some more data\n" );
Paul Evans <leonerd@leonerd.org.uk>
To install IO::Async, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Async
CPAN shell
perl -MCPAN -e shell install IO::Async
For more information on module installation, please visit the detailed CPAN module installation guide.