NAME
AnyEvent::Process - Start a process and watch for events
SYNOPSIS
use AnyEvent::Process;
my $proc = new AnyEvent::Process(
fh_table => [
# Connect OUTPIPE file handle to STDIN of a new process
\*STDIN => ['pipe', '<', \*OUTPIPE],
# Connect INPIPE file handle to STDOUT of a new process
\*STDOUT => ['pipe', '>', \*INPIPE],
# Print everything written to STDERR by a new process to STDERR of current
# process, but prefix every line with 'bc ERROR: '
\*STDERR => ['decorate', '>', 'bc ERROR: ', \*STDERR]
],
# We don't want to wait longer than 10 seconds, so kill bc after that time
kill_interval => 10,
# Execute bc in a new process
code => sub {
exec 'bc', '-q';
});
# Start bc in a new process
$proc->run();
# Send data to bc standart input
print OUTPIPE "123^456\n";
close OUTPIPE;
# Read from bc standart output
my $result = <INPIPE>;
print "BC computed $result";
DESCRIPTION
This module starts a new process. It allows connecting file descriptor in the new process to files or handles (both to perl handles or to AnyEvent:Handle).
It is possible to monitor the process execution using a watchdog callback or kill the process after a defined time.
METHODS
new
Creates new AnyEvent::Process instance.
Arguments:
- fh_table (optional)
-
Can be used to define opened files in a created process. Syntax of this option is the following:
[ HANDLE => [TYPE, DIRECTION, ARGS...], HANDLE => [TYPE, DIRECTION, ARGS...], ... ]
where
- HANDLE
-
is a handle reference or a filedescriptor number, which will be opened in the new process.
- DIRECTION
-
can be
>
if the HANDLE in the new process shall be opened for writting,<
if it shall be opened for reading or+<
if it shall be opened in the read-write mode. - TYPE
-
Following types are supported:
- pipe
-
Opens an unidirectional pipe or a bidirectional socket (depends on the DIRECTION) between the current and the new process. ARGS can be a glob reference, then the second end of the pipe or socket pair is connected to it, or
handle => [handle_args...]
, where handle_args are an argument passed to the AnyEvent::Handle constructor, which will be connected to the second end of the pipe or socket. In the a case handle_args is in the form ofmethod => [method_args...]
and method is AnyEvent::Handle method, then this method is called with method_args, after the handle is instantiated.Example: \*STDOUT => ['pipe', '>', handle => [push_read => [line => \&reader]]]
- open
-
Opens the specified HANDLE using open with DIRECTION and ARGS as its arguments.
Example: 0 => ['open', '<', '/dev/null']
- decorate
-
Decorate every line written to the HANDLE by the child. The DIRECTION must be
>
. ARGS are in the formDECORATOR, OUTPUT
. OUTPUT is a glob reference and specifies a file handle, into which decorated lines are written. Decorator is a string or a code reference. If the decorator is a string, it is prepended to every line written by the started process. If the DECORATOR is a code reference, it is called for each line written to the HANDLE with that line as its argument and its return value is written to the OUTPUT.Example: \*STDERR => ['decorate', '>', 'Child STDERR: ', \*STDERR]
- code (optional, but must be specified either in new or run)
-
A code reference, which is executed in the newly started process.
- args (optional)
-
Arguments past to a code reference specified as code argument when it is called.
- on_completion (optional)
-
Callback, which is executed when the process finishes. It receives AnyEvent::Process::Job instance as the first argument and exit code as the second argument.
It is called after all AnyEvent::Handle callbacks specified in the fh_table.
- watchdog_interval (in seconds, optional)
-
How often a watchdog shall be called. If undefined or set to 0, the watchdog functionality is disabled.
- on_watchdog (optional)
-
Watchdog callback, receives AnyEvent::Process::Job instance as its argument. If it returns false value, the watched process is killed (see on_kill).
- kill_interval (in seconds, optional)
-
Maximum time the process can run. After this time expires, the process is killed.
- on_kill (optional, sends SIGKILL by default)
-
Called, when the process shall be killed. Receives AnyEvent::Process::Job instance as its argument.
run
Run a process. Any argument specified to the constructor can be overridden here. Returns AnyEvent::Process::Job, which represents the new process, or undef on an error.
- Returned AnyEvent::Process::Job instance has following methods:
-
- pid
-
Returns PID of the process.
- kill
-
Send signal specified as the argument to the process.
- close
-
Close all pipes and socketpairs between this process and the child.
kill
Run the kill method of the latest created AnyEvent::Process::Job - sends signal specified as its argument to the process.
pid
Run the pid method of the latest created AnyEvent::Process::Job - returns PID of the process.
close
Run the close method of the latest created AnyEvent::Process::Job.
SEE ALSO
AnyEvent - Event framework for PERL.
AnyEvent::Subprocess - Similar module, but with more dependencies and a little more complicated usage.
AUTHOR
Petr Malat <oss@malat.biz> http://malat.biz/
COPYRIGHT
Copyright (c) 2012 by Petr Malat <oss@malat.biz>
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html.