.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
.\"
.\" Standard preamble:
.\" ========================================================================
.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\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Proc::Queue 3pm"
.TH Proc::Queue 3pm "2008-01-08" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Proc::Queue \- limit the number of child processes running
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Proc::Queue size => 4, debug => 1;
\&
\&  package other;
\&  use POSIX ":sys_wait_h"; # imports WNOHANG
\&
\&  # this loop creates new children, but Proc::Queue makes it wait every
\&  # time the limit (4) is reached until enough children exit
\&  foreach (1..100) {
\&    my $f=fork;
\&    if(defined ($f) and $f==0) {
\&      print "\-\- I\*(Aqm a forked process $$\en";
\&      sleep rand 5;
\&      print "\-\- I\*(Aqm tired, going away $$\en";
\&      exit(0)
\&    }
\&    1 while waitpid(\-1, WNOHANG)>0; # reaps children
\&  }
\&
\&  Proc::Queue::size(10); # changing limit to 10 concurrent processes
\&  Proc::Queue::trace(1); # trace mode on
\&  Proc::Queue::debug(0); # debug is off
\&  Proc::Queue::delay(0.2); # set 200 miliseconds as minimum
\&                           # delay between fork calls
\&
\&  package other; # just to test it works on any package
\&
\&  print "going again!\en";
\&
\&  # another loop with different settings for Proc::Queue
\&  foreach (1..20) {
\&    my $f=fork;
\&    if(defined ($f) and $f==0) {
\&      print "\-\- I\*(Aqm a forked process $$\en";
\&      sleep rand 5;
\&      print "\-\- I\*(Aqm tired, going away $$\en";
\&      exit(0)
\&    }
\&  }
\&
\&  1 while wait != \-1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module lets you parallelise a perl program using the \f(CW\*(C`fork\*(C'\fR,
\&\f(CW\*(C`exit\*(C'\fR, \f(CW\*(C`wait\*(C'\fR and \f(CW\*(C`waitpid\*(C'\fR calls as usual but without taking care
of creating too many processes and overloading the machine.
.PP
It redefines perl \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, \f(CW\*(C`wait\*(C'\fR and \f(CW\*(C`waitpid\*(C'\fR core
functions. Old programs do not need to be reprogrammed, only the \f(CW\*(C`use
Proc::Queue ...\*(C'\fR sentence has to be added to them.
.PP
Additionally, the module has two debugging modes (debug and trace)
that seem too be very useful when developing parallel aplications:
.IP "debug mode:" 4
.IX Item "debug mode:"
when active, dumps lots of information about processes being created,
exiting, being caught by parent, etc.
.IP "trace mode:" 4
.IX Item "trace mode:"
prints a line every time one of the \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, \f(CW\*(C`wait\*(C'\fR or
\&\f(CW\*(C`waitpid\*(C'\fR functions are called.
.PP
It is also possible to set a minimun delay time between fork calls
to stop too many processes for starting in a short time interval.
.PP
Child processes continue to use the modified functions, but their
queues are reset and the maximun process number for them is set to 1
(anyway, children can change their queue size themselves).
.PP
Proc::Queue doesn't work if \s-1CHLD\s0 signal handler is set to
\&\f(CW\*(C`IGNORE\*(C'\fR.
.PP
Internally, Proc::Queue, automatically catches zombies and stores
their exit status in a private hash. To avoid leaking memory in long
running programs you have to call \f(CW\*(C`wait\*(C'\fR or \f(CW\*(C`waitpid\*(C'\fR to delete
entries from that hash or alternatively active the \f(CW\*(C`ignore_children\*(C'\fR
mode:
.PP
.Vb 1
\&  Proc::Queue::ignore_children(1)
.Ve
.PP
or
.PP
.Vb 1
\&  use Proc::Queue ignore_children=>1, ...
.Ve
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
This module redefines the \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`exit\*(C'\fR
calls.
.SS "\s-1EXPORT_OK\s0"
.IX Subsection "EXPORT_OK"
Functions \f(CW\*(C`fork_now\*(C'\fR, \f(CW\*(C`waitpids\*(C'\fR, \f(CW\*(C`run_back\*(C'\fR, \f(CW\*(C`run_back_now\*(C'\fR,
\&\f(CW\*(C`all_exit_ok\*(C'\fR, \f(CW\*(C`running_now\*(C'\fR, \f(CW\*(C`system_back\*(C'\fR and \f(CW\*(C`system_back_now\*(C'\fR
can be imported. Tag \f(CW\*(C`:all\*(C'\fR is defined to import all of them.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
There are several not exported functions that can be used to configure
the module:
.IP "\fIsize()\fR,  size($number)" 4
.IX Item "size(),  size($number)"
If an argument is given the maximun number of concurrent processes is
set to it and the number of maximun processes that were allowed before
is returned.
.Sp
If no argument is given, the number of processes allowed is returned.
.IP "\fIdelay()\fR, delay($time)" 4
.IX Item "delay(), delay($time)"
lets you set a minimun time in seconds to elapse between consecutive
calls to fork. It is useful to avoid creating too many processes in
a short time (that could degrade performance).
.Sp
If Time::HiRes module is available delays shorted that 1 second are
allowed.
.Sp
If no arg is given, the current delay is returned.
.Sp
To clear it use \f(CWProc::Queue::delay(0)\fR.
.IP "\fIweight()\fR, weight($weight)" 4
.IX Item "weight(), weight($weight)"
by default any process forked count as 1 through the max number of
processes allowed to run simultaneously (the queue size). \f(CW\*(C`weight\*(C'\fR
allows to change this, i.e.:
.Sp
.Vb 3
\&  Proc::Queue::weight(3);
\&  run_back { ... heavy process here ... };
\&  Proc::Queue::weight(1);
.Ve
.Sp
causes the \f(CW\*(C`heavy process\*(C'\fR to count as three normal processes.
.Sp
Valid weight values are integers greater than zero.
.Sp
Remember to reset the weight back to 1 (or whatever) after the heavier
processes have been forked!.
.IP "\fIallow_excess()\fR, allow_excess($allow_excess)" 4
.IX Item "allow_excess(), allow_excess($allow_excess)"
by default the next queued process will be started as soon as the
number of running processes is smaller than the queue size\*(--this is
regardless of the weight of the next queued process, so the queue
could become overloaded.  Setting \f(CW\*(C`allow_excess\*(C'\fR to false forces the
next queued process to wait until there is room for it in the queue,
that is, the size of the queue less the weighted number of currently
running processes must be no smaller than the weight of the next
queued process in order for the next process to start.
.Sp
Setting \f(CW\*(C`allow_excess\*(C'\fR to any value greater than zero (default is 1) resets
the default behavior.
.IP "ignore_children($on)" 4
.IX Item "ignore_children($on)"
calling
.Sp
.Vb 1
\&  Proc::Queue::ignore_children(1);
.Ve
.Sp
is the equivalent to
.Sp
.Vb 1
\&  $SIG{CHLD}=\*(AqIGNORE\*(Aq
.Ve
.Sp
when using Proc::Queue.
.IP "\fIdebug()\fR, debug($boolean), \fItrace()\fR, trace($boolean)" 4
.IX Item "debug(), debug($boolean), trace(), trace($boolean)"
Change or return the status for the debug and trace modes.
.PP
Other utility subroutines that can be imported from Proc::Queue are:
.IP "\fIfork_now()\fR" 4
.IX Item "fork_now()"
Sometimes you would need to fork a new child without waiting for other
children to exit if the queue is full, \f(CW\*(C`fork_now\*(C'\fR does that. It is
exportable so you can do...
.Sp
.Vb 1
\&  use Proc::Queue size => 5, qw(fork_now), debug =>1;
\&
\&  $f=fork_now;
\&  if(defined $f and $f == 0) {
\&      print "I\*(Aqm the child\en"; exit;
\&  }
.Ve
.IP "waitpids(@pid)" 4
.IX Item "waitpids(@pid)"
waits for all the processes in \f(CW@pid\fR to exit. It returns an array
with pairs of pid and exit values (pid1, exit1, pid2, exit2, pid3,
exit3,...) as returned by individual waitpid calls.
.IP "run_back(\e&code), run_back { code }" 4
.IX Item "run_back(&code), run_back { code }"
Runs the argument subrutine in a forked child process and returns the
pid number for the new process.
.IP "run_back_now(\e&code), run_back_now { code }" 4
.IX Item "run_back_now(&code), run_back_now { code }"
A mix between run_back and fork_now.
.IP "system_back(@command)" 4
.IX Item "system_back(@command)"
Similar to the \f(CW\*(C`system\*(C'\fR call but runs the command in the background
and waits for other children to exit first if there are already too many
running.
.Sp
Returns the pid of the forked process or undef if the program was not
found.
.IP "system_back_now(@command)" 4
.IX Item "system_back_now(@command)"
As \f(CW\*(C`system_back\*(C'\fR but without checking if the maximun number of children
allowed has been reached.
.IP "all_exit_ok(@pid)" 4
.IX Item "all_exit_ok(@pid)"
Do a \f(CW\*(C`waitpids\*(C'\fR call and test that all the processes exit with code 0.
.IP "\fIrunning_now()\fR" 4
.IX Item "running_now()"
Returns the number of child processes currently running.
.IP "import(pkg,opt,val,opt,val,...,fnt_name,fnt_name,...)" 4
.IX Item "import(pkg,opt,val,opt,val,...,fnt_name,fnt_name,...)"
The import function is not usually explicitally called but by the
\&\f(CW\*(C`use Proc::Queue\*(C'\fR statement.
.Sp
Options allowed are \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`weight\*(C'\fR and \f(CW\*(C`trace\*(C'\fR, i.e:
.Sp
.Vb 1
\&  use Proc::Queue size=>10, debug=>1;
.Ve
.Sp
Anything that is not \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`weight\*(C'\fR or \f(CW\*(C`trace\*(C'\fR is
expected to be a function name to be imported.
.Sp
.Vb 1
\&  use Proc::Queue size=>10, \*(Aq:all\*(Aq;
.Ve
.SS "\s-1BUGS\s0"
.IX Subsection "BUGS"
Proc::Queue is a very stable module, no bugs have been reported
for a long time.
.PP
Support for Win32 OSs is still experimental.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperlfunc\fR\|(1), \fIperlipc\fR\|(1), \s-1POSIX\s0, \fIperlfork\fR\|(1),
Time::HiRes, Parallel::ForkManager. The \f(CW\*(C`example.pl\*(C'\fR script
contained in the module distribution.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2001\-2003, 2005\-2008 by Salvador Fandin\*~o
<sfandino@yahoo.com>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.