General Information
-------------------

FCGI-Spawn is the module and daemon both built on top of FCGI-ProcManager
specially for those who need not ( almost ) to write any of his/her own Perl
code. This is the quote of FCGI-ProcManager's explanation:

"FCGI-ProcManager is a process manager for FCGI.  By implementing the
process manager in perl, we can more finely tune FastCGI performance, and
we can take CPU and memory advantages of fast forks and copy-on-write UNIX
process management characteristics."

But unlike this, the FCGI-Spawn is intended for those who need to have the
FCGI daemon with those specifications:
- communicate via given UNIX local socket or TCP port
With UNIX virtualization environments like FreeBSD's jail(8) the socket name and its
desired file mode is the stuff you posess for communication betweeen Web
server ( FastCGI requester ) and FastCGI daemon.
- execute any given file in FastCGI environment;
File name to execute is given with FastCGI protocol, this is what the PHP
does in FastCGI mode;
- fork with the given number of processes and share the compiled modules code
  in common memory areas with copy-on-write facilities;
- limit the number of requests served by the same process;
Same as MaxRequests feature of Apache, especially wanted for Perl in sight of it never
returns allocated memory to OS. On a complex Perl applications, the memory allocation
volume for particular porocess under load can grow up almost unpredictably. ;-)
- reload the Perl module on every request if it has been changed from
the moment it was loaded previously;
- Cache the oobjects liek the compiled templates, automatically recompiling
  them on change.
Useful for debugging and fixing code when put on production hosting, another
obiouse feature of PHP, including FastCGI mode. Absence of such a feature in
other Perl runtime environments can get any Perl newcomer stuck.

There were no quick recipe yet, so i gave myself a try to implement one. :-)

Installation
------------

FCGI-Spawn is expected to compile and run on the same systems range as
FCGI-ProcManager is.

To build,

  perl Makefile.PL
  make all
  make install

Usage
-----

To use CGI.pm in your applications unchanged, you chould apply the supplied
CGI.pm.patch. ON some cases, the application is needed to be patched anyway.
Obviously, it is enough to find CGI->new or 'new CGI' in your code and replace
it with $FCGI::Spawn::fcgi. That's all, folks.

Next, you should decide the what system user you should execute the daemon.
Typically, fcgi_spawn daemon is suitable for most cases, it takes this and some
more parameters on a command line.

Alternately, you may create an executable Perl file expected to being launched
as a daemon by yourself.

Also, you should configure the UNIX system user and/or group to launch the
daemon with. `To configure' I mean both the environment and ulimit(3). And, the
target daemon user should be able to create, and communicate via the socket set
as an argument for FCGI-Spawn instance creation ( the new() method ). And, bear
in mind that the FactCGI requester ( the Web server ) should be able to operate
via this socket, so after creation it should be writable by Web server user. To
satisfy this, I recommend the FCGI-Spawn daemon user be included into the same
group as Web server and socket's permissions should be 0660.

I tried to organize the request loop operations with using the pm_pre_dispatch() / pm_post_dispatch()
but could not keep in frames of its assumptions.
Refer for more usage details to:

  perldoc fcgi_spawn
  perldoc FCGI::Spawn
  perldoc FCGI::ProcManager


Copyright
---------
Copyright (c) 2006-2010, Peter Vereshagin <peter@vereshagin.org>


Disclaimer
----------

This library is free software released "AS IS WITH ALL FAULTS"
and WITHOUT ANY WARRANTIES under the terms of the GNU Lesser
General Public License, Version 2.1, a copy of which can be
found in the "COPYING" file of this distribution.