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/