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.