view release on metacpan or  search on metacpan

perllib/Arch/Run.pm  view on Meta::CPAN

    Gtk2->main;

=head1 DESCRIPTION

Arch::Run allows the user to run run subprocesses and capture their
output in a single threaded environment without blocking the whole
application.

You can use either B<poll> to wait for and handle process output, or
use B<handle_output> and B<handle_exits> to integrate
B<Arch::Run> with your applications main loop.


=head1 METHODS

The following functions are available:
B<run_with_pipe>,
B<run_async>,
B<get_output_handle>,
B<handle_output>,
B<poll>,
B<wait>,
B<killall>,
B<observe>,
B<unobserve>.


=over 4

=item B<run_with_pipe> I<$command>

=item B<run_with_pipe> I<$executable> I<$argument> ...

Fork and exec a program with STDIN and STDOUT connected to pipes. In
scalar context returns the output handle, STDIN will be connected to
/dev/null. In list context, returns the output and input handle.

The programs standard error handle (STDERR) is left unchanged.


=item B<run_async> I<%args>

Run a command asyncronously in the background.  Returns the
subprocesses pid.

Valid keys for I<%args> are:

=over 4

=item B<command> => I<$command>

=item B<command> => [ I<$executable> I<$argument> ... ]

Program and parameters.


=item B<mode> => I<$accum_mode>

Control how output data is accumulated and passed to B<data> and
B<finish> callbacks.

I<$accum_mode> can be one of

=over 4

=item B<RAW>

No accumulation.  Pass output to B<data> callback as it is received.


=item B<LINES>

Accumulate output in lines.  Pass every line separately to B<data>
callback.


=item B<ALL>

Accumulate all data.  Pass complete command output as one block to
B<data> callback.

=back


=item B<datacb> => I<$data_callback>

Codeblock or subroutine to be called when new output is available.
Receives one parameter, the accumulated command output.


=item B<exitcb> => I<$exit_callback>

Codeblock or subroutine to be called when subprocess exits.  Receives
a single parameter, the commands exit code. (Or maybe not. We have to
handle SIG{CHLD} then. But maybe we have to do so anyway.)

=back


=item B<get_output_handle> I<$pid>

Returns the STDOUT handle of process $pid.  You should never directly
read from the returned handle.  Use L<IO::Select> or L<IO::Poll> to
wait for output and call B<handle_output> to process the output.


=item B<handle_output> I<$pid>

Handle available output from process I<$pid>.

B<ATTENTION:> Call this method only if there really is output to be
read.  It will block otherwise.


=item B<poll> I<$timeout>

Check running subprocesses for available output and run callbacks as
appropriate.  Wait at most I<$timeout> seconds when no output is
available.

Returns the number of processes that had output available.


=item B<wait> I<$pid>

Wait for subprocess I<$pid> to terminate, repeatedly calling B<poll>.
Returns the processes exit status or C<undef> if B<poll> has already been
called after the processes exit.


=item B<killall> [I<$signal>]

Send signal I<$signal> (B<SIGINT> if omitted) to all managed
subprocesses, and wait until every subprocess to terminate.


=item B<observe> I<$observer>

Register an observer object that wishes to be notified of running
subprocesses.  I<$observer> should implement one or more of the
following methods, depending on which event it wishes to receive.

=over 4

=item B<-E<gt>cmd_start> I<$pid> I<$executable> I<$argument> ...

Called whenever a new subprocess has been started.  Receives the
subprocesses PID and the executed command line.


=item B<-E<gt>cmd_output_raw> I<$pid> I<$data>

Called whenever a subprocess has generated output.  Receives the
subprocesses PID and a block of output data.

B<NOTE:> I<$data> is not preprocesses (e.g. split into lines).
B<cmd_output_raw> receives data block as if B<RAW> mode was used.


=item B<-E<gt>cmd_exit> I<$pid> I<$exitcode>

Called whenever a subprocess exits.  Receives the subprocesses PID and
exit code.

=back


=item B<unobserve> I<$observer>

Remove I<$observer> from observer list.

=back

=cut