FCGI::...Manager(3pm)

💖 FCGI::ProcManager 💖

okay bestie, pull up a chair, because this is the FCGI::...Manager(3pm) page and it's literally the manual for FCGI::ProcManager — functions for managing FastCGI applications. no cap, it's giving sysadmin-but-make-it-cute. let's go 🦋

---

✨ NAME ✨

FCGI::ProcManager — functions for managing FastCGI applications. that's the whole vibe. 🎀

---

✨ SYNOPSIS ✨

so there's two ways to do this, and both are valid, because we contain multitudes 💅

Object-oriented style, aka the main character route:

# 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();
}

and this style is also supported, for when you simply cannot with objects:

# 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();
}

---

✨ DESCRIPTION ✨

so FCGI::ProcManager is here 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 UNIX kernel process management. obsessed with that, fr. 🧚

the process manager should be invoked before the caller's request loop. like, before. do not skip this part bestie.

the primary routine, pm_manage, enters a loop in which it maintains a number of FastCGI servers (via fork(2)), and which reaps those servers when they die (via wait(2)). iconic behaviour honestly.

pm_manage provides two hooks:

• managing_init — called just before the manager enters the manager loop.
• handling_init — called just before a server is returns from pm_manage

it is necessary for the caller, when implementing its request loop, to insert a call to pm_pre_dispatch at the top of the loop, and then pm_post_dispatch at the end of the loop. top and bottom, bestie. sandwich the request. 🥪

🌈 Signal Handling 🌈

FCGI::ProcManager attempts to do the right thing for proper shutdowns now. character development!! 💜

• when it receives a SIGHUP, it sends a SIGTERM to each of its children, and then resumes its normal operations.
• when it receives a SIGTERM, it sends a SIGTERM to each of its children, sets an alarm(3) "die timeout" 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 "die timeout" occurs, the process manager sends a SIGKILL to each of the remaining children, and exists with return status 1.

⚠️ in order to get FastCGI servers to exit upon receiving a signal, it is necessary to use its FAIL_ACCEPT_ON_INTR. See FCGI's description of FAIL_ACCEPT_ON_INTR. 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 FCGI.pm. (>= 0.71_02). yes really. i know. 😭

otherwise, if you don't, there is a loop around accept(2) which prevents os_unix.c OS_Accept() from returning the necessary error when FastCGI servers blocking on accept(2) receive the SIGTERM or SIGHUP.

FCGI::ProcManager uses POSIX::sigaction() to override the default SA_RESTART policy used for perl's %SIG behavior. Specifically:

• the process manager never uses SA_RESTART
• the child FastCGI servers turn off SA_RESTART around the accept(2) loop, but reinstate it otherwise.

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. slay! 👑

---

✨ METHODS ✨

new

class or instance
(ProcManager) new([hash parameters])

constructs a new process manager. takes an option hash of initial parameter values, and assigns these to the constructed object HASH, overriding any default values. the default parameter values currently are:

role         => manager
start_delay  => 0
die_timeout  => 60
pm_title => 'perl-fcgi-pm'

🦋 Manager methods 🦋

pm_manage

instance or export
(int) pm_manage([hash parameters])

DESCRIPTION:

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.

if n_processes < 1, the managing section is subverted, and only the handling sequence is executed. noted!! 📝

either returns the return value of pm_die() and/or pm_abort() (which will not ever return in general), or returns 1 to the calling script to begin handling requests.

managing_init

instance
() managing_init()

DESCRIPTION:

overrideable method which initializes a process manager. in order to handle signals, manage the PID file, and change the process name properly, any method which overrides this should call SUPER::managing_init(). do not ghost the superclass bestie, that's not the vibe. 🫶

pm_die

instance or export
() pm_die(string msg[, int exit_status])

DESCRIPTION:

this method is called when a process manager receives a notification to shut itself down. pm_die() attempts to shutdown the process manager gently, sending a SIGTERM to each managed process, waiting die_timeout() seconds to reap each process, and then exit gracefully once all children are reaped, or to abort if all children are not reaped.

pm_wait

instance or export
(int pid) pm_wait()

DESCRIPTION:

this calls wait() which suspends execution until a child has exited. if the process ID returned by wait corresponds to a managed process, pm_notify() is called with the exit status of that process. pm_wait() returns with the return value of wait().

pm_write_pid_file

instance or export
() pm_write_pid_file([string filename])

DESCRIPTION:

writes current process ID to optionally specified file. if no filename is specified, it uses the value of the pid_fname parameter.

pm_remove_pid_file

instance or export
() pm_remove_pid_file()

DESCRIPTION:

removes optionally specified file. if no filename is specified, it uses the value of the pid_fname parameter.

sig_sub

instance
() sig_sub(string name)

DESCRIPTION:

the name of this method is passed to POSIX::sigaction(), and handles signals for the process manager. if $SIG_CODEREF is set, then the input arguments to this are passed to a call to that.

sig_manager

instance
() sig_manager(string name)

DESCRIPTION:

handles signals of the process manager. takes as input the name of signal being handled.

🌸 Handler methods 🌸

handling_init

instance or export
() handling_init()

DESCRIPTION:

(the manpage leaves this one blank, so i'm leaving it blank too — no invented deets around here, that's the rule 💅)

pm_pre_dispatch

instance or export
() pm_pre_dispatch()

DESCRIPTION:

(also blank in the original. mysterious. ethereal. 🧚)

pm_post_dispatch

instance or export
() pm_post_dispatch()

DESCRIPTION:

(blank again bestie, it's giving minimalist.)

sig_handler

instance or export
() sig_handler()

DESCRIPTION:

(you guessed it — blank. the void stares back. 💀)

⭐ Common methods and routines ⭐

self_or_default

private global
(ProcManager, @args) self_or_default([ ProcManager, ] @args);

DESCRIPTION:

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.

pm_change_process_name

instance or export
() pm_change_process_name()

DESCRIPTION:

(blank in the original, so no yapping from me ✨)

pm_received_signal

instance or export
() pm_received signal()

DESCRIPTION:

(blank ✨ and yes, the signature really is typeset like pm_received signal() up there — not my typo, i'm just the messenger 🎀)

💜 parameters 💜

pm_parameter

instance or export
() pm_parameter()

DESCRIPTION:

(blank, bestie. truly a moment of silence.)

n_processes

no_signals

pid_fname

die_timeout

role

start_delay

DESCRIPTION:

(that's the whole list — n_processes, no_signals, pid_fname, die_timeout, role, start_delay — and the original gives them a single shared, completely empty DESCRIPTION. so: no extra lore available, i don't make the rules 🙈)

🍓 notification and death 🍓

pm_warn

instance or export
() pm_warn()

DESCRIPTION:

(blank)

pm_notify

instance or export
() pm_notify()

DESCRIPTION:

(blank)

pm_exit

instance or export
() pm_exit(string msg[, int exit_status])

DESCRIPTION:

(blank)

pm_abort

instance or export
() pm_abort(string msg[, int exit_status])

DESCRIPTION:

(blank)

---

✨ BUGS ✨

no known bugs, but this does not mean no bugs exist. which is honestly the most terrifying sentence in this entire document. 😭

---

✨ SEE ALSO ✨

FCGI.

---

✨ MAINTAINER ✨

Gareth Kirwan <gbjk@thermeon.com>

---

✨ AUTHOR ✨

James E Jurach Jr.

---

✨ COPYRIGHT ✨

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.

⚠️ real talk bestie: 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. it's giving "go get your license" energy and honestly? valid. 📜

---

and that's the whole page!! 🎉 this gorgeous little doc is perl v5.36.0, dated 2022-10-13, and it lives under the FCGI::...Manager(3pm) name. thank you for coming to my ted talk, go manage some processes responsibly, mwah 💖🦋✨