The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
AnyEvent-Proc-0.105
River stage one • 2 direct dependents • 4 total dependents
++
/ AnyEvent::Proc

NAME

AnyEvent::Proc - Run external commands

VERSION

version 0.105

SYNOPSIS

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

DESCRIPTION

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

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[, $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.

alive()

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

In fact, the method equals to

        $proc->fire(0)

wait([$callback])

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.

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

$fd defaults to stdout.

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

pull($peer)

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.

        $proc->pull($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

reader()

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;
        $reader->pipe(\$out);
        $proc->wait;
        # $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:

writer()

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;
        $writer->writeln('hi');
        $writer->finish;
        $proc->wait;
        # $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) = @_;
                ...;
        });

LIMITATIONS

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.

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