NAME

Test::MultiFork - Test suite support for multi-process programs

SYNOPSIS

use Test::MultiFork;

($name, $letter, $number) = procname([new name])
lockcommon()
@oldvalues = getcommon()
setcommon(@newvalues)
unlockcommon()

use Test::MultiFork qw(groupwait setgroup dofork stderr bail_on_bad_plan)

groupwait([$tag])
$oldgroup = setgroup([$newgroup])
dofork(fork_specification)

DESCRIPTION

This test module is to support creating test suites for programs and modules that run as multiple processes and do mostly blocking I/O.

Test::MultiFork handles the forking so that it can set up each child to coordinate the output. The output from each child fork is redirected to the parent. Each fork produces normal test output -- possibly using normal test modules like Test::Simple. The output is collected and rewritten by the parent process.

Each child fork has a letter and number designation. The forks are created by dofork(). Dofork takes a specifiction on the form: ([a-z](\d*))+. That is to say, one or more lower-case letters, each optionally followd by a number. The number says how many children to fork for that letter (default one). The specifier ab2c3 means have one a child (numbered 1); two b children (numbered 1, 2); and three c children (numbered 1, 2, 3).

To aid in writing tests, Test::MultiFork will pass data between the child processes. The data is test-writer defined.

SOURCE FILTER

Test::MultiFork acts as a source filter on your code. It does this so that it can do lock-step execution control.

The source filtering is controlled with pseudo labels. The labels must be the only thing on the line. The main source control is a label like FORK_abc:. This label tells Test::MultiFork how many times to fork (see above). Whatever comes after the FORK_ and before the : is a fork specifier.

With a FORK_abc: label, varient execution labels are enabled. Varient execution labels must be all lowercase. This is to allow you to use something different for you loop control labels. This module can be used without putting in any special labels.

Outside of a function, a varient execution label will synchronize all the program forks to that line of code. As each fork reaches that line, it will stop and wait until all forks get there. At that point, all of the forks will start up and run again.

Inside or outside of a function, once a varient execution labels is seen, source code is turned on or off (commented out) depending on if the process fork letter is in the label.

For example:

# let's fork 5 times
FORK_abc2d:

ab:
print "I'm an 'a' or 'b' process\n";

cd:
print "I'm an 'c' or 'd' process\n";

abcd:
print "we are all running in lockstep\n";

sub xyz {
a: 
	print "only a does something in this function\n";
abcd:
}

Since the processes run in lockstep (synchronized at the labels), loop controls must cover all processes.

In addition to fork() and the varient execution labels, you can override a default signal selection for debugging. By default the USR1 signal is used to aid debugging: if the parent process bails out, it will send USR1 signals to all the children to ask them to print out some diagnostics. The special label SIGNAL_xyz: changes which signal to use. Substitute xyz with your choice of signal or none to disable this feature.

IMPORTS

stderr

Import 'stderr' to send the STDERR output from each fork through the parent for tagging. The default is to leave STDERR alone.

bail_on_bad_plan

Bail out if a test plan isn't followed. This is most useful as a way to exit early if one of the fork()ed children exits early.

colorize

If $ENV{TERM} =~ /xterm/, then escape codes will be printed to change the background and foreground text colors so that each fork()ed child has a different color scheme.

FUNCTIONS

lockcommon()

Sets a lock on the shared common data.

getcommon()

Returns the current value of the common data. The common data is an array. In scalar context, the first element is returned. getcommon does not care if the common data is locked.

setcommon(@newvalues)

Sets the value of the common data to the new values. Dies if common data lock isn't held.

unlockcommon()

Releases a lock on the shared common data. Dies if the lock isn't already held.

groupwait([$tag])

Wait for all process forks in the process group to get reach this same synchronization point as designated by the $tag. The default tag is the current source file name and line number. All processes start in the default group. This is the function used to implement the varient execution lockstep synchronization.

setgroup([$newgroup])

With a $newgroup, changes the process' group identity. All processes start in group default. Returns the old group name.

dofork($fork_specification)

Fork off children processes. The parent process becomes the special-purpose test coordinator. The specification is as detailed in the DESCRIPTION above.

procname([$new_name])

Change the fork's name. The return value is a list: the current name, process' letter, the process' number.

INTEGRATION WITH TEST::*

Test::Simple and Test::More encourage you to specify a test plan at compile time. Make sure that dofork() is called before the test plan is specified.

When using Test::MultiFork's source filter in conjunction with Test::Builder anything built on top of it (eg: Test::Simple or Test::More) put Test::MultiFork first in the use list.

SEE ALSO

Test::Harness Test::Builder Test::Simple Test::More Test

BUGS

This is new and bearly tested. Please provide feedback!

LICENSE

Copyright (C) 2003-2006 David Muir Sharnoff <muir@idiom.com>. This module may be used/copied/etc on the same terms as Perl itself.