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) 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 does 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"; } Since the processes run in lockstep (synchronized at the labels), loops 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. 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. 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 BUGS This is brand-new and bearly tested. Please provide feedback! LICENSE Copyright (C) 2003 David Muir Sharnoff . This module may be used/copied/etc on the same terms as Perl itself.