Arch::Run - run subprocesses and capture output
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;
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.
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.