view release on metacpan or  search on metacpan

lib/AnyEvent/Process.pm  view on Meta::CPAN

Arguments:

=over 4

=item 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

=over 4

=item HANDLE

is a handle reference or a filedescriptor number, which will be opened in the 
new process.

=item DIRECTION

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

=item TYPE

Following types are supported:

=over 4

=item 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 C<handle =E<gt> 
[handle_args...]>, where handle_args are an argument passed to the 
L<AnyEvent::Handle|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 
C<method =E<gt> [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]]]

=item open

Opens the specified HANDLE using open with DIRECTION and ARGS as its arguments.

Example:
  0 => ['open', '<', '/dev/null']

=item decorate

Decorate every line written to the HANDLE by the child. The DIRECTION must be 
C<E<gt>>. ARGS are in the form C<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]

=back

=back

=item code (optional, but must be specified either in new or run) 

A code reference, which is executed in the newly started process.

=item args (optional)

Arguments past to a code reference specified as code argument when it is called.

=item 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.

=item watchdog_interval (in seconds, optional)

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

=item 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). 

=item kill_interval (in seconds, optional)

Maximum time the process can run. After this time expires, the process is 
killed.

=item on_kill (optional, sends SIGKILL by default)

Called, when the process shall be killed. Receives AnyEvent::Process::Job 
instance as its argument.

=back

=head2 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.

=over 4

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

=over 4

=item pid