1FCGI::ProcManager(3) User Contributed Perl Documentation FCGI::ProcManager(3)
2
6 FCGI::ProcManager - functions for managing FastCGI applications.
7
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 # 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'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 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 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 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
89 new
90 class or instance
91 (ProcManager) new([hash parameters])
92 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 role => manager
99 start_delay => 0
100 die_timeout => 60
101 pm_title => 'perl-fcgi-pm'
102
104 pm_manage
105 instance or export
106 (int) pm_manage([hash parameters])
107 DESCRIPTION:
109 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 If n_processes < 1, the managing section is subverted, and only the
116 handling sequence is executed.
117 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 managing_init
123 instance
124 () managing_init()
125 DESCRIPTION:
127 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 pm_die
134 instance or export
135 () pm_die(string msg[, int exit_status])
136 DESCRIPTION:
138 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 pm_wait
147 instance or export
148 (int pid) pm_wait()
149 DESCRIPTION:
151 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 pm_write_pid_file
158 instance or export
159 () pm_write_pid_file([string filename])
160 DESCRIPTION:
162 Writes current process ID to optionally specified file. If no filename
164 is specified, it uses the value of the "pid_fname" parameter.
165 pm_remove_pid_file
167 instance or export
168 () pm_remove_pid_file()
169 DESCRIPTION:
171 Removes optionally specified file. If no filename is specified, it
173 uses the value of the "pid_fname" parameter.
174 sig_sub
176 instance
177 () sig_sub(string name)
178 DESCRIPTION:
180 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 sig_manager
186 instance
187 () sig_manager(string name)
188 DESCRIPTION:
190 Handles signals of the process manager. Takes as input the name of
192 signal being handled.
193
195 handling_init
196 instance or export
197 () handling_init()
198 DESCRIPTION:
200 pm_pre_dispatch
202 instance or export
203 () pm_pre_dispatch()
204 DESCRIPTION:
206 pm_post_dispatch
208 instance or export
209 () pm_post_dispatch()
210 DESCRIPTION:
212 sig_handler
214 instance or export
215 () sig_handler()
216 DESCRIPTION:
218
220 self_or_default
221 private global
222 (ProcManager, @args) self_or_default([ ProcManager, ] @args);
223 DESCRIPTION:
225 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 pm_change_process_name
230 instance or export
231 () pm_change_process_name()
232 DESCRIPTION:
234 pm_received_signal
236 instance or export
237 () pm_received signal()
238 DESCRIPTION:
240
242 pm_parameter
243 instance or export
244 () pm_parameter()
245 DESCRIPTION:
247 n_processes
249 no_signals
250 pid_fname
251 die_timeout
252 role
253 start_delay
254 DESCRIPTION:
255
257 pm_warn
258 instance or export
259 () pm_warn()
260 DESCRIPTION:
262 pm_notify
264 instance or export
265 () pm_notify()
266 DESCRIPTION:
268 pm_exit
270 instance or export
271 () pm_exit(string msg[, int exit_status])
272 DESCRIPTION:
274 pm_abort
276 instance or export
277 () pm_abort(string msg[, int exit_status])
278 DESCRIPTION:
280
282 No known bugs, but this does not mean no bugs exist.
283
285 FCGI.
286
288 Gareth Kirwan <gbjk@thermeon.com>
289
291 James E Jurach Jr.
292
294 FCGI-ProcManager - A Perl FCGI Process Manager
295 Copyright (c) 2000, FundsXpress Financial Network, Inc.
296 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 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 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
314perl v5.36.0 2023-01-20 FCGI::ProcManager(3)