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 of method => [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 form DECORATOR, 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.