cpan/CGI/lib/CGI/Fast.pm

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