mingw/html/lib/Memoize/Expire.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Memoize::Expire - Plug-in module for automatic expiration of memoized values</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Memoize::Expire - Plug-in module for automatic expiration of memoized values</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#interface">INTERFACE</a></li>
  26         <li><a href="#alternatives">ALTERNATIVES</a></li>
  27         <li><a href="#caveats">CAVEATS</a></li>
  28         <li><a href="#author">AUTHOR</a></li>
  29         <li><a href="#see_also">SEE ALSO</a></li>
  30 </ul>
  31 <!-- INDEX END -->
  32
  33 <hr />
  34 <p>
  35 </p>
  36 <h1><a name="name">NAME</a></h1>
  37 <p>Memoize::Expire - Plug-in module for automatic expiration of memoized values</p>
  38 <p>
  39 </p>
  40 <hr />
  41 <h1><a name="synopsis">SYNOPSIS</a></h1>
  42 <pre>
  43   use Memoize;
  44   use Memoize::Expire;
  45   tie my %cache =&gt; 'Memoize::Expire',
  46                      LIFETIME =&gt; $lifetime,    # In seconds
  47                      NUM_USES =&gt; $n_uses;</pre>
  48 <pre>
  49   memoize 'function', SCALAR_CACHE =&gt; [HASH =&gt; \%cache ];</pre>
  50 <p>
  51 </p>
  52 <hr />
  53 <h1><a name="description">DESCRIPTION</a></h1>
  54 <p>Memoize::Expire is a plug-in module for Memoize.  It allows the cached
  55 values for memoized functions to expire automatically.  This manual
  56 assumes you are already familiar with the Memoize module.  If not, you
  57 should study that manual carefully first, paying particular attention
  58 to the HASH feature.</p>
  59 <p>Memoize::Expire is a layer of software that you can insert in between
  60 Memoize itself and whatever underlying package implements the cache.
  61 The layer presents a hash variable whose values expire whenever they
  62 get too old, have been used too often, or both. You tell <code>Memoize</code> to
  63 use this forgetful hash as its cache instead of the default, which is
  64 an ordinary hash.</p>
  65 <p>To specify a real-time timeout, supply the <code>LIFETIME</code> option with a
  66 numeric value.  Cached data will expire after this many seconds, and
  67 will be looked up afresh when it expires.  When a data item is looked
  68 up afresh, its lifetime is reset.</p>
  69 <p>If you specify <code>NUM_USES</code> with an argument of <em>n</em>, then each cached
  70 data item will be discarded and looked up afresh after the <em>n</em>th time
  71 you access it.  When a data item is looked up afresh, its number of
  72 uses is reset.</p>
  73 <p>If you specify both arguments, data will be discarded from the cache
  74 when either expiration condition holds.</p>
  75 <p>Memoize::Expire uses a real hash internally to store the cached data.
  76 You can use the <code>HASH</code> option to Memoize::Expire to supply a tied
  77 hash in place of the ordinary hash that Memoize::Expire will normally
  78 use.  You can use this feature to add Memoize::Expire as a layer in
  79 between a persistent disk hash and Memoize.  If you do this, you get a
  80 persistent disk cache whose entries expire automatically.  For
  81 example:</p>
  82 <pre>
  83   #   Memoize
  84   #      |
  85   #   Memoize::Expire  enforces data expiration policy
  86   #      |
  87   #   DB_File  implements persistence of data in a disk file
  88   #      |
  89   #   Disk file</pre>
  90 <pre>
  91   use Memoize;
  92   use Memoize::Expire;
  93   use DB_File;</pre>
  94 <pre>
  95   # Set up persistence
  96   tie my %disk_cache =&gt; 'DB_File', $filename, O_CREAT|O_RDWR, 0666];</pre>
  97 <pre>
  98   # Set up expiration policy, supplying persistent hash as a target
  99   tie my %cache =&gt; 'Memoize::Expire',
 100                      LIFETIME =&gt; $lifetime,    # In seconds
 101                      NUM_USES =&gt; $n_uses,
 102                      HASH =&gt; \%disk_cache;</pre>
 103 <pre>
 104   # Set up memoization, supplying expiring persistent hash for cache
 105   memoize 'function', SCALAR_CACHE =&gt; [ HASH =&gt; \%cache ];</pre>
 106 <p>
 107 </p>
 108 <hr />
 109 <h1><a name="interface">INTERFACE</a></h1>
 110 <p>There is nothing special about Memoize::Expire.  It is just an
 111 example.  If you don't like the policy that it implements, you are
 112 free to write your own expiration policy module that implements
 113 whatever policy you desire.  Here is how to do that.  Let us suppose
 114 that your module will be named MyExpirePolicy.</p>
 115 <p>Short summary: You need to create a package that defines four methods:</p>
 116 <dl>
 117 <dt><strong><a name="item_tiehash">TIEHASH</a></strong>
 118
 119 <dd>
 120 <p>Construct and return cache object.</p>
 121 </dd>
 122 </li>
 123 <dt><strong><a name="item_exists">EXISTS</a></strong>
 124
 125 <dd>
 126 <p>Given a function argument, is the corresponding function value in the
 127 cache, and if so, is it fresh enough to use?</p>
 128 </dd>
 129 </li>
 130 <dt><strong><a name="item_fetch">FETCH</a></strong>
 131
 132 <dd>
 133 <p>Given a function argument, look up the corresponding function value in
 134 the cache and return it.</p>
 135 </dd>
 136 </li>
 137 <dt><strong><a name="item_store">STORE</a></strong>
 138
 139 <dd>
 140 <p>Given a function argument and the corresponding function value, store
 141 them into the cache.</p>
 142 </dd>
 143 </li>
 144 <dt><strong><a name="item_clear">CLEAR</a></strong>
 145
 146 <dd>
 147 <p>(Optional.)  Flush the cache completely.</p>
 148 </dd>
 149 </li>
 150 </dl>
 151 <p>The user who wants the memoization cache to be expired according to
 152 your policy will say so by writing</p>
 153 <pre>
 154   tie my %cache =&gt; 'MyExpirePolicy', args...;
 155   memoize 'function', SCALAR_CACHE =&gt; [HASH =&gt; \%cache];</pre>
 156 <p>This will invoke <a href="#item_tiehash"><code>MyExpirePolicy-&gt;TIEHASH(args)</code></a>.
 157 MyExpirePolicy::TIEHASH should do whatever is appropriate to set up
 158 the cache, and it should return the cache object to the caller.</p>
 159 <p>For example, MyExpirePolicy::TIEHASH might create an object that
 160 contains a regular Perl hash (which it will to store the cached
 161 values) and some extra information about the arguments and how old the
 162 data is and things like that.  Let us call this object `C'.</p>
 163 <p>When Memoize needs to check to see if an entry is in the cache
 164 already, it will invoke <a href="#item_exists"><code>C-&gt;EXISTS(key)</code></a>.  <code>key</code> is the normalized
 165 function argument.  MyExpirePolicy::EXISTS should return 0 if the key
 166 is not in the cache, or if it has expired, and 1 if an unexpired value
 167 is in the cache.  It should <em>not</em> return <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>, because there is a
 168 bug in some versions of Perl that will cause a spurious FETCH if the
 169 EXISTS method returns <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>.</p>
 170 <p>If your EXISTS function returns true, Memoize will try to fetch the
 171 cached value by invoking <a href="#item_fetch"><code>C-&gt;FETCH(key)</code></a>.  MyExpirePolicy::FETCH should
 172 return the cached value.  Otherwise, Memoize will call the memoized
 173 function to compute the appropriate value, and will store it into the
 174 cache by calling <a href="#item_store"><code>C-&gt;STORE(key, value)</code></a>.</p>
 175 <p>Here is a very brief example of a policy module that expires each
 176 cache item after ten seconds.</p>
 177 <pre>
 178         package Memoize::TenSecondExpire;</pre>
 179 <pre>
 180         sub TIEHASH {
 181           my ($package, %args) = @_;
 182           my $cache = $args{HASH} || {};
 183           bless $cache =&gt; $package;
 184         }</pre>
 185 <pre>
 186         sub EXISTS {
 187           my ($cache, $key) = @_;
 188           if (exists $cache-&gt;{$key} &amp;&amp;
 189               $cache-&gt;{$key}{EXPIRE_TIME} &gt; time) {
 190             return 1
 191           } else {
 192             return 0;  # Do NOT return `undef' here.
 193           }
 194         }</pre>
 195 <pre>
 196         sub FETCH {
 197           my ($cache, $key) = @_;
 198           return $cache-&gt;{$key}{VALUE};
 199         }</pre>
 200 <pre>
 201         sub STORE {
 202           my ($cache, $key, $newvalue) = @_;
 203           $cache-&gt;{$key}{VALUE} = $newvalue;
 204           $cache-&gt;{$key}{EXPIRE_TIME} = time + 10;
 205         }</pre>
 206 <p>To use this expiration policy, the user would say</p>
 207 <pre>
 208         use Memoize;
 209         tie my %cache10sec =&gt; 'Memoize::TenSecondExpire';
 210         memoize 'function', SCALAR_CACHE =&gt; [HASH =&gt; \%cache10sec];</pre>
 211 <p>Memoize would then call <code>function</code> whenever a cached value was
 212 entirely absent or was older than ten seconds.</p>
 213 <p>You should always support a <code>HASH</code> argument to <a href="#item_tiehash"><code>TIEHASH</code></a> that ties
 214 the underlying cache so that the user can specify that the cache is
 215 also persistent or that it has some other interesting semantics.  The
 216 example above demonstrates how to do this, as does <code>Memoize::Expire</code>.</p>
 217 <p>
 218 </p>
 219 <hr />
 220 <h1><a name="alternatives">ALTERNATIVES</a></h1>
 221 <p>Brent Powers has a <code>Memoize::ExpireLRU</code> module that was designed to
 222 work with Memoize and provides expiration of least-recently-used data.
 223 The cache is held at a fixed number of entries, and when new data
 224 comes in, the least-recently used data is expired.  See
 225 <a href="http://search.cpan.org/search?mode=module&query=ExpireLRU">http://search.cpan.org/search</a>.</p>
 226 <p>Joshua Chamas's Tie::Cache module may be useful as an expiration
 227 manager.  (If you try this, let me know how it works out.)</p>
 228 <p>If you develop any useful expiration managers that you think should be
 229 distributed with Memoize, please let me know.</p>
 230 <p>
 231 </p>
 232 <hr />
 233 <h1><a name="caveats">CAVEATS</a></h1>
 234 <p>This module is experimental, and may contain bugs.  Please report bugs
 235 to the address below.</p>
 236 <p>Number-of-uses is stored as a 16-bit unsigned integer, so can't exceed
 237 65535.</p>
 238 <p>Because of clock granularity, expiration times may occur up to one
 239 second sooner than you expect.  For example, suppose you store a value
 240 with a lifetime of ten seconds, and you store it at 12:00:00.998 on a
 241 certain day.  Memoize will look at the clock and see 12:00:00.  Then
 242 9.01 seconds later, at 12:00:10.008 you try to read it back.  Memoize
 243 will look at the clock and see 12:00:10 and conclude that the value
 244 has expired.  This will probably not occur if you have
 245 <code>Time::HiRes</code> installed.</p>
 246 <p>
 247 </p>
 248 <hr />
 249 <h1><a name="author">AUTHOR</a></h1>
 250 <p>Mark-Jason Dominus (mjd-perl-memoize+@plover.com)</p>
 251 <p>Mike Cariaso provided valuable insight into the best way to solve this
 252 problem.</p>
 253 <p>
 254 </p>
 255 <hr />
 256 <h1><a name="see_also">SEE ALSO</a></h1>
 257 <p><code>perl(1)</code></p>
 258 <p>The Memoize man page.</p>
 259 <p><a href="http://www.plover.com/~mjd/perl/Memoize/">http://www.plover.com/~mjd/perl/Memoize/</a>  (for news and updates)</p>
 260 <p>I maintain a mailing list on which I occasionally announce new
 261 versions of Memoize.  The list is for announcements only, not
 262 discussion.  To join, send an empty message to
 263 <a href="mailto:mjd-perl-memoize-request@Plover.com.">mjd-perl-memoize-request@Plover.com.</a></p>
 264 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 265 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 266 <big><strong><span class="block">&nbsp;Memoize::Expire - Plug-in module for automatic expiration of memoized values</span></strong></big>
 267 </td></tr>
 268 </table>
 269
 270 </body>
 271
 272 </html>