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 | |
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.00a'; |
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 | # New is slightly different in that it calls FCGI's |
35 | # accept() method. |
36 | sub new { |
37 | return undef unless FCGI::accept() >= 0; |
38 | my($self,@param) = @_; |
39 | return $CGI::Q = $self->SUPER::new(@param); |
40 | } |
41 | |
42 | 1; |
43 | |
44 | =head1 NAME |
45 | |
46 | CGI::Fast - CGI Interface for Fast CGI |
47 | |
48 | =head1 SYNOPSIS |
49 | |
50 | use CGI::Fast qw(:standard); |
51 | $COUNTER = 0; |
52 | while (new CGI::Fast) { |
53 | print header; |
54 | print start_html("Fast CGI Rocks"); |
55 | print |
56 | h1("Fast CGI Rocks"), |
57 | "Invocation number ",b($COUNTER++), |
58 | " PID ",b($$),".", |
59 | hr; |
60 | print end_html; |
61 | } |
62 | |
63 | =head1 DESCRIPTION |
64 | |
65 | CGI::Fast is a subclass of the CGI object created by |
66 | CGI.pm. It is specialized to work well with the Open Market |
67 | FastCGI standard, which greatly speeds up CGI scripts by |
68 | turning them into persistently running server processes. Scripts |
69 | that perform time-consuming initialization processes, such as |
70 | loading large modules or opening persistent database connections, |
71 | will see large performance improvements. |
72 | |
73 | =head1 OTHER PIECES OF THE PUZZLE |
74 | |
75 | In order to use CGI::Fast you'll need a FastCGI-enabled Web |
76 | server. Open Market's server is FastCGI-savvy. There are also |
77 | freely redistributable FastCGI modules for NCSA httpd 1.5 and Apache. |
78 | FastCGI-enabling modules for Microsoft Internet Information Server and |
79 | Netscape Communications Server have been announced. |
80 | |
81 | In addition, you'll need a version of the Perl interpreter that has |
82 | been linked with the FastCGI I/O library. Precompiled binaries are |
83 | available for several platforms, including DEC Alpha, HP-UX and |
84 | SPARC/Solaris, or you can rebuild Perl from source with patches |
85 | provided in the FastCGI developer's kit. The FastCGI Perl interpreter |
86 | can be used in place of your normal Perl without ill consequences. |
87 | |
88 | You can find FastCGI modules for Apache and NCSA httpd, precompiled |
89 | Perl interpreters, and the FastCGI developer's kit all at URL: |
90 | |
91 | http://www.fastcgi.com/ |
92 | |
93 | =head1 WRITING FASTCGI PERL SCRIPTS |
94 | |
95 | FastCGI scripts are persistent: one or more copies of the script |
96 | are started up when the server initializes, and stay around until |
97 | the server exits or they die a natural death. After performing |
98 | whatever one-time initialization it needs, the script enters a |
99 | loop waiting for incoming connections, processing the request, and |
100 | waiting some more. |
101 | |
102 | A typical FastCGI script will look like this: |
103 | |
104 | #!/usr/local/bin/perl # must be a FastCGI version of perl! |
105 | use CGI::Fast; |
106 | &do_some_initialization(); |
107 | while ($q = new CGI::Fast) { |
108 | &process_request($q); |
109 | } |
110 | |
111 | Each time there's a new request, CGI::Fast returns a |
112 | CGI object to your loop. The rest of the time your script |
113 | waits in the call to new(). When the server requests that |
114 | your script be terminated, new() will return undef. You can |
115 | of course exit earlier if you choose. A new version of the |
116 | script will be respawned to take its place (this may be |
117 | necessary in order to avoid Perl memory leaks in long-running |
118 | scripts). |
119 | |
120 | CGI.pm's default CGI object mode also works. Just modify the loop |
121 | this way: |
122 | |
123 | while (new CGI::Fast) { |
124 | &process_request; |
125 | } |
126 | |
127 | Calls to header(), start_form(), etc. will all operate on the |
128 | current request. |
129 | |
130 | =head1 INSTALLING FASTCGI SCRIPTS |
131 | |
132 | See the FastCGI developer's kit documentation for full details. On |
133 | the Apache server, the following line must be added to srm.conf: |
134 | |
135 | AddType application/x-httpd-fcgi .fcgi |
136 | |
137 | FastCGI scripts must end in the extension .fcgi. For each script you |
138 | install, you must add something like the following to srm.conf: |
139 | |
140 | AppClass /usr/etc/httpd/fcgi-bin/file_upload.fcgi -processes 2 |
141 | |
142 | This instructs Apache to launch two copies of file_upload.fcgi at |
143 | startup time. |
144 | |
145 | =head1 USING FASTCGI SCRIPTS AS CGI SCRIPTS |
146 | |
147 | Any script that works correctly as a FastCGI script will also work |
148 | correctly when installed as a vanilla CGI script. However it will |
149 | not see any performance benefit. |
150 | |
151 | =head1 CAVEATS |
152 | |
153 | I haven't tested this very much. |
154 | |
155 | =head1 AUTHOR INFORMATION |
156 | |
157 | be used and modified freely, but I do request that this copyright |
158 | notice remain attached to the file. You may modify this module as you |
159 | wish, but if you redistribute a modified version, please attach a note |
160 | listing the modifications you have made. |
161 | |
162 | Address bug reports and comments to: |
163 | lstein@genome.wi.mit.edu |
164 | |
165 | =head1 BUGS |
166 | |
167 | This section intentionally left blank. |
168 | |
169 | =head1 SEE ALSO |
170 | |
171 | L<CGI::Carp>, L<CGI> |
172 | |
173 | =cut |