1FCGI::ProcManager(3)  User Contributed Perl Documentation FCGI::ProcManager(3)
2
3
4

NAME

6        FCGI::ProcManager - functions for managing FastCGI applications.
7

SYNOPSIS

9        # In Object-oriented style.
10        use CGI::Fast;
11        use FCGI::ProcManager;
12        my $proc_manager = FCGI::ProcManager->new({
13           n_processes => 10
14        });
15        $proc_manager->pm_manage();
16        while (my $cgi = CGI::Fast->new()) {
17          $proc_manager->pm_pre_dispatch();
18          # ... handle the request here ...
19          $proc_manager->pm_post_dispatch();
20        }
21
22        # This style is also supported:
23        use CGI::Fast;
24        use FCGI::ProcManager qw(pm_manage pm_pre_dispatch
25                     pm_post_dispatch);
26        pm_manage( n_processes => 10 );
27        while (my $cgi = CGI::Fast->new()) {
28          pm_pre_dispatch();
29          #...
30          pm_post_dispatch();
31        }
32

DESCRIPTION

34       FCGI::ProcManager is used to serve as a FastCGI process manager.  By
35       re-implementing it in perl, developers can more finely tune performance
36       in their web applications, and can take advantage of copy-on-write
37       semantics prevalent in UNIX kernel process management.  The process
38       manager should be invoked before the caller''s request loop
39
40       The primary routine, "pm_manage", enters a loop in which it maintains a
41       number of FastCGI servers (via fork(2)), and which reaps those servers
42       when they die (via wait(2)).
43
44       "pm_manage" provides too hooks:
45
46        C<managing_init> - called just before the manager enters the manager loop.
47        C<handling_init> - called just before a server is returns from C<pm_manage>
48
49       It is necessary for the caller, when implementing its request loop, to
50       insert a call to "pm_pre_dispatch" at the top of the loop, and then
51       7"pm_post_dispatch" at the end of the loop.
52
53   Signal Handling
54       FCGI::ProcManager attempts to do the right thing for proper shutdowns
55       now.
56
57       When it receives a SIGHUP, it sends a SIGTERM to each of its children,
58       and then resumes its normal operations.
59
60       When it receives a SIGTERM, it sends a SIGTERM to each of its children,
61       sets an alarm(3) "die timeout" handler, and waits for each of its
62       children to die.  If all children die before this timeout, process
63       manager exits with return status 0.  If all children do not die by the
64       time the "die timeout" occurs, the process manager sends a SIGKILL to
65       each of the remaining children, and exists with return status 1.
66
67       In order to get FastCGI servers to exit upon receiving a signal, it is
68       necessary to use its FAIL_ACCEPT_ON_INTR.  See FCGI's description of
69       FAIL_ACCEPT_ON_INTR.  Unfortunately, if you want/need to use CGI::Fast,
70       it is currently necessary to run the latest (at the time of writing)
71       development version of FCGI.pm. (>= 0.71_02)
72
73       Otherwise, if you don't, there is a loop around accept(2) which
74       prevents os_unix.c OS_Accept() from returning the necessary error when
75       FastCGI servers blocking on accept(2) receive the SIGTERM or SIGHUP.
76
77       FCGI::ProcManager uses POSIX::sigaction() to override the default
78       SA_RESTART policy used for perl's %SIG behavior.  Specifically, the
79       process manager never uses SA_RESTART, while the child FastCGI servers
80       turn off SA_RESTART around the accept(2) loop, but reinstate it
81       otherwise.
82
83       The desired (and implemented) effect is to give a request as big a
84       chance as possible to succeed and to delay their exits until after
85       their request, while allowing the FastCGI servers waiting for new
86       requests to die right away.
87

METHODS

89   new
90        class or instance
91        (ProcManager) new([hash parameters])
92
93       Constructs a new process manager.  Takes an option has of initial
94       parameter values, and assigns these to the constructed object HASH,
95       overriding any default values.  The default parameter values currently
96       are:
97
98        role         => manager
99        start_delay  => 0
100        die_timeout  => 60
101        pm_title => 'perl-fcgi-pm'
102

Manager methods

104   pm_manage
105        instance or export
106        (int) pm_manage([hash parameters])
107
108       DESCRIPTION:
109
110       When this is called by a FastCGI script to manage application servers.
111       It defines a sequence of instructions for a process to enter this
112       method and begin forking off and managing those handlers, and it
113       defines a sequence of instructions to intialize those handlers.
114
115       If n_processes < 1, the managing section is subverted, and only the
116       handling sequence is executed.
117
118       Either returns the return value of pm_die() and/or pm_abort() (which
119       will not ever return in general), or returns 1 to the calling script to
120       begin handling requests.
121
122   managing_init
123        instance
124        () managing_init()
125
126       DESCRIPTION:
127
128       Overrideable method which initializes a process manager.  In order to
129       handle signals, manage the PID file, and change the process name
130       properly, any method which overrides this should call
131       SUPER::managing_init().
132
133   pm_die
134        instance or export
135        () pm_die(string msg[, int exit_status])
136
137       DESCRIPTION:
138
139       This method is called when a process manager receives a notification to
140       shut itself down.  pm_die() attempts to shutdown the process manager
141       gently, sending a SIGTERM to each managed process, waiting
142       die_timeout() seconds to reap each process, and then exit gracefully
143       once all children are reaped, or to abort if all children are not
144       reaped.
145
146   pm_wait
147        instance or export
148        (int pid) pm_wait()
149
150       DESCRIPTION:
151
152       This calls wait() which suspends execution until a child has exited.
153       If the process ID returned by wait corresponds to a managed process,
154       pm_notify() is called with the exit status of that process.  pm_wait()
155       returns with the return value of wait().
156
157   pm_write_pid_file
158        instance or export
159        () pm_write_pid_file([string filename])
160
161       DESCRIPTION:
162
163       Writes current process ID to optionally specified file.  If no filename
164       is specified, it uses the value of the "pid_fname" parameter.
165
166   pm_remove_pid_file
167        instance or export
168        () pm_remove_pid_file()
169
170       DESCRIPTION:
171
172       Removes optionally specified file.  If no filename is specified, it
173       uses the value of the "pid_fname" parameter.
174
175   sig_sub
176        instance
177        () sig_sub(string name)
178
179       DESCRIPTION:
180
181       The name of this method is passed to POSIX::sigaction(), and handles
182       signals for the process manager.  If $SIG_CODEREF is set, then the
183       input arguments to this are passed to a call to that.
184
185   sig_manager
186        instance
187        () sig_manager(string name)
188
189       DESCRIPTION:
190
191       Handles signals of the process manager.  Takes as input the name of
192       signal being handled.
193

Handler methods

195   handling_init
196        instance or export
197        () handling_init()
198
199       DESCRIPTION:
200
201   pm_pre_dispatch
202        instance or export
203        () pm_pre_dispatch()
204
205       DESCRIPTION:
206
207   pm_post_dispatch
208        instance or export
209        () pm_post_dispatch()
210
211       DESCRIPTION:
212
213   sig_handler
214        instance or export
215        () sig_handler()
216
217       DESCRIPTION:
218

Common methods and routines

220   self_or_default
221        private global
222        (ProcManager, @args) self_or_default([ ProcManager, ] @args);
223
224       DESCRIPTION:
225
226       This is a helper subroutine to acquire or otherwise create a singleton
227       default object if one is not passed in, e.g., a method call.
228
229   pm_change_process_name
230        instance or export
231        () pm_change_process_name()
232
233       DESCRIPTION:
234
235   pm_received_signal
236        instance or export
237        () pm_received signal()
238
239       DESCRIPTION:
240

parameters

242   pm_parameter
243        instance or export
244        () pm_parameter()
245
246       DESCRIPTION:
247
248   n_processes
249   no_signals
250   pid_fname
251   die_timeout
252   role
253   start_delay
254       DESCRIPTION:
255

notification and death

257   pm_warn
258        instance or export
259        () pm_warn()
260
261       DESCRIPTION:
262
263   pm_notify
264        instance or export
265        () pm_notify()
266
267       DESCRIPTION:
268
269   pm_exit
270        instance or export
271        () pm_exit(string msg[, int exit_status])
272
273       DESCRIPTION:
274
275   pm_abort
276        instance or export
277        () pm_abort(string msg[, int exit_status])
278
279       DESCRIPTION:
280

BUGS

282       No known bugs, but this does not mean no bugs exist.
283

SEE ALSO

285       FCGI.
286

MAINTAINER

288       Gareth Kirwan <gbjk@thermeon.com>
289

AUTHOR

291       James E Jurach Jr.
292
294        FCGI-ProcManager - A Perl FCGI Process Manager
295        Copyright (c) 2000, FundsXpress Financial Network, Inc.
296
297        This library is free software; you can redistribute it and/or
298        modify it under the terms of the GNU Lesser General Public
299        License as published by the Free Software Foundation; either
300        version 2 of the License, or (at your option) any later version.
301
302        BECAUSE THIS LIBRARY IS LICENSED FREE OF CHARGE, THIS LIBRARY IS
303        BEING PROVIDED "AS IS WITH ALL FAULTS," WITHOUT ANY WARRANTIES
304        OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT
305        LIMITATION, ANY IMPLIED WARRANTIES OF TITLE, NONINFRINGEMENT,
306        MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND THE
307        ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY,
308        AND EFFORT IS WITH THE YOU.  See the GNU Lesser General Public
309        License for more details.
310
311        You should have received a copy of the GNU Lesser General Public
312        License along with this library; if not, write to the Free Software
313        Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
314
315
316
317perl v5.34.0                      2022-01-21              FCGI::ProcManager(3)
Impressum