1ProcManager(3) User Contributed Perl Documentation ProcManager(3)
2
6 FCGI::ProcManager - functions for managing FastCGI applications.
7
9 {
10 # In Object-oriented style.
11 use CGI::Fast;
12 use FCGI::ProcManager;
13 my $proc_manager = FCGI::ProcManager->new({ 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 # 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
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 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 "pm_manage" provides too hooks:
45 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 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 Signal Handling
54 FCGI::ProcManager attempts to do the right thing for proper shutdowns
55 now.
56 When it receives a SIGHUP, it sends a SIGTERM to each of its children,
58 and then resumes its normal operations.
59 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 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.pm's description of
69 FAIL_ACCEPT_ON_INTR. Unfortunately, if you want/need to use CGI::Fast,
70 it appears currently necessary to modify your installation of FCGI.pm,
71 with something like the following:
72 -*- patch -*-
74 --- FCGI.pm 2001/03/09 01:44:00 1.1.1.3
75 +++ FCGI.pm 2001/03/09 01:47:32 1.2
76 @@ -24,7 +24,7 @@
77 *FAIL_ACCEPT_ON_INTR = sub() { 1 };
78 sub Request(;***$$$) {
80 - my @defaults = (\*STDIN, \*STDOUT, \*STDERR, \%ENV, 0, 0);
81 + my @defaults = (\*STDIN, \*STDOUT, \*STDERR, \%ENV, 0, FAIL_ACCEPT_ON_INTR());
82 splice @defaults,0,@_,@_;
83 RequestX(@defaults);
84 }
85 -*- end patch -*-
86 Otherwise, if you don't, there is a loop around accept(2) which
88 prevents os_unix.c OS_Accept() from returning the necessary error when
89 FastCGI servers blocking on accept(2) receive the SIGTERM or SIGHUP.
90 FCGI::ProcManager uses POSIX::sigaction() to override the default
92 SA_RESTART policy used for perl's %SIG behavior. Specifically, the
93 process manager never uses SA_RESTART, while the child FastCGI servers
94 turn off SA_RESTART around the accept(2) loop, but re-enstate it
95 otherwise.
96 The desired (and implemented) effect is to give a request as big a
98 chance as possible to succeed and to delay their exits until after
99 their request, while allowing the FastCGI servers waiting for new
100 requests to die right away.
101
103 new
104 class or instance
105 (ProcManager) new([hash parameters])
106 Constructs a new process manager. Takes an option has of initial
108 parameter values, and assigns these to the constructed object HASH,
109 overriding any default values. The default parameter values currently
110 are:
111 role => manager
113 start_delay => 0
114 die_timeout => 60
115 pm_title => 'perl-fcgi-pm'
116
118 pm_manage
119 instance or export
120 (int) pm_manage([hash parameters])
121 DESCRIPTION:
123 When this is called by a FastCGI script to manage application servers.
125 It defines a sequence of instructions for a process to enter this
126 method and begin forking off and managing those handlers, and it
127 defines a sequence of instructions to intialize those handlers.
128 If n_processes < 1, the managing section is subverted, and only the
130 handling sequence is executed.
131 Either returns the return value of pm_die() and/or pm_abort() (which
133 will not ever return in general), or returns 1 to the calling script to
134 begin handling requests.
135 managing_init
137 instance
138 () managing_init()
139 DESCRIPTION:
141 Overrideable method which initializes a process manager. In order to
143 handle signals, manage the PID file, and change the process name
144 properly, any method which overrides this should call
145 SUPER::managing_init().
146 pm_die
148 instance or export
149 () pm_die(string msg[, int exit_status])
150 DESCRIPTION:
152 This method is called when a process manager receives a notification to
154 shut itself down. pm_die() attempts to shutdown the process manager
155 gently, sending a SIGTERM to each managed process, waiting
156 die_timeout() seconds to reap each process, and then exit gracefully
157 once all children are reaped, or to abort if all children are not
158 reaped.
159 pm_wait
161 instance or export
162 (int pid) pm_wait()
163 DESCRIPTION:
165 This calls wait() which suspends execution until a child has exited.
167 If the process ID returned by wait corresponds to a managed process,
168 pm_notify() is called with the exit status of that process. pm_wait()
169 returns with the return value of wait().
170 pm_write_pid_file
172 instance or export
173 () pm_write_pid_file([string filename])
174 DESCRIPTION:
176 Writes current process ID to optionally specified file. If no filename
178 is specified, it uses the value of the "pid_fname" parameter.
179 pm_remove_pid_file
181 instance or export
182 () pm_remove_pid_file()
183 DESCRIPTION:
185 Removes optionally specified file. If no filename is specified, it
187 uses the value of the "pid_fname" parameter.
188 sig_sub
190 instance
191 () sig_sub(string name)
192 DESCRIPTION:
194 The name of this method is passed to POSIX::sigaction(), and handles
196 signals for the process manager. If $SIG_CODEREF is set, then the
197 input arguments to this are passed to a call to that.
198 sig_manager
200 instance
201 () sig_manager(string name)
202 DESCRIPTION:
204 Handles signals of the process manager. Takes as input the name of
206 signal being handled.
207
209 handling_init
210 instance or export
211 () handling_init()
212 DESCRIPTION:
214 pm_pre_dispatch
216 instance or export
217 () pm_pre_dispatch()
218 DESCRIPTION:
220 pm_post_dispatch
222 instance or export
223 () pm_post_dispatch()
224 DESCRIPTION:
226 sig_handler
228 instance or export
229 () sig_handler()
230 DESCRIPTION:
232
234 self_or_default
235 private global
236 (ProcManager, @args) self_or_default([ ProcManager, ] @args);
237 DESCRIPTION:
239 This is a helper subroutine to acquire or otherwise create a singleton
241 default object if one is not passed in, e.g., a method call.
242 pm_change_process_name
244 instance or export
245 () pm_change_process_name()
246 DESCRIPTION:
248 pm_received_signal
250 instance or export
251 () pm_received signal()
252 DESCRIPTION:
254
256 pm_parameter
257 instance or export
258 () pm_parameter()
259 DESCRIPTION:
261 n_processes
263 no_signals
264 pid_fname
265 die_timeout
266 role
267 start_delay
268 DESCRIPTION:
269
271 pm_warn
272 instance or export
273 () pm_warn()
274 DESCRIPTION:
276 pm_notify
278 instance or export
279 () pm_notify()
280 DESCRIPTION:
282 pm_exit
284 instance or export
285 () pm_exit(string msg[, int exit_status])
286 DESCRIPTION:
288 pm_abort
290 instance or export
291 () pm_abort(string msg[, int exit_status])
292 DESCRIPTION:
294
296 No known bugs, but this does not mean no bugs exist.
297
299 FCGI.
300
302 Gareth Kirwan <gbjk@thermeon.com>
303
305 James E Jurach Jr.
306
308 FCGI-ProcManager - A Perl FCGI Process Manager
309 Copyright (c) 2000, FundsXpress Financial Network, Inc.
310 This library is free software; you can redistribute it and/or
312 modify it under the terms of the GNU Lesser General Public
313 License as published by the Free Software Foundation; either
314 version 2 of the License, or (at your option) any later version.
315 BECAUSE THIS LIBRARY IS LICENSED FREE OF CHARGE, THIS LIBRARY IS
317 BEING PROVIDED "AS IS WITH ALL FAULTS," WITHOUT ANY WARRANTIES
318 OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT
319 LIMITATION, ANY IMPLIED WARRANTIES OF TITLE, NONINFRINGEMENT,
320 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND THE
321 ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY,
322 AND EFFORT IS WITH THE YOU. See the GNU Lesser General Public
323 License for more details.
324 You should have received a copy of the GNU Lesser General Public
326 License along with this library; if not, write to the Free Software
327 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
328perl v5.12.0 2009-07-22 ProcManager(3)