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


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


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


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



Start the IPC management (Insert signal handlers).


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.


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


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().


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.


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.


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.


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.


The source code repository for Test2-Harness can be found at


Chad Granum <>


Chad Granum <>


Copyright 2020 Chad Granum <>.

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