.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "FCGI::ProcManager 3pm"
.TH FCGI::ProcManager 3pm "2017-09-18" "perl v5.26.0" "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"
.Vb 1
\& FCGI::ProcManager \- functions for managing FastCGI applications.
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 12
\& # In Object\-oriented style.
\& use CGI::Fast;
\& use FCGI::ProcManager;
\& my $proc_manager = FCGI::ProcManager\->new({
\&    n_processes => 10
\& });
\& $proc_manager\->pm_manage();
\& while (my $cgi = CGI::Fast\->new()) {
\&   $proc_manager\->pm_pre_dispatch();
\&   # ... handle the request here ...
\&   $proc_manager\->pm_post_dispatch();
\& }
\&
\& # This style is also supported:
\& use CGI::Fast;
\& use FCGI::ProcManager qw(pm_manage pm_pre_dispatch
\&              pm_post_dispatch);
\& pm_manage( n_processes => 10 );
\& while (my $cgi = CGI::Fast\->new()) {
\&   pm_pre_dispatch();
\&   #...
\&   pm_post_dispatch();
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
FCGI::ProcManager is used to serve as a FastCGI process manager.  By
re-implementing it in perl, developers can more finely tune performance in
their web applications, and can take advantage of copy-on-write semantics
prevalent in \s-1UNIX\s0 kernel process management.  The process manager should
be invoked before the caller''s request loop
.PP
The primary routine, \f(CW\*(C`pm_manage\*(C'\fR, enters a loop in which it maintains a
number of FastCGI servers (via \fIfork\fR\|(2)), and which reaps those servers
when they die (via \fIwait\fR\|(2)).
.PP
\&\f(CW\*(C`pm_manage\*(C'\fR provides too hooks:
.PP
.Vb 2
\& C<managing_init> \- called just before the manager enters the manager loop.
\& C<handling_init> \- called just before a server is returns from C<pm_manage>
.Ve
.PP
It is necessary for the caller, when implementing its request loop, to
insert a call to \f(CW\*(C`pm_pre_dispatch\*(C'\fR at the top of the loop, and then
7\f(CW\*(C`pm_post_dispatch\*(C'\fR at the end of the loop.
.SS "Signal Handling"
.IX Subsection "Signal Handling"
FCGI::ProcManager attempts to do the right thing for proper shutdowns now.
.PP
When it receives a \s-1SIGHUP,\s0 it sends a \s-1SIGTERM\s0 to each of its children, and
then resumes its normal operations.
.PP
When it receives a \s-1SIGTERM,\s0 it sends a \s-1SIGTERM\s0 to each of its children, sets
an \fIalarm\fR\|(3) \*(L"die timeout\*(R" handler, and waits for each of its children to
die.  If all children die before this timeout, process manager exits with
return status 0.  If all children do not die by the time the \*(L"die timeout\*(R"
occurs, the process manager sends a \s-1SIGKILL\s0 to each of the remaining
children, and exists with return status 1.
.PP
In order to get FastCGI servers to exit upon receiving a signal, it is
necessary to use its \s-1FAIL_ACCEPT_ON_INTR.\s0  See \s-1FCGI\s0's description of
\&\s-1FAIL_ACCEPT_ON_INTR.\s0  Unfortunately, if you want/need to use CGI::Fast, it
is currently necessary to run the latest (at the time of writing) development
version of \s-1FCGI\s0.pm. (>= 0.71_02)
.PP
Otherwise, if you don't, there is a loop around \fIaccept\fR\|(2) which prevents
os_unix.c \fIOS_Accept()\fR from returning the necessary error when FastCGI
servers blocking on \fIaccept\fR\|(2) receive the \s-1SIGTERM\s0 or \s-1SIGHUP.\s0
.PP
FCGI::ProcManager uses \fIPOSIX::sigaction()\fR to override the default \s-1SA_RESTART\s0
policy used for perl's \f(CW%SIG\fR behavior.  Specifically, the process manager
never uses \s-1SA_RESTART,\s0 while the child FastCGI servers turn off \s-1SA_RESTART\s0
around the \fIaccept\fR\|(2) loop, but reinstate it otherwise.
.PP
The desired (and implemented) effect is to give a request as big a chance as
possible to succeed and to delay their exits until after their request,
while allowing the FastCGI servers waiting for new requests to die right
away.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 2
\& class or instance
\& (ProcManager) new([hash parameters])
.Ve
.PP
Constructs a new process manager.  Takes an option has of initial parameter
values, and assigns these to the constructed object \s-1HASH,\s0 overriding any
default values.  The default parameter values currently are:
.PP
.Vb 4
\& role         => manager
\& start_delay  => 0
\& die_timeout  => 60
\& pm_title => \*(Aqperl\-fcgi\-pm\*(Aq
.Ve
.SH "Manager methods"
.IX Header "Manager methods"
.SS "pm_manage"
.IX Subsection "pm_manage"
.Vb 2
\& instance or export
\& (int) pm_manage([hash parameters])
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
When this is called by a FastCGI script to manage application servers.  It
defines a sequence of instructions for a process to enter this method and
begin forking off and managing those handlers, and it defines a sequence of
instructions to initialize those handlers.
.PP
If n_processes < 1, the managing section is subverted, and only the
handling sequence is executed.
.PP
Either returns the return value of \fIpm_die()\fR and/or \fIpm_abort()\fR (which will
not ever return in general), or returns 1 to the calling script to begin
handling requests.
.SS "managing_init"
.IX Subsection "managing_init"
.Vb 2
\& instance
\& () managing_init()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
Overrideable method which initializes a process manager.  In order to
handle signals, manage the \s-1PID\s0 file, and change the process name properly,
any method which overrides this should call \fISUPER::managing_init()\fR.
.SS "pm_die"
.IX Subsection "pm_die"
.Vb 2
\& instance or export
\& () pm_die(string msg[, int exit_status])
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
This method is called when a process manager receives a notification to
shut itself down.  \fIpm_die()\fR attempts to shutdown the process manager
gently, sending a \s-1SIGTERM\s0 to each managed process, waiting \fIdie_timeout()\fR
seconds to reap each process, and then exit gracefully once all children
are reaped, or to abort if all children are not reaped.
.SS "pm_wait"
.IX Subsection "pm_wait"
.Vb 2
\& instance or export
\& (int pid) pm_wait()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
This calls \fIwait()\fR which suspends execution until a child has exited.
If the process \s-1ID\s0 returned by wait corresponds to a managed process,
\&\fIpm_notify()\fR is called with the exit status of that process.
\&\fIpm_wait()\fR returns with the return value of \fIwait()\fR.
.SS "pm_write_pid_file"
.IX Subsection "pm_write_pid_file"
.Vb 2
\& instance or export
\& () pm_write_pid_file([string filename])
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
Writes current process \s-1ID\s0 to optionally specified file.  If no filename is
specified, it uses the value of the \f(CW\*(C`pid_fname\*(C'\fR parameter.
.SS "pm_remove_pid_file"
.IX Subsection "pm_remove_pid_file"
.Vb 2
\& instance or export
\& () pm_remove_pid_file()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
Removes optionally specified file.  If no filename is specified, it uses
the value of the \f(CW\*(C`pid_fname\*(C'\fR parameter.
.SS "sig_sub"
.IX Subsection "sig_sub"
.Vb 2
\& instance
\& () sig_sub(string name)
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
The name of this method is passed to \fIPOSIX::sigaction()\fR, and handles signals
for the process manager.  If \f(CW$SIG_CODEREF\fR is set, then the input arguments
to this are passed to a call to that.
.SS "sig_manager"
.IX Subsection "sig_manager"
.Vb 2
\& instance
\& () sig_manager(string name)
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
Handles signals of the process manager.  Takes as input the name of signal
being handled.
.SH "Handler methods"
.IX Header "Handler methods"
.SS "handling_init"
.IX Subsection "handling_init"
.Vb 2
\& instance or export
\& () handling_init()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "pm_pre_dispatch"
.IX Subsection "pm_pre_dispatch"
.Vb 2
\& instance or export
\& () pm_pre_dispatch()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "pm_post_dispatch"
.IX Subsection "pm_post_dispatch"
.Vb 2
\& instance or export
\& () pm_post_dispatch()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "sig_handler"
.IX Subsection "sig_handler"
.Vb 2
\& instance or export
\& () sig_handler()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SH "Common methods and routines"
.IX Header "Common methods and routines"
.SS "self_or_default"
.IX Subsection "self_or_default"
.Vb 2
\& private global
\& (ProcManager, @args) self_or_default([ ProcManager, ] @args);
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.PP
This is a helper subroutine to acquire or otherwise create a singleton
default object if one is not passed in, e.g., a method call.
.SS "pm_change_process_name"
.IX Subsection "pm_change_process_name"
.Vb 2
\& instance or export
\& () pm_change_process_name()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "pm_received_signal"
.IX Subsection "pm_received_signal"
.Vb 2
\& instance or export
\& () pm_received signal()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SH "parameters"
.IX Header "parameters"
.SS "pm_parameter"
.IX Subsection "pm_parameter"
.Vb 2
\& instance or export
\& () pm_parameter()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "n_processes"
.IX Subsection "n_processes"
.SS "no_signals"
.IX Subsection "no_signals"
.SS "pid_fname"
.IX Subsection "pid_fname"
.SS "die_timeout"
.IX Subsection "die_timeout"
.SS "role"
.IX Subsection "role"
.SS "start_delay"
.IX Subsection "start_delay"
\&\s-1DESCRIPTION:\s0
.SH "notification and death"
.IX Header "notification and death"
.SS "pm_warn"
.IX Subsection "pm_warn"
.Vb 2
\& instance or export
\& () pm_warn()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "pm_notify"
.IX Subsection "pm_notify"
.Vb 2
\& instance or export
\& () pm_notify()
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "pm_exit"
.IX Subsection "pm_exit"
.Vb 2
\& instance or export
\& () pm_exit(string msg[, int exit_status])
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SS "pm_abort"
.IX Subsection "pm_abort"
.Vb 2
\& instance or export
\& () pm_abort(string msg[, int exit_status])
.Ve
.PP
\&\s-1DESCRIPTION:\s0
.SH "BUGS"
.IX Header "BUGS"
No known bugs, but this does not mean no bugs exist.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1FCGI\s0.
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Gareth Kirwan <gbjk@thermeon.com>
.SH "AUTHOR"
.IX Header "AUTHOR"
James E Jurach Jr.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 2
\& FCGI\-ProcManager \- A Perl FCGI Process Manager
\& Copyright (c) 2000, FundsXpress Financial Network, Inc.
\&
\& This library is free software; you can redistribute it and/or
\& modify it under the terms of the GNU Lesser General Public
\& License as published by the Free Software Foundation; either
\& version 2 of the License, or (at your option) any later version.
\&
\& BECAUSE THIS LIBRARY IS LICENSED FREE OF CHARGE, THIS LIBRARY IS
\& BEING PROVIDED "AS IS WITH ALL FAULTS," WITHOUT ANY WARRANTIES
\& OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT
\& LIMITATION, ANY IMPLIED WARRANTIES OF TITLE, NONINFRINGEMENT,
\& MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND THE
\& ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY,
\& AND EFFORT IS WITH THE YOU.  See the GNU Lesser General Public
\& License for more details.
\&
\& You should have received a copy of the GNU Lesser General Public
\& License along with this library; if not, write to the Free Software
\& Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111\-1307  USA
.Ve