1package CGI::Fast;
2
3# See the bottom of this file for the POD documentation.  Search for the
4# string '=head'.
5
6# You can run this file through either pod2man or pod2html to produce pretty
7# documentation in manual or html file format (these utilities are part of the
8# Perl 5 distribution).
9
10# Copyright 1995,1996, Lincoln D. Stein.  All rights reserved.
11# It may be used and modified freely, but I do request that this copyright
12# notice remain attached to the file.  You may modify this module as you
13# wish, but if you redistribute a modified version, please attach a note
14# listing the modifications you have made.
15
16# The most recent version and complete docs are available at:
17#   http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
18#   ftp://ftp-genome.wi.mit.edu/pub/software/WWW/
19$CGI::Fast::VERSION='1.05';
20
21use CGI;
22use FCGI;
23@ISA = ('CGI');
24
25# workaround for known bug in libfcgi
26while (($ignore) = each %ENV) { }
27
28# override the initialization behavior so that
29# state is NOT maintained between invocations
30sub save_request {
31    # no-op
32}
33
34# If ENV{FCGI_SOCKET_PATH} is specified, we maintain a FCGI Request handle
35# in this package variable.
36use vars qw($Ext_Request);
37BEGIN {
38   # If ENV{FCGI_SOCKET_PATH} is given, explicitly open the socket,
39   # and keep the request handle around from which to call Accept().
40   if ($ENV{FCGI_SOCKET_PATH}) {
41	my $path    = $ENV{FCGI_SOCKET_PATH};
42	my $backlog = $ENV{FCGI_LISTEN_QUEUE} || 100;
43	my $socket  = FCGI::OpenSocket( $path, $backlog );
44	$Ext_Request = FCGI::Request( \*STDIN, \*STDOUT, \*STDERR,
45					\%ENV, $socket, 1 );
46   }
47}
48
49# New is slightly different in that it calls FCGI's
50# accept() method.
51sub new {
52     my ($self, $initializer, @param) = @_;
53     unless (defined $initializer) {
54	if ($Ext_Request) {
55          return undef unless $Ext_Request->Accept() >= 0;
56	} else {
57         return undef unless FCGI::accept() >= 0;
58     }
59     }
60     return $CGI::Q = $self->SUPER::new($initializer, @param);
61}
62
631;
64
65=head1 NAME
66
67CGI::Fast - CGI Interface for Fast CGI
68
69=head1 SYNOPSIS
70
71    use CGI::Fast qw(:standard);
72    $COUNTER = 0;
73    while (new CGI::Fast) {
74	print header;
75	print start_html("Fast CGI Rocks");
76	print
77	    h1("Fast CGI Rocks"),
78	    "Invocation number ",b($COUNTER++),
79            " PID ",b($$),".",
80	    hr;
81        print end_html;
82    }
83
84=head1 DESCRIPTION
85
86CGI::Fast is a subclass of the CGI object created by
87CGI.pm.  It is specialized to work well with the Open Market
88FastCGI standard, which greatly speeds up CGI scripts by
89turning them into persistently running server processes.  Scripts
90that perform time-consuming initialization processes, such as
91loading large modules or opening persistent database connections,
92will see large performance improvements.
93
94=head1 OTHER PIECES OF THE PUZZLE
95
96In order to use CGI::Fast you'll need a FastCGI-enabled Web
97server.  Open Market's server is FastCGI-savvy.  There are also
98freely redistributable FastCGI modules for NCSA httpd 1.5 and Apache.
99FastCGI-enabling modules for Microsoft Internet Information Server and
100Netscape Communications Server have been announced.
101
102In addition, you'll need a version of the Perl interpreter that has
103been linked with the FastCGI I/O library.  Precompiled binaries are
104available for several platforms, including DEC Alpha, HP-UX and
105SPARC/Solaris, or you can rebuild Perl from source with patches
106provided in the FastCGI developer's kit.  The FastCGI Perl interpreter
107can be used in place of your normal Perl without ill consequences.
108
109You can find FastCGI modules for Apache and NCSA httpd, precompiled
110Perl interpreters, and the FastCGI developer's kit all at URL:
111
112  http://www.fastcgi.com/
113
114=head1 WRITING FASTCGI PERL SCRIPTS
115
116FastCGI scripts are persistent: one or more copies of the script
117are started up when the server initializes, and stay around until
118the server exits or they die a natural death.  After performing
119whatever one-time initialization it needs, the script enters a
120loop waiting for incoming connections, processing the request, and
121waiting some more.
122
123A typical FastCGI script will look like this:
124
125    #!/usr/local/bin/perl    # must be a FastCGI version of perl!
126    use CGI::Fast;
127    &do_some_initialization();
128    while ($q = new CGI::Fast) {
129	&process_request($q);
130    }
131
132Each time there's a new request, CGI::Fast returns a
133CGI object to your loop.  The rest of the time your script
134waits in the call to new().  When the server requests that
135your script be terminated, new() will return undef.  You can
136of course exit earlier if you choose.  A new version of the
137script will be respawned to take its place (this may be
138necessary in order to avoid Perl memory leaks in long-running
139scripts).
140
141CGI.pm's default CGI object mode also works.  Just modify the loop
142this way:
143
144    while (new CGI::Fast) {
145	&process_request;
146    }
147
148Calls to header(), start_form(), etc. will all operate on the
149current request.
150
151=head1 INSTALLING FASTCGI SCRIPTS
152
153See the FastCGI developer's kit documentation for full details.  On
154the Apache server, the following line must be added to srm.conf:
155
156    AddType application/x-httpd-fcgi .fcgi
157
158FastCGI scripts must end in the extension .fcgi.  For each script you
159install, you must add something like the following to srm.conf:
160
161    FastCgiServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -processes 2
162
163This instructs Apache to launch two copies of file_upload.fcgi at
164startup time.
165
166=head1 USING FASTCGI SCRIPTS AS CGI SCRIPTS
167
168Any script that works correctly as a FastCGI script will also work
169correctly when installed as a vanilla CGI script.  However it will
170not see any performance benefit.
171
172=head1 EXTERNAL FASTCGI SERVER INVOCATION
173
174FastCGI supports a TCP/IP transport mechanism which allows FastCGI scripts to run
175external to the webserver, perhaps on a remote machine.  To configure the
176webserver to connect to an external FastCGI server, you would add the following
177to your srm.conf:
178
179    FastCgiExternalServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -host sputnik:8888
180
181Two environment variables affect how the C<CGI::Fast> object is created,
182allowing C<CGI::Fast> to be used as an external FastCGI server.  (See C<FCGI>
183documentation for C<FCGI::OpenSocket> for more information.)
184
185=over
186
187=item FCGI_SOCKET_PATH
188
189The address (TCP/IP) or path (UNIX Domain) of the socket the external FastCGI
190script to which bind can listen for incoming connections from the web server.
191
192=item FCGI_LISTEN_QUEUE
193
194Maximum length of the queue of pending connections.
195
196=back
197
198For example:
199
200    #!/usr/local/bin/perl    # must be a FastCGI version of perl!
201    use CGI::Fast;
202    &do_some_initialization();
203    $ENV{FCGI_SOCKET_PATH} = "sputnik:8888";
204    $ENV{FCGI_LISTEN_QUEUE} = 100;
205    while ($q = new CGI::Fast) {
206	&process_request($q);
207    }
208
209=head1 CAVEATS
210
211I haven't tested this very much.
212
213=head1 AUTHOR INFORMATION
214
215Copyright 1996-1998, Lincoln D. Stein.  All rights reserved.
216
217This library is free software; you can redistribute it and/or modify
218it under the same terms as Perl itself.
219
220Address bug reports and comments to: lstein@cshl.org
221
222=head1 BUGS
223
224This section intentionally left blank.
225
226=head1 SEE ALSO
227
228L<CGI::Carp>, L<CGI>
229
230=cut
231