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.

SEE ALSO

AnyEvent AnyEvent::Handle AnyEvent::Util

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.