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 ) = @_;
while( $$buffref =~ s/^(.*)\n// ) {
print "Rot13 of 'hello world' is '$1'\n";
}
return 0;
},
},
on_finish => sub {
$loop->stop;
},
);
$loop->add( $process );
$loop->run;
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(2)), or a command.
EVENTS¶
The following events are invoked, either using subclass methods or CODE
references in parameters:
on_finish $exitcode¶
Invoked after the process has exited by normal means (i.e. an
exit(2) syscall
from a process, or "return"ing from the code block), and has closed
all its file descriptors.
on_exception $exception, $errno, $exitcode¶
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.
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(2) 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 the following keys:
- via => STRING
- Configures how this file descriptor will be configured for
the child process. Must be given one of the following mode names:
- pipe_read
- The child will be given the writing end of a pipe(2); the
parent may read from the other.
- pipe_write
- 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.
- pipe_rdwr
- 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.
- socketpair
- 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".
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.
The value of this argument is implied by any of the following
alternatives.
- 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.
- into => SCALAR
- 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.
- 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.
- stdio => ...
- 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.
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.
$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.
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¶
$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.
EXAMPLES¶
Capturing the STDOUT stream of a process¶
By configuring the "stdout" filehandle of the process using the
"into" key, data written by the process can be captured.
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.
See also the "run_child" method of IO::Async::Loop.
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.
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 );
Sending data to STDIN of a process¶
By configuring the "stdin" filehandle of the process using the
"from" key, data can be written into the "STDIN" stream of
the process.
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":
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" );
AUTHOR¶
Paul Evans <leonerd@leonerd.org.uk>