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 watchdog callback or kill the process after defined time.

METHODS

new

Creates new AnyEvent::Process instance.

Arguments:

fh_table (optional)

Can be used to define open 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 filedescriptor number, which will be opened in the new process.

DIRECTION

can be > if the HANDLE in new process shall be opened for writting, < if it shall be opened for reading or +< if it shall be opened in read-write mode.

TYPE

Following types are supported:

pipe

Opens unidirectional pipe or bidirectional socket (depends on DIRECTION) between current and new process. ARGS can be a glob reference, then the second and of pipe or socket pair is connected to it, or handle => [handle_args...], where handle_args are argument passed to AnyEvent::Handle constructor, which will be connected to the second end of pipe or socket. In the 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 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 child. 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 started process. If DECORATOR is a code reference, it is called for each line written to HANDLE with that line as argument and its return value is written to 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 callback specified in fh_table.

watchdog_interval (in seconds, optional)

How often a watchdog shall be called. If undefined or set to 0, watchdog functionality is disabled.

on_watchdog (optional)

Watchdog callback, receives AnyEvent::Process::Job instance as an argument. If it returns false value, 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 an argument.

run

Run a process. Any argument specified to constructor can be overridden here. Returns AnyEvent::Process::Job, which represents the new process, or undef on error.

Returned AnyEvent::Process::Job instance has following methods:

pid

Returns PID of the process.

kill

Send signal specified as argument to the process.

close

Close all pipes and socketpairs between this process and child.

kill

Run kill method of latest created AnyEvent::Process::Job - sends signal specified as argument to the process.

pid

Run pid method of latest created AnyEvent::Process::Job - returns PID of the process.

close

Run close method of latest created AnyEvent::Process::Job.

SEE ALSO

AnyEvent - Event framework for PERL.

AnyEvent::Subprocess - Similar module, but with more dependencies and 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.