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
36       Note that as CGI::Fast is based on CGI.pm it is no longer advised as a
37       way to write Perl web apps. See
38       <https://metacpan.org/pod/CGI#CGI.pm-HAS-BEEN-REMOVED-FROM-THE-PERL-CORE>
39       for more information about this
40

OTHER PIECES OF THE PUZZLE

42       In order to use CGI::Fast you'll need the FCGI module.  See
43       http://www.cpan.org/ for details.
44

WRITING FASTCGI PERL SCRIPTS

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

INSTALLING FASTCGI SCRIPTS

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

USING FASTCGI SCRIPTS AS CGI SCRIPTS

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

EXTERNAL FASTCGI SERVER INVOCATION

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

FILE HANDLES

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

CAVEATS

180       I haven't tested this very much.
181

LICENSE

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

BUGS

194       This section intentionally left blank.
195

SEE ALSO

197       CGI::Carp, CGI
198
199
200
201perl v5.36.0                      2022-07-22                      CGI::Fast(3)
Impressum