View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Peter Vereshagin > FCGI-Spawn > FCGI::Spawn



Annotate this POD


Open  1
View/Report Bugs
Module Version: 0.16.7   Source  


 FCGI::Spawn - FastCGI server for CGI-like applications effective multiprocessing


Minimum unrecommended way to illustrate it working:


Never put this in production use. The fcgi_spawn script supplied should care about sadly mandatory whistles and bells, at least the security is a king in sight of this:

FCGI::Spawn code should be run as its own user id, and the web server should be configured to request its FastCGI; in the case the local socket file is used, the web server should have the read and write permissions on it, the default name is /tmp/spawner.sock. Consider about sock_chmod/sock_chown parameters for this, too.

In the case if you request via TCP care should be taken on network security like DMZ/VPN/firewalls setup instead of sock_* parameters.

About the ready to run applications compatibility refer to fcgi_spawn docs.

Every other thing is explained in FCGI::ProcManager docs.


The overall idea is to make Perl server-side scripts as convinient for newbies and server administrators as PHP in FastCGI mode.

FCGI::Spawn is used to serve as a FastCGI process manager. Besides the features the FCGI::ProcManager posess itself, the FCGI::Spawn is targeted as web server admin understandable instance for building the own fastcgi server with copy-on-write memory sharing among forks and with single input parameters like the limits on the number of processes and maximum requests per fork.

Another thing to mention is that it is able to execute any file pointed by Web server ( FastCGI requester ). So we have the daemon that is hot ready for hosting providing :-)

The definitive care is taken in FCGI::Spawn on security. Besides the inode settings on local UNIX socket taken as input parameter, it is aware to avoid hosting users from changing the max_requests parameter meant correspondent to MaxRequests Apache's forked MPM parameter, and the respective current requests counter value as well.

The aforementioned max_requests parameter takes also care about the performance to avoid forks' memory leaks to consume all the RAM accounted on your hardware.

For shared hosting it is assumed that system administrator controls the process manager daemon script contents with those user hardware consumption limits and executes it with a user's credentials. E. g., the user should be able to send signal to the daemon to initiate graceful restart on his/her demand ( this is yet to be done ) or change the settings those administrator can specifically allow in the daemon starter script without restart ( both of those features are about to be done in the future ).

The call stack lets you set up your own code reference for your scripts execution. Also, feature exists that you can cache some object, like the template or XSLT processor and the recompilation to happen only on the template or xsl file(s) change. Environment variables can be preserved from changing in CGI programs, too. Those features are new in 0.16.

Seeking for convention between high preformance needs that the perl compile cache possess and the convinience of debugging with recompilation on every request that php provides, the stats feature allows you not to recompile the tested source like those of DBI and frameworks but focus the development on your application only, limiting the recompilation with your application(s) namespace(s) only. This may be useful in both development environment to make the recompilation yet faster and on a production host to make the details of code adaptaion to hosting clear in a much less time needed.

Behind the scenes of fcgi_spawn ^

Here are the details for those unsatisfied with fcgi_spawn but trying with FCGI::Spawn anyway:

Why not mod_perl/mod_perl2/mod_fcgid?

Why still mod_perl?

Why not simply FCGI::ProcManager?

Targeted as a library for a single particular application or applications' framework, it takes you to make FCGI::Spawn and fcgi_spawn to obtain the ready to use application-agnostic daemon. It seems to require too much in Perl knowledge from regular system administrator ( same as for audit goes here ), in comparison to php's fastcgi mode. Even with that, it is not as mock as FCGI::Spawn for software developer. You will need to be me if you will need its features, if you are a sysadmin, while I'm the both.


Be sure to have FCGI::ProcManager.


new({hash parameters})

Class method. Constructs a new process manager. Takes an option hash of the sock_name and sock_chown initial parameter values, and passes the entire hash rest to ProcManager's constructor. The parameters are:

Every other parameter is passed "as is" to the FCGI::ProcManager's constructor. Except for addition about the n_processes, which defaults to 5.


Instance method. Performs fork()s by mean of "pm_manage" in FCGI::ProcManager and necessary preparational steps. It is executed, if not yet, by:


Instance method. Fork a new process handling request like that being processed by web server. Performs prepare() if object is not yet prepared.


Instance method. performs user's code execution. Isolates the max_requests, environment and current requests counter values from changing in the user's source. Performs the remembering of the included Perl modules files and the files for the xinc() feature, too.

xinc( '/path/to/file', $ref );

Static function. Returns the previous result of the function referenced by $ref called with file as the argument. Typical usage is the template compilation. Those get recompiled in the case the files were changed. Depends on x_stats and x_stats_policy properties.

If the $ref is an array reference, then it is expected to contain the file names with full path those depend on the followed parameter, file name. This is useful in the case when one template file includes another, and so on. For example, the included file should be the '/path/to/header_or_footer_file' in this case, and the next parameter is [ '/path/to/index_page_template', '/path/to/landing_page_template', ... ] with all the dependent files mentioned. Those dependent files should be xinc()'ed at the end of the every xinc() chain with the code reference.


Static function. Reads the supplied parameter up to "maxlength" bytes size chunked by "readchunk" bufer size and returns string reference. Deprecated and will be removed in future versions.

statnames_to_policy( 'mtime', 'ctime', ... );

Static function. Convert the list of file inode attributes' names checked by stat() builtin to the list of numbers for it described in the perldoc -f stat . In the case if the special word 'all' if met on the list, all the attributes are checked besides 'atime' (8). Also, you can define the order in which the stats are checked to reload perl modules: if the change is met, no further checks of this list for particular module on particular request are made as a decision to recompile that source is already taken. This is the convinient way to define the modules reload policy, the 'stat_policy' object property, among with the need in modules' reload itself by the 'stats' property checked as boolean only.

Thanks, Bugs, TODOs, Pros and Contras ( The Etcetera ) ^

The Inclusion

Arbitrary source file can be included to supply the response in this way:

the built-in: do()


system() or exec()

Useful for debugging. Makes your FastCGI server to act as the simple CGI, except POST input requires complex trick:

 use Time::Local qw/timegm/;
 use POSIX qw/strftime/;

 use IPC::Run3;
 use IPC::Run::SafeHandles;
 use CGI::Util qw/escape/;
 use IO::File;
 use HTTP::Request::Common;

  $spawn->{     callout } = sub{ 
    my( $sn, $fcgi ) = @_; 
    my( $in, $out, $err ) ;
    IF( $env{'REQUEST_METHOD'} eq 'POST' ){
                $in = HTTP::Request::Common::POST( $ENV{'REQUEST_URI'},
                        "Content_Type" => $ENV{'CONTENT_TYPE'},
                        "Content" => [ 
                                map { 
                                                        my $val = $FCGI::Spawn::fcgi->param( $_ );
                                                        if( 'Fh' eq ref $val ){
                                                                $val =  [ ${ $FCGI::Spawn::fcgi->{'.tmpfiles'}->{
                                                                                 ${ $FCGI::Spawn::fcgi->param( $_ ) }
                                                                        }->{name} },
                                                                        $FCGI::Spawn::fcgi->param( $_ ) ,
                                                        $_ => $val 
                $ENV{ CONTENT_LENGTH } = 
                $ENV{ HTTP_CONTENT_LENGTH } = 
                length $in;
    my $pid = run3( $sn, \$in, \$out, \$out ) or die $!;
    print $out;

One also can write the own inclusion code it by self defining the:

your own CODE ref

is able to be set by the "callout" initial parameter and/or "callout" object property.

Bugs and TODOs

Tracked and to be reported at:

Development repository is at: git://

Tested Environments

Nginx everywhere.


Tar.gz at CPAN, as always.

Sourceforge has latest development snapshot:;a=snapshot;h=HEAD;sf=tgz .


Peter Vereshagin <>,

License: same as FCGI::ProcManager's one. More info on FCGI::Spawn at:

syntax highlighting: