view release on metacpan or  search on metacpan

lib/AnyEvent/Run.pm  view on Meta::CPAN

    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;

=head1 DESCRIPTION

AnyEvent::Run is a subclass of L<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 L<AnyEvent::Util>'s fork_call function.

=head1 METHODS

=head2 $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 L<AnyEvent::Handle> for additional parameters for new().

=over 4

=item 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.

=item args

Optional. Arrayref of arguments to be passed to cmd.

=item 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;

=item method

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

=item 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

=back

=head1 BUGS

L<AnyEvent::Handle>'s linger option is not supported.

Open file descriptors are not closed under Windows after forking.

=head1 THANKS

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

=head1 SEE ALSO

L<AnyEvent>