AnyEvent::Run - Run a process or coderef asynchronously


    use AnyEvent;
    use AnyEvent::Run;
    my $cv = AnyEvent->condvar;

    my $handle = AnyEvent::Run->new(
        cmd      => [ 'ls', '-l' ],
        priority => 19,              # optional nice value 
        on_read  => sub {
            my $handle = shift;
        on_error  => sub {
            my ($handle, $fatal, $msg) = @_;
    # Send data to the process's STDIN



AnyEvent::Run is a subclass of AnyEvent::Handle, so reading it's documentation first is recommended.

This module is designed to run a child process, using an explicit command line, a class name, or a coderef. It should work on any Unix system as well as Windows 2000 and higher.

For an alternate way of running a coderef in a forked process using AnyEvent, see AnyEvent::Util's fork_call function.


$handle = new( %args )

Creates and returns a new AnyEvent::Run object. The process forks and either execs (Unix) or launches a new process (Windows). If using a coderef, the coderef is run in the forked process.

The process's STDIN, STDOUT, and STDERR and connected to $handle->{fh}.

The child process is automatically killed if the AnyEvent::Run object goes out of scope.

See AnyEvent::Handle for additional parameters for new().


Required. Takes a string, an arrayref, or a code reference.

    cmd => 'ps ax'
    cmd => [ 'ps, 'ax' ]
    cmd => sub { print "Hi, I'm $$\n" }

When launching an external command, using an arrayref is recommended so that your command is properly escaped.

Take care when using coderefs on Windows, as your code will run in a thread. Avoid using modules that are not thread-safe.


Optional. Arrayref of arguments to be passed to cmd.


Optional. Class name to be loaded in the child process. Using this method is a more efficient way to execute Perl code than by using a coderef. This will exec a new Perl interpreter, loading only this class, and will call that class's main() method.

    my $handle = AnyEvent::Run->new(
        class => 'My::SubProcess',
    package My::SubProcess;
    sub main {
        print "Hi, I'm $$\n";

Optional. When using class, instead of calling main(), the given method will be called.


Optional. A numeric value between -19 and 19. On Unix, you must be root to change the priority to a value less than 0. On Windows, these values are mapped to the following priority levels:

    -19 to -16  High
    -15 to  -6  Above Normal
    -5  to   4  Normal
     5  to  14  Below Normal
    15  to  19  Idle


AnyEvent::Handle's linger option is not supported.

Open file descriptors are not closed under Windows after forking.


This module was based in part on POE::Wheel::Run and POE::Wheel::Run::Win32.


AnyEvent AnyEvent::Handle AnyEvent::Util


Andy Grundman, <>


This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.