NAME

Win32::ProcFarm::Parent - stand-in for child process in ProcFarm RPC system

SYNOPSIS

use Win32::ProcFarm::Parent;
use Win32::ProcFarm::Port;

$port_obj = Win32::ProcFarm::Port->new(9000, 1);

$iface = Win32::ProcFarm::Parent->new_async($port_obj, 'Child.pl', Win32::GetCwd);

$iface->connect;

$iface->execute('child_sub', @params);

until($iface->get_state eq 'fin') {
	print "Waiting for ReturnValue.\n";
	sleep(1);
}
print "GotReturnValue.\n";
print $iface->get_retval;

DESCRIPTION

Installation instructions

This installs with MakeMaker as part of Win32::ProcFarm.

To install via MakeMaker, it's the usual procedure - download from CPAN, extract, type "perl Makefile.PL", "nmake" then "nmake install". Don't do an "nmake test" because the I haven't written a test suite yet.

State Diagram

Win32::ProcFarm::Parent is designed to provide support for asynchronous subroutine calls against the child process. To support this, the Win32::ProcFarm::Parent object can be in one of four states.

= item init

In the init state, the Win32::ProcFarm::Parent object has been asynchronously spun off, but has yet to establish a communications channel via the Win32::ProcFarm::Port object. A call to the connect method will rectify this situation and move the object into the idle state.

idle

In the idle state, the child process has yet to be assigned a task and is waiting for one to be assigned. A call to the execute method will assign the child process a task and move the Win32::ProcFarm::Parent object into the wait state.

wait

In the wait state, the child process has been assigned a task and is busy executing it. Calls to the get_state method will check to see if the task has finished executing. If it has, the Win32::ProcFarm::Parent object will retrieve the return values, store them internally, and move the object into the fin state.

fin

In the fin state, the Win32::ProcFarm::Parent object is waiting for the return values to be retrieved by the get_retval method. A call to that method will return the values and move the object back into the idle state.

METHODS

new_async

The new_async method creates a new Win32::ProcFarm::Parent object and spins off the child process, but does not initiate communication with it. The Win32::ProcFarm::Parent object is left in the init state.

The parameters are:

$port_obj

A Win32::ProcFarm::Port object that will be connected to by the child processes.

$script

The script name to execute for the child processes.

$curdir

The working directory to use when running the script. If this is the same directory the script is in, the script name can be specified without a path.

$timeout

An optional value indicating how long jobs should be allowed to execute before they are deemed to have blocked. Blocked jobs will be terminated and a new process created to take their place.

connect

The connect method initiates communication with a child process. Note that we cannot presume that the order in which the child processes connect to the TCP port is the same order in which they were started. The first thing the child process does upon the TCP connection being accepted is to send its unique identifier, which the Win32::ProcFarm::Parent object uses to retrieve the appropriate Win32::Process from the class hash of those objects.

The connect call moves the Win32::ProcFarm::Parent object into the idle state.

execute

The execute command instructs the child process to start executing a given subroutine with a list of passed parameters. The data is send over the socket connection and the Win32::ProcFarm::Parent object moved into the wait state.

get_state

The get_state method returns the current state. If the current state is wait, the method first checks to see if the child process has finished executing the subrouting call. If it has, the method retrieves the return data and moves the Win32::ProcFarm::Parent object into the fin state.

The get_state method is also responsible for dealing with timeout scenarios where the child process has exceeded the time allowed to execute the subroutine. In that situation, the child process is terminated and a new child process initiated, connected to, and the Win32::ProcFarm::Parent object placed in the fin state.

get_retval

The get_retval method returns the list of return values returned by the child process and moves the Win32::ProcFarm::Parent object into the idle state.