CGI-SpeedyCGI
view release on metacpan or search on metacpan
# Set/get some SpeedyCGI options
$sp->setopt('timeout', 30);
print "maxruns=", $sp->getopt('maxruns'), "\n";
DESCRIPTION
SpeedyCGI is a way to run perl scripts persistently, which can make them
run much more quickly. A script can be made to to run persistently by
changing the interpreter line at the top of the script from:
#!/usr/bin/perl
to
#!/usr/bin/speedy
After the script is initially run, instead of exiting, the perl
interpreter is kept running. During subsequent runs, this interpreter is
used to handle new executions instead of starting a new perl interpreter
each time. A very fast frontend program, written in C, is executed for
each request. This fast frontend then contacts the persistent Perl
process, which is usually already running, to do the work and return the
results.
By default each perl script runs in its own Unix process, so one perl
script can't interfere with another. Command line options can also be
used to deal with programs that have memory leaks or other problems that
might keep them from otherwise running persistently.
SpeedyCGI can be used to speed up perl CGI scripts. It conforms to the
CGI specification, and does not run perl code inside the web server.
Since the perl interpreter runs outside the web server, it can't cause
problems for the web server itself.
SpeedyCGI also provides an Apache module so that under the Apache web
server, scripts can be run without the overhead of doing a fork/exec for
each request. With this module a small amount of frontend code is run
within the web server - the perl interpreters still run outside the
server.
SpeedyCGI and PersistentPerl are currently both names for the same code.
SpeedyCGI was the original name, but because people weren't sure what it
did, the name PersistentPerl was picked as an alias. At some point
SpeedyCGI will be replaced by PersistentPerl, or become a sub-class of
PersistentPerl to avoid always having two distributions.
OPTIONS
Setting Option Values
SpeedyCGI options can be set in several ways:
Command Line
The speedy command line is the same as for regular perl, with the
exception that SpeedyCGI specific options can be passed in after a
"--".
For example the line:
#!/usr/bin/speedy -w -- -t300
at the top of your script will set the perl option "`-w'" and will
pass the "`-t'" option to SpeedyCGI, setting the Timeout value to
300 seconds.
Environment
Environment variables can be used to pass in options. This can only
be done before the initial execution, not from within the script
itself. The name of the environment variable is always SPEEDY_
followed by the option name in upper-case. For example to set the
speedy Timeout option, use the environment variable named
SPEEDY_TIMEOUT.
Module
The CGI::SpeedyCGI module provides the setopt method to set options
from within the perl script at runtime. There is also a getopt
method to retrieve the current options. See the section on "METHODS"
below.
Apache
If you are using the optional Apache module, SpeedyCGI options can
be set in the httpd.conf file. The name of the apache directive will
always be Speedy followed by the option name. For example to set the
Timeout option, use the apache directive SpeedyTimeout.
Context
Not all options below are available in all contexts. The context for
which each option is valid is listed on the "Context" line in the
section below. There are three contexts:
speedy
The command-line "speedy" program, used normally with #! at the top
of your script or from a shell prompt.
mod_speedycgi
The optional Apache mod_speedycgi module.
module
During perl execution via the CGI::SpeedyCGI module's getopt/setopt
methods.
Options Available
BackendProg
Command Line : -p<string>
Default Value : "/usr/bin/speedy_backend"
Context : mod_speedycgi, speedy
Description:
Path to the speedy backend program.
BufsizGet
Command Line : -B<number>
Default Value : 131072
Context : speedy
Description:
Use <number> bytes as the maximum size for the buffer that
receives data from the perl backend.
BufsizPost
Command Line : -b<number>
Default Value : 131072
Context : speedy
Description:
Use <number> bytes as the maximum size for the buffer that
sends data to the perl backend.
Group
Command Line : -g<string>
Default Value : "none"
Context : mod_speedycgi, speedy
Description:
Allow a single perl interpreter to run multiple scripts.
All scripts that are run with the same group name and by
the same user will be run by the same group of perl
interpreters. If the group name is "none" then grouping is
disabled and each interpreter will run one script.
Different group names allow scripts to be separated into
different groups. Name is case-sensitive, and only the
first 12-characters are significant. Specifying an empty
group name is the same as specifying the group name
"default" - this allows just specifying "-g" on the command
line to turn on grouping.
MaxBackends
Command Line : -M<number>
Default Value : 0 (no max)
Context : mod_speedycgi, speedy
Description:
If non-zero, limits the number of speedy backends running
for this perl script to <number>.
MaxRuns
Command Line : -r<number>
Default Value : 500
Context : mod_speedycgi, module, speedy
Description:
Once the perl interpreter has run <number> times, re-exec
the backend process. Zero indicates no maximum. This
option is useful for processes that tend to consume
resources over time.
PerlArgs
Command Line : N/A
Default Value : ""
Context : mod_speedycgi
Description:
Command-line options to pass to the perl interpreter.
Timeout
Command Line : -t<number>
Default Value : 3600 (one hour)
Context : mod_speedycgi, module, speedy
Description:
If no new requests have been received after <number>
seconds, exit the persistent perl interpreter. Zero
indicates no timeout.
TmpBase
Command Line : -T<string>
Default Value : "/tmp/speedy"
Context : mod_speedycgi, speedy
Description:
Use the given prefix for creating temporary files. This
must be a filename prefix, not a directory name.
Version
Command Line : -v
Context : speedy
Description:
Print the SpeedyCGI version and exit.
METHODS
The following methods are available in the CGI::SpeedyCGI module.
new Create a new CGI::SpeedyCGI object.
my $sp = CGI::SpeedyCGI->new;
register_cleanup($function_ref)
Register a function that will be called at the end of each request,
after your script finishes running, but before STDOUT and STDERR are
closed. Multiple functions can be added by calling the method more
than once. At the end of the request, each function will be called
in the order in which it was registered.
$sp->register_cleanup(\&cleanup_func);
add_shutdown_handler($function_ref)
Add a function to the list of functions that will be called right
before the perl interpreter exits. This is not at the end of each
request, it is when the perl interpreter decides to exit completely
due to a Timeout or reaching MaxRuns.
$sp->add_shutdown_handler(sub {$dbh->logout});
set_shutdown_handler($function_ref)
Deprecated. Similar to `add_shutdown_handler', but only allows for a
single function to be registered.
$sp->set_shutdown_handler(sub {$dbh->logout});
i_am_speedy
Returns a boolean telling whether this script is running under
SpeedyCGI or not. A perl script can run under regular perl, or under
SpeedyCGI. This method allows the script to tell which environment
it is in.
$sp->i_am_speedy;
To make your script as portable as possible, you can use the
following test to make sure both the SpeedyCGI module is available
and you are running under SpeedyCGI:
if (eval {require CGI::SpeedyCGI} && CGI::SpeedyCGI->i_am_speedy) {
Do something SpeedyCGI specific here...
To increase the speed of this check you can also test whether the
following variable is defined instead of going through the object
interface:
$CGI::SpeedyCGI::i_am_speedy
setopt($optname, $value)
Set one of the SpeedyCGI options given in the section on "Options
Available". Returns the option's previous value. $optname is case-
insensitive.
$sp->setopt('TIMEOUT', 300);
getopt($optname)
Return the current value of one of the SpeedyCGI options. $optname
is case-insensitive.
$sp->getopt('TIMEOUT');
shutdown_now
Shut down the perl interpreter right away. This function does not
return.
$sp->shutdown_now
shutdown_next_time
Shut down the perl interpreter as soon as this request is done.
$sp->shutdown_next_time
INSTALLATION
To install SpeedyCGI you will need to either download a binary package
for your OS, or compile SpeedyCGI from source code. See the section on
"DOWNLOADING" for information on where to obtain the source code and
binaries.
( run in 0.717 second using v1.01-cache-2.11-cpan-ceb78f64989 )