NAME

Win32::ProcFarm::Pool - manages a pool of child processes

SYNOPSIS

        use Win32::ProcFarm::Pool;

        $Pool = Win32::ProcFarm::Pool->new($poolsize, $portnum, $scriptname, Win32::GetCwd);

        foreach $i (@list) {
                $Pool->add_waiting_job($i, 'child_sub', $i);
        }

        $Pool->do_all_jobs(0.1);

        %ping_data = $Pool->get_return_data;
        $Pool->clear_return_data;

        foreach $i (@list) {
                print "$i:\t$ping_data{$i}->[0]\n";
        }

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.

More usage instructions

See Docs/tutorial.pod for more information.

METHODS

new

The new method creates a new Win32::ProcFarm::Pool object (amazing, eh!). It takes 5 parameters:

$num_threads

This indicates the number of threads that should be created.

$port_num

This indicates the port number to use for the listener.

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

%options

A hash of options. The current options are:

timeout

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

listeners

Indicates how many listeners should be allocated on the port object. During thread instantiation, this controls how many unconnected threads can be spun off. For optimum thread creation speed, this should be set to one more than the number of processors. By default, this is set to three. Setting this to too high a value does not appear to have much effect on the overall thread creation rate, but setting it to two low a value (such as one) could have a dramatic effect on the thread creation rate for multiprocessor machines.

result_sub

If specified, the attached subroutine will be called as soon as each job finishes executing. The subroutine will be passed the key name and then return values. This allows for asynchronous reponses to job execution, rather than having to wait for the entire pool to finish running before operating on the results.

add_threads

The add_threads method call adds additional threads to a pool. The only accepted parameter is the number of new threads to add.

min_threads

The min_threads increases the number of threads in the pool to the specified value. If there are more threads in the pool that the specified value, the number of threads in the pool is unchanged.

add_waiting_job

The add_waiting_job method adds a job to the waiting pool. It takes three parameters:

$key

This should be a unique identifier that will be used to retrieve the return values from the return data hash.

$command

The name of the subroutine that the child process will execute.

@params

A list of parameters for that subroutine.

do_all_jobs

The do_all_jobs command will execute all the jobs in the waiting pool. The first passed parameter specifies the number of seconds to wait between sweeps through the thread pool to check for completed jobs. The number of seconds can be fractional (i.e. 0.1 for a tenth of a second). The second passed parameter specifies the minimum interval between jobs becoming eligible to run.

get_return_data

Return the return_data hash, indexed on the unique key passed initially.

clear_return_data

Clears out the return_data hash.

INTERNAL METHODS

These methods are considered internal methods. Child classes of Win32::ProcFarm::Pool may modify these methods in order to change the behavior of the resultant Pool object.