+++ /dev/null
-FastCGI Developer's Kit
-/fastcgi/words
-fcgi-hd.gif
-[FastCGI]
-<center>FastCGI Developer's Kit</center>
-
-<!--Copyright (c) 1996 Open Market, Inc. -->
-<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
-<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
-
-<center>
-Mark R. Brown<br>
-Open Market, Inc.<br>
-<p>
-
-Document Version: 1.08<br>
-11 June 1996<br>
-</center>
-<p>
-
-<h5 align=center>
-Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
- MA 02142 U.S.A.<br>
-Tel: 617-621-9500 Fax: 617-621-1703 URL:
- <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
-$Id: fcgi-devel-kit.gut,v 1.1 1997/09/16 15:36:26 stanleyg Exp $ <br>
-</h5>
-<hr>
-
-<ul type=square>
- <li><a HREF = "#S1">1. Introduction</a>
- <li><a HREF = "#S2">2. Getting started</a>
- <li><a HREF = "#S3">3. Writing applications</a>
- <ul type=square>
- <li><a HREF = "#S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a>
- <li><a HREF = "#S3.2">3.2 Using the <tt>fcgiapp</tt> library</a>
- <li><a HREF = "#S3.3">3.3 Using Perl and Tcl</a>
- <li><a HREF = "#S3.4">3.4 Using Java</a>
- </ul>
- <li><a HREF = "#S4">4. Running applications</a>
- <ul type=square>
- <li><a HREF = "#S4.1">4.1 Using a Web server that supports FastCGI</a>
- <li><a HREF = "#S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a>
- </ul>
- <li><a HREF = "#S5">5. Known problems</a>
- <li><a HREF = "#S6">6. Getting support</a>
-</ul>
-
-<hr>
-
-
-
-<h3><a NAME = "S1">1. Introduction</a></h3>
-
-FastCGI is an open extension to CGI that provides high performance
-for all Internet applications without the penalties of Web server
-APIs.<p>
-
-FastCGI is designed to be layered on top of existing Web server
-APIs. For instance, the <tt>mod_fastcgi</tt> Apache module adds
-FastCGI support to the Apache server. FastCGI can also be used,
-with reduced functionality and reduced performance, on any Web server
-that supports CGI.<p>
-
-This FastCGI Developer's Kit is designed to make developing FastCGI
-applications easy. The kit currently supports FastCGI
-applications written in C/C++, Perl, Tcl, and Java.<p>
-
-This document:
-
-<ul type=square>
- <li>Describes how to configure and build the
- kit for your development platform.
-
- <li>Tells how to write applications using the
- libraries in the kit.
-
- <li>Tells how to run applications using Web servers that support
- FastCGI or using any Web server and <tt>cgi-fcgi</tt>.
-</ul>
-
-The kit includes a <a href="fastcgi-whitepaper/fastcgi.htm">technical white
-paper</a>, <tt>doc/fastcgi-whitepaper/fastcgi.htm</tt>.
-You should read at least the first three sections of the
-technical white paper before starting to write FastCGI applications.
-The <a href="fcgi-perf.htm">performance paper</a> will help you understand
-how application design affects performance with FastCGI.<p>
-
-The <a href ="fcgi-spec.html">FastCGI Specification</a>,
-<tt>doc/fcgi-spec.html</tt>, defines the interface between a FastCGI
-application and a Web server that supports FastCGI. The software in
-the kit implements the specification. You don't need to
-read the specification in order to write applications.<p>
-
-Additional information is provided in the
-<a href ="http://www.fastcgi.com/words/FAQ.htm">FAQ</a> document, which
-contains frequently asked questions about application development
-using FastCGI, as well as some general information.<p>
-
-Experience with CGI programming will be extremely valuable in writing FastCGI
-applications. If you don't have enough experience with CGI programming,
-you should read one of the popular books on the topic or study the
-<a href = "http://hoohoo.ncsa.uiuc.edu/cgi/">NCSA CGI page</a>.
-For a more formal treatment of CGI/1.1 see the
-<a href = "http://ds.internic.net/internet-drafts/draft-robinson-www-interface-01.txt">Internet Draft CGI 1.1 Specification</a>.<p>
-
-
-
-<h3><a NAME = "S2">2. Getting started</a></h3>
-
-The kit is a compressed tar (tar.Z) file,
-distributed via the
-<a href = "http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a>
-Web page. Unpacking the tar file creates a new directory
-<tt>fcgi-devel-kit</tt>.<p>
-
-Open the kit's index page, <tt>fcgi-devel-kit/index.html</tt>, using
-the "Open File" command in your Web browser. The index page gives you
-an overview of the kit structure and helps you navigate the kit. The
-index page also contains links that run some example applications, but
-the applications won't work when index.html is opened using the "Open
-File" command because they aren't aren't being accessed through a Web
-server.<p>
-
-In order to use the kit in earnest you'll need a Web server that you
-control, a Web server running with your user ID. The Web server will
-be starting FastCGI applications that you will need to debug; this
-will be a lot more convenient for you if these processes run with your
-user ID. It is best to have a Web server that supports FastCGI.
-<a href = "#S4">Section 4</a> discusses Web server issues.<p>
-
-If you can, keep the kit on a file system accessible from your
-personal workstation, do your builds on your workstation, and run your
-Web server on your workstation. If that's not possible, arrange a
-configuration such that the kit is accessible from the machine that's
-going to run your Web server, and build the kit and your applications
-on a machine that's configured exactly the same way (same processor
-architecture, operating system, etc.) as the machine that's going to
-run your Web server.<p>
-
-To build the kit you execute this sequence of commands
-in the <tt>fcgi-devel-kit</tt> directory:<p>
-
-<pre>
- % ./configure
- % make
-</pre>
-
-We've built and exercised the kit on these platforms
-(listed in alphabetical order):<p>
-
-<ul type=square>
- <li>
- BSD/OS 1.1 (Intel Pentium), gcc
- <li>
- Digital UNIX V3.2 148 (Alpha), gcc/cc
- <li>
- Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc
- <li>
- IBM AIX 1 4 (RS/6000), gcc
- <li>
- Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc
- <li>
- Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc
- <li>
- Sun SunOS 4.1.4 (SPARC), gcc
-</ul>
-
-Once you've built the kit, follow the directions in
-<a href = "#S4">Section 4</a> to bring up your Web server
-and run the example applications.<p>
-
-
-
-<h3><a NAME = "S3">3. Writing applications</a></h3>
-
-
-<h4><a NAME = "S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a>
-</h4>
-
-The <tt>fcgi_stdio</tt> library provides
-the easiest transition for C CGI programs and C CGI
-programmers to FastCGI. Using this library your application
-can run using either CGI or FastCGI, with the same binary
-for both situations.<p>
-
-To introduce the <tt>fcgi_stdio</tt> library
-we give a pair of examples: a tiny CGI program and the translation of this
-program to FastCGI. These two example programs are included in the kit.<p>
-
-The CGI program is <tt>examples/tiny-cgi.c</tt>:<p>
-
-<pre>
- #include <stdio.h>
- #include <stdlib.h>
-
- void main(void)
- {
- int count = 0;
- printf("Content-type: text/html\r\n"
- "\r\n"
- "<title>CGI Hello!</title>"
- "<h1>CGI Hello!</h1>"
- "Request number %d running on host <i>%s</i>\n",
- ++count, getenv("SERVER_NAME"));
- }
-</pre>
-
-The key features of this tiny CGI program are:<p>
-
-<ul type = square>
- <li>
- The program sends data to the Web server by writing to
- <tt>stdout</tt>, using <tt>printf</tt> in this example. The CGI
- program first sends a <tt>Content-type</tt> header, then a
- small HTML document. The program includes <tt>stdio.h</tt> in
- order to get access to the <tt>printf</tt> function.<p>
- <li>
- The program obtains parameters provided by the Web server by
- reading environment variables. The CGI program reads the
- <tt>SERVER_NAME</tt> variable using <tt>getenv</tt> and
- includes the value in the HTML document. The program includes
- <tt>stdlib.h</tt> in order to get access to the
- <tt>getenv</tt> function.<p>
-</ul>
-
-The <tt>count</tt> variable is degenerate in this example;
-the CGI program runs a single request, so the request number
-is always one. This variable will be more interesting
-in the FastCGI example.<p>
-
-<a NAME = "S3.1.1">The</a>
-corresponding FastCGI program is <tt>examples/tiny-fcgi.c</tt>:<p>
-
-<pre>
- #include "fcgi_stdio.h"
- #include <stdlib.h>
-
- void main(void)
- {
- int count = 0;
- while(FCGI_Accept() >= 0)
- printf("Content-type: text/html\r\n"
- "\r\n"
- "<title>FastCGI Hello!</title>"
- "<h1>FastCGI Hello!</h1>"
- "Request number %d running on host <i>%s</i>\n",
- ++count, getenv("SERVER_NAME"));
- }
-</pre>
-
-The key features of this tiny FastCGI program are:<p>
-
-<ul type = square>
- <li>
- The program is structured as a loop that begins by calling the
- function <tt>FCGI_Accept</tt>. The <tt>FCGI_Accept</tt>
- function blocks until a new request arrives for the program to
- execute. The program includes <tt>fcgi_stdio.h</tt> in order
- to get access to the <tt>FCGI_Accept</tt> function.<p>
- <li>
- Within the loop, <tt>FCGI_Accept</tt> creates a
- CGI-compatible world. <tt>printf</tt> and <tt>getenv</tt>
- operate just as in the CGI program. <tt>stdin</tt> and
- <tt>stderr</tt>, not used by this tiny program, also
- operate just as in a CGI program.<p>
-</ul>
-
-The <tt>count</tt> variable increments each time through the loop, so
-the program displays a new request number each time. You can use
-the reload button in your browser to demonstrate this, once you've
-got the program built and running.<p>
-
-
-<h4>Building the program</h4>
-
-If you can build <tt>examples/tiny-cgi.c</tt>,
-it will be straightforward for you to build
-<tt>examples/tiny-fcgi.c</tt>. You need to:<p>
-
-<ul type = square>
- <li>
- Add the directory containing the
- <tt>fcgi_stdio.h</tt> header to the compiler's include search
- path. The kit calls this directory <tt>include</tt>.<p>
- <li>
- Add the library <tt>libfcgi.a</tt> to the linker's command
- line so that it will be searched when linking. The
- <tt>libfcgi.a</tt> library implements the functions defined in
- <tt>fcgi_stdio.h</tt>. The kit calls the directory containing
- this library <tt>libfcgi</tt>.<p>
- <li>
- Determine whether or not the linker on your
- platform searches the Berkeley socket
- library by default, and if not, add linker directives to
- force this search.<p>
-</ul>
-
-See <tt>examples/Makefile</tt> (created by <tt>configure</tt>)
-for a Makefile that builds both
-programs. Autoconf handles the platform-dependent linking issues; to
-see how, examine <tt>configure.in</tt> and
-<tt>examples/Makefile.in</tt>.<p>
-
-
-<h4>Running the program</h4>
-
-<a href = "#S4">Section 4</a> is all about
-how to run FastCGI applications.<p>
-
-You can use CGI to run application binaries built with the
-<tt>fcgi_stdio</tt> library. The <tt>FCGI_Accept</tt>
-function tests its environment to determine how the application was
-invoked. If it was invoked as a CGI program, the first
-call to FCGI_Accept is essentially a no-op and the second call
-returns <tt>-1</tt>. In effect, the request loop disappears.<p>
-
-Of course, when a FastCGI application is run using CGI it does not
-get the benefits of FastCGI. For instance, the application exits
-after servicing a single request, so it cannot maintain
-cached information.<p>
-
-
-<h4>Implementation details</h4>
-
-<tt>fcgi_stdio.h</tt> works by first including <tt>stdio.h</tt>, then
-defining macros to replace essentially all of the types and procedures
-defined in <tt>stdio.h</tt>. (<tt>stdio.h</tt> defines a few
-procedures that have nothing to do with <tt>FILE *</tt>, such as
-<tt>sprintf</tt> and <tt>sscanf</tt>; <tt>fcgi_stdio.h</tt> doesn't
-replace these.) For instance, <tt>FILE</tt> becomes
-<tt>FCGI_FILE</tt> and <tt>printf</tt> becomes <tt>FCGI_printf</tt>.
-You'll only see these new names if you read <tt>fcgi_stdio.h</tt> or
-examine your C source code after preprocessing.<p>
-
-Here are some
-consequences of this implementation technique:<p>
-
-<ul type = square>
- <li>
- On some platforms the implementation will break if you include
- <tt>stdio.h</tt> after including <tt>fcgi_stdio.h</tt>,
- because <tt>stdio.h</tt> often defines macros for functions such
- as <tt>getc</tt> and <tt>putc</tt>. Fortunately, on most
- platforms <tt>stdio.h</tt> is protected against multiple
- includes by lines near the top of the file that look like
- <pre>
- #ifndef _STDIO_H
- #define _STDIO_H
- </pre>
- The specific symbol used for multiple-include protection,
- <tt>_STDIO_H</tt> in this example, varies from platform to
- platform. As long as your platform protects <tt>stdio.h</tt>
- against multiple includes, you can forget about this issue.<p>
- <li>
- If your application passes <tt>FILE *</tt> to functions
- implemented in libraries for which you have source code, then
- you'll want to recompile these
- libraries with <tt>fcgi_stdio.h</tt> included.
- Most C compilers provide a command-line option for including
- headers in a program being compiled; using such a compiler feature
- allows you to rebuild your libraries without making source changes.
- For instance the gcc command line
- <pre>
- gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c
- </pre>
- causes gcc to include <tt>fcgi_stdio.h</tt> before it even
- begins to read the module <tt>wonderlib.c</tt>.<p>
- <li>
- If your application passes <tt>FILE *</tt> to functions
- implemented in libraries
- for which you do not have source code, then
- you'll need to include the headers for these libraries
- <i>before</i> you include <tt>fcgi_stdio.h</tt>.
- You can't pass the <tt>stdin</tt>,
- <tt>stdout</tt>, or <tt>stderr</tt> streams produced by
- <tt>FCGI_Accept</tt> to any functions implemented by these
- libraries. You can pass a stream on a Unix file to a library
- function by following this pattern:
- <pre>
- FILE *myStream = fopen(path, "r");
- answer = MungeStream(FCGI_ToFile(myStream));
- </pre>
- Here <tt>MungeStream</tt> is a library function that you can't
- recompile and <tt>FCGI_ToFile</tt> is a macro that converts
- from <tt>FCGI_FILE *</tt> to <tt>FILE *</tt>. The macro
- <tt>FCGI_ToFile</tt> is defined in <tt>fcgi_stdio.h</tt>.<p>
-</ul>
-
-
-<h4>Converting CGI programs</h4>
-
-The main task in converting a CGI program into a FastCGI program is
-separating the code that needs to execute once, initializing the
-program, from the code that needs to run for each request.
-In our tiny example, initializing the <tt>count</tt> variable
-is outside the loop, while incrementing the <tt>count</tt> variable
-goes inside.<p>
-
-Retained application state may be an issue. You must ensure that
-any application state created in processing one request has no
-unintended effects on later requests. FastCGI offers the possibility
-of significant application performance improvements, through caching;
-it is up to you to make the caches work
-correctly.<p>
-
-Storage leaks may be an issue. Many CGI programs don't worry about
-storage leaks because the programs don't run for long enough for
-bloating to be a problem. When converting to FastCGI, you
-can either use a tool such as
-<a href ="http://www.pure.com/"><i>Purify</i></a> from Pure Software
-to discover and fix storage
-leaks, or you can run a C garbage collector such as
-<a href ="http://www.geodesic.com/"><i>Great Circle</i></a>
-from Geodesic Systems.<p>
-
-
-<h4>Limitations</h4>
-
-Currently there are some limits to the compatibility provided
-by the <tt>fcgi_stdio</tt> library:<p>
-
-<ul type = square>
- <li>
- The library does not provide FastCGI versions of
- the functions <tt>fscanf</tt> and <tt>scanf</tt>. If you wish
- to apply <tt>fscanf</tt> or <tt>scanf</tt> to <tt>stdin</tt>
- of a FastCGI program, the workaround is to read lines or other
- natural units into memory and then call <tt>sscanf</tt>. If
- you wish to apply <tt>fscanf</tt> to a stream on a Unix file,
- the workaround is to follow the pattern:
- <pre>
- FILE *myStream = fopen(path, "r");
- count = fscanf(FCGI_ToFile(myStream), format, ...);
- </pre>
-</ul>
-
-<h4>Reference documentation</h4>
-
-The <a href = "FCGI_Accept.3"><tt>FCGI_Accept</tt> manpage</a>,
-<tt>doc/FCGI_Accept.3</tt>, describes the function in the traditional
-format.<p>
-
-The <a href = "FCGI_Finish.3"><tt>FCGI_Finish</tt></a>
-(<tt>doc/FCGI_Finish.3</tt>),
-<a href = "FCGI_SetExitStatus.3"><tt>FCGI_SetExitStatus</tt></a>
-(<tt>doc/FCGI_SetExitStatus.3</tt>), and
-<a href = "FCGI_StartFilterData.3"><tt>FCGI_StartFilterData</tt></a>
-(<tt>doc/FCGI_StartFilterData.3</tt>)
-manpages document capabilities of the <tt>fcgi-stdio</tt>
-library that are not illustrated above.<p>
-
-
-<h4><a NAME = "S3.2">3.2 Using the <tt>fcgiapp</tt> library</a></h4>
-
-The <tt>fcgiapp</tt> library is a second C library for FastCGI. It
-does not provide the high degree of source code compatibility provided
-by <tt>fcgi_stdio</tt>; in return, it does not make such heavy use of
-<tt>#define</tt>. <tt>fcgi_stdio</tt> is implemented as
-a thin layer on top of <tt>fcgiapp</tt>.<p>
-
-Applications built using the <tt>fcgiapp</tt> library cannot run
-as CGI programs; that feature is provided at the <tt>fcgi_stdio</tt>
-level.<p>
-
-Functions defined in <tt>fcgiapp</tt> are named using the prefix
-<tt>FCGX_</tt> rather than <tt>FCGI_</tt>. For instance,
-<tt>FCGX_Accept</tt> is the <tt>fcgiapp</tt> version of
-<tt>FCGI_Accept</tt>.<p>
-
-Documentation of the <tt>fcgiapp</tt> library takes the form
-of extensive comments in the header file <tt>include/fcgiapp.h</tt>.
-The sample programs <tt>examples/tiny-fcgi2.c</tt> and
-<tt>examples/echo2.c</tt> illustrate how to use
-<tt>fcgiapp</tt>.<p>
-
-
-<h4><a NAME = "S3.3">3.3 Using Perl and Tcl</a></h4>
-
-A major advantage of the FastCGI approach to high-performance Web
-applications is its language-neutrality. CGI scripts written in
-popular languages such as Perl and Tcl can be evolved into
-high-performance FastCGI applications.<p>
-
-We have produced FastCGI-integrated Perl and Tcl
-interpreters. Doing so was easy, since Perl and Tcl
-are conventional C applications and <tt>fcgi_stdio</tt> was
-designed for converting conventional C applications. Essentially no source
-code changes were required in these programs; a small amount
-of code was added in order to make <tt>FCGI_Accept</tt> and other
-FastCGI primitives available in these languages. And because
-these interpreters were developed using <tt>fcgi_stdio</tt>, they
-run standard Perl and Tcl applications (e.g. CGI scripts) as well
-as FastCGI applications.<p>
-
-See the
-<a href = "http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a>
-Web page for downloadable Perl and Tcl binaries for selected platforms.
-Because many users of Perl and Tcl run extended versions of these languages,
-the kit includes separate companion documents describing
-<a href ="fcgi-perl.htm">how to build FastCGI-integrated Perl</a>
-and <a href ="fcgi-tcl.htm">how to build FastCGI-integrated Tcl</a>.<p>
-
-Here are the Perl and Tcl versions of <tt>tiny-fcgi</tt>:<p>
-<pre>
-#!./perl
-use FCGI;
-$count = 0;
-while(FCGI::accept() >= 0) {
- print("Content-type: text/html\r\n\r\n",
- "<title>FastCGI Hello! (Perl)</title>\n",
- "<h1>FastCGI Hello! (Perl)</h1>\n";
- "Request number ", ++$count,
- " running on host <i>";$env(SERVER_NAME)</i>");
-}
-</pre>
-
-<pre>
-#!./tclsh
-set count 0
-while {[FCGI_Accept] >= 0 } {
- incr count
- puts -nonewline "Content-type: text/html\r\n\r\n"
- puts "<title>FastCGI Hello! (Tcl)</title>"
- puts "<h1>FastCGI Hello! (Tcl)</h1>"
- puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"
-}
-</pre>
-
-Converting a Perl or Tcl CGI application to FastCGI is not fundamentally
-different from converting a C CGI application to FastCGI. You separate
-the portion of the application that performs one-time
-initialization from the portion that performs per-request
-processing. You put the per-request processing into a loop
-controlled by <tt>FCGI::accept</tt> (Perl) or <tt>FCGI_Accept</tt>
-(Tcl).
-
-
-
-<h4><a NAME = "S3.4">3.4 Using Java</a></h4>
-
-Java is not just for browser-based applets. It is already suitable for
-writing some Web server applications, and its range of applicability will
-only grow as Java compilers and other Java tools improve. Java's
-modules, garbage collection, and threads are especially valuable
-for writing long-lived application servers.<p>
-
-The <tt>FCGIInterface</tt> class provides facilities for Java
-applications analogous to what <tt>fcgi_stdio</tt> provides for C
-applications. Using this library your Java application can run using
-either CGI or FastCGI.<p>
-
-The kit includes separate companion document on
-<a href ="fcgi-java.htm">using FastCGI with Java</a>. The
-source code for FastCGI classes is contained in
-directory <tt>java/src</tt>
-and the compiled code in <tt>java/classes</tt>.<p>
-
-Here is the Java version of <tt>tiny-fcgi</tt>:<p>
-
-<pre>
-import FCGIInterface;
-
-class TinyFCGI {
- public static void main (String args[]) {
- int count = 0;
- while(new FCGIInterface().FCGIaccept()>= 0) {
- count ++;
- System.out.println("Content-type: text/html\r\n\r\n");
- System.out.println(
- "<title>FastCGI Hello! (Java)</title>");
- System.out.println("<h1>FastCGI Hello! (Java)</h1>");
- System.out.println(
- "request number " + count + " running on host <i>" +
- System.getProperty("SERVER_NAME") + "</i>");
- }
- }
-}
-</pre>
-<p>
-
-
-<h3><a NAME = "S4">4. Running applications</a></h3>
-
-
-<h3><a NAME = "S4.1">4.1 Using a Web server that supports FastCGI</a></h3>
-
-For a current listing of Web servers that support FastCGI,
-see the <a HREF = "http://www.fastcgi.com/servers">www.fastcgi.com/servers</a>
-Web page.<p>
-
-All of the Web servers that support FastCGI perform management of
-FastCGI applications. You don't need to start and stop FastCGI
-applications; the Web server takes care of this. If an application
-process should crash, the Web server restarts it.<p>
-
-Web servers support FastCGI via new configuration directives.
-Since these directives are server-specific, get more information
-from the documentation that accompanies each server.<p>
-
-The directory
-<a HREF = "../examples/conf"><tt>examples/conf</tt></a> contains config
-files designed to run the example programs included in the FastCGI
-Developer's Kit. Each config file contains specific installation
-instructions.<p>
-
-The more advanced example programs take advantage of special features
-of the Open Market Secure WebServer, such as anonymous ticketing
-and support for the Authorizer role. If you don't have this server,
-download a
-<a HREF= "http://www.openmarket.com/store/eval/swsg.htm">free
-evaluation copy</a> to run the examples.<p>
-
-
-<h3><a NAME = "S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a></h3>
-
-The program <tt>cgi-fcgi</tt> allows you to run FastCGI applications
-using any Web server that supports CGI.<p>
-
-Here is how <tt>cgi-fcgi</tt> works. <tt>cgi-fcgi</tt> is a
-standard CGI program that uses Unix domain or TCP/IP sockets
-to communicate with
-a FastCGI application. <tt>cgi-fcgi</tt> takes the path name
-or host/port name of a
-listening socket as a parameter and <tt>connect</tt>s to the FastCGI
-application listening on that socket. <tt>cgi-fcgi</tt> then forwards the CGI
-environment variables and <tt>stdin</tt> data to the FastCGI
-application, and forwards the <tt>stdout</tt> and <tt>stderr</tt> data
-from the FastCGI application to the Web server. When the FastCGI
-application signals the end of its response, <tt>cgi-fcgi</tt> flushes
-its buffers and exits.<p>
-
-Obviously, having <tt>cgi-fcgi</tt> is not as good as having
-a server with integrated FastCGI support:<p>
-
-<ul>
- <li>Communication is slower than with a Web server that avoids the
- fork/exec overhead on every FastCGI request.
-
- <li><tt>cgi-fcgi</tt> does not perform application management,
- so you need to provide this yourself.
-
- <li><tt>cgi-fcgi</tt> supports only the Responder role.
-</ul>
-
-But <tt>cgi-fcgi</tt> does allow you to
-develop applications that retain state in memory between connections,
-which often provides a major performance boost over normal CGI. And
-all the applications you develop using <tt>cgi-fcgi</tt>
-will work with Web servers that have integrated support for
-FastCGI.<p>
-
-The file <tt>examples/tiny-fcgi.cgi</tt> demonstrates
-a way to use <tt>cgi-fcgi</tt> to run a typical application,
-in this case the <tt>examples/tiny-fcgi</tt> application:
-
-<pre>
- #!../cgi-fcgi/cgi-fcgi -f
- -connect sockets/tiny-fcgi tiny-fcgi
-</pre>
-
-On most Unix platforms, executing this command-interpreter file runs
-<tt>cgi-fcgi</tt> with arguments <tt>-f</tt> and
-<tt>examples/tiny-fcgi.cgi</tt>. (Beware: On some
-Unix platforms, including HP-UX, the first line of a command-interpreter file
-cannot contain more than 32 characters, including the newline;
-you may need to install the <tt>cgi-fcgi</tt> application in a standard
-place like <tt>/usr/local/bin</tt> or create a symbolic link
-to the <tt>cgi-fcgi</tt> application in the directory containing
-your application.)
-The <tt>cgi-fcgi</tt> program reads the command-interpreter file and
-connects to the FastCGI application whose listening socket is
-<tt>examples/sockets/tiny-fcgi</tt>.<p>
-
-Continuing the example, if
-<tt>cgi-fcgi</tt>'s connection attempt fails, it
-creates a new process
-running the program <tt>examples/tiny-fcgi</tt> and listening on
-socket <tt>examples/sockets/tiny-fcgi</tt>. Then <tt>cgi-fcgi</tt>
-retries the connection attempt, which now should succeed.<p>
-
-The <tt>cgi-fcgi</tt> program has two other modes of operation.
-In one mode it connects to applications but does not start them;
-in the other it starts applications but does not connect
-to them. These modes are required when using TCP/IP. The
-<a href = "cgi-fcgi.1"><tt>cgi-fcgi</tt> manpage</a>,
-<tt>doc/cgi-fcgi.1</tt>, tells the full story.<p>
-
-To run the example applications using <tt>cgi-fcgi</tt>, start your
-Web server and give it the directory <tt>fcgi-devel-kit</tt> as the
-root of its URL space. If the machine running your server is called
-<tt>bowser</tt> and your server is running on port <tt>8888</tt>,
-you'd then open the URL <tt>http://bowser:8888/index.html</tt> to
-reach the kit's index page. Now the links on the index page that run
-example applications via <tt>cgi-fcgi</tt> should be active.<p>
-
-
-
-<h3><a NAME = "S5">5. Known problems</a></h3>
-
-On Digital UNIX 3.0 there's a problem with Unix domain listening
-sockets on NFS file systems. The symptom when using cgi-fcgi is an
-exit status of 38 (<tt>ENOTSOCK</tt>: socket operation on non-socket),
-but cgi-fcgi may dump core in this case when compiled optimized.
-Work-around: Store your Unix domain listening
-sockets on a non NFS file system, upgrade to Digital UNIX 3.2, or use
-TCP sockets.<p>
-
-On AIX there's a problem with shared listening sockets.
-The symptoms can include application core dumps and kernel panic.
-Work-around: Run a single FastCGI application server per listening
-socket.<p>
-
-
-
-<h3><a NAME = "S6">6. Getting support</a></h3>
-
-The mailing list <tt>fastcgi-developers@openmarket.com</tt>
-is used for discussions of issues in developing FastCGI applications.
-Topics include announcement of FastCGI-capable Web servers or
-changes to such servers, announcement of new application libraries
-or changes to such libraries, announcement of known bugs, discussion
-of design trade-offs in FastCGI application programming, and discussion
-of development plans and experiences. To join the
-list, send a message to
-<a href = "mailto:fastcgi-developers-request@openmarket.com">fastcgi-developers-request@openmarket.com</a>
-with a message body consisting of the word "subscribe"
-(leaving off the quotes).<p>
-
-Mail sent to this list is archived and available on the
-World-Wide Web at
-<pre>
- http://www.fastcgi.com/mail/
-</pre>
-
-Open Market Secure WebServer customers get FastCGI
-support where they get server support.<p>
-
-
-
-<hr>
-
-<address>
-© 1996, Open Market, Inc. / mbrown@openmarket.com
-</address>
-
+++ /dev/null
-Integrating FastCGI with Java
-/fastcgi/words
-fcgi-hd.gif
-[FastCGI]
-<center>Integrating FastCGI with Java</center>
-
-<!--Copyright (c) 1996 Open Market, Inc. -->
-<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
-<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
-<!-- $Id: fcgi-java.gut,v 1.1 1997/09/16 15:36:26 stanleyg Exp $ -->
-
-<P ALIGN=CENTER>
-Steve Harris
-<BR>
-Open Market, Inc.
-<BR>
-<EM>7 May 1996</EM>
-</P>
-
-<h5 align=center>
-Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
- MA 02142 U.S.A.<br>
-Tel: 617-621-9500 Fax: 617-621-1703 URL:
- <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
-</h5>
-<hr>
-
-<H3><A NAME = "S1"> 1. Introduction</A></H3>
-Java is an object-oriented programming language developed by Sun
-Microsystems. The Java Depvelopers Kit (JDK), which contains the basic
-Java class packages, is available from Sun in both source and binary
-forms at Sun's
-<a href="http://java.sun.com/java.sun.com/JDK-1.0/index.html">JavaSoft</a>
-site. This document assumes that you have some familiarity with the
-basics of compiling and running Java programs.
-<p>
-There are two kinds of applications built using Java.
-<ul>
- <li> <i>Java Applets</i> are graphical components which are run off
- HTML pages via the <tt><APPLET></tt> HTML extention tag.<br><br>
-
- <li> <i>Java Applications (Apps) </i> are stand-alone programs
- that are run by invoking the Java interpreter directly. Like
- C programs, they have a <tt>main()</tt> method which the interpreter
- uses as an entry point.
-</ul>
-The initial emphasis on using Java for client side applets should not
-obscure the fact that Java is a full strength programming language
-which can be used to develop server side stand alone applications,
-including CGI and now FastCGI applications.
-<p>
-The remainder of this document explains how to write and run FastCGI Java
-applications. It also illustrates the conversion of a sample Java CGI program
-to a FastCGI program.
-
-
-
-<H3><A NAME = "S2"> 2. Writing FastCGI applications in Java</A></H3>
-
-Writing a FastCGI application in Java is as simple as writing one in C.
-
-<ol>
- <li> Import the <tt>FCGIInterface</tt> class.
- <li> Perform one-time initialization at the top of the
- <tt>main()</tt> method.
- <li> Create a new <tt>FCGIInterface</tt> object and send it an
- <tt>FCGIaccept()</tt> message in a loop.
- <li> Put the per-request application code inside that loop.
-</ol>
-
-On return from <tt>FCGIaccept()</tt> you can access the request's environment
-variables using <tt>System.getProperty</tt> and perform request-related
-I/O through the standard variables <tt>System.in</tt>,
-<tt>System.out</tt>, and <tt>System.err</tt>.<p>
-
-To illustrate these points, the kit includes <tt>examples/TinyCGI</tt>,
-a CGI Java application, and <tt>examples/TinyFCGI</tt>, the FastCGI
-version of TinyCGI. These programs perform the same
-functions as the C programs <tt>examples/tiny-cgi.c</tt> and
-<tt>examples/tiny-fcgi.c</tt> that are used as examples in the
-<A HREF="fcgi-devel-kit.htm#S3.1.1">FastCGI Developer's Kit document</A>.
-
-
-<h4>A. TinyCGI</h4>
-<PRE>
-class TinyCGI {
- public static void main (String args[]) {
- int count = 0;
- ++count;
- System.out.println("Content-type: text/html\n\n");
- System.out.println("<html>");
- System.out.println(
- "<head><TITLE>CGI-Hello</TITLE></head>");
- System.out.println("<body>");
- System.out.println("<H3>CGI Hello</H3>");
- System.out.println("request number " + count +
- " running on host "
- + System.getProperty<"SERVER_NAME"));
- System.out.println("</body>");
- System.out.println("</html>");
- }
- }
-
-</PRE>
-<h4>B. TinyFCGI</h4>
-<PRE>
-import FCGIInterface;
-
-class TinyFCGI {
- public static void main (String args[]) {
- int count = 0;
- while(new FCGIInterface().FCGIaccept()>= 0) {
- count ++;
- System.out.println("Content-type: text/html\n\n");
- System.out.println("<html>");
- System.out.println(
- "<head><TITLE>FastCGI-Hello Java stdio</TITLE></head>");
- System.out.println("<body>");
- System.out.println("<H3>FastCGI-Hello Java stdio</H3>");
- System.out.println("request number " + count +
- " running on host "
- + System.getProperty<"SERVER_NAME"));
- System.out.println("</body>");
- System.out.println("</html>");
- }
- }
- }
-
-</PRE>
-<h4>C. Running these Examples</h4>
-
-We assume that you have downloaded the JDK and the FastCGI Developer's
-Kit, and that you have a Web server running that can access the
-<tt>fcgi-devel-kit/examples</tt> directory. In all cases where we
-specify paths, we are using relative paths within
-<tt>fcgi-devel-kit</tt> or the JDK which will need to be enlarged to a
-full path by the user.
-
-<h5>Configuring</h5>
-<ol>
- <li> Add your JDK's <tt>java/bin</tt> directory to your Unix <tt>PATH</tt>
- if it isn't there already.<br><br>
-
- <li> Add the directories <tt>fcgi-devel-kit/examples</tt> and
- <tt>fcgi-devel-kit/java/classes</tt> to your Java
- <tt>CLASSPATH</tt>.<br><br>
-
- <li>In your Open Market Secure WebServer configuration file,
- <tt>httpd.config</tt>, add the following two lines:<br><br>
-
- <tt>ExternalAppClass TinyFCGI -host </tt><i>hostName:portNum</i><br>
- <tt>Responder TinyFCGI fcgi-devel-kit/examples/TinyFCGI</tt><br><br>
-
- <ul>
- <li><i>hostName</i> is the name of your host machine.<br>
- <li><i>portNum</i> is the port that you've selected for
- communication between the Web server and the Java application.<br>
- </ul><br>
-
- On other servers you can use <tt>cgi-fcgi</tt> to get a
- similar effect.
-
- <li> Create a soft link <tt>examples/javexe</tt> to the
- <tt>java/bin</tt> directory in your JDK.
- This link is required only to run the
- CGI scripts <tt>examples/TinyCGI.cgi</tt> and
- <tt>examples/TinyFCGI.cgi</tt>, which use it to
- invoke the Java interpreter <tt>java/bin/java</tt>.
- It is not used by FastCGI applications.
-
- <li> You might have to modify <tt>examples/TinyFCGI.cgi</tt> to use a
- Unix shell for which your CLASSPATH is defined.
-</ol>
-
-<h5> Running </h5>
-
-<ul>
- <li> To run TinyFCGI as FastCGI, you invoke the Java interpreter
- with the -D option, giving it the <tt>FCGI_PORT</tt> environment
- variable
- and the same <i>portNum</i> that was used in the Web server
- configuration. The command is:
- <br><br>
- <tt>java -DFCGI_PORT=portNum TinyFCGI</tt>
- <br><br>
- Then point your browser at <tt>fcgi-devel-kit/examples/TinyFCGI</tt>.
- Notice that each time you reload, the count increments.<br><br>
-
- <li> To run TinyCGI, point your browser at
- <tt>fcgi-devel-kit/examples/TinyCGI.cgi</tt> on your host machine.
- Notice that the count does not increment.<br><br>
-
- <li> Finally, you can run TinyFCGI as a straight CGI program by pointing
- your browser at <tt>fcgi-devel-kit/examples/TinyFCGI.cgi.</tt> The results
- are exactly the same as when you ran TinyCGI. Invoking a FastCGI
- program without an <tt>FCGI_PORT</tt> parameter tells the
- FastCGI interface
- to leave the normal CGI environment in place.
-</ul>
-<p>
-Due to gaps in the Java interpreter's support for listening
-sockets, Java FastCGI applications are currently limited to
-being started as external applications. They can't be started and
-managed by the Web server because they are incapable of using
-a listening socket that the Web server creates.
-
-
-
-<H3><A NAME = "S3"> 3. Standard I/O and Application Libraries</A></H3>
-
-As we have seen above, FastCGI for Java offers a redefinition
-of standard I/O corresponding to the the <i>fcgi_stdio</i> functionality.
-It also offers a set of directly callable I/O methods corresponding to
-the <i>fcgiapp</i> C library. To understand where these methods occur
-we need to look briefly at the FastCGI redefinition of standard I/O.<p>
-
-Java defines standard I/O in the <i>java.System</i> class as follows:<p>
-
-public static InputStream in = new BufferedInputStream(new FileInputStream(FileDescriptor.in), 128);<br>
-public static PrintStream out = new PrintStream(new BufferedOutputStream(new FileOutputStream(FileDescriptor.out), 128), true);<br>
-public static PrintStream err = new PrintStream(new BufferedOutputStream(new FileOutputStream(FileDescriptor.err), 128), true);<p>
-
-The File Descriptors <i>in</i>, <i>out</i>, <i>err</i> are constants set to 0, 1 and 2 respectively.<p>
-
-The FastCGI interface redefines <i>java.System in, out</i>, and <i>err</i>
-by replacing the File streams with Socket streams and inserting streams
-which know how to manage the FastCGI protocol between the Socket streams
-and the Buffered streams in the above definitions.
-<p>
-For those cases where the FCGI application needs to bypass the standard I/O
-streams, it can directly access the methods of the FCGI input and output
-streams which roughly correspond to the functions in the C <i>fcgiapp</i>
-library. These streams can be accessed via the <i>request</i> class variable
-in FCGIInterface. Each Request object has instance variables that refer to an
-FCGIInputStream, and to two FCGIOutputStreams associated with that request.
-
-<H3><A NAME = "S4"> 4. Environment Variables</A></H3>
-
-Java does not use the C <i/>environ<i/> list. Nor is there a <i>getenv</i>
-command that reads system environment variables. This is intentional for
-reasons of portability and security. Java has an internal dictionary of
-properties which belongs to the System class. These System properties
-are <i>name/value</i> associations that constitute the Java environment.
-When a Java application starts up, it reads in a file with default properties.
-As we have seen, additional System properties may be inserted by using
-the -D <i>Java</i> command argument.<p>
-
-For CGI, where the Java application is invoked from a .cgi script that,
-in turn, invokes the Java interpreter, this script could read the environment
-and pass the variables to the Java application either by writing a file
-or by creating -D options on the fly. Both of these methods are somewhat
-awkward.<p>
-
-For FastCGI Java applications, the environment variables are obtained from
-the FastCGI web server via <tt>FCGI_PARAMS</tt> records that are sent to the
-application at the start of each request. The FastCGI interface stores the
-original startup properties, combines these with the properties obtained
-from the server, and puts the new set of properties in the System properties
-dictionary. The only parameter that has to be specifically added at startup
-time is the FCGI_PORT parameter for the Socket creation. In the future, we
-expect that even this parameter won't be needed, since its use is due to an
-acknowledged rigidity in the JDK's implementation of sockets.<p>
-
-<H3><A NAME = "S4"> 5. Further examples: EchoFCGI and Echo2FCGI</A></H3>
-
-The next two examples illustrate the points made in the last two sections.
-EchoFCGI and Echo2FCGI both echo user input and display the application's
-environment variables. EchoFCGI reads the user input from System.in, while
-Echo2FCGI reads the user input directly from the intermediate FastCGI input
-stream.
-
-<h4>A. EchoFCGI</h4>
-<pre>
-import FCGIInterface;
-import FCGIGlobalDefs;
-import java.io.*;
-
-class EchoFCGI {
-
- public static void main (String args[]) {
- int status = 0;
- while(new FCGIInterface().FCGIaccept()>= 0) {
- System.out.println("Content-type: text/html\n\n");
- System.out.println("<html>");
- System.out.println(
- "<head%gt;<TITLE>FastCGI echo
- </TITLE></head>");
- System.out.println("<body>");
- System.out.println(
- "<H2>FastCGI echo</H2>");
- System.out.println("<H3>STDIN</H3>");
- for ( int c = 0; c != -1; ) {
- try {
- c = System.in.read();
- } catch(IOException e) {
- System.out.println(
- "<br><b>SYSTEM EXCEPTION");
- Runtime rt = Runtime.getRuntime();
- rt.exit(status);
- }
- if (c != -1) {
- System.out.print((char)c);
- }
- }
- System.out.println(
- "<H3>Environment Variables:</H3>");
-
- System.getProperties().list(System.out);
- System.out.println("</body>");
- System.out.println("</html>");
- }
- }
- }
-</pre>
-<h4>B. Echo2FCGI</h4>
-<pre>
-import FCGIInterface;
-import FCGIGlobalDefs;
-import FCGIInputStream;
-import FCGIOutputStream;
-import FCGIMessage;
-import FCGIRequest;
-import java.io.*;
-
-class Echo2FCGI {
-
- public static void main (String args[]) {
- int status = 0;
- FCGIInterface intf = new FCGIInterface();
- while(intf.FCGIaccept()>= 0) {
- System.out.println("Content-type: text/html\n\n");
- System.out.println("<html>");
- System.out.println(
- "<head><TITLE>FastCGI echo
- </TITLE></head>");
- System.out.println("<body>");
- System.out.println("<H2>FastCGI echo</H2>");
- System.out.println("<H3>STDIN:</H3">);
- for ( int c = 0; c != -1; ) {
- try {
- c = intf.request.inStream.read();
- } catch(IOException e) {
- System.out.println(
- "<br><b>SYSTEM EXCEPTION");
- Runtime rt = Runtime.getRuntime();
- rt.exit(status);
- }
- if (c != -1) {
- System.out.print((char)c);
- }
- }
- System.out.println(
- "<H3>Environment Variables:</H3>");
-
- System.getProperties().list(System.out);
- System.out.println(<"/body>");
- System.out.println("</html>");
- }
- }
- }
-</pre>
-<h4>C. Running these Examples</h4>
-
-<h5>Configuring</h5>
-
-As with TinyFCGI, you need to configure the web server to recognize these
-two FastCGI applications. Your configuration now looks like this:<p>
-<pre>
-ExternalAppClass java1 -host hostname:portNum
-Responder java1 fcgi-devel-kit/examples/TinyFCGI
-ExternalAppClass java2 -host hostname:portNumA
-Responder java2 fcgi-devel-kit/examples/EchoFCGI
-ExternalAppClass java3 -host hostname:porNumB
-Responder java3 fcgi-devel-kit/examples/Echo2FCGI
-</pre>
-<p>
-Note that the application classes and port numbers are different for each
-application.
-
-<h5>Running</h5>
-
-As with TinyFCGI, you need to run these programs with the -D option
-using FCGI_PORT and the appropriate port number.
-
-To get some data for standard input we have created two html pages with
-forms that use a POST method. These are echo.html and echo2.html. You must
-edit these .html files to expand the path to <i>fcgi-devel-kit/examples</i>
-to a full path. Once the appropriate Java program is running, point your browser at the corresponding HTML page, enter some data and select the <i>go_find</i> button.
-
-
-<H3><A NAME = "S6"> 6. FastCGI Java Classes</A></H3>
-
-The Java FastCGI classes are included in both source and byte code format in
-<i>fcgi-devel-kit/java/src</i> and :<i>fcgi-devel-kit/java/classes</i>
-respectively. The following is a brief description of these classes:<p>
-
-<dl>
-<dt><i>FCGIInterface</i><dd> This class contains the FCGIaccept method called
- by the FastCGI user application. This method sets up the appropriate
- FastCGI environment for communication with the web server and manages
- FastCGI requests.<br>
-
- <dt><i>FCGIInputStream</i><dd> This input stream manages FastCGI
- internal buffers to ensure that the user gets all of the FastCGI
- messages associated with a request. It uses FCGIMessage objects
- to interpret these incoming messages.<br>
-
- <dt><i>FCGIOutputStream</i><dd> This output stream manages FastCGI
- internal buffers to send user data back to the web server
- and to notify the server of various FCGI protocol conditions.
- It uses FCGIMessage objects to format outgoing FastCGI messages.<br>
-
-<dt><i>FCGIMessage</i><dd> This is the only class that understands the
- actual structure of the FastCGI messages. It interprets incoming
- FastCGI records and constructs outgoing ones..<br>
-
-<dt><i>FCGIRequest</i><dd>This class currently contains data fields
- used by FastCGI to manage user requests. In a multi-threaded
- version of FastCGI, the role of this class will be expanded.<br>
-
-<dt><i>FCGIGlobalDefs</i><dd>This class contains definitions of FastCGI
- constants.
-</dl>
-<HR>
-<ADDRESS><A HREF="mailto:harris@openmarket.com">Steve Harris // harris@openmarket.com</A></ADDRESS>
+++ /dev/null
-Understanding FastCGI Application Performance
-/fastcgi/words
-fcgi-hd.gif
-[FastCGI]
-<center>Understanding FastCGI Application Performance</center>
-
-<!--Copyright (c) 1996 Open Market, Inc. -->
-<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
-<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
-
-<center>
-Mark R. Brown<br>
-Open Market, Inc.<br>
-<p>
-
-10 June 1996<br>
-</center>
-<p>
-
-<h5 align=center>
-Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
- MA 02142 U.S.A.<br>
-Tel: 617-621-9500 Fax: 617-621-1703 URL:
- <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
-$Id: fcgi-perf.gut,v 1.1 1997/09/16 15:36:26 stanleyg Exp $ <br>
-</h5>
-<hr>
-
-<ul type=square>
- <li><a HREF = "#S1">1. Introduction</a>
- <li><a HREF = "#S2">2. Performance Basics</a>
- <li><a HREF = "#S3">3. Caching</a>
- <li><a HREF = "#S4">4. Database Access</a>
- <li><a HREF = "#S5">5. A Performance Test</a>
- <ul type=square>
- <li><a HREF = "#S5.1">5.1 Application Scenario</a>
- <li><a HREF = "#S5.2">5.2 Application Design</a>
- <li><a HREF = "#S5.3">5.3 Test Conditions</a>
- <li><a HREF = "#S5.4">5.4 Test Results and Discussion</a>
- </ul>
- <li><a HREF = "#S6">6. Multi-threaded APIs</a>
- <li><a HREF = "#S7">7. Conclusion</a>
-</ul>
-<p>
-
-<hr>
-
-
-<h3><a name = "S1">1. Introduction</a></h3>
-
-
-Just how fast is FastCGI? How does the performance of a FastCGI
-application compare with the performance of the same
-application implemented using a Web server API?<p>
-
-Of course, the answer is that it depends upon the application.
-A more complete answer is that FastCGI often wins by a significant
-margin, and seldom loses by very much.<p>
-
-Papers on computer system performance can be laden with complex graphs
-showing how this varies with that. Seldom do the graphs shed much
-light on <i>why</i> one system is faster than another. Advertising copy is
-often even less informative. An ad from one large Web server vendor
-says that its server "executes web applications up to five times
-faster than all other servers," but the ad gives little clue where the
-number "five" came from.<p>
-
-This paper is meant to convey an understanding of the primary factors
-that influence the performance of Web server applications and to show
-that architectural differences between FastCGI and server APIs often
-give an "unfair" performance advantage to FastCGI applications. We
-run a test that shows a FastCGI application running three times faster
-than the corresponding Web server API application. Under different
-conditions this factor might be larger or smaller. We show you what
-you'd need to measure to figure that out for the situation you face,
-rather than just saying "we're three times faster" and moving on.<p>
-
-This paper makes no attempt to prove that FastCGI is better than Web
-server APIs for every application. Web server APIs enable lightweight
-protocol extensions, such as Open Market's SecureLink extension, to be
-added to Web servers, as well as allowing other forms of server
-customization. But APIs are not well matched to mainstream applications
-such as personalized content or access to corporate databases, because
-of API drawbacks including high complexity, low security, and
-limited scalability. FastCGI shines when used for the vast
-majority of Web applications.<p>
-
-
-
-<h3><a name = "S2">2. Performance Basics</a></h3>
-
-
-Since this paper is about performance we need to be clear on
-what "performance" is.<p>
-
-The standard way to measure performance in a request-response system
-like the Web is to measure peak request throughput subject to a
-response time constriaint. For instance, a Web server application
-might be capable of performing 20 requests per second while responding
-to 90% of the requests in less than 2 seconds.<p>
-
-Response time is a thorny thing to measure on the Web because client
-communications links to the Internet have widely varying bandwidth.
-If the client is slow to read the server's response, response time at
-both the client and the server will go up, and there's nothing the
-server can do about it. For the purposes of making repeatable
-measurements the client should have a high-bandwidth communications
-link to the server.<p>
-
-[Footnote: When designing a Web server application that will be
-accessed over slow (e.g. 14.4 or even 28.8 kilobit/second modem)
-channels, pay attention to the simultaneous connections bottleneck.
-Some servers are limited by design to only 100 or 200 simultaneous
-connections. If your application sends 50 kilobytes of data to a
-typical client that can read 2 kilobytes per second, then a request
-takes 25 seconds to complete. If your server is limited to 100
-simultaneous connections, throughput is limited to just 4 requests per
-second.]<p>
-
-Response time is seldom an issue when load is light, but response
-times rise quickly as the system approaches a bottleneck on some
-limited resource. The three resources that typical systems run out of
-are network I/O, disk I/O, and processor time. If short response time
-is a goal, it is a good idea to stay at or below 50% load on each of
-these resources. For instance, if your disk subsystem is capable of
-delivering 200 I/Os per second, then try to run your application at
-100 I/Os per second to avoid having the disk subsystem contribute to
-slow response times. Through careful management it is possible to
-succeed in running closer to the edge, but careful management is both
-difficult and expensive so few systems get it.<p>
-
-If a Web server application is local to the Web server machine, then
-its internal design has no impact on network I/O. Application design
-can have a big impact on usage of disk I/O and processor time.<p>
-
-
-
-<h3><a name = "S3">3. Caching</a></h3>
-
-
-It is a rare Web server application that doesn't run fast when all the
-information it needs is available in its memory. And if the
-application doesn't run fast under those conditions, the possible
-solutions are evident: Tune the processor-hungry parts of the
-application, install a faster processor, or change the application's
-functional specification so it doesn't need to do so much work.<p>
-
-The way to make information available in memory is by caching. A
-cache is an in-memory data structure that contains information that's
-been read from its permanent home on disk. When the application needs
-information, it consults the cache, and uses the information if it is
-there. Otherwise is reads the information from disk and places a copy
-in the cache. If the cache is full, the application discards some old
-information before adding the new. When the application needs to
-change cached information, it changes both the cache entry and the
-information on disk. That way, if the application crashes, no
-information is lost; the application just runs more slowly for awhile
-after restarting, because the cache doesn't improve performance
-when it is empty.<p>
-
-Caching can reduce both disk I/O and processor time, because reading
-information from disk uses more processor time than reading it from
-the cache. Because caching addresses both of the potential
-bottlenecks, it is the focal point of high-performance Web server
-application design. CGI applications couldn't perform in-memory
-caching, because they exited after processing just one request. Web
-server APIs promised to solve this problem. But how effective is the
-solution?<p>
-
-Today's most widely deployed Web server APIs are based on a
-pool-of-processes server model. The Web server consists of a parent
-process and a pool of child processes. Processes do not share memory.
-An incoming request is assigned to an idle child at random. The child
-runs the request to completion before accepting a new request. A
-typical server has 32 child processes, a large server has 100 or 200.<p>
-
-In-memory caching works very poorly in this server model because
-processes do not share memory and incoming requests are assigned to
-processes at random. For instance, to keep a frequently-used file
-available in memory the server must keep a file copy per child, which
-wastes memory. When the file is modified all the children need to be
-notified, which is complex (the APIs don't provide a way to do it).<p>
-
-FastCGI is designed to allow effective in-memory caching. Requests
-are routed from any child process to a FastCGI application server.
-The FastCGI application process maintains an in-memory cache.<p>
-
-In some cases a single FastCGI application server won't
-provide enough performance. FastCGI provides two solutions:
-session affinity and multi-threading.<p>
-
-With session affinity you run a pool of application processes and the
-Web server routes requests to individual processes based on any
-information contained in the request. For instance, the server can
-route according to the area of content that's been requested, or
-according to the user. The user might be identified by an
-application-specific session identifier, by the user ID contained in
-an Open Market Secure Link ticket, by the Basic Authentication user
-name, or whatever. Each process maintains its own cache, and session
-affinity ensures that each incoming request has access to the cache
-that will speed up processing the most.<p>
-
-With multi-threading you run an application process that is designed
-to handle several requests at the same time. The threads handling
-concurrent requests share process memory, so they all have access to
-the same cache. Multi-threaded programming is complex -- concurrency
-makes programs difficult to test and debug -- but with FastCGI you can
-write single threaded <i>or</i> multithreaded applications.<p>
-
-
-
-<h3><a name = "S4">4. Database Access</a></h3>
-
-
-Many Web server applications perform database access. Existing
-databases contain a lot of valuable information; Web server
-applications allow companies to give wider access to the information.<p>
-
-Access to database management systems, even within a single machine,
-is via connection-oriented protocols. An application "logs in" to a
-database, creating a connection, then performs one or more accesses.
-Frequently, the cost of creating the database connection is several
-times the cost of accessing data over an established connection.<p>
-
-To a first approximation database connections are just another type of
-state to be cached in memory by an application, so the discussion of
-caching above applies to caching database connections.<p>
-
-But database connections are special in one respect: They are often
-the basis for database licensing. You pay the database vendor
-according to the number of concurrent connections the database system
-can sustain. A 100-connection license costs much more than a
-5-connection license. It follows that caching a database connection
-per Web server child process is not just wasteful of system's hardware
-resources, it could break your software budget.<p>
-
-
-
-<h3><a name = "S5">5. A Performance Test</a></h3>
-
-
-We designed a test application to illustrate performance issues. The
-application represents a class of applications that deliver
-personalized content. The test application is quite a bit simpler
-than any real application would be, but still illustrates the main
-performance issues. We implemented the application using both FastCGI
-and a current Web server API, and measured the performance of each.<p>
-
-<h4><a name = "S5.1">5.1 Application Scenario</a></h4>
-
-The application is based on a user database and a set of
-content files. When a user requests a content file, the application
-performs substitutions in the file using information from the
-user database. The application then returns the modified
-content to the user.<p>
-
-Each request accomplishes the following:<p>
-
-<ol>
- <li>authentication check: The user id is used to retrieve and
- check the password.<p>
-
- <li>attribute retrieval: The user id is used to retrieve all
- of the user's attribute values.<p>
-
- <li>file retrieval and filtering: The request identifies a
- content file. This file is read and all occurrences of variable
- names are replaced with the user's corresponding attribute values.
- The modified HTML is returned to the user.<p>
-</ol>
-
-Of course, it is fair game to perform caching to shortcut
-any of these steps.<p>
-
-Each user's database record (including password and attribute
-values) is approximately 100 bytes long. Each content file is 3,000
-bytes long. Both database and content files are stored
-on disks attached to the server platform.<p>
-
-A typical user makes 10 file accesses with realistic think times
-(30-60 seconds) between accesses, then disappears for a long time.<p>
-
-
-<h4><a name = "S5.2">5.2 Application Design</a></h4>
-
-The FastCGI application maintains a cache of recently-accessed
-attribute values from the database. When the cache misses
-the application reads from the database. Because only a small
-number of FastCGI application processes are needed, each process
-opens a database connection on startup and keeps it open.<p>
-
-The FastCGI application is configured as multiple application
-processes. This is desirable in order to get concurrent application
-processing during database reads and file reads. Requests are routed
-to these application processes using FastCGI session affinity keyed on
-the user id. This way all a user's requests after the first hit in
-the application's cache.<p>
-
-The API application does not maintain a cache; the API application has
-no way to share the cache among its processes, so the cache hit rate
-would be too low to make caching pay. The API application opens and
-closes a database connection on every request; keeping database
-connections open between requests would result in an unrealistically
-large number of database connections open at the same time, and very
-low utilization of each connection.<p>
-
-
-<h4><a name = "S5.3">5.3 Test Conditions</a></h4>
-
-The test load is generated by 10 HTTP client processes. The processes
-represent disjoint sets of users. A process makes a request for a
-user, then a request for a different user, and so on until it is time
-for the first user to make another request.<p>
-
-For simplicity the 10 client processes run on the same machine
-as the Web server. This avoids the possibility that a network
-bottleneck will obscure the test results. The database system
-also runs on this machine, as specified in the application scenario.<p>
-
-Response time is not an issue under the test conditions. We just
-measure throughput.<p>
-
-The API Web server is in these tests is Netscape 1.1.<p>
-
-
-<h4><a name = "S5.4">5.4 Test Results and Discussion</a></h4>
-
-Here are the test results:<p>
-
-<ul>
-<pre>
- FastCGI 12.0 msec per request = 83 requests per second
- API 36.6 msec per request = 27 requests per second
-</pre>
-</ul>
-
-Given the big architectural advantage that the FastCGI application
-enjoys over the API application, it is not surprising that the
-FastCGI application runs a lot faster. To gain a deeper
-understanding of these results we measured two more conditions:<p>
-
-<ul>
- <li>API with sustained database connections. If you could
- afford the extra licensing cost, how much faster would
- your API application run?<p>
-
-<pre>
- API 16.0 msec per request = 61 requests per second
-</pre>
-
- Answer: Still not as fast as the FastCGI application.<p>
-
- <li>FastCGI with cache disabled. How much benefit does the
- FastCGI application get from its cache?<p>
-
-<pre>
- FastCGI 20.1 msec per request = 50 requests per second
-</pre>
-
- Answer: A very substantial benefit, even though the database
- access is quite simple.<p>
-</ul>
-
-What these two extra experiments show is that if the API and FastCGI
-applications are implemented in exactly the same way -- caching
-database connections but not caching user profile data -- the API
-application is slightly faster. This is what you'd expect, since the
-FastCGI application has to pay the cost of inter-process
-communication not present in the API application.<p>
-
-In the real world the two applications would not be implemented in the
-same way. FastCGI's architectural advantage results in much higher
-performance -- a factor of 3 in this test. With a remote database
-or more expensive database access the factor would be higher.
-With more substantial processing of the content files the factor
-would be smaller.<p>
-
-
-
-<h3><a name = "S6">6. Multi-threaded APIs</a></h3>
-
-
-Web servers with a multi-threaded internal structure (and APIs to
-match) are now starting to become more common. These servers don't
-have all of the disadvantages described in Section 3. Does this mean
-that FastCGI's performance advantages will disappear?<p>
-
-A superficial analysis says yes. An API-based application in a
-single-process, multi-threaded server can maintain caches and database
-connections the same way a FastCGI application can. The API-based
-application does not pay for inter-process communication, so the
-API-based application will be slightly faster than the FastCGI
-application.<p>
-
-A deeper analysis says no. Multi-threaded programming is complex,
-because concurrency makes programs much more difficult to test and
-debug. In the case of multi-threaded programming to Web server APIs,
-the normal problems with multi-threading are compounded by the lack of
-isolation between different applications and between the applications
-and the Web server. With FastCGI you can write programs in the
-familiar single-threaded style, get all the reliability and
-maintainability of process isolation, and still get very high
-performance. If you truly need multi-threading, you can write
-multi-threaded FastCGI and still isolate your multi-threaded
-application from other applications and from the server. In short,
-multi-threading makes Web server APIs unusable for practially all
-applications, reducing the choice to FastCGI versus CGI. The
-performance winner in that contest is obviously FastCGI.<p>
-
-
-
-<h3><a name = "S7">7. Conclusion</a></h3>
-
-
-Just how fast is FastCGI? The answer: very fast indeed. Not because
-it has some specially-greased path through the operating system, but
-because its design is well matched to the needs of most applications.
-We invite you to make FastCGI the fast, open foundation for your Web
-server applications.<p>
-
-
-
-<hr>
-<a href="http://www.openmarket.com/"><IMG SRC="omi-logo.gif" ALT="OMI Home Page"></a>
-
-<address>
-© 1995, Open Market, Inc. / mbrown@openmarket.com
-</address>
-
-</body>
-</html>
+++ /dev/null
-Integrating FastCGI with Perl-5
-/fastcgi/words
-fcgi-hd.gif
-[FastCGI]
-<center>Integrating FastCGI with Perl-5</center>
-
-<!--Copyright (c) 1996 Open Market, Inc. -->
-<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
-<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
-
-<h5 align=center>
-Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
- MA 02142 U.S.A.<br>
-Tel: 617-949-7000 URL:
- <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
-$Id: fcgi-perl.gut,v 1.1 1997/09/16 15:36:26 stanleyg Exp $ <br>
-</h5>
-<hr>
-
-<ul type=square>
- <li><a HREF = "#S1">1. Introduction</a>
- <li><a HREF = "#S2">2. Perl with sfio and an FCGI module</a>
- <li><a HREF = "#S3">3. Perl with fcgi_stdio and an FCGI module</a>
- <ul type=square>
- <li><a HREF = "#S3.1">3.1 Basic recipe</a>
- <li><a HREF = "#S3.2">3.2 Semi-advanced recipe</a>
- <li><a HREF = "#S3.3">3.3 Advanced recipe</a>
- </ul>
- <li><a HREF = "#S4">4. Writing FastCGI applications in Perl</a>
-</ul>
-
-
-<H3><A NAME = "S1"> 1. Introduction</A></H3>
-Perl (Practical Extraction and Report Language) is a scripting language that
-is often used for CGI programming. Perl is freely available as a
-source kit.<p>
-
-FastCGI has been integrated with Perl in two different ways:
-<ol>
- <li>By writing a module that plugs into any Perl interpreter that's
- been built with sfio, a stdio alternative from AT&T.
- <li>By writing a module that plugs into any Perl interpreter that's
- been built with FastCGI's fcgi_stdio library
- layering over stdio.
-</ul>
-The first approach, implemented by Sven Verdoolaege
-(skimo@breughel.ufsia.ac.be), is probably the better of the two,
-since sfio is a generally useful addition to Perl.
-The second approach, implemented by engineers at Open Market,
-predates the availability of an sfio-integrated
-Perl and demonstrates that the fcgi_stdio library
-can be used with a substantial C application.<p>
-
-The two approaches
-are compatible at the Perl source code level; a Perl
-application developed using
-one approach can be run using the other. And both approaches
-result in a general-purpose Perl interpreter, not a Perl interpreter
-that's only usable for FastCGI applications.<p>
-
-This memo documents both approaches and explains a small
-Perl FastCGI application.<p>
-
-
-<h3><a name ="S2"> 2. Perl with sfio and an FCGI module</a></h3>
-
-As of release 5 patch 3 subpatch 2 (5.003.02), Perl has announced an optional
-support for sfio (safe/fast string/file I/O), which is an alternative
-to stdio that AT&T distributes freely. An advantage of sfio over stdio
-is that sfio provides the ability to implement
-new stream classes that don't simply transfer sequential bytes to or from
-a file descriptor. This flexibility is exactly what FastCGI needs in order
-to implement the standard I/O streams in a manner that's
-transparent to applications.<p>
-
-Perl interpreters incorporating sfio are not widely available in
-binary form, so most likely you'll have to build your own.
-Your build should go smoothly if you follow the instructions
-below. The instructions assume:<p>
-
-<ul>
- <li>You are building Perl 5.0 patch level 3 subpatch level 2 (5.003.02)
- or higher. That's the first Perl release to support sfio.<p>
-</ul>
-<P>
-
-Follow these steps to build a Perl with sfio:<p>
-
-<ol>
- <li>Obtain sfio source code from
- <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc">
- ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc</a><p>
-
- <li>Unpack the tar file using <tt>tar xvf</tt> command. <EM>$sfio</EM>
- will be used as a shorthand for the directory in which sfio package
- is installed.<p>
-
- <li>Update your $PATH variable as specified in <tt>$sfio/README</tt> and
- run <tt>make</tt> command in the <tt>$sfio/src/lib/sfio</tt> subdirectory.<p>
-
- <li>Rename or delete the file <tt>$sfio/include/stdio.h</tt>, since it may
- interfere in the further build process.<p>
-
- <li>Obtain Perl source (version 5 subversion 003 patchlevel 2 or higher) from
- <a href="http://fohnix.metronet.com/perlinfo/source/5.0/unsupported">
- http://fohnix.metronet.com/perlinfo/source/5.0/unsupported</a><p>
-
- <li>Unpack the tar file using <tt>tar xvf</tt> command. <EM>$perl</EM> is
- used as a shorthand for the directory that is created.<p>
-
- <li>Configure, build, and install Perl as follows:
-
-<pre>
-% cd $perl
-% ./Configure -Duseperlio -Dusesfio
-% make
-% make test
-% make install
-</pre><p>
-
-There are certain Configure questions that must be answered
-differently when building Perl with sfio:<p>
-
-<DL>
-
-<DT><EM>Perl5 can now use alternate file IO mechanisms to ANSI stdio.
-However these are experimental and may cause problems with some
-extension modules.
-Use stdio as with previous versions? [y] </EM></DT>
-<DD>
-You should answer no.
-</DD><P>
-
-<DT><EM>Any additional cc flags?</EM></DT>
-<DD>
-You should use the following cc flags along with any defaults that Perl
-Configure supplied:
-<UL>
-<LI> <strong>-I<em>$sfio</em>/include</strong>
-</UL>
-</DD><P>
-
-<DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
-<DD>
-You should specify the following <tt>ld</tt> flags:
-<UL>
-<LI> <strong>-L<em>$sfio</em>/lib</strong>
-</UL>
-</DD><P>
-
-<DT><EM>Additional Libraries:</EM></DT>
-<DD>
-Check that <strong>-lsfio</strong> is one of the specified libraries. Press
-return key to continue.
-</DD><P>
-</DL>
-
-<b>NOTE</b>: If you did not install Perl as a root user, make sure to
-correctly set environment variable <tt>PERL5LIB</tt> to indicate the location
-of Perl libraries. For example, if you installed Perl binary into the
-<tt>$INSTALL</tt> subdirectory and you are running Solaris, the following
-will set your proper library path:
-<pre>
-% setenv PERL5LIB $INSTALL/lib:$INSTALL/lib/sun4-solaris/perl5.003_02
-</pre>
-</ul>
-<p>
-
- <li>Obtain Perl/Sfio module for FastCGI support from
- <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO">
- ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO</a><p>
-
- <li>Unpack FCGI module using <tt>tar</tt> command. We use <tt>$sfiomod</tt>
- to denote the subdirectory that is created in the process.<p>
-
- <li>Build and install the module with the following commands:
-<pre>
-% cd $sfiomod
-% $INSTALL/bin/perl Makefile.PL
-% make
-% make test
-% make install
-</pre>
-</ol>
-
-
-<H3><a NAME = "S3">3. Perl with fcgi_stdio and an FCGI module</a></H3>
-
-<H4><a NAME = "S3.1">3.1 Basic recipe</a></H4>
-
-Here are the assumptions embedded in the following recipe:
-<UL>
-
-<LI>You are building Perl 5.0 Patch 2 (5.002) or higher, since
-all examples that are provided are based on that release.
-<P></P>
-
-<LI>You have gcc version 2.7 installed on your system, and use it in the
-build. gcc is convenient because it supports the <tt>-include</tt>
-command-line option that instructs the C preprocessor to include a specific
-file before processing any other include files. This allows you to include
-<tt>fcgi_stdio.h</tt> without modifying Perl source files. (The reason for
-specifying gcc version 2.7 is that I have experienced bad behavior with an
-earlier version and the <tt>-include</tt> flag -- the C preprocessor died
-with SIGABRT.)
-<P></P>
-
-<LI> <EM>$fcgi</EM> is used as shorthand for the full path of the FastCGI
-developers kit.
-</UL>
-<P>
-If those are valid assumptions, follow these steps:
-<OL>
-<LI> Pull the Perl source kit from
-<A HREF="http://www.metronet.com/perlinfo/src/latest.tar.gz">
-http://www.metronet.com/perlinfo/src/latest.tar.gz</A>
-<P>
-There are good sources of information on Perl at:
-<UL>
-<LI> <A HREF="http://www.perl.com/">http://www.perl.com/</A>
-<LI> <A HREF="http://www.metronet.com/perlinfo/">http://www.metronet.com/perlinfo/</A>
-</UL>
-</P>
-</A>
-<LI> Unpack the tar file in the parent directory of the FastCGI kit
-directory, so that the perl directory is a sibling of <tt>fcgi-devel-kit</tt>.
-<EM>$perl</EM> is used as shorthand for the full path of the directory
-in which Perl is installed.
-<p>
-<LI> Copy the version specific and the common files from
-<tt>fcgi-devel-kit/perl-5</tt> into the Perl-5 kit.
-<PRE>
-> cd $perl
-> mv perl.c perl.c.orig
-> mv proto.h proto.h.orig
-> mv Configure Configure.orig
-> cp -r ../fcgi-devel-kit/perl-5/perl5.002/* .
-> cp -r ../fcgi-devel-kit/perl-5/common/* .
-</PRE>
-<P>
-The files you are copying contain the Perl-5 FCGI extension, some
-files modified from the distribution, and a script to simplify the
-configuration process.
-</P>
-<LI> Set environment variables.
-The Perl-5 FastCGI configuration process requires that the environment
-variable <TT>FCGIDIR</TT> be set to the top level directory of the FastCGI
-development kit.
-<PRE>
-> setenv FCGIDIR <EM>$fcgi</EM>
-</PRE>
-If you do not want to use <tt>gcc</tt> to build Perl you can set the
-environment variable <TT>CC</TT> to the desired compiler. For example:
-<PRE>
-> setenv CC gcc2.7
-</PRE>
-By default Perl's installation prefix is /usr/local, so binaries get
-installed in /usr/local/bin, library files get installed into
-/usr/local/lib/perl, etc. If you want to specify a different installation
-prefix set the environment variable <tt>PERL_PREFIX</tt>.
-<PRE>
-> setenv PERL_PREFIX /usr/local/perl5-fcgi
-</PRE>
-<LI> Run fcgi-configure.
-<PRE>
-> ./fcgi-configure
-</PRE>
-<P>
-<TT>fcgi-configure</TT> is a wrapper around Perl's <tt>Configure</tt> script.
-It sets some variables according the the value of some environment variables,
-and runs Perl's <tt>Configure</tt> script
-in such a way that it does not prompt the
-user for any input. 90% of the time this should work without a problem.
-If for some reason this does not work for you, you'll have to
-follow the steps in the next section.<p>
-<LI> Run make.
-<PRE>
-> make
-</PRE>
-<LI> Install the newly built Perl-5.
-<PRE>
-> make install
-</PRE>
-</OL><p>
-
-
-<H4><a NAME = "S3.2">3.2 Semi-advanced recipe</a></H4>
-
-If you do not have experience configuring and building Perl, you
-should find someone who does. Perl can be pretty intimidating to configure
-since it asks you a large number of irrelevant-seeming
-questions that you won't know how to answer.<p>
-<P>
-<OL>
-<LI>Go into the top level directory of the Perl distribution and run
-<tt>Configure</tt>.
-<PRE>
-> cd $perl
-> ./Configure
-</PRE>
-<LI>
-There are some questions that you are going to
-have to answer differently when building FastCGI into Perl.
-These are described below:
-<P></P>
-<DL>
-<DT><EM>Use which C compiler?</EM></DT>
-<DD>
-You should specify <tt>gcc</tt>.
-</DD>
-<P></P>
-<DT><EM>Any additional cc flags?</EM></DT>
-<DD>
-You should use the following cc flags along with any defaults that Perl
-Configure supplied:
-<UL>
-<LI> <strong>-I<em>$fcgi</em>/include</strong>
-<LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong>
-</UL>
-This assumes you are using GCC.
-</DD>
-<P></P>
-
-<DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
-<DD>
-You should specify the following <tt>ld</tt> flags:
-<UL>
-<LI> <strong>-L<em>$fcgi</em>/libfcgi</strong>
-</UL
-</DD>
-<P></P>
-
-<DT><EM>Additional Libraries:</EM></DT>
-<DD>
-add <strong>-lfcgi</strong> to the list of additional libraries.
-It should be added before -lc.
-</DD>
-<P></P>
-
-<DT><EM>What extensions do you wish to load dynamically?</EM></DT>
-<DD>
-If you can support dynamic extensions, <tt>Configure</tt>
-will ask which of the
-supplied extensions should be loaded dynamically. Since we copied the FCGI
-extension into the Perl source directory it should be one of the ones in the
-default list. If you want FCGI to be dynamically loaded you should specify
-it here, otherwise leave it out.
-</DD>
-<P></P>
-
-<DT><EM>What extensions do you wish to load statically?</EM></DT>
-<DD>
-If you do not support Dynamic extensions this is the only question about
-extensions you would get asked. You should specify FCGI here if you did not
-get asked about dynamic extensions (or did not specify FCGI as a dynamic
-extension).
-</DD>
-</DL>
-<P></P>
-<LI> Copy in the new <tt>proto.h</tt>.
-<P>
-The file proto.h has some macros that conflict with the FastCGI macros.
-The version of <tt>proto.h</tt> supplied in the FastCGI kit
-includes these changes:<p>
-<UL>
-<LI> At the beginning of the file it adds the following lines:
-<PRE>
-#ifdef _FCGI_STDIO
-#undef printf
-#endif
-</PRE>
-<LI> At the bottom it adds:
-<PRE>
-#ifdef _FCGI_STDIO
-#define printf FCGI_printf
-#endif
-</PRE>
-</UL>
-<LI> Copy in the new <tt>perl.c</tt>.
-<P>
-Perl-5.002 has a bug in <tt>perl.c</tt> that has a great
-chance of getting exercised
-with FastCGI. A fix has been sumbitted to the Perl developers and hopefully
-it'll make it into perl-5.003. It was a one line fix, here is a diff for the
-curious:
-<PRE>
-*** perl.c 1996/03/15 17:10:10 1.1
---- perl.c 1996/03/15 17:11:23
-***************
-*** 405,410 ****
---- 405,411 ----
- if (e_fp) {
- if (Fflush(e_fp) || ferror(e_fp) || fclose(e_fp))
- croak("Can't write to temp file for -e: %s", Strerror(errno));
-+ e_fp = Nullfp;
- argc++,argv--;
- scriptname = e_tmpname;
- }
-</PRE>
-Pretty straightforward.<p>
-<LI> Build and install Perl.
-<PRE>
-> make
-<EM>[...]</EM>
-> make install
-</PRE>
-</UL>
-</P>
-<H4><a NAME = "S3.3">3.3 Advanced recipe</a></H4>
-
-<P>
-If you already have a Perl-5 package that has been configured, and you do
-not really want to re-run Configure, you can take the following steps.
-</P>
-<P ALIGN=CENTER><STRONG>THIS IS NOT RECOMMENDED</STRONG></P>
-<P>
-Edit config.sh with your favorite editor and modify the following lines:
-<DL>
-<DT><EM>cc</EM></DT>
-<DD>
-Change to use gcc if you are not using it already.
-</DD>
-<P></P>
-
-<DT><EM>ccflags</EM> AND <EM>cppflags</EM></DT>
-<DD>
-Add the following flags:
-<UL>
-<LI> <strong>-I<em>$fcgi</em>/include</strong>
-<LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong>
-</UL>
-This assumes you are using GCC. See the above section on assumptions
-</DD>
-<P></P>
-
-<DT><EM>extensions</EM> AND <EM>known_extensions</EM></DT>
-<DD>
-Add FCGI to the list of extensions
-</DD>
-<P></P>
-
-<DT><EM>ldflags</EM></DT>
-<DD>
-Add -L $fcgi/libfcgi to the list.
-</DD>
-<P></P>
-
-<DT><EM>libs</EM></DT>
-<DD>
-Add -lfcgi to the list of libraries, should be added before -lc.
-</DD>
-<P></P>
-<DT><EM>static_ext</EM><STRONG> or </STRONG><EM>dynamic_ext</EM></DT>
-<DD>
-Add FCGI to the list of statically or dynamically loaded extensions.
-</DD>
-<P></P>
-<DT><EM>d_stdio_cnt_lval, d_stdio_ptr_lval, d_stdiobase, d_stdstdio</EM></DT>
-<DL>
-Change all of these to undef.
-</DL>
-<P>
-One you have edited config.sh you should do a "make Makefile depend all".
-If you're paranoid like me you may want to do a "make clean" first.
-</P>
-
-
-<H3><A NAME = "S4"> 4. Writing FastCGI applications in Perl</A></H3>
-<P>
-The Perl program <tt>examples/tiny-perl-fcgi</tt> performs the same function as
-the C program <tt>examples/tiny-fcgi</tt> that's used as an example in the
-<A HREF="fcgi-devel-kit.html#S3.1.1">FastCGI Developer's Kit document</A>.
-Here's what the Perl version looks like:
-</P>
-<pre>
-#!./perl
-use FCGI;
-$count = 0;
-while(FCGI::accept() >= 0) {
- print("Content-type: text/html\r\n\r\n",
- "<title>FastCGI Hello! (Perl)</title>\n",
- "<h1>FastCGI Hello! (Perl)</h1>\n",
- "Request number ", $++count,
- " running on host <i>$ENV('SERVER_NAME')</i>");
-}
-</pre>
-
-If you've built Perl according to the recipe and you have a Web server set
-up to run FastCGI applications, load the FastCGI Developer's Kit Index Page
-in that server and run this Perl application now.<p>
-
-The script invokes Perl indirectly via the symbolic link
-<tt>examples/perl</tt>. It does this because HP-UX has a limit of 32
-characters for the first line of a command-interpreter file such as
-<tt>examples/tiny-perl-fcgi</tt>. If you run on HP-UX you won't want
-to sprinkle symbolic links to perl everywhere, so you should
-choose a <tt>PERL_PREFIX</tt> shorter than <tt>/usr/local/perl5-fcgi</tt>.<p>
-
-You need to be aware of the following bug. If the
-initial environment to a FastCGI Perl application is empty (contains
-no name-value pairs) then when the first call to <tt>FCGI::accept</tt>
-returns, the environment will <i>still</i> be empty,
-i.e. <tt>%ENV</tt> will contain no associations. All the variables
-associated with the first request are lost. There are two known
-workarounds:<p>
-
-<ul>
- <li>
- In your Perl application, enumerate <tt>%ENV</tt> using
- <tt>each</tt> before entering the <tt>FCGI::accept</tt>
- loop. The program <tt>examples/tiny-perl-fcgi</tt>
- contains code for this.<p>
- <li>
- In configuring your application be sure to set at least one
- initial environment variable. You do this with the
- <tt>AppClass -initial-env</tt> directive to the Web server,
- or by running <tt>cgi-fcgi</tt> in a non-empty environment.
-</ul><p>
-
-The Perl subroutine <tt>FCGI::accept</tt> treats the initial
-environment differently than the C function <tt>FCGI_Accept</tt>. The
-first call to the
-C function <tt>FCGI_Accept</tt> replaces the initial environment with
-the environment of the first request. The first call to the Perl subroutine
-<tt>FCGI::accept</tt> adds the variable bindings of the first request
-to the bindings present in the initial environment. So when the first
-call to <tt>FCGI::accept</tt> returns, bindings from the initial
-environment are still there (unless, due to naming conflicts, some of
-them have been overwritten by the first request). The next call to
-<tt>FCGI::accept</tt> removes the bindings made on the previous call
-before adding a new set for the request just accepted, again preserving
-the initial environment.<p>
-
-The Perl <tt>FCGI</tt> module also includes
-subroutines <tt>FCGI::finish</tt>, <tt>FCGI::set_exit_status</tt>,
-and <tt>FCGI::start_filter_data</tt> that correspond to
-C functions in <tt>fcgi_stdio.h</tt>; see the manpages for
-full information.<p>
-
-Converting a Perl CGI application to FastCGI is not fundamentally
-different from converting a C CGI application. You separate
-the portion of the application that performs one-time
-initialization from the portion that performs per-request
-processing. You put the per-request processing into a loop
-controlled by <tt>FCGI::accept</tt>.<p>
-
+++ /dev/null
-Integrating FastCGI with Tcl
-/fastcgi/words
-fcgi-hd.gif
-[FastCGI]
-<center>Integrating FastCGI with Tcl</center>
-
-<!--Copyright (c) 1996 Open Market, Inc. -->
-<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
-<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
-
-<P ALIGN=CENTER>
-Michael S. Shanzer
-<BR>
-Open Market, Inc.
-<BR>
-<EM>19 January 1995</EM>
-</P>
-
-<h5 align=center>
-Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
- MA 02142 U.S.A.<br>
-Tel: 617-621-9500 Fax: 617-621-1703 URL:
- <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
-$Id: fcgi-tcl.gut,v 1.1 1997/09/16 15:36:26 stanleyg Exp $ <br>
-</h5>
-<hr>
-
-
-<h3><a NAME = "S1">1. Introduction</a></h3>
-
-
-Tcl (tool command language) is an embeddable scripting language
-that's often used for CGI programming. Tcl is freely available
-as a source kit.<p>
-
-We've built a Tcl interpreter that runs as a FastCGI application. Our
-purpose in doing so was twofold:
-
-<ul>
- <li><i>Create a useful artifact.</i>
- Open Market has written many CGI applications using Tcl.
- Now we'd like to turn them into FastCGI applications.<p>
- <li><i>Demonstrate how easy it is to integrate FastCGI with an
- existing program.</i>
- The Tcl interpreter is a substantial program, so integrating
- FastCGI with the Tcl interpreter is a good test of the
- <tt>fcgi_stdio</tt> compatability library.
-</ul>
-
-We've succeeded on both counts. We now have a platform for
-migrating our Tcl-based CGI applications to FastCGI. And
-the integration required a very small effort. The only source
-code change to the Tcl interpreter was the routine addition of a
-handful of new commands: <tt>FCGI_Accept</tt>, <tt>FCGI_Finish</tt>,
-<tt>FCGI_SetExitStatus</tt>, and <tt>FCGI_StartFilterData</tt>.<p>
-
-The FastCGI-integrated Tcl interpreter works as usual when run
-from a shell or as a CGI program. You don't need two Tcls,
-one for FastCGI and one for other uses.<p>
-
-The remainder of this document gives a recipe you can follow to
-build FastCGI into Tcl, explains what's happening in the recipe,
-and illustrates the use of FastCGI Tcl with
-an example program.<p>
-
-<h3><a NAME = "S2">2. Recipe</a></h3>
-
-Here are the assumptions embedded in the following recipe:
-<ul>
- <li>You are building Tcl 7.4p3, the current stable Tcl release
- as this is written.
- You unpack the Tcl kit into a directory <tt>tcl7.4</tt>
- that's a sibling of the FastCGI kit directory
- <tt>fcgi-devel-kit</tt>.<p>
-
- <li>You have gcc version 2.7
- installed on your system, and use it in the build.
- gcc is convenient because it supports the <tt>-include</tt>
- command-line option
- that instructs the C preprocessor to include a specific file before
- processing any other include files. This allows you to include
- <tt>fcgi_stdio.h</tt> without modifying Tcl source files. (The
- reason for specifying gcc version 2.7 is that I have
- experienced bad behavior with an earlier version and the <tt>-include</tt>
- flag -- the C preprocessor died with SIGABRT.)<p>
-
- <li>You have GNU autoconf
- installed on your system. If you don't have GNU autoconf,
- you will have to make certain edits by hand and
- repeat these edits for each build platform.<p>
-</ul>
-
-If those are valid assumptions, follow these steps:
-<ol>
- <li><i>Build the FastCGI Developer's Kit.</i>
- Tcl needs to link against <tt>libfcgi.a</tt>, so
- <a href="http://www.fastcgi.com/kit/doc/fcgi-devel-kit.htm#S2">build
- the FastCGI Developer's Kit</a>
- in order to create this library for your platform.<p>
-
- <li><i>Pull the Tcl 7.4p3 kit.</i>
- You'll need the files
- <a href="ftp://ftp.smli.com/pub/tcl/tcl7.4.tar.Z">tcl7.4.tar.Z</a>,
- <a href="ftp://ftp.smli.com/pub/tcl/tcl7.4p1.patch.gz">tcl7.4p1.patch.gz</a>,
- <a href="ftp://ftp.smli.com/pub/tcl/tcl7.4p2.patch.gz">tcl7.4p2.patch.gz</a>,
- and
- <a href="ftp://ftp.smli.com/pub/tcl/tcl7.4p3.patch.gz">tcl7.4p3.patch.gz</a>.
- (Some older Netscape browsers can't perform these
- retrievals because of a protocol conflict between Netscape
- and Sun's firewall.)<p>
-
- Unpack the tar file in the parent directory of the
- FastCGI kit directory you used in the previous step,
- so that the directories <tt>tcl7.4</tt> and <tt>fcgi-devel-kit</tt>
- are siblings. After unpacking the tar file, follow the directions
- in the <tt>README</tt> to apply the patches.<p>
-
- The <a href="http://www.sunlabs.com:80/research/tcl/">Sun Labs Tcl/Tk
- Project Page</a> contains a wealth of information on Tcl, including
- up to date information on the latest kits.<p>
-
- <li><i>Copy the files <tt>tclFCGI.c</tt>, <tt>tclAppInit.c</tt>,
- <tt>Makefile.in</tt>, and <tt>configure.in</tt> from the FastCGI kit.</i>
- <pre>
- > cd tcl7.4
- > mv tclAppInit.c tclAppInit.c.orig
- > mv Makefile.in.orig Makefile.in.orig.orig
- > mv Makefile.in Makefile.in.orig
- > mv configure.in configure.in.orig
- > cp ../fcgi-devel-kit/tcl/tcl7.4/* .
- > cp ../fcgi-devel-kit/tcl/common/* .</pre>
-
- <li><i>Create a new <tt>configure</tt> script.</i>
- <pre>
- > autoconf</pre>
-
- <li><i>Configure and build.</i>
- <pre>
- > ./configure
- > make</pre>
- The <tt>make</tt> creates the Tcl interpreter <tt>tclsh</tt>
- and library archive <tt>libtcl.a</tt> (for embedding Tcl in
- your own C applications). The Tcl <tt>README</tt> file
- explains how you can experiment with <tt>tclsh</tt>
- without installing it in a standard place.<p>
-</ol>
-
-<h3><a NAME = "S3">3. Recipe Explained</a></h3>
-
-The recipe alone is fine if you are using Tcl 7.4p3, you have gcc
-version 2.7, and you have GNU autoconf. In case one or more of these
-assumptions doesn't hold for you, and to illuminate how little work was
-involved in integrating FastCGI, here's an explanation of how
-and why you would modify the files <tt>tclAppInit.c</tt>,
-<tt>Makefile.in</tt>, and <tt>configure.in</tt> from the Tcl kit.
-
-<ul>
- <li><tt>tclAppInit.c</tt>:<p>
- <ul>
- <li>Add the following three lines of code
- to the function <tt>Tcl_AppInit</tt> after the call
- to <tt>Tcl_Init</tt> and after the comment about calling init
- procedures:
- <pre>
- if (FCGI_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }</pre>
- This registers four Tcl commands (<tt>FCGI_Accept</tt>,
- <tt>FCGI_Finish</tt>, <tt>FCGI_SetExitStatus</tt>, and
- <tt>FCGI_StartFilterData</tt>), implemented in
- <tt>tclFCGI.c</tt>, with the Tcl interpreter.<p>
- </ul>
-
- <li><tt>Makefile.in</tt>:<p>
- <ul>
- <li>Add <tt>tclFCGI.o</tt> to the <tt>GENERIC_OBJS</tt> variable, and
- add <tt>tclFCGI.c</tt> to the <tt>SRCS</tt> variable.<p>
-
- This builds the FastCGI Tcl commands and
- links them into the Tcl interpreter.<p>
-
- <li>Add <tt>-I../fcgi-devel-kit/include
- -include ../fcgi-devel-kit/include/fcgi_stdio.h</tt>
- to the <tt>CFLAGS</tt> variable.<p>
-
- This includes <tt>fcgi_stdio.h</tt>
- when compiling C code for the Tcl interpreter, overriding
- the normal <tt>stdio</tt> types, variables, and functions.<p>
-
- <li>Add <tt>../fcgi-devel-kit/libfcgi/libfcgi.a</tt> before the
- <tt>@LIBS@</tt> part of the <tt>LIBS</tt> variable.<p>
-
- This links the implementation of <tt>fcgi_stdio.h</tt>
- into the Tcl interpreter, for use by the <tt>FCGI_accept</tt>
- command and any code that uses <tt>stdio</tt> variables
- or calls <tt>stdio</tt> functions.<p>
- </ul><p>
-
- The last two edits will vary if you use a compiler other than gcc or
- install the <tt>tcl7.4</tt> directory
- somewhere else in relation to the <tt>fcgi-devel-kit</tt> directory.<p>
-
- <li><tt>configure.in</tt>:<p>
- <ul>
- <li>
- Replace the lines
- <pre>
-AC_C_CROSS
-CC=${CC-cc}</pre>
- with the lines
- <pre>
-AC_PROG_CC
-AC_C_CROSS</pre>
- This selects gcc in preference to other C compilers.<p>
-
- <li>
- Add the following lines just after the
- <tt>AC_SUBST(CC)</tt> line:
- <pre>
-AC_CHECK_LIB(socket, main, [LIBS="$LIBS -lsocket"])
-AC_CHECK_LIB(nsl, main, [LIBS="$LIBS -lnsl"])
-AC_SUBST(LIBS)</pre>
- This ensures that the socket libraries used by FastCGI
- are linked into the Tcl interpreter.<p>
- </ul>
- If GNU autoconf is not available to you, you'll leave
- <tt>configure.in</tt> alone and perform the following steps:<p>
- <ul>
- <li>
- Execute
- <pre>
- > SETENV CC gcc</pre>
- before running <tt>configure</tt>.<p>
-
- <li>
- If you are running on a SVR4-derived Unix platform,
- edit <tt>Makefile</tt> to add
- <tt>-lsocket -lnsl</tt> to the <tt>LIBS</tt> value
- after running <tt>configure</tt>.<p>
- </ul>
- If you ever re-run <tt>configure</tt>, you'll need to repeat
- these steps.<p>
-
-</ul>
-
-
-<h3><a NAME = "S4">4. Writing FastCGI applications in Tcl</a></h3>
-
-The Tcl program <tt>tcl/tiny-tcl-fcgi</tt> performs the same
-function as the C program <tt>examples/tiny-fcgi.c</tt>
-that's used as an example in the
-<a href="fcgi-devel-kit.html#S3.1.1">FastCGI Developer's Kit
-document</a>. Here's what the Tcl version looks like:<p>
-
-<pre>
-#!./tclsh
-set count 0
-while {[FCGI_Accept] >= 0 } {
- incr count
- puts -nonewline "Content-type: text/html\r\n\r\n"
- puts "<title>FastCGI Hello! (Tcl)</title>"
- puts "<h1>FastCGI Hello! (Tcl)</h1>"
- puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"
-}
-</pre>
-
-If you've built Tcl according to the recipe and you have a Web server
-set up to run FastCGI applications, load the FastCGI Developer's Kit
-Index Page in that server and run this Tcl application now.<p>
-
-The script invokes Tcl indirectly via the symbolic link
-<tt>examples/tclsh</tt>. It does this because HP-UX has a limit of 32
-characters for the first line of a command-interpreter file such as
-<tt>examples/tiny-tcl-fcgi</tt>. If you run on HP-UX you won't want
-to sprinkle symbolic links to <tt>tclsh</tt> everywhere, so you should install
-<tt>tclsh</tt> with a shorter pathname than
-<tt>/usr/local/tcl7.4-fcgi/bin/tclsh7.4</tt>.<p>
-
-The Tcl command <tt>FCGI_Accept</tt> treats the initial
-environment differently than the C function <tt>FCGI_Accept</tt>. The
-first call to the
-C function <tt>FCGI_Accept</tt> replaces the initial environment with
-the environment of the first request. The first call to the Tcl command
-<tt>FCGI_Accept</tt> adds the variable bindings of the first request
-to the bindings present in the initial environment. So when the first
-call to <tt>FCGI_Accept</tt> returns, bindings from the initial
-environment are still there (unless, due to naming conflicts, some of
-them have been overwritten by the first request). The next call to
-<tt>FCGI_Accept</tt> removes the bindings made on the previous call
-before adding a new set for the request just accepted, again preserving
-the initial environment.<p>
-
-The FastCGI-integrated <tt>tclsh</tt> also includes
-commands <tt>FCGI_Finish</tt>, <tt>FCGI_SetExitStatus</tt>,
-and <tt>FCGI_StartFilterData</tt> that correspond to
-C functions in <tt>fcgi_stdio.h</tt>; see the manpages for
-full information.<p>
-
-Converting a Tcl CGI application to FastCGI is not fundamentally
-different from converting a C CGI application. You separate
-the portion of the application that performs one-time
-initialization from the portion that performs per-request
-processing. You put the per-request processing into a loop
-controlled by <tt>FCGI_Accept</tt>.<p>
-
-<HR>
-<ADDRESS><A HREF="mailto:shanzer@openmarket.com">Mike Shanzer // shanzer@openmarket.com</A></ADDRESS>
projects / catagits/fcgi2.git / commitdiff