Arch::Run(3pm)						User Contributed Perl Documentation					    Arch::Run(3pm)

NAME

       Arch::Run - run subprocesses and capture output

SYNOPSIS

	   use Gtk2 -init;
	   use Arch::Run qw(poll run_async LINES);

	   my $window = Gtk2::Window->new;
	   my $label = Gtk2::Label->new;
	   my $pbar = Gtk2::ProgressBar->new;
	   my $vbox = Gtk2::VBox->new;
	   $vbox->add($label); $vbox->add($pbar); $window->add($vbox);
	   $window->signal_connect(destroy => sub { Gtk2->main_quit; });
	   $window->set_default_size(200, 48); $window->show_all;
	   sub set_str { $label->set_text($_[0]); }

	   my $go = 1;	# keep progress bar pulsing
	   Glib::Timeout->add(100, sub { $pbar->pulse; poll(0); $go; });

	   run_async(
	       command => [ 'du', '-hs', glob('/usr/share/*') ],
	       mode    => LINES,
	       datacb  => sub { chomp(my $str = $_[0]); set_str($str); },
	       exitcb  => sub { $go = 0; set_str("exit code: $_[0]"); },
	   );

	   Gtk2->main;

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 poll to wait for and handle process output, or use handle_output and handle_exits to integrate Arch::Run with your
       applications main loop.

METHODS

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

       run_with_pipe $command
       run_with_pipe $executable $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.

       run_async %args
	   Run a command asyncronously in the background.  Returns the subprocesses pid.

	   Valid keys for %args are:

	   command => $command
	   command => [ $executable $argument ... ]
	       Program and parameters.

	   mode => $accum_mode
	       Control how output data is accumulated and passed to data and finish callbacks.

	       $accum_mode can be one of

	       RAW No accumulation.  Pass output to data callback as it is received.

	       LINES
		   Accumulate output in lines.	Pass every line separately to data callback.

	       ALL Accumulate all data.  Pass complete command output as one block to data callback.

	   datacb => $data_callback
	       Codeblock or subroutine to be called when new output is available.  Receives one parameter, the accumulated command output.

	   exitcb => $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.)

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

       handle_output $pid
	   Handle available output from process $pid.

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

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

	   Returns the number of processes that had output available.

       wait $pid
	   Wait for subprocess $pid to terminate, repeatedly calling poll.  Returns the processes exit status or "undef" if poll has already been
	   called after the processes exit.

       killall [$signal]
	   Send signal $signal (SIGINT if omitted) to all managed subprocesses, and wait until every subprocess to terminate.

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

	   ->cmd_start $pid $executable $argument ...
	       Called whenever a new subprocess has been started.  Receives the subprocesses PID and the executed command line.

	   ->cmd_output_raw $pid $data
	       Called whenever a subprocess has generated output.  Receives the subprocesses PID and a block of output data.

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

	   ->cmd_exit $pid $exitcode
	       Called whenever a subprocess exits.  Receives the subprocesses PID and exit code.

       unobserve $observer
	   Remove $observer from observer list.

perl v5.10.1							    2005-10-08							    Arch::Run(3pm)