lib/CGI/Fast.pm

package CGI::Fast;

# See the bottom of this file for the POD documentation.  Search for the
# string '=head'.

# You can run this file through either pod2man or pod2html to produce pretty
# documentation in manual or html file format (these utilities are part of the
# Perl 5 distribution).

# Copyright 1995,1996, Lincoln D. Stein.  All rights reserved.
# It may be used and modified freely, but I do request that this copyright
# notice remain attached to the file.  You may modify this module as you 
# wish, but if you redistribute a modified version, please attach a note
# listing the modifications you have made.

# The most recent version and complete docs are available at:
#   http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
#   ftp://ftp-genome.wi.mit.edu/pub/software/WWW/
$CGI::Fast::VERSION='1.05';

use CGI;
use FCGI;
@ISA = ('CGI');

# workaround for known bug in libfcgi
while (($ignore) = each %ENV) { }

# override the initialization behavior so that
# state is NOT maintained between invocations 
sub save_request {
    # no-op
}

# If ENV{FCGI_SOCKET_PATH} is specified, we maintain a FCGI Request handle
# in this package variable.
use vars qw($Ext_Request);
BEGIN {
   # If ENV{FCGI_SOCKET_PATH} is given, explicitly open the socket,
   # and keep the request handle around from which to call Accept().
   if ($ENV{FCGI_SOCKET_PATH}) {
        my $path    = $ENV{FCGI_SOCKET_PATH};
        my $backlog = $ENV{FCGI_LISTEN_QUEUE} || 100;
        my $socket  = FCGI::OpenSocket( $path, $backlog );
        $Ext_Request = FCGI::Request( \*STDIN, \*STDOUT, \*STDERR, 
                                        \%ENV, $socket, 1 );
   }
}

# New is slightly different in that it calls FCGI's
# accept() method.
sub new {
     my ($self, $initializer, @param) = @_;
     unless (defined $initializer) {
        if ($Ext_Request) {
          return undef unless $Ext_Request->Accept() >= 0;
        } else {
         return undef unless FCGI::accept() >= 0;
     }
     }
     return $CGI::Q = $self->SUPER::new($initializer, @param);
}

1;

=head1 NAME

CGI::Fast - CGI Interface for Fast CGI

=head1 SYNOPSIS

    use CGI::Fast qw(:standard);
    $COUNTER = 0;
    while (new CGI::Fast) {
        print header;
        print start_html("Fast CGI Rocks");
        print
            h1("Fast CGI Rocks"),
            "Invocation number ",b($COUNTER++),
            " PID ",b($$),".",
            hr;
        print end_html;
    }

=head1 DESCRIPTION

CGI::Fast is a subclass of the CGI object created by
CGI.pm.  It is specialized to work well with the Open Market
FastCGI standard, which greatly speeds up CGI scripts by
turning them into persistently running server processes.  Scripts
that perform time-consuming initialization processes, such as
loading large modules or opening persistent database connections,
will see large performance improvements.

=head1 OTHER PIECES OF THE PUZZLE

In order to use CGI::Fast you'll need a FastCGI-enabled Web
server.  Open Market's server is FastCGI-savvy.  There are also
freely redistributable FastCGI modules for NCSA httpd 1.5 and Apache.
FastCGI-enabling modules for Microsoft Internet Information Server and
Netscape Communications Server have been announced.

In addition, you'll need a version of the Perl interpreter that has
been linked with the FastCGI I/O library.  Precompiled binaries are
available for several platforms, including DEC Alpha, HP-UX and 
SPARC/Solaris, or you can rebuild Perl from source with patches
provided in the FastCGI developer's kit.  The FastCGI Perl interpreter
can be used in place of your normal Perl without ill consequences.

You can find FastCGI modules for Apache and NCSA httpd, precompiled
Perl interpreters, and the FastCGI developer's kit all at URL:

  http://www.fastcgi.com/

=head1 WRITING FASTCGI PERL SCRIPTS

FastCGI scripts are persistent: one or more copies of the script 
are started up when the server initializes, and stay around until
the server exits or they die a natural death.  After performing
whatever one-time initialization it needs, the script enters a 
loop waiting for incoming connections, processing the request, and
waiting some more.

A typical FastCGI script will look like this:

    #!/usr/local/bin/perl    # must be a FastCGI version of perl!
    use CGI::Fast;
    &do_some_initialization();
    while ($q = new CGI::Fast) {
        &process_request($q);
    }

Each time there's a new request, CGI::Fast returns a
CGI object to your loop.  The rest of the time your script
waits in the call to new().  When the server requests that
your script be terminated, new() will return undef.  You can
of course exit earlier if you choose.  A new version of the
script will be respawned to take its place (this may be
necessary in order to avoid Perl memory leaks in long-running
scripts).

CGI.pm's default CGI object mode also works.  Just modify the loop
this way:

    while (new CGI::Fast) {
        &process_request;
    }

Calls to header(), start_form(), etc. will all operate on the
current request.

=head1 INSTALLING FASTCGI SCRIPTS

See the FastCGI developer's kit documentation for full details.  On
the Apache server, the following line must be added to srm.conf:

    AddType application/x-httpd-fcgi .fcgi

FastCGI scripts must end in the extension .fcgi.  For each script you
install, you must add something like the following to srm.conf:

    FastCgiServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -processes 2

This instructs Apache to launch two copies of file_upload.fcgi at 
startup time.

=head1 USING FASTCGI SCRIPTS AS CGI SCRIPTS

Any script that works correctly as a FastCGI script will also work
correctly when installed as a vanilla CGI script.  However it will
not see any performance benefit.

=head1 EXTERNAL FASTCGI SERVER INVOCATION

FastCGI supports a TCP/IP transport mechanism which allows FastCGI scripts to run
external to the webserver, perhaps on a remote machine.  To configure the
webserver to connect to an external FastCGI server, you would add the following
to your srm.conf:

    FastCgiExternalServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -host sputnik:8888

Two environment variables affect how the C<CGI::Fast> object is created,
allowing C<CGI::Fast> to be used as an external FastCGI server.  (See C<FCGI>
documentation for C<FCGI::OpenSocket> for more information.)

=over

=item FCGI_SOCKET_PATH

The address (TCP/IP) or path (UNIX Domain) of the socket the external FastCGI
script to which bind an listen for incoming connections from the web server.

=item FCGI_LISTEN_QUEUE

Maximum length of the queue of pending connections.  

=back

For example:

    #!/usr/local/bin/perl    # must be a FastCGI version of perl!
    use CGI::Fast;
    &do_some_initialization();
    $ENV{FCGI_SOCKET_PATH} = "sputnik:8888";
    $ENV{FCGI_LISTEN_QUEUE} = 100;
    while ($q = new CGI::Fast) {
        &process_request($q);
    }

=head1 CAVEATS

I haven't tested this very much.

=head1 AUTHOR INFORMATION

Copyright 1996-1998, Lincoln D. Stein.  All rights reserved.  

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

Address bug reports and comments to: lstein@cshl.org

=head1 BUGS

This section intentionally left blank.

=head1 SEE ALSO

L<CGI::Carp>, L<CGI>

=cut
Revision:	1.1
Committed:	Thu Jun 30 14:27:09 2005 UTC (21 years, 3 months ago) by root
Branch:	MAIN
CVS Tags:	PERL-5-8-7, HEAD
Branch point for:	PERL
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	package 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
21			use CGI;
22			use FCGI;
23			@ISA = ('CGI');
24
25			# workaround for known bug in libfcgi
26			while (($ignore) = each %ENV) { }
27
28			# override the initialization behavior so that
29			# state is NOT maintained between invocations
30			sub 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.
36			use vars qw($Ext_Request);
37			BEGIN {
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.
51			sub 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
63			1;
64
65			=head1 NAME
66
67			CGI::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
86			CGI::Fast is a subclass of the CGI object created by
87			CGI.pm. It is specialized to work well with the Open Market
88			FastCGI standard, which greatly speeds up CGI scripts by
89			turning them into persistently running server processes. Scripts
90			that perform time-consuming initialization processes, such as
91			loading large modules or opening persistent database connections,
92			will see large performance improvements.
93
94			=head1 OTHER PIECES OF THE PUZZLE
95
96			In order to use CGI::Fast you'll need a FastCGI-enabled Web
97			server. Open Market's server is FastCGI-savvy. There are also
98			freely redistributable FastCGI modules for NCSA httpd 1.5 and Apache.
99			FastCGI-enabling modules for Microsoft Internet Information Server and
100			Netscape Communications Server have been announced.
101
102			In addition, you'll need a version of the Perl interpreter that has
103			been linked with the FastCGI I/O library. Precompiled binaries are
104			available for several platforms, including DEC Alpha, HP-UX and
105			SPARC/Solaris, or you can rebuild Perl from source with patches
106			provided in the FastCGI developer's kit. The FastCGI Perl interpreter
107			can be used in place of your normal Perl without ill consequences.
108
109			You can find FastCGI modules for Apache and NCSA httpd, precompiled
110			Perl interpreters, and the FastCGI developer's kit all at URL:
111
112			http://www.fastcgi.com/
113
114			=head1 WRITING FASTCGI PERL SCRIPTS
115
116			FastCGI scripts are persistent: one or more copies of the script
117			are started up when the server initializes, and stay around until
118			the server exits or they die a natural death. After performing
119			whatever one-time initialization it needs, the script enters a
120			loop waiting for incoming connections, processing the request, and
121			waiting some more.
122
123			A 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
132			Each time there's a new request, CGI::Fast returns a
133			CGI object to your loop. The rest of the time your script
134			waits in the call to new(). When the server requests that
135			your script be terminated, new() will return undef. You can
136			of course exit earlier if you choose. A new version of the
137			script will be respawned to take its place (this may be
138			necessary in order to avoid Perl memory leaks in long-running
139			scripts).
140
141			CGI.pm's default CGI object mode also works. Just modify the loop
142			this way:
143
144			while (new CGI::Fast) {
145			&process_request;
146			}
147
148			Calls to header(), start_form(), etc. will all operate on the
149			current request.
150
151			=head1 INSTALLING FASTCGI SCRIPTS
152
153			See the FastCGI developer's kit documentation for full details. On
154			the Apache server, the following line must be added to srm.conf:
155
156			AddType application/x-httpd-fcgi .fcgi
157
158			FastCGI scripts must end in the extension .fcgi. For each script you
159			install, you must add something like the following to srm.conf:
160
161			FastCgiServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -processes 2
162
163			This instructs Apache to launch two copies of file_upload.fcgi at
164			startup time.
165
166			=head1 USING FASTCGI SCRIPTS AS CGI SCRIPTS
167
168			Any script that works correctly as a FastCGI script will also work
169			correctly when installed as a vanilla CGI script. However it will
170			not see any performance benefit.
171
172			=head1 EXTERNAL FASTCGI SERVER INVOCATION
173
174			FastCGI supports a TCP/IP transport mechanism which allows FastCGI scripts to run
175			external to the webserver, perhaps on a remote machine. To configure the
176			webserver to connect to an external FastCGI server, you would add the following
177			to your srm.conf:
178
179			FastCgiExternalServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -host sputnik:8888
180
181			Two environment variables affect how the C<CGI::Fast> object is created,
182			allowing C<CGI::Fast> to be used as an external FastCGI server. (See C<FCGI>
183			documentation for C<FCGI::OpenSocket> for more information.)
184
185			=over
186
187			=item FCGI_SOCKET_PATH
188
189			The address (TCP/IP) or path (UNIX Domain) of the socket the external FastCGI
190			script to which bind an listen for incoming connections from the web server.
191
192			=item FCGI_LISTEN_QUEUE
193
194			Maximum length of the queue of pending connections.
195
196			=back
197
198			For 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
211			I haven't tested this very much.
212
213			=head1 AUTHOR INFORMATION
214
215			Copyright 1996-1998, Lincoln D. Stein. All rights reserved.
216
217			This library is free software; you can redistribute it and/or modify
218			it under the same terms as Perl itself.
219
220			Address bug reports and comments to: lstein@cshl.org
221
222			=head1 BUGS
223
224			This section intentionally left blank.
225
226			=head1 SEE ALSO
227
228			L<CGI::Carp>, L<CGI>
229
230			=cut