NAME

CGI::SpeedyCGI - Speed up CGI scripts by running them persistently


SYNOPSIS

 #!/usr/local/bin/speedy

 ### Your CGI Script Here

 ##
 ## Optionally, use the CGI::SpeedyCGI module for various things
 ##

 # Create a SpeedyCGI object
 use CGI::SpeedyCGI;
 my $sp = CGI::SpeedyCGI->new;

 # See if we are running under SpeedyCGI or not.
 print "Running under speedy=", $sp->i_am_speedy ? 'yes' : 'no', "\n";

 # Set up a shutdown handler
 $sp->set_shutdown_handler(sub { do something here });

 # Set/get some SpeedyCGI options
 $sp->setopt('timeout', 30);
 print "maxruns=", $sp->getopt('maxruns'), "\n";


DESCRIPTION

SpeedyCGI is a way to run CGI perl scripts persistently, which usually makes them run much more quickly. Converting scripts to use SpeedyCGI is in most cases as simple has changing the interpreter line at the top of the script from

    #!/usr/local/bin/perl

to

    #!/usr/local/bin/speedy

After the script is initially run, instead of exiting, SpeedyCGI keeps the perl interpreter running in memory. During subsequent runs, this interpreter is used to handle new requests, instead of starting a new perl interpreter for each execution.

SpeedyCGI conforms to the CGI specification, and does not work inside the web server. A very fast cgi-bin (written in C) is executed for each request. This fast cgi-bin then contacts the persistent Perl process, which is usually already in memory, to do the work and return the results.

Since all of these processes run outside the web server, they can't cause problems for the web server itself. Also, each perl program runs as its own Unix process, so one program 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.


OPTIONS


How to Set

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:

        #!/usr/local/bin/speedy -w -- -t300

at the top of your script will call SpeedyCGI with the perl option ``-w'' and will pass the ``-t'' option to speedy, telling it to exit if no new requests have been received after 300 seconds.

Environment
Environment variables can be used to pass in options. This can only be done before the initial execution (ie not from within the script itself).

CGI::SpeedyCGI
The CGI::SpeedyCGI module provides a method, setopt, to set options from within the perl script at runtime. There is also a getopt method to retrieve the current options.

mod_speedycgi
If you are using the optional Apache module, SpeedyCGI options can be set in the httpd.conf file.


Options Available

The following options are available:

TIMEOUT
    Command Line        : -tN
    Environment         : SPEEDY_TIMEOUT
    CGI::SpeedyCGI      : TIMEOUT
    mod_speedycgi       : SpeedyTimeout
    Default Value       : 3600 (one hour)

    Description:

        If no new requests have been received after N
        seconds, exit the persistent perl interpreter.
        Use 0 to indicate no timeout.

MAXRUNS
    Command Line        : -rN
    Environment         : SPEEDY_MAXRUNS
    CGI::SpeedyCGI      : MAXRUNS
    mod_speedycgi       : SpeedyMaxruns
    Default Value       : 0 (ie no max)

    Description:

        Once the perl interpreter has run N times, exit.

TMPBASE
    Command Line        : -Tstr
    Environment         : SPEEDY_TMPBASE
    CGI::SpeedyCGI      : n/a
    mod_speedycgi       : SpeedyTmpbase
    Default Value       : /tmp/speedy

    Description:

        Use the given prefix for creating temporary files.
        This must be a filename prefix, not a directory name.

BUFSIZ_POST
    Command Line        : -bN
    Environment         : SPEEDY_BUFSIZ_POST
    CGI::SpeedyCGI      : n/a
    mod_speedycgi       : n/a
    Default Value       : 1024

    Description:

        Use N bytes for the buffer that sends data
        to the CGI script.

BUFSIZ_GET
    Command Line        : -BN
    Environment         : SPEEDY_BUFSIZ_GET
    CGI::SpeedyCGI      : n/a
    mod_speedycgi       : n/a
    Default Value       : 8192

    Description:

        Use N bytes for the buffer that receives data
        from the CGI script.


METHODS

The following methods are available in the CGI::SpeedyCGI module.

new
Create a new CGI::SpeedyCGI object.

    my $sp = CGI::SpeedyCGI->new;

set_shutdown_handler($function_ref)
Register a function 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, maxruns, etc)

    $sp->set_shutdown_handler(sub {$dbh->logout});

i_am_speedy
Returns a boolean telling whether this script is running under SpeedyCGI or not. A CGI 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;

setopt($optname, $value)
Set one of the SpeedyCGI options given in the OPTIONS section. Returns the previous value that the option had. $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');


INSTALLATION

SpeedyCGI has been tried with perl versions 5.004_04 and 5.005_02, and under Solaris 2.6, Redhat Linux 5.1, and FreeBSD 3.1. There may be problems wither other OSes or earlier versions of Perl.

To install, do the following:

    perl Makefile.PL
    make
    make test
    make install

This will install a ``speedy'' binary in the same directory where ``perl'' was installed. If you want to install the optional Apache module, see the README in the apache directory.


BUGS


TODO


MAILING LIST

speedycgi@newlug.org. Subscribe by sending a message to speedycgi-request@newlug.org with ``subscribe'' in the body.

Archive is at http://newlug.org/mailArchive/speedycgi


DOWNLOADING

SpeedyCGI can be retrieved from:

    http://daemoninc.com/speedycgi
    http://www.cpan.org/modules/by-authors/id/H/HO/HORROCKS/


AUTHOR

    Sam Horrocks
    Daemon Consulting Inc.
    http://daemoninc.com
    sam@daemoninc.com


COPYRIGHT

Copyright (c) 1999 Daemon Consulting Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.