CHOOSING A CACHE 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 page 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() or exit;

THE CGI::CACHE ROUTINES

setup(...)

  setup( { cache_options => \%cache_options,
             [enable_output => 1],
             [watched_output_handle => \*STDOUT],
             [watched_error_handle => \*STDERR] );
             [output_handle => <watched_output_handle>],
             [error_handle => <watched_error_handle>] } );

  <enable_output> - used to disable output while caching
  <cache_options> - options for configuration of the cache
  <watched_output_handle> - the file handle to monitor for normal output
  <watched_error_handle> - the file handle to monitor for error output
  <output_handle> - the file handle to which to send normal output
  <error_handle> - the file handle to which to send error output
    

Sets up the module. The cache_options parameter contains the same values as the parameters for the Cache::SizeAwareFileCache 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 Cache::SizeAwareFileCache. Consult perldoc Cache::SizeAwareFileCache for more accurate information.

  use CGI::Cache;

  open FH, ">TEST.OUT";

  CGI::Cache::setup( { watched_output_handle => \*FH } );
  CGI::Cache::set_key( 'test key' );
  CGI::Cache::start() or exit;

  # This is cached, and then sent to FH
  print FH "Test output 1\n";

  CGI::Cache::stop();

  close FH;

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 and prints the output if it exists. If the cache file does not exist, then CGI::Cache captures the output filehandle and redirects the CGI script's output to the cache file.

This function returns 1 if caching has started, and 0 if the cached output was printed. A common metaphor for using this function is:

  CGI::Cache::start() or exit;
    

This function dies if you haven't yet defined your cache key.

$status = stop( [<cache_output>] );

    <cache_output> - do we write the captured output to a cache file?
    

The stop() routine tells us to stop capturing output. The argument "cache_output" tells us whether or not to store the captured output in the cache. By default this argument is 1, since this is usually what we want to do. In an error condition, however, we may not want to cache the output. A cache_output argument of 0 is used in this case.

You don't have to call the stop() routine if you simply want to catch all output that the script generates for the duration of its execution. If the script exits without calling stop(), CGI::Cache will call it for you upon program exit. 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.

This function returns 0 if capturing has not been started (by a call to start()), and 1 otherwise.

$status = pause();

Temporarily disable caching of output. Returns 0 if CGI::Cache is not currently caching output, and 1 otherwise.

$status = continue();

Re-enable caching of output. This function returns 0 if capturing has not been started (by a call to start()) or if pause() was not previously called, and 1 otherwise.

$scalar = buffer( [<content>] );

The buffer method gives direct access to the buffer of cached output. The optional <content> parameter allows you to set the contents using a list or scalar. (The list will be joined into a scalar and stored in the buffer.) The return value is the contents of the buffer after any changes.

$status = invalidate_cache_entry();

Forces the cache entry to be invalidated. It is always successful, and always returns 1. It doesn't make much sense to call this after calling start(), as CGI::Cache will have already determined that the cache entry is invalid.

$status = clear_cache();

Deletes the cache. It is always successful, and always returns 1.

CGI::Fast

  #!/usr/bin/perl

  use strict;

  use CGI::Fast;
  use CGI::Cache;

  my $COUNTER = 0;

  # Set up cache
  CGI::Cache::setup();

  while (my $cgi = new CGI::Fast)
  {
    CGI::Cache::set_key($cgi->Vars);

    $COUNTER++;

    # This should short-circuit the rest of the loop if a cache value is
    # already there
    CGI::Cache::start() or next;

    print $cgi->header, "\n";

    print<<EOF;
  <html>
  <head><title>FastCGI</title></head>
  <body>Counter: $COUNTER PID: $$</body>
  </html>
  EOF

    CGI::Cache::stop();
  }

FCGI

  #!/usr/bin/perl

  use strict;

  use FCGI;
  use CGI::Cache;
  use CGI;
  use IO::Handle;

  my $COUNTER = 0;

  my $stdout = new IO::Handle;
  my $stderr = new IO::Handle;

  my %env;

  my $request = FCGI::Request(\*STDIN, $stdout, $stderr, \%env);

  # Set up cache
  if ($request->IsFastCGI())
  {
    CGI::Cache::setup( { output_handle => $stdout,
                         error_handle => $stderr } );
  }
  else
  {
    CGI::Cache::setup();
  }

  while ($request->Accept() >= 0)
  {
    my $cgi = new CGI($env{QUERY_STRING});
    CGI::Cache::set_key($cgi->Vars);

    $COUNTER++;

    # This should short-circuit the rest of the loop if a cache value is
    # already there
    CGI::Cache::start() or next;

    print $cgi->header, "\n";

    print<<EOF;
  <html>
  <head><title>FastCGI</title></head>
  <body>Counter: $COUNTER PID: $$</body>
  </html>
  EOF

    CGI::Cache::stop();
  }

SpeedyCGI

  #!/usr/bin/speedy

  use strict;

  use CGI;
  use CGI::Cache;

  use vars qw($COUNTER);

  # Set up cache
  CGI::Cache::setup();

  $COUNTER++;

  my $cgi = new CGI;

  CGI::Cache::set_key($cgi->Vars);

  # This should short-circuit the rest of the program if a cache value is
  # already there
  CGI::Cache::start() or exit;

  print $cgi->header, "\n";

  print<<EOF;
  <html>
  <head><title>SpeedyCGI</title></head>
  <body>Counter: $COUNTER PID: $$</body>
  </html>
  EOF

  CGI::Cache::stop();