view release on metacpan or  search on metacpan

lib/CGI/Cache.pm  view on Meta::CPAN

If the "default_expires_in" option is set, all objects in this cache will be
cleared after that number of seconds. If this option is not provided, the
cache entry will never expire by default.

=item $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 default size is unlimited.

=back

Normally CGI::Cache monitors STDOUT, storing output in a temporary buffer,
before printing it to the output filehandle. It also monitors STDERR in order
to determine if your CGI script has failed: if it has failed, then the buffer
is discarded. Otherwise, the buffered output is cached for a later execution
of your program. 

The enable_output option allows you to cache the output but not
send it to the output filehandle. This is useful, for example, if you want to
store the output, then use buffer() to access it for processing before calling
stop(), which stores the buffer in the cache.

The remaining four optional parameters allow you to modify the filehandles
that CGI::Cache listens on and outputs to. The watched handles are the handles
which CGI::Cache will monitor for output. The output and error handles are the
handles to which CGI::Cache will send the output after it is cached. These
default to whatever the watched handles are. This feature is useful when
CGI::Cache is used to cache output to files:

  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;

NOTE: If you plan to modify warn() or die() (i.e. redefine $SIG{__WARN__} or
$SIG{__DIE__}) so that they no longer print to STDERR, you must do so before
calling setup(). For example, if you do a "require CGI::Carp
qw(fatalsToBrowser)", make sure you do it before calling CGI::Cache::setup().


=item 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.


=item 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.


=item $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 B<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.

=item $status = pause();

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


=item $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.


=item $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.


=item $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.