fcgi-devel-kit.htm

FastCGI,语言无关的、可伸缩架构的CGI开放扩展

      </P>
      <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>
      <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>
      <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>
      <P>
         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>
      <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>
      <P>
         See the <A HREF="http://fastcgi.com">fastcgi.com</A> Web page for more information about the Perl and Tcl
         libraries.
      </P>
      <P>
         Here are the Perl and Tcl versions of <TT>tiny-fcgi</TT>:
      </P>
<PRE>
#!./perl
use FCGI;
$count = 0;
while(FCGI::accept() &gt;= 0) {
    print(&quot;Content-type: text/html\r\n\r\n&quot;,
          &quot;&lt;title&gt;FastCGI Hello! (Perl)&lt;/title&gt;\n&quot;,
          &quot;&lt;h1&gt;FastCGI Hello! (Perl)&lt;/h1&gt;\n&quot;;
          &quot;Request number &quot;,  ++$count,
          &quot; running on host &lt;i&gt;&quot;;$env(SERVER_NAME)&lt;/i&gt;&quot;);
}
</PRE>
<PRE>
#!./tclsh
set count 0 
while {[FCGI_Accept] &gt;= 0 } {
    incr count
    puts -nonewline &quot;Content-type: text/html\r\n\r\n&quot;
    puts &quot;&lt;title&gt;FastCGI Hello! (Tcl)&lt;/title&gt;&quot;
    puts &quot;&lt;h1&gt;FastCGI Hello! (Tcl)&lt;/h1&gt;&quot;
    puts &quot;Request number $count running on host &lt;i&gt;$env(SERVER_NAME)&lt;/i&gt;&quot;
}
</PRE>
      <P>
         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).
      </P>
      <H4>
         <A NAME="S3.4">3.4 Using Java</A>
      </H4>
      <P>
         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&#39;s
         modules, garbage collection, and threads are especially valuable for writing long-lived application servers.
      </P>
      <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>
      <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>
      <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()&gt;= 0) {
            count ++;
            System.out.println(&quot;Content-type: text/html\r\n\r\n&quot;);
            System.out.println(
                    &quot;&lt;title&gt;FastCGI Hello! (Java)&lt;/title&gt;&quot;);
            System.out.println(&quot;&lt;h1&gt;FastCGI Hello! (Java)&lt;/h1&gt;&quot;);
            System.out.println(
                    &quot;request number &quot; + count + &quot; running on host &lt;i&gt;&quot; +
                    System.getProperty(&quot;SERVER_NAME&quot;) + &quot;&lt;/i&gt;&quot;);
        }
    }
}
</PRE>
      <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>
      <P>
         For a current listing of Web servers that support FastCGI, see the <A HREF=
         "http://fastcgi.com">fastcgi.com</A> Web page.
      </P>
      <P>
         Some of the Web servers that support FastCGI perform management of FastCGI applications. You don&#39;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>
      <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>
      <H3>
         <A NAME="S4.2">4.2 Using <TT>cgi-fcgi</TT> with any Web server</A>
      </H3>
      <P>
         The program <TT>cgi-fcgi</TT> allows you to run FastCGI applications using any Web server that supports CGI.
      </P>
      <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>
      <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>
         <LI>
            <TT>cgi-fcgi</TT> does not perform application management, so you need to provide this yourself.
         </LI>
         <LI>
            <TT>cgi-fcgi</TT> supports only the Responder role.
         </LI>
      </UL>
      <P>
         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>
      <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:
      </P>
<PRE>
    #!../cgi-fcgi/cgi-fcgi -f
    -connect sockets/tiny-fcgi tiny-fcgi
</PRE>
      <P>
         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>
      <P>
         Continuing the example, if <TT>cgi-fcgi</TT>&#39;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>
      <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>
      <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&#39;d then open the URL
         <TT>http://bowser:8888/index.html</TT> to reach the kit&#39;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>
      <P>
         On Digital UNIX 3.0 there&#39;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>
      <P>
         On AIX there&#39;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>
      <P>
         The mailing list <TT>fastcgi-developers</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, see <A HREF=
         "http://fastcgi.com/fastcgi-developers">http://fastcgi.com/fastcgi-developers</A>.
      </P>
      <P>
         A link to a mail archive can be found on the FastCGI home page, <A HREF=
         "http://www.fastcgi.com">http://www.fastcgi.com</A>
      </P>
      <HR>
      <ADDRESS>
         &copy; 1996, Open Market, Inc. / [e-mail]
      </ADDRESS>
   </BODY>
</HTML>