NAME

CGI::Cache - Perl extension to help cache output of time-intensive CGI scripts so that subsequent visits to such scripts will not cost as much time.

WARNING

The interface as of version 1.01 has changed considerably and is NOT compatible with earlier versions.

SYNOPSIS

use CGI;
use CGI::Cache;

my $query = new CGI;

# Set up a cache in /tmp/CGI_Cache/demo_cgi, with publicly read/writable
# cache entries, a maximum size of 20 megabytes, and a time-to-live of 6
# hours.
CGI::Cache::setup( { cache_key => '/tmp/CGI_Cache',
                     namespace => 'demo_cgi',
                     filemode => 0666,
                     max_size => 20 * 1024 * 1024,
                     expires_in => 6 * 60 * 60,
                   } );

CGI::Cache::set_key($query->Vars);
CGI::Cache::start();

print "Content-type: text/html\n\n";

print <<EOF;
This prints to STDOUT, which will be cached.
If the next visit is within 6 hours, the cached STDOUT
will be served instead of executing these 'prints'.
EOF

DESCRIPTION

This module is intended to be used in a CGI script that may benefit from caching its output. Some CGI scripts may take longer to execute because the data needed in order to construct the page may not be readily available. Such a script may need to query a remote database, or may rely on data that doesn't arrive in a timely fashion, or it may just be computationally intensive. Nonetheless, if you can afford the tradeoff of showing older, cached data vs. CGI execution time, then this module will perform that function.

This module was written such that any existing CGI code could benefit from caching without really changing any of existing CGI code guts. The CGI script can do just what it has always done, that is, construct an html page and print it to the STDOUT file descriptor, then exit. What you'll do in order to cache pages is include the module, specify some cache options and the cache key, and then call start() to begin caching output.

Internally, the CGI::Cache module ties the STDOUT file descriptor to an internal variable to which all output to STDOUT is saved. When the user calls stop() (or the END{} block of CGI::Cache is executed during script shutdown) the contents of the variable are inserted into the cache using the cache key the user specified earlier with set_key().

Once a page has been cached in this fashion, then a subsequent visit to that CGI script will check for an existing cache entry for the given key before continuing through the code. If the file exists, then the cache file's content is printed to the real STDOUT and the process exits before executing the regular CGI code.

CHOOSING A CACHE KEY

The cache key is used by CGI::Cache to determine when cached output can be used. The key should be a unique data structure that fully describes the execution of the script. Conveniently, CGI::Cache can take the CGI module's parameters (using CGI::Vars) as the key. However, in some cases you may want to specially construct the key.

For example, say we have a CGI script "airport" that computes the number of miles between major airports. You supply two airport codes to the script and it builds a web pages that reports the number of miles by air between those two locations. In addition, there is a third parameter which tells the script whether to write debugging information to a log file. Suppose the URL for Indianapolis Int'l to Chicago O'Hare looked like:

http://www.some.machine/cgi/airport?from=IND&to=ORD&debug=1

We might want to remove the debug parameter because the output from the user's perspective is the same regardless of whether a log file is written:

my $params = $query->Vars;
delete $params->{'debug'};
CGI::Cache::set_key($params);
CGI::Cache::start();

THE CGI::CACHE ROUTINES

setup( \%options );

Sets up the cache. The parameters are the same as the parameters for the File::Cache module's new() method, with the same defaults. Below is a brief overview of the options and their defaults. This overview may be out of date with your version of File::Cache. Consult perldoc File::Cache for more accurate information.

$options{cache_key}

The cache_key is the location of the cache. Here cache_key is used in keeping with the terminology used by File::Cache, and is different from the key referred to in set_key below.

$options{namespace}

Namespaces provide isolation between cache objects. It is recommended that you use a namespace that is unique to your script. That way you can have multiple scripts whose output is cached by CGI::Cache, and they will not collide. This value defaults to a subdirectory of your temp directory whose name matches the name of your script (as reported by $ENV{SCRIPT_NAME}, or $0 if $ENV{SCRIPT_NAME} is not defined).

$options{expires_in}

If the "expires_in" option is set, all objects in this cache will be cleared after that number of seconds. If expires_in is not set, the web pages will never expire. The default is 24 hours.

$options{cache_key}

The "cache_key" is used to determine the underlying filesystem namespace to use. Leaving this unset will cause the cache to be created in a subdirectory of your temporary directory called CGI_Cache. (The term "key" here is a bit misleading in light of the usage of the term earlier--this is really the path to the cache.)

$options{max_size}

"max_size" specifies the maximum size of the cache, in bytes. Cache objects are removed during the set() operation in order to reduce the cache size before the new cache value is added. The max_size will be maintained regardless of the value of auto_remove_stale. The default size is unlimited.

set_key ( <data> );

set_key takes any type of data (e.g. a list, a string, a reference to a complex data structure, etc.) and uses it to create a unique key to use when caching the script's output.

start();

Could you guess that the start() routine is what does all the work? It is this call that actually looks for an existing cache file, returning its content if it exists, then exits. If the cache file does not exist, then it captures the STDOUT filehandle and allows the CGI script's normal STDOUT be redirected to the cache file.

stop( [<dump> = 1] ); <dump> - do we dump the the cache file to STDOUT?

The stop() routine tells us to stop capturing STDOUT to the cache file. The cache file is closed and the file descriptor for STDOUT is restored to normal. The argument "dump" tells us whether or not to dump what has been captured in the cache file to the real STDOUT. By default this argument is 1, since this is usually what we want to do. In an error condition, however, we may want to cease caching and not print any of it to STDOUT. A dump argument of 0 is used in this case.

You don't have to call the stop() routine if you simply want to catch all STDOUT that the script generates for the duration of its execution. If the script exits without calling stop(), then the END{} block of the module will check to see of stop() has been called, and if not, it will call it. Note that CGI::Cache will detect whether your script is exiting as the result of an error, and will not cache the output in this case.

BUGS

Contact david@coppit.org for bug reports and suggestions.

AUTHOR

The original code (written before October 1, 2000) was written by Broc Seib, and is copyright (c) 1998 Broc Seib. All rights reserved.

Maintenance of CGI::Cache is now being done by David Coppit (david@coppit.org).

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

File::Cache
perldoc -f open