local-lib5/man/man3/FCGI::ProcManager.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "ProcManager 3"
 127 .TH ProcManager 3 "2009-07-22" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 .Vb 1
 134 \& FCGI::ProcManager \- functions for managing FastCGI applications.
 135 .Ve
 136 .SH "SYNOPSIS"
 137 .IX Header "SYNOPSIS"
 138 {
 139  # In Object-oriented style.
 140  use CGI::Fast;
 141  use FCGI::ProcManager;
 142  my \f(CW$proc_manager\fR = FCGI::ProcManager\->new({
 143         n_processes => 10
 144  });
 145  \f(CW$proc_manager\fR\->\fIpm_manage()\fR;
 146  while (my \f(CW$cgi\fR = CGI::Fast\->\fInew()\fR) {
 147    \f(CW$proc_manager\fR\->\fIpm_pre_dispatch()\fR;
 148    # ... handle the request here ...
 149    \f(CW$proc_manager\fR\->\fIpm_post_dispatch()\fR;
 150  }
 151 .PP
 152 .Vb 10
 153 \& # This style is also supported:
 154 \& use CGI::Fast;
 155 \& use FCGI::ProcManager qw(pm_manage pm_pre_dispatch
 156 \&                          pm_post_dispatch);
 157 \& pm_manage( n_processes => 10 );
 158 \& while (my $cgi = CGI::Fast\->new()) {
 159 \&   pm_pre_dispatch();
 160 \&   #...
 161 \&   pm_post_dispatch();
 162 \& }
 163 .Ve
 164 .SH "DESCRIPTION"
 165 .IX Header "DESCRIPTION"
 166 FCGI::ProcManager is used to serve as a FastCGI process manager.  By
 167 re-implementing it in perl, developers can more finely tune performance in
 168 their web applications, and can take advantage of copy-on-write semantics
 169 prevalent in \s-1UNIX\s0 kernel process management.  The process manager should
 170 be invoked before the caller''s request loop
 171 .PP
 172 The primary routine, \f(CW\*(C`pm_manage\*(C'\fR, enters a loop in which it maintains a
 173 number of FastCGI servers (via \fIfork\fR\|(2)), and which reaps those servers
 174 when they die (via \fIwait\fR\|(2)).
 175 .PP
 176 \&\f(CW\*(C`pm_manage\*(C'\fR provides too hooks:
 177 .PP
 178 .Vb 2
 179 \& C<managing_init> \- called just before the manager enters the manager loop.
 180 \& C<handling_init> \- called just before a server is returns from C<pm_manage>
 181 .Ve
 182 .PP
 183 It is necessary for the caller, when implementing its request loop, to
 184 insert a call to \f(CW\*(C`pm_pre_dispatch\*(C'\fR at the top of the loop, and then
 185 7\f(CW\*(C`pm_post_dispatch\*(C'\fR at the end of the loop.
 186 .SS "Signal Handling"
 187 .IX Subsection "Signal Handling"
 188 FCGI::ProcManager attempts to do the right thing for proper shutdowns now.
 189 .PP
 190 When it receives a \s-1SIGHUP\s0, it sends a \s-1SIGTERM\s0 to each of its children, and
 191 then resumes its normal operations.
 192 .PP
 193 When it receives a \s-1SIGTERM\s0, it sends a \s-1SIGTERM\s0 to each of its children, sets
 194 an \fIalarm\fR\|(3) \*(L"die timeout\*(R" handler, and waits for each of its children to
 195 die.  If all children die before this timeout, process manager exits with
 196 return status 0.  If all children do not die by the time the \*(L"die timeout\*(R"
 197 occurs, the process manager sends a \s-1SIGKILL\s0 to each of the remaining
 198 children, and exists with return status 1.
 199 .PP
 200 In order to get FastCGI servers to exit upon receiving a signal, it is
 201 necessary to use its \s-1FAIL_ACCEPT_ON_INTR\s0.  See \s-1FCGI\s0.pm's description of
 202 \&\s-1FAIL_ACCEPT_ON_INTR\s0.  Unfortunately, if you want/need to use CGI::Fast, it
 203 appears currently necessary to modify your installation of \s-1FCGI\s0.pm, with
 204 something like the following:
 205 .PP
 206 .Vb 5
 207 \& \-*\- patch \-*\-
 208 \& \-\-\- FCGI.pm     2001/03/09 01:44:00     1.1.1.3
 209 \& +++ FCGI.pm     2001/03/09 01:47:32     1.2
 210 \& @@ \-24,7 +24,7 @@
 211 \&  *FAIL_ACCEPT_ON_INTR = sub() { 1 };
 212 \&
 213 \&  sub Request(;***$$$) {
 214 \& \-    my @defaults = (\e*STDIN, \e*STDOUT, \e*STDERR, \e%ENV, 0, 0);
 215 \& +    my @defaults = (\e*STDIN, \e*STDOUT, \e*STDERR, \e%ENV, 0, FAIL_ACCEPT_ON_INTR());
 216 \&      splice @defaults,0,@_,@_;
 217 \&      RequestX(@defaults);
 218 \&  }
 219 \& \-*\- end patch \-*\-
 220 .Ve
 221 .PP
 222 Otherwise, if you don't, there is a loop around \fIaccept\fR\|(2) which prevents
 223 os_unix.c \fIOS_Accept()\fR from returning the necessary error when FastCGI
 224 servers blocking on \fIaccept\fR\|(2) receive the \s-1SIGTERM\s0 or \s-1SIGHUP\s0.
 225 .PP
 226 FCGI::ProcManager uses \fIPOSIX::sigaction()\fR to override the default \s-1SA_RESTART\s0
 227 policy used for perl's \f(CW%SIG\fR behavior.  Specifically, the process manager
 228 never uses \s-1SA_RESTART\s0, while the child FastCGI servers turn off \s-1SA_RESTART\s0
 229 around the \fIaccept\fR\|(2) loop, but re-enstate it otherwise.
 230 .PP
 231 The desired (and implemented) effect is to give a request as big a chance as
 232 possible to succeed and to delay their exits until after their request,
 233 while allowing the FastCGI servers waiting for new requests to die right
 234 away.
 235 .SH "METHODS"
 236 .IX Header "METHODS"
 237 .SS "new"
 238 .IX Subsection "new"
 239 .Vb 2
 240 \& class or instance
 241 \& (ProcManager) new([hash parameters])
 242 .Ve
 243 .PP
 244 Constructs a new process manager.  Takes an option has of initial parameter
 245 values, and assigns these to the constructed object \s-1HASH\s0, overriding any
 246 default values.  The default parameter values currently are:
 247 .PP
 248 .Vb 4
 249 \& role         => manager
 250 \& start_delay  => 0
 251 \& die_timeout  => 60
 252 \& pm_title => \*(Aqperl\-fcgi\-pm\*(Aq
 253 .Ve
 254 .SH "Manager methods"
 255 .IX Header "Manager methods"
 256 .SS "pm_manage"
 257 .IX Subsection "pm_manage"
 258 .Vb 2
 259 \& instance or export
 260 \& (int) pm_manage([hash parameters])
 261 .Ve
 262 .PP
 263 \&\s-1DESCRIPTION:\s0
 264 .PP
 265 When this is called by a FastCGI script to manage application servers.  It
 266 defines a sequence of instructions for a process to enter this method and
 267 begin forking off and managing those handlers, and it defines a sequence of
 268 instructions to intialize those handlers.
 269 .PP
 270 If n_processes < 1, the managing section is subverted, and only the
 271 handling sequence is executed.
 272 .PP
 273 Either returns the return value of \fIpm_die()\fR and/or \fIpm_abort()\fR (which will
 274 not ever return in general), or returns 1 to the calling script to begin
 275 handling requests.
 276 .SS "managing_init"
 277 .IX Subsection "managing_init"
 278 .Vb 2
 279 \& instance
 280 \& () managing_init()
 281 .Ve
 282 .PP
 283 \&\s-1DESCRIPTION:\s0
 284 .PP
 285 Overrideable method which initializes a process manager.  In order to
 286 handle signals, manage the \s-1PID\s0 file, and change the process name properly,
 287 any method which overrides this should call \fISUPER::managing_init()\fR.
 288 .SS "pm_die"
 289 .IX Subsection "pm_die"
 290 .Vb 2
 291 \& instance or export
 292 \& () pm_die(string msg[, int exit_status])
 293 .Ve
 294 .PP
 295 \&\s-1DESCRIPTION:\s0
 296 .PP
 297 This method is called when a process manager receives a notification to
 298 shut itself down.  \fIpm_die()\fR attempts to shutdown the process manager
 299 gently, sending a \s-1SIGTERM\s0 to each managed process, waiting \fIdie_timeout()\fR
 300 seconds to reap each process, and then exit gracefully once all children
 301 are reaped, or to abort if all children are not reaped.
 302 .SS "pm_wait"
 303 .IX Subsection "pm_wait"
 304 .Vb 2
 305 \& instance or export
 306 \& (int pid) pm_wait()
 307 .Ve
 308 .PP
 309 \&\s-1DESCRIPTION:\s0
 310 .PP
 311 This calls \fIwait()\fR which suspends execution until a child has exited.
 312 If the process \s-1ID\s0 returned by wait corresponds to a managed process,
 313 \&\fIpm_notify()\fR is called with the exit status of that process.
 314 \&\fIpm_wait()\fR returns with the return value of \fIwait()\fR.
 315 .SS "pm_write_pid_file"
 316 .IX Subsection "pm_write_pid_file"
 317 .Vb 2
 318 \& instance or export
 319 \& () pm_write_pid_file([string filename])
 320 .Ve
 321 .PP
 322 \&\s-1DESCRIPTION:\s0
 323 .PP
 324 Writes current process \s-1ID\s0 to optionally specified file.  If no filename is
 325 specified, it uses the value of the \f(CW\*(C`pid_fname\*(C'\fR parameter.
 326 .SS "pm_remove_pid_file"
 327 .IX Subsection "pm_remove_pid_file"
 328 .Vb 2
 329 \& instance or export
 330 \& () pm_remove_pid_file()
 331 .Ve
 332 .PP
 333 \&\s-1DESCRIPTION:\s0
 334 .PP
 335 Removes optionally specified file.  If no filename is specified, it uses
 336 the value of the \f(CW\*(C`pid_fname\*(C'\fR parameter.
 337 .SS "sig_sub"
 338 .IX Subsection "sig_sub"
 339 .Vb 2
 340 \& instance
 341 \& () sig_sub(string name)
 342 .Ve
 343 .PP
 344 \&\s-1DESCRIPTION:\s0
 345 .PP
 346 The name of this method is passed to \fIPOSIX::sigaction()\fR, and handles signals
 347 for the process manager.  If \f(CW$SIG_CODEREF\fR is set, then the input arguments
 348 to this are passed to a call to that.
 349 .SS "sig_manager"
 350 .IX Subsection "sig_manager"
 351 .Vb 2
 352 \& instance
 353 \& () sig_manager(string name)
 354 .Ve
 355 .PP
 356 \&\s-1DESCRIPTION:\s0
 357 .PP
 358 Handles signals of the process manager.  Takes as input the name of signal
 359 being handled.
 360 .SH "Handler methods"
 361 .IX Header "Handler methods"
 362 .SS "handling_init"
 363 .IX Subsection "handling_init"
 364 .Vb 2
 365 \& instance or export
 366 \& () handling_init()
 367 .Ve
 368 .PP
 369 \&\s-1DESCRIPTION:\s0
 370 .SS "pm_pre_dispatch"
 371 .IX Subsection "pm_pre_dispatch"
 372 .Vb 2
 373 \& instance or export
 374 \& () pm_pre_dispatch()
 375 .Ve
 376 .PP
 377 \&\s-1DESCRIPTION:\s0
 378 .SS "pm_post_dispatch"
 379 .IX Subsection "pm_post_dispatch"
 380 .Vb 2
 381 \& instance or export
 382 \& () pm_post_dispatch()
 383 .Ve
 384 .PP
 385 \&\s-1DESCRIPTION:\s0
 386 .SS "sig_handler"
 387 .IX Subsection "sig_handler"
 388 .Vb 2
 389 \& instance or export
 390 \& () sig_handler()
 391 .Ve
 392 .PP
 393 \&\s-1DESCRIPTION:\s0
 394 .SH "Common methods and routines"
 395 .IX Header "Common methods and routines"
 396 .SS "self_or_default"
 397 .IX Subsection "self_or_default"
 398 .Vb 2
 399 \& private global
 400 \& (ProcManager, @args) self_or_default([ ProcManager, ] @args);
 401 .Ve
 402 .PP
 403 \&\s-1DESCRIPTION:\s0
 404 .PP
 405 This is a helper subroutine to acquire or otherwise create a singleton
 406 default object if one is not passed in, e.g., a method call.
 407 .SS "pm_change_process_name"
 408 .IX Subsection "pm_change_process_name"
 409 .Vb 2
 410 \& instance or export
 411 \& () pm_change_process_name()
 412 .Ve
 413 .PP
 414 \&\s-1DESCRIPTION:\s0
 415 .SS "pm_received_signal"
 416 .IX Subsection "pm_received_signal"
 417 .Vb 2
 418 \& instance or export
 419 \& () pm_received signal()
 420 .Ve
 421 .PP
 422 \&\s-1DESCRIPTION:\s0
 423 .SH "parameters"
 424 .IX Header "parameters"
 425 .SS "pm_parameter"
 426 .IX Subsection "pm_parameter"
 427 .Vb 2
 428 \& instance or export
 429 \& () pm_parameter()
 430 .Ve
 431 .PP
 432 \&\s-1DESCRIPTION:\s0
 433 .SS "n_processes"
 434 .IX Subsection "n_processes"
 435 .SS "no_signals"
 436 .IX Subsection "no_signals"
 437 .SS "pid_fname"
 438 .IX Subsection "pid_fname"
 439 .SS "die_timeout"
 440 .IX Subsection "die_timeout"
 441 .SS "role"
 442 .IX Subsection "role"
 443 .SS "start_delay"
 444 .IX Subsection "start_delay"
 445 \&\s-1DESCRIPTION:\s0
 446 .SH "notification and death"
 447 .IX Header "notification and death"
 448 .SS "pm_warn"
 449 .IX Subsection "pm_warn"
 450 .Vb 2
 451 \& instance or export
 452 \& () pm_warn()
 453 .Ve
 454 .PP
 455 \&\s-1DESCRIPTION:\s0
 456 .SS "pm_notify"
 457 .IX Subsection "pm_notify"
 458 .Vb 2
 459 \& instance or export
 460 \& () pm_notify()
 461 .Ve
 462 .PP
 463 \&\s-1DESCRIPTION:\s0
 464 .SS "pm_exit"
 465 .IX Subsection "pm_exit"
 466 .Vb 2
 467 \& instance or export
 468 \& () pm_exit(string msg[, int exit_status])
 469 .Ve
 470 .PP
 471 \&\s-1DESCRIPTION:\s0
 472 .SS "pm_abort"
 473 .IX Subsection "pm_abort"
 474 .Vb 2
 475 \& instance or export
 476 \& () pm_abort(string msg[, int exit_status])
 477 .Ve
 478 .PP
 479 \&\s-1DESCRIPTION:\s0
 480 .SH "BUGS"
 481 .IX Header "BUGS"
 482 No known bugs, but this does not mean no bugs exist.
 483 .SH "SEE ALSO"
 484 .IX Header "SEE ALSO"
 485 \&\s-1FCGI\s0.
 486 .SH "MAINTAINER"
 487 .IX Header "MAINTAINER"
 488 Gareth Kirwan <gbjk@thermeon.com>
 489 .SH "AUTHOR"
 490 .IX Header "AUTHOR"
 491 James E Jurach Jr.
 492 .SH "COPYRIGHT"
 493 .IX Header "COPYRIGHT"
 494 .Vb 2
 495 \& FCGI\-ProcManager \- A Perl FCGI Process Manager
 496 \& Copyright (c) 2000, FundsXpress Financial Network, Inc.
 497 \&
 498 \& This library is free software; you can redistribute it and/or
 499 \& modify it under the terms of the GNU Lesser General Public
 500 \& License as published by the Free Software Foundation; either
 501 \& version 2 of the License, or (at your option) any later version.
 502 \&
 503 \& BECAUSE THIS LIBRARY IS LICENSED FREE OF CHARGE, THIS LIBRARY IS
 504 \& BEING PROVIDED "AS IS WITH ALL FAULTS," WITHOUT ANY WARRANTIES
 505 \& OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT
 506 \& LIMITATION, ANY IMPLIED WARRANTIES OF TITLE, NONINFRINGEMENT,
 507 \& MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND THE
 508 \& ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY,
 509 \& AND EFFORT IS WITH THE YOU.  See the GNU Lesser General Public
 510 \& License for more details.
 511 \&
 512 \& You should have received a copy of the GNU Lesser General Public
 513 \& License along with this library; if not, write to the Free Software
 514 \& Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111\-1307  USA
 515 .Ve