view release on metacpan or  search on metacpan

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

Callback handler called when process exits

=item * I<on_ttl_exceed>

Callback handler called when I<ttl> exceeds

=item * I<on_timeout>

Callback handler called when any inactivity I<timeout> value exceeds

=item * I<on_wtimeout>

Callback handler called when STDIN write inactivity I<wtimeout> value exceeds

=item * I<on_rtimeout>

Callback handler called when STDOUT read inactivity I<rtimeout> value exceeds

=item * I<on_etimeout>

Callback handler called when STDERR read inactivity I<etimeout> value exceeds

=back

=head2 in()

Returns a L<AnyEvent::Handle> for STDIN

Useful for piping data into us:

	$socket->print($proc->in->fh)

=head2 out()

Returns a L<AnyEvent::Handle> for STDOUT

=head2 err()

Returns a L<AnyEvent::Handle> for STDERR

=head2 pid()

Returns the PID of the subprocess

=head2 fire([$signal])

Sends a named signal to the subprocess. C<$signal> defaults to I<TERM> if omitted.

=head2 kill()

Kills the subprocess the most brutal way. Equals to

	$proc->fire('kill')

=head2 fire_and_kill([$signal, ]$time[, $callback])

Fires specified signal C<$signal> (or I<TERM> if omitted) and after C<$time> seconds kills the subprocess.

See L</wait> for the meaning of the callback parameter and return value.

Without calllback, this is a synchronous call. After this call, the subprocess can be considered to be dead. Returns the exit code of the subprocess.

=head2 alive()

Check whether is subprocess is still alive. Returns I<1> or I<0>

In fact, the method equals to

	$proc->fire(0)

=head2 wait([$callback])

Waits for the subprocess to be finished call the callback with the exit code. Returns a condvar.

Without callback, this is a synchronous call directly returning the exit code.

=head2 finish()

Closes STDIN of subprocess

=head2 end()

Closes all handles of subprocess

=head2 stop_timeout()

Stopps read/write timeout for STDIN, STDOUT and STDERR.

See I<timeout> and I<on_timeout> options in I<new()>.

=head2 stop_wtimeout()

Stopps write timeout for STDIN.

See I<wtimeout> and I<on_wtimeout> options in I<new()>.

=head2 stop_rtimeout()

Stopps read timeout for STDIN.

See I<rtimeout> and I<on_rtimeout> options in I<new()>.

=head2 stop_etimeout()

Stopps read timeout for STDIN.

See I<etimeout> and I<on_etimeout> options in I<new()>.

=head2 write($scalar)

Queues the given scalar to be written.

=head2 write($type => @args)

See L<AnyEvent::Handle>::push_write for more information.

=head2 writeln(@lines)

Queues one or more line to be written.

=head2 pipe([$fd, ]$peer)

Pipes any output of STDOUT to another handle. C<$peer> maybe another L<AnyEvent::Proc> instance, an L<AnyEvent::Handle>, a L<Coro::Channel>, an object that implements the I<print> method (like L<IO::Handle>, including any subclass), a ScalarRef or a ...

C<$fd> defaults to I<stdout>.

	$proc->pipe(stderr => $socket);

=head2 pull($peer)

Pulls any data from another handle to STDIN. C<$peer> maybe another L<AnyEvent::Proc> instance, an L<AnyEvent::Handle>, an L<IO::Handle> (including any subclass), a L<Coro::Channel>, a ScalarRef or a GlobRef.

	$proc->pull($socket);

=head2 readline_cb($callback)

Reads a single line from STDOUT and calls C<$callback>

=head2 readline_cv([$condvar])

Reads a single line from STDOUT and send the result to C<$condvar>. A condition variable will be created and returned, if C<$condvar> is omitted.

=head2 readline_ch([$channel])

Reads a singe line from STDOUT and put the result to coro channel C<$channel>. A L<Coro::Channel> will be created and returned, if C<$channel> is omitted.

=head2 readlines_cb($callback)

Read lines continiously from STDOUT and calls on every line the handler C<$callback>.

=head2 readlines_ch([$channel])

Read lines continiously from STDOUT and put every line to coro channel C<$channel>. A L<Coro::Channel> will be created and returned, if C<$channel> is omitted.

=head2 readline()

Reads a single line from STDOUT synchronously and return the result.

Same as

	$proc->readline_cv->recv

=head2 readline_error_cb($callback)

Bevahes equivalent as I<readline_cb>, but for STDERR.

=head2 readline_error_cv([$condvar])

Bevahes equivalent as I<readline_cv>, but for STDERR.

=head2 readline_error_ch([$channel])

Bevahes equivalent as I<readline_ch>, but for STDERR.

=head2 readlines_error_cb($callback)

Bevahes equivalent as I<readlines_cb>, but for STDERR.

=head2 readlines_error_ch([$channel])

Bevahes equivalent as I<readlines_ch>, but for STDERR.

=head2 readline_error()

Bevahes equivalent as I<readline>, but for STDERR.

=head1 FUNCTIONS

=head2 reader()

Creates a new file descriptor for pulling data from process.

	use AnyEvent::Proc qw(reader);
	my $reader = reader();
	my $proc = AnyEvent::Proc->new(
		bin => '/bin/sh',
		args => [ -c => "echo hi >&$reader" ] # overloads to fileno
		extras => [ $reader ], # unordered list of all extra descriptors
	);
	my $out;
	$reader->pipe(\$out);
	$proc->wait;
	# $out contains now 'hi'

This calls C<< /bin/sh -c "echo hi >&3" >>, so that any output will be dupped into fd #3.

C<$reader> provides following methods:

=over 4

=item * L</on_timeout>

=item * L</stop_timeout>

=item * L</pipe>

=item * L</readline_cb>

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

=item * L</readline>

=back

=head2 writer()

Creates a new file descriptor for pushing data to process.

	use AnyEvent::Proc qw(writer);
	my $writer = writer();
	my $out;
	my $proc = AnyEvent::Proc->new(
		bin => '/bin/sh',
		args => [ -c => "cat <&$writer" ] # overloads to fileno
		extras => [ $writer ], # unordered list of all extra descriptors
		outstr => \$out,
	);
	my $out;
	$writer->writeln('hi');
	$writer->finish;
	$proc->wait;
	# $out contains now 'hi'

This calls C</bin/sh -c "cat <&3">, so that any input will be dupped from fd #3.

C<$writer> provides following methods:

=over 4

=item * L</finish>

=item * L</on_timeout>

=item * L</stop_timeout>

=item * L</write>

=item * L</writeln>

=back

Unfortunally L</pull> is unimplemented.

=head2 run($bin[, @args])

Bevahes similar to L<perlfunc/system>. In scalar context, it returns STDOUT of the subprocess. STDERR will be passed-through by L<perlfunc/warn>.

	$out = AnyEvent::Proc::run(...)

In list context, STDOUT and STDERR will be separately returned.

	($out, $err) = AnyEvent::Proc::run(...)

The exit-code is stored in C<$?>. Please keep in mind that for portability reasons C<$?> is shifted by 8 bits.

	$exitcode = $? >> 8

=head2 run_cb($bin[, @args], $callback)

Like L</run>, but asynchronous with callback handler. Returns the condvar. See L</wait> for more information.

	AnyEvent::Proc::run_cb($bin, @args, sub {
		my ($out, $err, $status) = @_;
		...;
	});

=head1 LIMITATIONS

Use L<EV>. The fallback module L<AnyEvent::Impl::Perl> has some issues with pipes. In some cases, L<AnyEvent::Handle> don't receive data from its pipe peer and the application will block forever. I haven't a solution yet, so don't rely on pipes when ...

=head1 EXPORTS

Nothing by default. The following functions will be exported on request:

=over 4

=item * L</run>

=item * L</run_cb>

=item * L</reader>

=item * L</writer>

=back

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website
https://github.com/zurborg/libanyevent-proc-perl/issues

When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.

=head1 AUTHOR

David Zurborg <zurborg@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by David Zurborg.

This is free software, licensed under:

  The ISC License

=cut