---
name: "Arch::Run"
section: "3pm"
platform: "linux"
package: "libarch-perl"
version: "0.5.2-2"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/Arch::Run"
---

# Arch::Run(3pm)

run subprocesses and capture output

## 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.