FREE ESSAY ON MY DYING BRIDE

MY DYING BRIDE

Performance Enhancement 
FastCGI API 
What a FastCGI Application Looks Like 
FastCGI and C 
FastCGI with Perl and Tcl
Installing and Configuring FastCGI 
Incorporating FastCGI Functionality into Apache 
cgi-fcgi
Building the FastCGI Developer's Kit 
Making Perl Fly 
Perl FastCGI Programs
The mod_fastcgi Module 
The AppClass Directive 
Example
Summary
C
FastCGI
FastCGI is a high-performance replacement to the CGI standard. It provides a significant
improvement in performance over the existing CGI interface. In its current
implementation, FastCGI provides many
desirable enhancements that make it a very attractive and competitive alternative to
proprietary technologies for developing Web-based applications. Under many circumstances,
it will be a better choice to
implement FastCGI than to develop a custom server module using Apache's proprietary
server Application Programmer's Interface (API). 
FastCGI is available from http://www.fastcgi.com. (See Figure C.1.) The site is the
official resource to all FastCGI information. It has complete documentation and
whitepapers on
FastCGI. Also nice is a mailing list-a threaded archive that is available through the
Web. 
Figure C.1. The FastCGI home page. 
FastCGI is a proposed open standard; this means that it is not currently widely accepted,
but it has received a warm welcome by many significant people on the Internet who are
responsible for setting the
standards. More than likely, this welcome will turn into acceptance on both free and
commercial Web server offerings, which will help it in becoming blessed from a standard
point of view. 
FastCGI is appealing not only because of its performance enhancements but because the
effort required to migrate existing code is very small. As a bonus, software developed
under this proposed standard
has a high degree of portability. These portability issues help a great deal toward
setting it as a viable candidate to become a standard, especially on installations that
have committed extensive resources to
CGI development. 
FastCGI is not a development environment in terms of having to learn yet another
programming language. In a very simplistic description, FastCGI it is a CGI program that
uses additional libraries, so it does
require that you learn an API. The basic API is tiny, though; one call is all you need to
migrate many of your current programs. 
FastCGI Features
The main features of FastCGI are as follows: 
A huge increase in performance. FastCGI programs continue to live between requests,
making their responsiveness faster and reducing delays due to forking and program
initialization. 
Programming language-independent implementation. Like CGI, you can develop your FastCGI
application with a variety of languages. Currently there are programming libraries for
Perl, C/C++, Tcl,
and Java. Porting existing code to FastCGI is easy, allowing you to easily migrate your
existing code base without having to redo what you have done. 
FastCGI processes are isolated from the Web server core. Much like CGI, FastCGI
applications offer greater security and reliability than developing a similar
functionality as a module using a server
API. 
Server technology separation. There are FastCGI modules for various servers, including
Apache, NCSA, and the Open Market Secure WebServer. For any other server that supports
CGIs, the
cgi-fcgi program, included in the FastCGI distribution, implements the FastCGI
environment. 
Distributed computing support. FastCGI applications can execute on a different host from
the Web server. This allows you to offload FastCGI execution to other application
servers, permitting your
Web server to handle an increased load. FastCGI programs can run on any host that can be
reached over TCP/IP. 
The concept of roles. Traditional CGI programs fall into the responder role; they respond
to some action initiated by a browser and send back some HTML. FastCGI programs can also
perform other
roles, such as a filter or as part of some authentication scheme. This allows for
providing extra functionality that would usually be relegated to a server module. The
currently available FastCGI module
for Apache does not include support for roles other than responder, but this may change
in the future. 
Performance Enhancement
The increase in performance alone would be a good enough reason to migrate CGIs to
FastCGI, especially on loaded servers. This increase in performance is achieved primarily
because FastCGI processes
are persistent. Forking under UNIX is very expensive, and FastCGI addresses this issue by
reusing processes. This saves on the initialization time and can also provide
enhancements when data calculated by
one call to the program can be reused in another transaction. 
Unlike CGIs, which are forked every time there's a request for the functionality, FastCGI
processes are reused. After a request is fulfilled, the process remains, waiting for
additional requests. 
Programs that rely on an interpreter such as Perl or Tcl can gain a great deal from this
technology because the command interpreter will compile the program once, not once per
call. The time required to do
all this pre-run initialization is eliminated. On the program side, this can yield to
enhancements such as establishing a connection with a database or some other process
because the connection only needs to
happen once. Add to this the load to launch the interpreter program, and the savings are
significant. 
What sort of performance gains can you obtain? According to information posted on the
FastCGI Web site, Open Market's tests show the following: 
Request 
Client, Server, and Application Processing Time 
Static File 
21ms + 0.19ms/KB 
FastCGI 
22ms + 0.28ms/KB 
CGI 
59ms + 0.37ms/KB 
Add to this the cumulative time that it takes for an application to establish a TCP/IP
connection to, say, a database. Under CGI, a process will have to initialize each time it
is run. FastCGI can yield a
performance increase of four times the speed of the same program used as CGI. In load
terms, this could mean that your server could potentially handle four times your current
CGI load. However, the level
of enhancement will depend on the source of the bottleneck. If your database server is
the current source of the problem, FastCGI cannot do much about that except reduce the
number of connections that
the database server will need to perform, perhaps giving it more time to process data
instead. 
FastCGI API
The FastCGI API has a handful of calls: 
FCGI_Accept is used to implement the server connectivity and control the running of the
FastCGI program. 
FCGI_Finish gives you control after the FastCGI program has executed, but before running
the next request. 
FCGI_SetExitStatus is used to set the exit status of the request. Most CGI programs don't
return meaningful exit status, so this call is seldom used. 
FCGI_StartFileterData enables you to implement a special type of FastCGI application,
called a filter. Currently the Apache implementation of the FastCGI module doesn't
support roles, of which the
filter type is a member, but this likely will change in the near future. Filters allow
you to implement programs that will convert one data format to another on-the-fly (for
example, TIFF to GIF). 
Data is read and written through the standard input, output, and error streams. FastCGI
also provides macros that map files and streams to native calls supported by your
operating system. 
Like CGI, you can create FastCGI applications in almost any language. However, you are
currently limited to the ports of the library. Currently available are Perl, C/C++, Tcl,
Java, and very soon Python,
which should be available by the time you read this. Also in the works is a multithreaded
C/C++ library that has not been released, but should be available as part of the 1.6
release. The multithreaded library
allows a single application process to handle concurrent requests, which will allow you
to implement things like HTTP-based chat applications. 
Even though FastCGI is not universal, most developers should find themselves at home in
one of the programming languages previously mentioned. As soon as FastCGI gains more
acceptance, there will be
additional libraries implemented. Developers are encouraged to port the FastCGI libraries
to their programming language of choice, ensuring that the openness of the extension is
more widely supported. The
success of FastCGI will depend on getting many vendors and programmers to support it.
Given its current feature set, it should have no trouble reaching this goal. 
The design of FastCGI also wins big on the learning curve because unlike server APIs, you
are still programming a CGI, so you can leverage what you already know. The only issues
that you will need to
address have to do with reorganizing your application so that the initialization code,
which is done once, is kept separate from the application body. FastCGI applications are
long-lived; they are kept alive
between transactions. This also means that memory needs to be managed because unlike
CGIs, which have a short life span, FastCGI processes may execute for undetermined
amounts of time. 
Data sent to a FastCGI application by the server is accessed through special streams that
provide complete binary compatibility with the CGI standard. This also allows a FastCGI
program to run as a regular
CGI program. A FastCGI program can determine, at runtime, if it is being run as CGI or as
FastCGI and behave accordingly. 
This translates into an environment that allows you to migrate FastCGI programs down,
should you ever need to. This provides server independence because the same binary can be
run on two servers-say
Apache and Netscape-under the same operating system without even needing to be rebuilt or
require programming modifications, even if the server couldn't support FastCGI. This
feature alone is very
interesting from a legacy and recycling standpoint. Also, all servers support FastCGI.
The FastCGI Developer's Kit comes with a program called cgi-fcgi that allows you to run
FastCGI responder
applications. The cgi-fcgi program allows any Web server that supports CGI to run
FastCGI. 
FastCGI applications communicate with Apache using a single full-duplex connection.
Through this connection, the server transmits the environment variables and stdin to the
FastCGI application; stdout and
stderr streams from the application are sent back to the server. 
What a FastCGI Application Looks Like
A modified version of my HelloWorld.c looks like this: 
#include fcgi_stdio.h
#include *stdio.h*
int main (void)
{
int timesVisited = 0;
while(FCGI_Accept() *=0)
{
printf (Content-type: text/html\r\n\r\n);
printf(*HTML*);
printf(*HEAD**TITLE*Hello World!*/TITLE**/HEAD*);
printf(*BODY**H1*Hello, this is a FastCGI program!*/H1*);
printf(*BIG**P*I can tell that you are visiting from %s.*/P*);
printf(*p*This page has been accessed: %d times*/P**/BIG**/BODY*, getenv(REMOTE_HOST),
++timesVisited);
printf(*/HTML*);
}
}
This version makes use of the fact that the application is persistent and will maintain a
count of the times the program is run (until the program dies). 
As you can see from this example, FastCGI applications follow this sequence: 
1.Initialization. Persistent connections or data that should be available from request to
request are initialized in this section. Initialization is done only once. The initial
environment for FastCGI applications
is set through the AppClass directive, which is added by the FastCGI module. 
2.The Response Loop. This loop is started by the FCGI_Accept() routine, implemented in
the FastCGI library. A call to this routine blocks program execution until the program
receives a client request.
When it receives one, the routine unblocks, sets up an environment for the program, and
runs one loop through the body. This routine is also responsible for determining the
context under which the
program is running (FastCGI or CGI) and sets the environment accordingly. 
3.Body. This portion of the program gets executed by each request. This is the meat of
your program. Each request will have its own environment variables, just as in a regular
CGI. 
4.End of Response. A subsequent call to FCGI_Accept informs the server that the program
has completed a request and is ready for another. FCGI_Accept once more blocks execution
until the next
request. 
This process is repeated until the FastCGI application is killed by the System
administrator or the Web server. If the process were to die, the FastCGI module or
cgi-fcgi program in the Web server is
responsible for making a FastCGI process available to handle the request. This means that
if it dies, the server will fork another process to replace the original. 
FastCGI and C
FastCGI implements two libraries: fcgi_stdio and fcgiapp. Both of these libraries are
provided for building C applications utilizing the FastCGI toolkit. 
The fcgi_stdio library implements stdio-compatible functionality and can be used for
developing or porting existing C CGI applications. This library provides full binary
compatibility between FastCGI and CGI
programs. 
fcgiapp provides additional functionality to FastCGI applications at the expense of
losing the CGI compatibility. There's also an increase in the knowledge required to
develop the application. 
FastCGI with Perl and Tcl
You can run Perl- and Tcl-interpreted programs under FastCGI. In order to run them,
you'll have to compile a specially modified version of the interpreter that has been
modified to work with FastCGI. You
will not, however, need to maintain both a regular and a special version of the
interpreter. The special version will work as expected when used under a normal context.
Future versions of Perl and Tcl will
incorporate changes that will make it possible to use unmodified versions of the program
with FastCGI. 
Patches for both Perl and Tcl are available. Some prebuilt binaries are also available at
http://www.fastcgi.com. 
Installing and Configuring FastCGI
To build and run FastCGI applications, you'll need to have two different pieces of
software: the FastCGI module for Apache and the FastCGI Developer's Kit. 
Both the toolkit and the Apache module are included in the CD-ROM that accompanies this
book; however, you should make sure that they are still current. At the time of this
writing, the Apache module
was still based on a beta version of 1.1. The latest and greatest versions of the module
and developer's kit are available at the FastCGI Web sites:
http://www.fastcgi.com/servers and
http://www.fastcgi.com/applibs, respectively. The version of the toolkit included on the
CD-ROM is 1.5. 
Incorporating FastCGI Functionality into Apache
To add the FastCGI module to Apache is simple. Copy apache-fastcgi/src/mod_fastcgi.c to
the Apache source directory (/usr/local/etc/httpd/src). Then you need to add an entry for
the module in Apache's
src/Configuration file. Add the following line at the end of the Module listings: 
Module fastcgi_module mod_fastcgi.o
You'll need to run Apache's configuration program, src/Configure, and rebuild the Apache
by issuing a make command while focused on the Apache src directory. 
While Apache builds, you can add the following configuration directives to your servers
conf/srm.conf configuration file: 
AddType application/x-httpd-fcgi .fcgi
Alias /fcgi-bin/ /usr/local/etc/httpd/fcgi-bin
# AppClass
Create the fcgi-bin directory, while in /usr/local/etc/httpd: 
% mkdir fcgi-bin
As you may be able to guess by now, FastCGI applications should be run from a directory
other than the cgi-bin directory. 
After Apache builds, issue the following commands: 
% cd /usr/local/etc/httpd
% mv httpd httpd.prev
% mv src/httpd .
% strip httpd
% kill -HUP 'cat /usr/local/etc/httpd/logs/httpd.pid`
This will restart the server and force rereading of the new configuration directives you
just added. Watch for any error messages. If you get an error, more than likely one of
the directives you added is
incorrect. 
If the restart of the server proceeded without problems, congratulations-your sever is
now ready to run FastCGI programs. 
cgi-fcgi
An alternative way of implementing FastCGI on Apache, or any other server, is to use the
cgi-fcgi program. cgi-fcgi is a standard CGI program that uses TCP/IP sockets to
communicate with FastCGI
applications. cgi-fcgi takes the pathname or host/port name as a parameter and connects
to the FastCGI application listening on that TCP port. cgi-fcgi then forwards the
environment variables and stdin to the
FastCGI application and returns to the server the stdout and stderr streams. When the
FastCGI application ends the connection, cgi-fcgi flushes and exits. 
Although this is not as efficient as a module imbedded into the server because the
cgi-fcgi program gets forked with every request, it is much better than not having it.
For example, if your Perl FastCGI
program takes 1 second to compile and 2 seconds to connect to a database, you'll still
have significant savings over forking Perl and recompiling the program with each request.
cgi-fcgi is a tiny program when
compared to Perl and many other programs. 
Building the FastCGI Developer's Kit
To build the developer's kit, you'll need to configure it. The folks at Open Market have
provided a nice script that automates the configuration process to run it. Just type
./configure while focused inside the
fcgi-devel-kit directory. After a few moments you should be able to type make and have
the libraries built. You will need this kit to build FastCGI-savvy interpreters or C
programs. 
After you build the kit, you may be interested in installing the library
libfcgi/libfcgi.a to some place useful such as /usr/local/lib. Remember to do a ranlib on
the library after you move it to refresh it. While you're
at it, you may want to copy the include directory to /usr/local/include/fcgi. That way it
will be easier for you to reference it while building your own programs. 
After the kit is built, you may want to try your luck at building the sample HelloWorld.c
program listed earlier. Note that you may need to change the location of the fcgi_stdio.h
header file to reflect its new
location. 
To build the FastCGI program, issue the following commands: 
cc -o Hello.fcgi -lfcgi HelloWorld.c
Put the resulting Hello.fcgi on your fcgi-bin directory. Before you can access it, you'll
need to add an AppClass entry into your srm.conf: 
AppClass /usr/local/etc/httpd/fcgi-bin/Hello.fcgi
and restart the server with 
% kill -HUP `cat /usr/local/etc/httpd/logs/httpd.pid`
The AppClass directive takes care of starting and maintaining the FastCGI application. At
this point you should be able to access it by pointing your browser to
http://localhost/fcgi-bin/Hello.fcgi. 
You should get a similar result to those displayed in Figure C.2. 
Figure C.2. The FastCGI version of Hello World!. Notice that it keeps state. My version
is fancier than the HelloWorld listing. 
Making Perl Fly
You will notice an even bigger improvement on Perl CGIs. This is because FastCGI will
keep the Perl program running; the interpreter won't have to fork, exec, compile, and
execute for each request. A
good thing. 
Before you can incorporate FastCGI into your Perl programs, you have to build a special
version of Perl. The FastCGI Developer's Kit contains the patches you'll need to build a
version of Perl that supports
FastCGI. After you build this version, there's no need to keep your old Perl around. A
FastCGI-savvy Perl binary will work just fine with regular Perl scripts. 
Future versions of Perl may have support for FastCGI right out of the box. Currently
there's an active discussion on the perl5-porters mailing list regarding the issues that
need to change in Perl's
implementation to support FastCGI as a true Perl module-that is, requiring no
recompiling. The Tcl7.5 FastCGI module, when it makes its debut, won't require a rebuilt
of Tcl. The new Python module also
doesn't need a rebuild. 
At the time of this writing, the patches available for FastCGI were for version 5.002 of
Perl. By the time you read this, they will be updated to the current Perl version, 5.003.

The patch process is simple; you just replace a few files in the standard Perl
distribution with files provided in the kit. Here's the process: 
1.1. Put the unarchived Perl and fcgi-devel-kit on a directory side by side and issue the
following commands: 
% cd perl5.002 
% mv perl.c perl.c.dist 
% mv proto.h proto.h.dist 
% mv Configure Configure.dist 
% cp -r ../fcgi-devel-kit/perl-5/perl5.002/* 
% cp -r ../fcgi-devel-kit/perl-5/common/* 
2.2. Set the environment variable FCGIDIR to the absolute path of the fcgi-devel-kit. In
my case, the distribution was in the /tmp/fcgiPerl directory. This variable will tell the
configuration program where
to find things: 
setenv FCGIDIR /tmp/fcgiPerl/fcgi-devel-kit 
3.3. If you don't use gcc, set the environment variable CC to the name of your compiler:

setenv CC cc 
4.4. If you want to install the Perl distribution somewhere other than /usr/local/bin,
define the environment variable PERL_PREFIX. I kept the default setting. 
5.5. Execute the fcgi-configure script: 
% ./fcgi-configure 
The fcgi-configure script is a wrapper that automatically sets some of the configure
variables without requiring user input. If this fails, you'll have to run the Configure
command in the Perl directory. You
may want to take a look at the documentation that came with the FastCGI Developer's Kit
for any tips to solve the problem. 
6.6. Do a make to build the software: 
% make 
If it all goes smoothly, you can finish the installation with a make install, which will
install Perl to the location specified. That's it for the install! Make sure your scripts
reference the correct version of Perl. 
Perl FastCGI Programs
The modified version of my HelloWorld.c looks like this: 
#!/usr/local/bin/perl
use strict;
use FCGI;
my($timesVisited) = 0;
while(FCGI::accept() *=0){
print Content-type: text/plain\n\n;
print **STOP;
*HTML*
*HEAD*
*TITLE*Hello World!*/TITLE*
*/HEAD*
*BODY*
*H1*Hello, this is a FastCGI program!*/H1*
*P*I can tell that you are visiting from $ENV{REMOTE_HOST}*/P*
*P*This page has been accessed: ++$timesVisited*/P*
*/BODY*
*/HTML*
STOP
}
As you can see, this is pretty much the same organization as the C program. The one
gotcha with Perl is that if the initial environment to a FastCGI Perl application is
empty when the first call to FCGI::accept
returns, the environment will still be empty. The easiest workaround is to add an
environment with the AppClass -initial-env directive. See the section entitled, The
AppClass Directive, for more detailed
information. 
The mod_fastcgi Module
The FastCGI module provides Apache compatibility to FastCGI applications. This module is
not part of the standard Apache release, so you'll have obtain a copy from
http://www.fastcgi.com. A copy of the
latest version at the time this was written, August 1996, is included on the CD-ROM. 
This module processes any file with a MIME-type application/x-httpd-fcgi. Because the
ScriptAlias directive may have higher priority over AddType, FastCGI applications should
not reside on the cgi-bin
directory; if they do, they may be processed by the mod_cgi module regardless of the
extension given. This means that the application/x-httpd-fcgi MIME type is given to files
that do not reside in the
ScriptAlias directory and that have a name using the extension defined by the AddType
application/x-httpd-cfgi directive. Typically this will be .fcgi. The reason for this is
that Apache assigns priority to the
directives based on the order of compilation in the modules. 
The AppClass Directive
Syntax: 
AppClass executablePath [-processes p] [-listen-queue-Depth q] [-restart-delay secs]
[-priority N] [-initial-env key=value] 
Default: 
AppClass executablePath [-processes 1] [-listen-queue-Depth 5] [-restart-delay 5]
[-priority sameAsHTTP] 
Context: 
srm.conf 
Module: 
mod_fastcgi 
The AppClass directive, provided by mod_fastcgi, is responsible for starting up one or
more FastCGI application processes using the executable specified by executablePath. 
When a request for the file specified by executablePath is received, the request is
handled by the mod_fastcgi module, which connects the request to the appropriate process
belonging to the proper
AppClass. 
In addition to starting the process, the server will ensure that a process for handling a
particular AppClass will be available. Should a process exit because of an error or some
other condition, the server will
launch another process capable of handling the requests. 
AppClass has several other options: 
processes: 
Specifies the number of FastCGI processes that the server will spawn. Default value for
this setting is 1. 
listen-queue-depth: 
Sets the depth of the listen queue that is shared by the processes. The listen queue
stores additional requests that may be received while the
FastCGI application is processing another. Requests will queue until they reach the limit
imposed by listen-queue-depth. Additional requests
beyond the size of the queue are responded with an error to the client. Default value is
5. 
restart-delay: 
Specifies the number of seconds the server will wait before restarting a dead FastCGI
process. The server won't restart a process more often
than the time specified by this flag. The default value is 5 seconds. 
priority: 
This flag specifies the execution priority of the FastCGI process. The default priority
is inherited from the parent httpd server process. 
initial-env: 
This flag allows you to specify the initial environment sent to a FastCGI program when
the program initializes. You can specify multiple
initial-env flags, one per key=value pair. If not specified, the initial environment is
empty. It would be very useful to provide the FastCGI
application with information during its initialization phase. 
Example
If you wanted to start the HelloWorld.fcgi program, you would need to type this: 
AppClass /usr/local/etc/httpd/fcgi-bin/HelloWorld.fcgi -processes 2
For a Perl program, to circumvent the environment problem, you would have to do this: 
AppClass /usr/local/etc/httpd/fcgi-bin/HelloWorld.fcgi -processes 2 -initial- env:
DB_PATH_NAME=/proj/accts/db2
Summary
Although FastCGI is not the sole alternative for high performance CGI alternatives, the
features and price cannot be beat. It's especially interesting that existing code can be
ported easily without a real learning
curve. This alone makes it very attractive for programmers who have a backlog and don't
have much time to spend experimenting with new tools, yet need to implement a
high-performance CGI solution.
FastCGI is a great choice-the learning-and-setup curve is hours, not days like other
environments. Performance Enhancement 
FastCGI API 
What a FastCGI Application Looks Like 
FastCGI and C 
FastCGI with Perl and Tcl
Installing and Configuring FastCGI 
Incorporating FastCGI Functionality into Apache 
cgi-fcgi
Building the FastCGI Developer's Kit 
Making Perl Fly 
Perl FastCGI Programs