/ 
Parallel-Forker-1.200
River stage one • 2 direct dependents • 2 total dependents
/ Parallel::Forker

NAME

Parallel::Forker - Parallel job forking and management

SYNOPSIS

   use Parallel::Forker;
   $Fork = new Parallel::Forker;
   $SIG{CHLD} = sub { Fork::sig_child($Fork); };
   $SIG{TERM} = sub { $Fork->kill_tree_all('TERM') if $Fork; die "Quitting...\n"; };

   $Fork->schedule(run_on_start => sub {print "starting...";},
		   run_on_finish => sub {print "done...";},
		   )
	    ->run();

   $Fork->wait_all();   # Wait for all children to finish

   # More processes
   my $p1 = $Fork->schedule(...)->ready();
   my $p2 = $Fork->schedule(..., run_after=>[$p1])->ready();
   $Fork->wait_all();   # p1 will complete before p2 starts

   # Other functions
   $Fork->poll();       # Service any active children
   foreach my $proc ($Fork->running()) {   # Loop on each running child

DESCRIPTION

Parallel::Forker manages parallel processes that are either subroutines or system commands. Forker supports most of the features in all the other little packages out there, with the addition of being able to specify complicated expressions to determine which processes run after others, or run when others fail.

Function names loosely based on Parallel::ForkManager.

The unique property of Parallel::Forker is the ability to schedule processes based on expressions that are specified when the processes are defined. For example:

my $p1 = $Fork->schedule(..., label=>'p1');
my $p2 = $Fork->schedule(..., label=>'p2');
my $p3 = $Fork->schedule(..., run_after => "p1 | p2");
my $p4 = $Fork->schedule(..., run_after => "p1 & !p2");

Process p3 is specified to run after process p1 *or* p2 have completed successfully. Process p4 will run after p1 finishes successfuly, and process p2 has completed with bad exit status.

For more examples, see the tests.

METHODS

$self->find_proc_name (<name>)

Return a Parallel::Forker::Process objects for the given named process, or undef if not found.

$self->is_any_left

Return true if any processes are running, or runnable (need to run).

$self->kill_all (<signal>)

Send a kill to all running children.

$self->kill_tree_all (<signal>)

Send a kill to all running children and their subchildren. Requires the Schedule::Load package to be installed.

$self->max_proc

Specify the maximum number of processes to run at any one time. Defaults to undef, which runs all possible jobs at once.

$self->new (<parameters>)

Create a new manager object. There may be more then one manager in any application.

$self->poll

See if any children need work, and service them. Non-blocking; always returns immediately.

$self->processes

Return Parallel::Forker::Process objects for all processes.

$self->processes_sorted

Return Parallel::Forker::Process objects for all processes, in name sorted order.

$self->ready_all

Mark all processes as ready for scheduling.

$self->running

Return Parallel::Forker::Process objects for an processes that are currently running.

$self->schedule (<parameters>)

Register a new process perhaps for later running. Returns a Parallel::Forker::Process object. Parameters are passed by name as follows:

label

Optional name to use in run_after commands. Unlike name, this may be reused, in which case run_after will wait on all commands with the given label.

name

Optional name to use in run_after commands. Note names MUST be unique! When not specified, a unique number will be assigned automatically.

run_on_start

Subroutine reference to execute when the job begins. Executes under the forked process.

run_on_finish

Subroutine reference to execute when the job ends. Executes on the master process.

run_after

Add a new (or list of) processes that must be completed before this process can be runnable. You may pass a process object (from schedule), a process name, or a process label. You may use "|" or "&" in a string to run this process after a OR of any processes exit, or after ALL exit (the default.) ! in front of a process name indicates to run if that process fails with bad exit status. ^ in front of a process indicates to run if that process succeeds OR fails.

$self->sig_child

Must be called in SIG{CHLD} handler by the parent process. If there are multiple Parallel::Forker's each of their sig_child's must be called.

$self->wait_all

Wait for all running jobs to complete.

$self->write_tree (filename=><filename>)

Print a dump of the execution tree.

DISTRIBUTION

The latest version is available from CPAN and from http://www.veripool.com/.

Copyright 2002-2005 by Wilson Snyder. This package is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License or the Perl Artistic License.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>

SEE ALSO

Parallel::Forker::Process

NAME

Parallel::Forker::Process - Single parallel fork process object

SYNOPSIS

$obj->run;
$obj->poll;
$obj->kill(<"SIGNAL">);
$obj->kill_tree(<"SIGNAL">);

DESCRIPTION

Manage a single process under the control of Parallel::Forker.

Processes transition over 6 states. They begin in idle state, and are transitioned by the user into ready state. As their dependancies complete, Parallel::Forker transitions them to the runable state. As the max_proc limit permits, they transition to the running state, and executed. On completion, they transition to the done state. If a process depends on another process, and that other process fails, they transition to the parerr (parent error) state, and are never run.

METHODS

forkref

Return the parent Parallel::Forker object this process belongs to.

is_done

Returns true if the process is in the done state.

is_idle

Returns true if the process is in the idle state.

is_parerr

Returns true if the process is in the parent error state.

is_ready

Returns true if the process is in the ready state.

is_runable

Returns true if the process is in the runable state.

is_running

Returns true if the process is in the running state.

kill

Kill the process if it is running

kill_tree

Kill the process and any of it's subchildren. Requires Schedule::Load.

pid

Return the process ID if this job is running, else undef.

poll

Check the process for activity, invoking callbacks if needed. Generally Fork->poll() is used instead.

ready

Mark this process as being ready for execution when all run_after's are ready and CPU resources permit. When that occurs, run will be called on the process automatically.

kill (<signal>)

Send a kill to this child.

kill_tree_all (<signal>)

Send a kill to this child and its subchildren. Requires the Schedule::Load package to be installed.

run

Start this process now.

DISTRIBUTION

The latest version is available from CPAN and from http://www.veripool.com/.

Copyright 2002-2005 by Wilson Snyder. This package is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License or the Perl Artistic License.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>

SEE ALSO

Parallel::Forker