view release on metacpan or  search on metacpan

lib/AnyEvent/Open3/Simple.pm  view on Meta::CPAN

In version 0.80 or better, you may provide a callback as the last argument
which is called before C<on_start>, and takes the process object as its only
argument.  For example:

 foreach my $i (1..10)
 {
   $ipc->run($prog, @args, \$stdin, sub {
     my($proc) = @_;
     $proc->user({ iteration => $i });
   });
 }

This is useful for making data accessible to C<$ipc> object's callbacks that may
be out of scope otherwise.

=head1 CAVEATS

Some AnyEvent implementations may not work properly with the method
used by AnyEvent::Open3::Simple to wait for the child process to
terminate.  See L<AnyEvent/"CHILD PROCESS WATCHERS"> for details.

This module uses an idle watcher instead of a child watcher to detect
program termination on Microsoft Windows (but not Cygwin).  This is
because the child watchers are unsupported by AnyEvent on Windows.
The idle watcher implementation seems to pass the test suite, but there
may be some traps for the unwary.  There may be other platforms or
event loops where this is the appropriate choice, and you can use the
C<ANYEVENT_OPEN3_SIMPLE> environment variable or the C<implementation>
attribute to force it use an idle watcher instead.  Patches for detecting
environments where idle watchers should be used are welcome and
encouraged.

As of version 0.85, this module works on Windows with L<AnyEvent::Impl::EV>,
L<AnyEvent::Impl::Event> and L<AnyEvent::Impl::Perl> (possibly others),
although in the past they have either not worked or had limitations placed
on them.  Because the author of L<AnyEvent> does not hold the native Windows
port of Perl in high regard: problems such as this may pop up again
in the future and may not be addressed, and may be out of the control of the
author of this module.

Performance for the idle watcher implementation on native Windows (non-Cygwin)
is almost certainly suboptimal, but the author of this module uses it
and finds it useful despite this.

Writing to a subprocesses stdin with L<AnyEvent::Open3::Simple::Process#print>
or L<AnyEvent::Open3::Simple::Process#say> is unsupported on Microsoft
Windows (it does work under Cygwin though).

There are some traps for the unwary relating to buffers and deadlocks,
L<IPC::Open3> is recommended reading.

If you register a call back for C<on_exit>, but not C<on_error> then
use a condition variable to wait for the process to complete as in
this:

 my $cv = AnyEvent->condvar;
 my $ipc = AnyEvent::Open3::Simple->new(
   on_exit => sub { $cv->send },
 );
 $ipc->run('command_not_found');
 $cv->recv;

You might be waiting forever if there is an error starting the
process (if for example you give it a bad command).  To handle
this situation you might use croak on the condition variable
in the event of error:

 my $cv = AnyEvent->condvar;
 my $ipc = AnyEvent::Open3::Simple->new(
   on_exit => sub { $cv->send },
   on_error => sub {
     my $error = shift;
     $cv->croak($error);
   },
 );
 $ipc->run('command_not_found');
 $cv->recv;

This will cause the C<recv> to die, printing a useful diagnostic
if the exception isn't caught somewhere else.

=head1 SEE ALSO

=over 4

=item L<AnyEvent::Open3::Simple::Process>

Represents a process being run by this module, typically passed
into the callbacks.

=item L<AnyEvent::Subprocess>

Alternative to this module.

=item L<AnyEvent::Run>

Alternative to this module.

=back

=head1 AUTHOR

Author: Graham Ollis E<lt>plicease@cpan.orgE<gt>

Contributors:

Stephen R. Scaffidi

Scott Wiersdorf

Graham Knop (HAARG)

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut