NAME

IO::Async::Process - start and manage a child process

SYNOPSIS

 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 ) = @_;
          $$buffref =~ s/^(.*)\n// or return 0;

          print "Rot13 of 'hello world' is '$1'\n";
       },
    },
    
    on_finish => sub {
       $loop->loop_stop;
    },
 );

 $loop->add( $process );

 $loop->loop_forever;

DESCRIPTION

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()), or a command.

EVENTS

The following events are invoked, either using subclass methods or CODE references in parameters:

on_finish $exitcode

Invoked when the process exits by normal means.

on_exception $exception, $errno, $exitcode

Invoked when the process exits by an exception from code, or by failing to exec() the given command. $errno will be a dualvar, containing both number and string values.

Note that this has a different name and a different argument order from Loop->open_child's 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.

CONSTRUCTOR

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

PARAMETERS

The following named parameters may be passed to new or configure:

on_finish => CODE

on_exception => CODE

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.

command => ARRAY or STRING

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

code => CODE

A block of code to execute in the child process. It will be called in scalar context inside an eval block.

setup => ARRAY

Optional reference to an array to pass to the underlying Loop spawn_child method.

fdn => HASH

A hash describing how to set up file descriptor n. The hash may contain one of the following sets of keys:

on_read => CODE

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.

from => STRING

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.

stdin => ...

stdout => ...

stderr => ...

Shortcuts for fd0, fd1 and fd2 respectively.

METHODS

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

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

$status = $process->exitstatus

If the process exited due to normal exit(), returns the value that was passed to exit(). 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 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 Stream object have its read or write handle set to the other end of a pipe 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.

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.

$stream = $process->stdin

$stream = $process->stdout

$stream = $process->stderr

Shortcuts for calling fd with 0, 1, or 2 respectively, to obtain the IO::Async::Stream representing the standard input, output, or error streams of the child process.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm IO::Async

perl -MCPAN -e shell
install IO::Async