.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ForkManager 3pm"
.TH ForkManager 3pm "2006-06-14" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Parallel::ForkManager \- A simple parallel processing fork manager
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Parallel::ForkManager;
.Ve
.PP
.Vb 1
\&  $pm = new Parallel::ForkManager($MAX_PROCESSES);
.Ve
.PP
.Vb 3
\&  foreach $data (@all_data) {
\&    # Forks and returns the pid for the child:
\&    my $pid = $pm\->start and next;
.Ve
.PP
.Vb 1
\&    ... do some work with $data in the child process ...
.Ve
.PP
.Vb 2
\&    $pm\->finish; # Terminates the child process
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is intended for use in operations that can be done in parallel 
where the number of processes to be forked off should be limited. Typical 
use is a downloader which will be retrieving hundreds/thousands of files.
.PP
The code for a downloader would look something like this:
.PP
.Vb 2
\&  use LWP::Simple;
\&  use Parallel::ForkManager;
.Ve
.PP
.Vb 1
\&  ...
.Ve
.PP
.Vb 5
\&  @links=( 
\&    ["http://www.foo.bar/rulez.data","rulez_data.txt"], 
\&    ["http://new.host/more_data.doc","more_data.doc"],
\&    ...
\&  );
.Ve
.PP
.Vb 1
\&  ...
.Ve
.PP
.Vb 2
\&  # Max 30 processes for parallel download
\&  my $pm = new Parallel::ForkManager(30);
.Ve
.PP
.Vb 2
\&  foreach my $linkarray (@links) {
\&    $pm\->start and next; # do the fork
.Ve
.PP
.Vb 3
\&    my ($link,$fn) = @$linkarray;
\&    warn "Cannot get $fn from $link"
\&      if getstore($link,$fn) != RC_OK;
.Ve
.PP
.Vb 3
\&    $pm\->finish; # do the exit in the child process
\&  }
\&  $pm\->wait_all_children;
.Ve
.PP
First you need to instantiate the ForkManager with the \*(L"new\*(R" constructor. 
You must specify the maximum number of processes to be created. If you 
specify 0, then \s-1NO\s0 fork will be done; this is good for debugging purposes.
.PP
Next, use \f(CW$pm\fR\->start to do the fork. \f(CW$pm\fR returns 0 for the child process, 
and child pid for the parent process (see also \*(L"\fIfork()\fR\*(R" in \fIperlfunc\fR\|(1p)). 
The \*(L"and next\*(R" skips the internal loop in the parent process. \s-1NOTE:\s0 
\&\f(CW$pm\fR\->start dies if the fork fails.
.PP
$pm\->finish terminates the child process (assuming a fork was done in the 
\&\*(L"start\*(R").
.PP
\&\s-1NOTE:\s0 You cannot use \f(CW$pm\fR\->start if you are already in the child process. 
If you want to manage another set of subprocesses in the child process, 
you must instantiate another Parallel::ForkManager object!
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "new $processes" 5
.el .IP "new \f(CW$processes\fR" 5
.IX Item "new $processes"
Instantiate a new Parallel::ForkManager object. You must specify the maximum 
number of children to fork off. If you specify 0 (zero), then no children 
will be forked. This is intended for debugging purposes.
.ie n .IP "start [ $process_identifier ]" 5
.el .IP "start [ \f(CW$process_identifier\fR ]" 5
.IX Item "start [ $process_identifier ]"
This method does the fork. It returns the pid of the child process for 
the parent, and 0 for the child process. If the \f(CW$processes\fR parameter 
for the constructor is 0 then, assuming you're in the child process, 
\&\f(CW$pm\fR\->start simply returns 0.
.Sp
An optional \f(CW$process_identifier\fR can be provided to this method... It is used by 
the \*(L"run_on_finish\*(R" callback (see \s-1CALLBACKS\s0) for identifying the finished
process.
.ie n .IP "finish [ $exit_code ]" 5
.el .IP "finish [ \f(CW$exit_code\fR ]" 5
.IX Item "finish [ $exit_code ]"
Closes the child process by exiting and accepts an optional exit code 
(default exit code is 0) which can be retrieved in the parent via callback. 
If you use the program in debug mode ($processes == 0), this method doesn't 
do anything.
.ie n .IP "set_max_procs $processes" 5
.el .IP "set_max_procs \f(CW$processes\fR" 5
.IX Item "set_max_procs $processes"
Allows you to set a new maximum number of children to maintain. Returns 
the previous setting.
.IP "wait_all_children" 5
.IX Item "wait_all_children"
You can call this method to wait for all the processes which have been 
forked. This is a blocking wait.
.SH "CALLBACKS"
.IX Header "CALLBACKS"
You can define callbacks in the code, which are called on events like starting 
a process or upon finish.
.PP
The callbacks can be defined with the following methods:
.ie n .IP "run_on_finish $code\fR [, \f(CW$pid ]" 4
.el .IP "run_on_finish \f(CW$code\fR [, \f(CW$pid\fR ]" 4
.IX Item "run_on_finish $code [, $pid ]"
You can define a subroutine which is called when a child is terminated. It is
called in the parent process.
.Sp
The paremeters of the \f(CW$code\fR are the following:
.Sp
.Vb 5
\&  \- pid of the process, which is terminated
\&  \- exit code of the program
\&  \- identification of the process (if provided in the "start" method)
\&  \- exit signal (0\-127: signal name)
\&  \- core dump (1 if there was core dump at exit)
.Ve
.ie n .IP "run_on_start $code" 4
.el .IP "run_on_start \f(CW$code\fR" 4
.IX Item "run_on_start $code"
You can define a subroutine which is called when a child is started. It called
after the successful startup of a child in the parent process.
.Sp
The parameters of the \f(CW$code\fR are the following:
.Sp
.Vb 2
\&  \- pid of the process which has been started
\&  \- identification of the process (if provided in the "start" method)
.Ve
.ie n .IP "run_on_wait $code, [$period]" 4
.el .IP "run_on_wait \f(CW$code\fR, [$period]" 4
.IX Item "run_on_wait $code, [$period]"
You can define a subroutine which is called when the child process needs to wait
for the startup. If \f(CW$period\fR is not defined, then one call is done per
child. If \f(CW$period\fR is defined, then \f(CW$code\fR is called periodically and the
module waits for \f(CW$period\fR seconds betwen the two calls. Note, \f(CW$period\fR can be
fractional number also. The exact \*(L"$period seconds\*(R" is not guarranteed,
signals can shorten and the process scheduler can make it longer (on busy
systems).
.Sp
The \f(CW$code\fR called in the \*(L"start\*(R" and the \*(L"wait_all_children\*(R" method also.
.Sp
No parameters are passed to the \f(CW$code\fR on the call.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Sh "Parallel get"
.IX Subsection "Parallel get"
This small example can be used to get URLs in parallel.
.PP
.Vb 16
\&  use Parallel::ForkManager;
\&  use LWP::Simple;
\&  my $pm=new Parallel::ForkManager(10);
\&  for my $link (@ARGV) {
\&    $pm\->start and next;
\&    my ($fn)= $link =~ /^.*\e/(.*?)$/;
\&    if (!$fn) {
\&      warn "Cannot determine filename from $fn\en";
\&    } else {
\&      $0.=" ".$fn;
\&      print "Getting $fn from $link\en";
\&      my $rc=getstore($link,$fn);
\&      print "$link downloaded. response code: $rc\en";
\&    };
\&    $pm\->finish;
\&  };
.Ve
.Sh "Callbacks"
.IX Subsection "Callbacks"
Example of a program using callbacks to get child exit codes:
.PP
.Vb 2
\&  use strict;
\&  use Parallel::ForkManager;
.Ve
.PP
.Vb 3
\&  my $max_procs = 5;
\&  my @names = qw( Fred Jim Lily Steve Jessica Bob Dave Christine Rico Sara );
\&  # hash to resolve PID\(aqs back to child specific information
.Ve
.PP
.Vb 1
\&  my $pm =  new Parallel::ForkManager($max_procs);
.Ve
.PP
.Vb 8
\&  # Setup a callback for when a child finishes up so we can
\&  # get it\(aqs exit code
\&  $pm\->run_on_finish(
\&    sub { my ($pid, $exit_code, $ident) = @_;
\&      print "** $ident just got out of the pool ".
\&        "with PID $pid and exit code: $exit_code\en";
\&    }
\&  );
.Ve
.PP
.Vb 5
\&  $pm\->run_on_start(
\&    sub { my ($pid,$ident)=@_;
\&      print "** $ident started, pid: $pid\en";
\&    }
\&  );
.Ve
.PP
.Vb 6
\&  $pm\->run_on_wait(
\&    sub {
\&      print "** Have to wait for one children ...\en"
\&    },
\&    0.5
\&  );
.Ve
.PP
.Vb 2
\&  foreach my $child ( 0 .. $#names ) {
\&    my $pid = $pm\->start($names[$child]) and next;
.Ve
.PP
.Vb 7
\&    # This code is the child process
\&    print "This is $names[$child], Child number $child\en";
\&    sleep ( 2 * $child );
\&    print "$names[$child], Child $child is about to get out...\en";
\&    sleep 1;
\&    $pm\->finish($child); # pass an exit code to finish
\&  }
.Ve
.PP
.Vb 3
\&  print "Waiting for Children...\en";
\&  $pm\->wait_all_children;
\&  print "Everybody is out of the pool!\en";
.Ve
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Do not use Parallel::ForkManager in an environment, where other child
processes can affect the run of the main program, so using this module
is not recommended in an environment where \fIfork()\fR / \fIwait()\fR is already used.
.PP
If you want to use more than one copies of the Parallel::ForkManager, then
you have to make sure that all children processes are terminated, before you
use the second object in the main program.
.PP
You are free to use a new copy of Parallel::ForkManager in the child
processes, although I don't think it makes sense.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2000 Szabó, Balázs (dLux)
.PP
All right reserved. This program is free software; you can redistribute it 
and/or modify it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  dLux (Szabó, Balázs) <dlux@kapu.hu>
.Ve
.SH "CREDITS"
.IX Header "CREDITS"
.Vb 4
\&  Noah Robin <sitz@onastick.net> (documentation tweaks)
\&  Chuck Hirstius <chirstius@megapathdsl.net> (callback exit status, example)
\&  Grant Hopwood <hopwoodg@valero.com> (win32 port)
\&  Mark Southern <mark_southern@merck.com> (bugfix)
.Ve