/ 
AnyEvent-Proc-0.101
River stage one • 2 direct dependents • 4 total dependents
/ AnyEvent::Proc

NAME

AnyEvent::Proc - Run external commands

VERSION

version 0.101

DESCRIPTION

AnyEvent::Proc is a AnyEvent-based helper class for running external commands with full control over STDIN, STDOUT and STDERR.

SYNOPSIS

my $proc = AnyEvent::Proc->new(bin => 'cat');
$proc->writeln('hello');
my $hello = $proc->readline;
$proc->fire;
$proc->wait;

METHODS

new(%options)

  • bin (mandatory)

    Name (or path) to a binary

  • args

    ArrayRef with command arguments

  • ttl

    Time-to-life timeout after the process automatically gets killed

    See also on_ttl_exceed callback handler.

  • timeout

    Inactive timeout value (fractional seconds) for all handlers.

    See also on_timeout callback handler. If omitted, after exceeding timeout all handlers will be closed and the subprocess can finish.

  • wtimeout

    Like timeout but sets only the write timeout value for STDIN.

    Corresponding callback handler: on_wtimeout

  • rtimeout

    Like timeout but sets only the read timeout value for STDOUT.

    Corresponding callback handler: on_rtimeout

  • etimeout

    Like timeout but sets only the read timeout value for STDERR.

    Corresponding callback handler: on_etimeout

  • outstr

    When set to a ScalarRef, any output (STDOUT) will be appended to this scalar

  • errstr

    Same as outstr, but for STDERR.

  • on_exit

    Callback handler called when process exits

  • on_ttl_exceed

    Callback handler called when ttl exceeds

  • on_timeout

    Callback handler called when any inactivity timeout value exceeds

  • on_wtimeout

    Callback handler called when STDIN write inactivity wtimeout value exceeds

  • on_rtimeout

    Callback handler called when STDOUT read inactivity rtimeout value exceeds

  • on_etimeout

    Callback handler called when STDERR read inactivity etimeout value exceeds

in()

Returns a AnyEvent::Handle for STDIN

Useful for piping data into us:

$socket->print($proc->in->fh)

out()

Returns a AnyEvent::Handle for STDOUT

err()

Returns a AnyEvent::Handle for STDERR

pid()

Returns the PID of the subprocess

fire([$signal])

Sends a named signal to the subprocess. $signal defaults to TERM if omitted.

kill()

Kills the subprocess the most brutal way. Equals to

$proc->fire('kill')

fire_and_kill([$signal, ]$time)

Fires specified signal $signal (or TERM if omitted) and after $time seconds kills the subprocess.

This is a synchronous call. After this call, the subprocess can be considered to be dead.

Returns the exit code of the subprocess.

alive()

Check whether is subprocess is still alive. Returns 1 or 0

In fact, the method equals to

$proc->fire(0)

wait()

Waits for the subprocess to be finished returns the exit code.

finish()

Closes STDIN of subprocess

end()

Closes all handles of subprocess

stop_timeout()

Stopps read/write timeout for STDIN, STDOUT and STDERR.

See timeout and on_timeout options in new().

stop_wtimeout()

Stopps write timeout for STDIN.

See wtimeout and on_wtimeout options in new().

stop_rtimeout()

Stopps read timeout for STDIN.

See rtimeout and on_rtimeout options in new().

stop_etimeout()

Stopps read timeout for STDIN.

See etimeout and on_etimeout options in new().

write($scalar)

Queues the given scalar to be written.

write($type => @args)

See AnyEvent::Handle::push_write for more information.

writeln(@lines)

Queues one or more line to be written.

pipe([$fd, ]$peer)

Pipes any output of STDOUT to another handle. $peer maybe another AnyEvent::Proc instance, an AnyEvent::Handle, a Coro::Channel, an object that implements the print method, a ScalarRef or a GlobRef or a CodeRef.

$fd defaults to stdout.

$proc->pipe(stderr => $socket);

readline_cb($callback)

Reads a single line from STDOUT and calls $callback

readline_cv([$condvar])

Reads a single line from STDOUT and send the result to $condvar. A condition variable will be created and returned, if $condvar is omitted.

readline_ch([$channel])

Reads a singe line from STDOUT and put the result to coro channel $channel. A Coro::Channel will be created and returned, if $channel is omitted.

readlines_cb($callback)

Read lines continiously from STDOUT and calls on every line the handler $callback.

readlines_ch([$channel])

Read lines continiously from STDOUT and put every line to coro channel $channel. A Coro::Channel will be created and returned, if $channel is omitted.

readline()

Reads a single line from STDOUT synchronously and return the result.

Same as

$proc->readline_cv->recv

readline_error_cb($callback)

Bevahes equivalent as readline_cb, but for STDERR.

readline_error_cv([$condvar])

Bevahes equivalent as readline_cv, but for STDERR.

readline_error_ch([$channel])

Bevahes equivalent as readline_ch, but for STDERR.

readlines_error_cb($callback)

Bevahes equivalent as readlines_cb, but for STDERR.

readlines_error_ch([$channel])

Bevahes equivalent as readlines_ch, but for STDERR.

readline_error()

Bevahes equivalent as readline, but for STDERR.

FUNCTIONS

run($bin[, @args])

Bevahes similar to "system" in perlfunc. In scalar context, it returns STDOUT of the subprocess. STDERR will be passed-through by "warn" in perlfunc.

$out = AnyEvent::Proc::run(...)

In list context, STDOUT and STDERR will be separately returned.

($out, $err) = AnyEvent::Proc::run(...)

The exit-code is stored in $?. Please keep in mind that for portability reasons $? is shifted by 8 bits.

$exitcode = $? >> 8

EXPORTS

Nothing by default. The following functions will be exported on request:

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libanyevent-proc-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by David Zurborg.

This is free software, licensed under:

The ISC License