NAME

AnyEvent::Run - Run a process or coderef asynchronously

SYNOPSIS

    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;
            ...
            $cv->send;
        },
        on_error  => sub {
            my ($handle, $fatal, $msg) = @_;
            ...
            $cv->send;
        },
    );
    
    # Send data to the process's STDIN
    $handle->push_write($data);
    $cv->recv;

DESCRIPTION

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.

METHODS

$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().

cmd

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.

args

Optional. Arrayref of arguments to be passed to cmd.

class

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";
    }
    
    1;

method

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

priority

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

BUGS

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

Open file descriptors are not closed under Windows after forking.

THANKS

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

AUTHOR

Andy Grundman, <andy@hybridized.org>

COPYRIGHT AND LICENSE

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