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