---
name: "Test2::Harness::IPC"
section: "3pm"
platform: "linux"
package: "libtest2-harness-perl"
version: "1.000158-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test2::Harness::IPC"
---

# Test2::Harness::IPC(3pm)

Base class for modules that control child processes.

## NAME

Test2::Harness::IPC - Base class for modules that control child processes.

## DESCRIPTION

This module is the base class for all parts of Test2::Harness that have to do process management.

## ATTRIBUTES

- $pid = $ipc-\>pid

  The root PID of the IPC object.

- $hashref = $ipc-\>handlers

  Custom signal handlers specific to the IPC object.

- $hashref = $ipc-\>procs

  Hashref of `"$pid => $proc"` where `$proc` is an instance of Test2::Harness::IPC::Proc.

- $hashref = $ipc-\>procs\_by\_cat

  Hashref of `"$category => { $pid => $proc }"`.

- $hashref = $ipc-\>waiting

  Hashref of processes that have finished, but have not been handled yet.

  This is an implementation detail you should not rely on.

- $float = $ipc-\>wait\_time

  How long to sleep between loops when in a wait cycle.

- $bool = $ipc-\>started

  True if the IPC process has started.

- $ipc-\>sig\_count

  Implementation detail, used to break wait loops when signals are received.

## METHODS

- $ipc-\>start

  Start the IPC management (Insert signal handlers).

- $ipc-\>stop

  Stop the IPC management (Remove signal handlers).

- $ipc-\>set\_sig\_handler($sig, sub { ... })

  Set a custom signal handler. This is a safer version of `"local %SIG{$sig}"` for use with IPC.

  The callback will get exactly one argument, the name of the signal that was recieved.

- $ipc-\>handle\_sig($sig)

  Handle the specified signal. Will cause process exit if the signal has no handler.

- $ipc-\>**killall()**

  - $ipc-\>killall($sig)

  Kill all tracked child process with the given signal. `"TERM"` is used if no signal is specified.

  This will not wait on the processes, you must call `"$ipc->wait()"`.

- $ipc-\>check\_timeouts

  This is a no-op on the IPC base class. This is called every loop of `"$ipc->wait"`. If you subclass the IPC class you can fill this in to make processes timeout if needed.

- $ipc-\>check\_for\_fork

  This is used a lot internally to check if this is a forked process. If this is a forked process the IPC object is completely reset with no remaining internal state (except signal handlers).

- $ipc-\>set\_proc\_exit($proc, @args)

  Calls `"$proc->set_exit(@args)"`. This is called by `"$ipc->wait"`. You can override it to add custom tasks when a process exits.

- $int = $ipc-\>**wait()**

  - $int = $ipc-\>wait(%params)

  Wait on processes, return the number found.

  Default is non-blocking.

  Options:

  - timeout =\> $float

    If a blocking paremeter is provided this can be used to break the wait after a timeout. Time::HiRes is used, so timeout is in seconds with decimals.

  - all =\> $bool

    Block until **ALL** processes are done.

  - cat =\> $category

    Block until at least 1 process from the category is complete.

  - all\_cat =\> $category

    Block until **ALL** processes from the category are complete.

  - block =\> $bool

    Block until at least 1 process is complete.

- $ipc-\>watch($proc)

  Add a process to be monitored.

- $proc = $ipc-\>spawn($proc)

  - $proc = $ipc-\>spawn(%params)

  In the first form `$proc` is an instance of Test2::Harness::IPC::Proc that provides `spawn_params()`.

  In the second form the following params are allowed:

  Anything supported by `run_cmd()` in Test2::Harness::Util::IPC.

  - process\_class =\> $CLASS

    Default is Test2::Harness::IPC::Process.

  - command =\> $command

    Program command to call. This is required.

  - env\_vars =\> { ... }

    Specify custom environment variables for the new process.

## SOURCE

The source code repository for Test2-Harness can be found at *http://github.com/Test-More/Test2-Harness/*.

## MAINTAINERS

- Chad Granum \<exodist@cpan.org\>

  ## AUTHORS

- Chad Granum \<exodist@cpan.org\>

  ## COPYRIGHT

Copyright 2020 Chad Granum \<exodist7@gmail.com\>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See *http://dev.perl.org/licenses/*