AnyEvent::Proc - Run external commands


version 0.105


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


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



  • 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


Returns a AnyEvent::Handle for STDIN

Useful for piping data into us:



Returns a AnyEvent::Handle for STDOUT


Returns a AnyEvent::Handle for STDERR


Returns the PID of the subprocess


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


Kills the subprocess the most brutal way. Equals to


fire_and_kill([$signal, ]$time[, $callback])

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

See "wait" for the meaning of the callback parameter and return value.

Without calllback, this is a synchronous call. After this call, the subprocess can be considered to be dead. Returns the exit code of the subprocess.


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

In fact, the method equals to



Waits for the subprocess to be finished call the callback with the exit code. Returns a condvar.

Without callback, this is a synchronous call directly returning the exit code.


Closes STDIN of subprocess


Closes all handles of subprocess


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

See timeout and on_timeout options in new().


Stopps write timeout for STDIN.

See wtimeout and on_wtimeout options in new().


Stopps read timeout for STDIN.

See rtimeout and on_rtimeout options in new().


Stopps read timeout for STDIN.

See etimeout and on_etimeout options in new().


Queues the given scalar to be written.

write($type => @args)

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


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 (like IO::Handle, including any subclass), a ScalarRef or a GlobRef or a CodeRef.

$fd defaults to stdout.

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


Pulls any data from another handle to STDIN. $peer maybe another AnyEvent::Proc instance, an AnyEvent::Handle, an IO::Handle (including any subclass), a Coro::Channel, a ScalarRef or a GlobRef.



Reads a single line from STDOUT and calls $callback


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


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.


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


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.


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

Same as



Bevahes equivalent as readline_cb, but for STDERR.


Bevahes equivalent as readline_cv, but for STDERR.


Bevahes equivalent as readline_ch, but for STDERR.


Bevahes equivalent as readlines_cb, but for STDERR.


Bevahes equivalent as readlines_ch, but for STDERR.


Bevahes equivalent as readline, but for STDERR.



Creates a new file descriptor for pulling data from process.

        use AnyEvent::Proc qw(reader);
        my $reader = reader();
        my $proc = AnyEvent::Proc->new(
                bin => '/bin/sh',
                args => [ -c => "echo hi >&$reader" ] # overloads to fileno
                extras => [ $reader ], # unordered list of all extra descriptors
        my $out;
        # $out contains now 'hi'

This calls /bin/sh -c "echo hi >&3", so that any output will be dupped into fd #3.

$reader provides following methods:


Creates a new file descriptor for pushing data to process.

        use AnyEvent::Proc qw(writer);
        my $writer = writer();
        my $out;
        my $proc = AnyEvent::Proc->new(
                bin => '/bin/sh',
                args => [ -c => "cat <&$writer" ] # overloads to fileno
                extras => [ $writer ], # unordered list of all extra descriptors
                outstr => \$out,
        my $out;
        # $out contains now 'hi'

This calls /bin/sh -c "cat <&3", so that any input will be dupped from fd #3.

$writer provides following methods:

Unfortunally "pull" is unimplemented.

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

run_cb($bin[, @args], $callback)

Like "run", but asynchronous with callback handler. Returns the condvar. See "wait" for more information.

        AnyEvent::Proc::run_cb($bin, @args, sub {
                my ($out, $err, $status) = @_;


Use EV. The fallback module AnyEvent::Impl::Perl has some issues with pipes. In some cases, AnyEvent::Handle don't receive data from its pipe peer and the application will block forever. I haven't a solution yet, so don't rely on pipes when you use AE's pure-perl backend.


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


Please report any bugs or feature requests on the bugtracker website

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.


David Zurborg <>


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

This is free software, licensed under:

  The ISC License