<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HTML::Mason::Cache::BaseCache - Base cache object</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:autarch@houseabsolute.urth.org" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><A NAME="__index__"></a></p>
<ul>
<li><A HREF="#name">NAME</a></li>
<li><A HREF="#description">DESCRIPTION</a></li>
<li><A HREF="#methods">METHODS</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<h1><A NAME="name">NAME</a></h1>
<p>HTML::Mason::Cache::BaseCache - Base cache object</p>
<p>
</p>
<hr />
<h1><A NAME="description">DESCRIPTION</a></h1>
<p>This is the base module for all cache implementations used in Mason.
It provides a few additional methods on top of <code>Cache::BaseCache</code> in
Dewitt Clinton's <code>Cache::Cache</code> package.</p>
<p>An object of this class is returned from <A HREF="../Request.html#item_cache">$m->cache</a>.</p>
<p>
</p>
<hr />
<h1><A NAME="methods">METHODS</a></h1>
<dl>
<dt><strong><A NAME="clear" class="item">clear ()</a></strong></dt>
<A NAME="item_clear"></a><dd>
<p>Remove all values in the cache.</p>
</dd>
<dt><strong><A NAME="get" class="item">get (key, [%params])</a></strong></dt>
<A NAME="item_get"></a><dd>
<p>Returns the value associated with <em>key</em> or undef if it is
non-existent or expired. This is extended with the following optional
name/value parameters:</p>
<dl>
<dt><strong><A NAME="busy_lock_duration" class="item">busy_lock => duration</a></strong></dt>
<dd>
<p>If the value has expired, set its expiration time to the current time plus
<em>duration</em> (instead of removing it from the cache) before returning undef.
This is used to prevent multiple processes from recomputing the same
expensive value simultaneously. The <em>duration</em> may be of any form acceptable
to <A HREF="../Cache/BaseCache.html#item_set">set</a>.</p>
</dd>
<dt><strong><A NAME="expire_if_sub" class="item">expire_if => sub</a></strong></dt>
<dd>
<p>If the value exists and has not expired, call <em>sub</em> with the cache
object as a single parameter. If <em>sub</em> returns a true value, expire
the value.</p>
</dd>
</dl>
</dd>
<dt><strong><A NAME="get_object" class="item">get_object (key)</a></strong></dt>
<A NAME="item_get_object"></a><dd>
<p>Returns the underlying <code>Cache::Object</code> object associated with <em>key</em>.
The most useful methods on this object are</p>
<pre>
$co->get_created_at(); # when was object stored in cache
$co->get_accessed_at(); # when was object last accessed
$co->get_expires_at(); # when does object expire</pre>
</dd>
<dt><strong><A NAME="expire" class="item">expire (key)</a></strong></dt>
<A NAME="item_expire"></a><dd>
<p>Expires the value associated with <em>key</em>, if it exists. Differs from
<A HREF="../Cache/BaseCache.html#item_remove">remove</a> only in that
the cache object is left around, e.g. for retrieval by
<A HREF="../Cache/BaseCache.html#item_get_object">get_object</a>.</p>
</dd>
<dt><strong><A NAME="remove" class="item">remove (key)</a></strong></dt>
<A NAME="item_remove"></a><dd>
<p>Removes the cache object associated with <em>key</em>, if it exists.</p>
</dd>
<dt><strong><A NAME="set" class="item">set (key, data, [duration])</a></strong></dt>
<A NAME="item_set"></a><dd>
<p>Associates <em>data</em> with <em>key</em> in the cache. <em>duration</em>
indicates the time until the value should be erased. If
<em>duration</em> is unspecified, the value will never expire
by time.</p>
<p><em>$expires_in</em> may be a simple number of seconds, or a string of the
form "[number] [unit]", e.g., "10 minutes". The valid units are s,
second, seconds, sec, m, minute, minutes, min, h, hour, hours, d, day,
days, w, week, weeks, M, month, months, y, year, and years.</p>
</dd>
</dl>
</body>
</html>