1CGI::Fast(3)          User Contributed Perl Documentation         CGI::Fast(3)
2
3
4

NAME

6       CGI::Fast - CGI Interface for Fast CGI
7

SYNOPSIS

9           use CGI::Fast
10               socket_path  => '9000',
11               socket_perm  => 0777,
12               listen_queue => 50;
13
14           use CGI qw/ :standard /;
15
16           $COUNTER = 0;
17
18           # optional, will default to STDOUT, STDERR
19           CGI::Fast->file_handles({
20               fcgi_output_file_handle => IO::Handle->new,
21               fcgi_error_file_handle  => IO::Handle->new,
22           });
23
24           while ($q = CGI::Fast->new) {
25               process_request($q);
26           }
27

DESCRIPTION

29       CGI::Fast is a subclass of the CGI object created by CGI.pm.  It is
30       specialized to work with the FCGI module, which greatly speeds up CGI
31       scripts by turning them into persistently running server processes.
32       Scripts that perform time-consuming initialization processes, such as
33       loading large modules or opening persistent database connections, will
34       see large performance improvements.
35

OTHER PIECES OF THE PUZZLE

37       In order to use CGI::Fast you'll need the FCGI module.  See
38       http://www.cpan.org/ for details.
39

WRITING FASTCGI PERL SCRIPTS

41       FastCGI scripts are persistent: one or more copies of the script are
42       started up when the server initializes, and stay around until the
43       server exits or they die a natural death.  After performing whatever
44       one-time initialization it needs, the script enters a loop waiting for
45       incoming connections, processing the request, and waiting some more.
46
47       A typical FastCGI script will look like this:
48
49           #!perl
50           use CGI::Fast;
51           do_some_initialization();
52           while ($q = CGI::Fast->new) {
53               process_request($q);
54           }
55
56       Each time there's a new request, CGI::Fast returns a CGI object to your
57       loop.  The rest of the time your script waits in the call to new().
58       When the server requests that your script be terminated, new() will
59       return undef.  You can of course exit earlier if you choose.  A new
60       version of the script will be respawned to take its place (this may be
61       necessary in order to avoid Perl memory leaks in long-running scripts).
62
63       CGI.pm's default CGI object mode also works.  Just modify the loop this
64       way:
65
66           while (CGI::Fast->new) {
67               process_request();
68           }
69
70       Calls to header(), start_form(), etc. will all operate on the current
71       request.
72

INSTALLING FASTCGI SCRIPTS

74       See the FastCGI developer's kit documentation for full details.  On the
75       Apache server, the following line must be added to srm.conf:
76
77           AddType application/x-httpd-fcgi .fcgi
78
79       FastCGI scripts must end in the extension .fcgi.  For each script you
80       install, you must add something like the following to srm.conf:
81
82           FastCgiServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -processes 2
83
84       This instructs Apache to launch two copies of file_upload.fcgi at
85       startup time.
86

USING FASTCGI SCRIPTS AS CGI SCRIPTS

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

EXTERNAL FASTCGI SERVER INVOCATION

93       FastCGI supports a TCP/IP transport mechanism which allows FastCGI
94       scripts to run external to the webserver, perhaps on a remote machine.
95       To configure the webserver to connect to an external FastCGI server,
96       you would add the following to your srm.conf:
97
98           FastCgiExternalServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -host sputnik:8888
99
100       Two environment variables affect how the "CGI::Fast" object is created,
101       allowing "CGI::Fast" to be used as an external FastCGI server. (See
102       "FCGI" documentation for "FCGI::OpenSocket" for more information.)
103
104       You can set these as ENV variables or imports in the use CGI::Fast
105       statement.  If the ENV variables are set then these will be favoured so
106       you can override the import statements on the command line, etc.
107
108       FCGI_SOCKET_PATH / socket_path
109           The address (TCP/IP) or path (UNIX Domain) of the socket the
110           external FastCGI script to which bind an listen for incoming
111           connections from the web server.
112
113       FCGI_SOCKET_PERM / socket_perm
114           Permissions for UNIX Domain socket.
115
116       FCGI_LISTEN_QUEUE / listen_queue
117           Maximum length of the queue of pending connections, defaults to
118           100.
119
120       For example:
121
122           use CGI::Fast
123               socket_path  => "sputnik:8888",
124               listen_queue => "50"
125           ;
126
127           use CGI qw/ :standard /;
128
129           do_some_initialization();
130
131           while ($q = CGI::Fast->new) {
132               process_request($q);
133           }
134
135       Or:
136
137           use CGI::Fast;
138           use CGI qw/ :standard /;
139
140           do_some_initialization();
141
142           $ENV{FCGI_SOCKET_PATH} = "sputnik:8888";
143           $ENV{FCGI_LISTEN_QUEUE} = 50;
144
145           while ($q = CGI::Fast->new) {
146               process_request($q);
147           }
148
149       Note the importance of having use CGI after use CGI::Fast as this will
150       prevent any CGI import pragmas being overwritten by CGI::Fast. You can
151       use CGI::Fast as a drop in replacement like so:
152
153           use CGI::Fast qw/ :standard /
154

FILE HANDLES

156       FCGI defaults to using STDOUT and STDERR as its output filehandles -
157       this may lead to unexpected redirect of output if you migrate scripts
158       from CGI.pm to CGI::Fast. To get around this you can use the
159       file_handles method, which you must do before the first call to
160       CGI::Fast->new. For example using IO::Handle:
161
162           CGI::Fast->file_handles({
163               fcgi_output_file_handle => IO::Handle->new,
164               fcgi_error_file_handle  => IO::Handle->new,
165           });
166
167           while (CGI::Fast->new) {
168               ..
169           }
170
171       Overriding STDIN using the "fcgi_input_file_handle" key is also
172       possible, however doing so is likely to break at least POST requests.
173

CAVEATS

175       I haven't tested this very much.
176

LICENSE

178       Copyright 1996-1998, Lincoln D. Stein.  All rights reserved. Currently
179       maintained by Lee Johnson
180
181       This library is free software; you can redistribute it and/or modify it
182       under the same terms as Perl itself.
183
184       Address bug reports and comments to:
185
186           https://github.com/leejo/cgi-fast
187

BUGS

189       This section intentionally left blank.
190

SEE ALSO

192       CGI::Carp, CGI
193
194
195
196perl v5.28.1                      2017-11-17                      CGI::Fast(3)
Impressum