{ "content": [ { "type": "text", "text": "# Memoize::Expire (perldoc)\n\n**Summary:** Memoize::Expire - Plug-in module for automatic expiration of memoized values\n\n**Synopsis:** use Memoize;\nuse Memoize::Expire;\ntie my %cache => 'Memoize::Expire',\nLIFETIME => $lifetime, # In seconds\nNUMUSES => $nuses;\nmemoize 'function', SCALARCACHE => [HASH => \\%cache ];\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (8 lines)\n- **DESCRIPTION** (51 lines)\n- **INTERFACE** (96 lines)\n- **ALTERNATIVES** (11 lines)\n- **CAVEATS** (11 lines)\n- **AUTHOR** (4 lines)\n- **SEE ALSO** (1 lines) — 1 subsections\n - perl (8 lines)\n\n## Full Content\n\n### NAME\n\nMemoize::Expire - Plug-in module for automatic expiration of memoized values\n\n### SYNOPSIS\n\nuse Memoize;\nuse Memoize::Expire;\ntie my %cache => 'Memoize::Expire',\nLIFETIME => $lifetime, # In seconds\nNUMUSES => $nuses;\n\nmemoize 'function', SCALARCACHE => [HASH => \\%cache ];\n\n### DESCRIPTION\n\nMemoize::Expire is a plug-in module for Memoize. It allows the cached values for memoized\nfunctions to expire automatically. This manual assumes you are already familiar with the Memoize\nmodule. If not, you should study that manual carefully first, paying particular attention to the\nHASH feature.\n\nMemoize::Expire is a layer of software that you can insert in between Memoize itself and\nwhatever underlying package implements the cache. The layer presents a hash variable whose\nvalues expire whenever they get too old, have been used too often, or both. You tell \"Memoize\"\nto use this forgetful hash as its cache instead of the default, which is an ordinary hash.\n\nTo specify a real-time timeout, supply the \"LIFETIME\" option with a numeric value. Cached data\nwill expire after this many seconds, and will be looked up afresh when it expires. When a data\nitem is looked up afresh, its lifetime is reset.\n\nIf you specify \"NUMUSES\" with an argument of *n*, then each cached data item will be discarded\nand looked up afresh after the *n*th time you access it. When a data item is looked up afresh,\nits number of uses is reset.\n\nIf you specify both arguments, data will be discarded from the cache when either expiration\ncondition holds.\n\nMemoize::Expire uses a real hash internally to store the cached data. You can use the \"HASH\"\noption to Memoize::Expire to supply a tied hash in place of the ordinary hash that\nMemoize::Expire will normally use. You can use this feature to add Memoize::Expire as a layer in\nbetween a persistent disk hash and Memoize. If you do this, you get a persistent disk cache\nwhose entries expire automatically. For example:\n\n# Memoize\n# |\n# Memoize::Expire enforces data expiration policy\n# |\n# DBFile implements persistence of data in a disk file\n# |\n# Disk file\n\nuse Memoize;\nuse Memoize::Expire;\nuse DBFile;\n\n# Set up persistence\ntie my %diskcache => 'DBFile', $filename, OCREAT|ORDWR, 0666];\n\n# Set up expiration policy, supplying persistent hash as a target\ntie my %cache => 'Memoize::Expire',\nLIFETIME => $lifetime, # In seconds\nNUMUSES => $nuses,\nHASH => \\%diskcache;\n\n# Set up memoization, supplying expiring persistent hash for cache\nmemoize 'function', SCALARCACHE => [ HASH => \\%cache ];\n\n### INTERFACE\n\nThere is nothing special about Memoize::Expire. It is just an example. If you don't like the\npolicy that it implements, you are free to write your own expiration policy module that\nimplements whatever policy you desire. Here is how to do that. Let us suppose that your module\nwill be named MyExpirePolicy.\n\nShort summary: You need to create a package that defines four methods:\n\nTIEHASH\nConstruct and return cache object.\n\nEXISTS\nGiven a function argument, is the corresponding function value in the cache, and if so, is\nit fresh enough to use?\n\nFETCH\nGiven a function argument, look up the corresponding function value in the cache and return\nit.\n\nSTORE\nGiven a function argument and the corresponding function value, store them into the cache.\n\nCLEAR\n(Optional.) Flush the cache completely.\n\nThe user who wants the memoization cache to be expired according to your policy will say so by\nwriting\n\ntie my %cache => 'MyExpirePolicy', args...;\nmemoize 'function', SCALARCACHE => [HASH => \\%cache];\n\nThis will invoke \"MyExpirePolicy->TIEHASH(args)\". MyExpirePolicy::TIEHASH should do whatever is\nappropriate to set up the cache, and it should return the cache object to the caller.\n\nFor example, MyExpirePolicy::TIEHASH might create an object that contains a regular Perl hash\n(which it will to store the cached values) and some extra information about the arguments and\nhow old the data is and things like that. Let us call this object `C'.\n\nWhen Memoize needs to check to see if an entry is in the cache already, it will invoke\n\"C->EXISTS(key)\". \"key\" is the normalized function argument. MyExpirePolicy::EXISTS should\nreturn 0 if the key is not in the cache, or if it has expired, and 1 if an unexpired value is in\nthe cache. It should *not* return \"undef\", because there is a bug in some versions of Perl that\nwill cause a spurious FETCH if the EXISTS method returns \"undef\".\n\nIf your EXISTS function returns true, Memoize will try to fetch the cached value by invoking\n\"C->FETCH(key)\". MyExpirePolicy::FETCH should return the cached value. Otherwise, Memoize will\ncall the memoized function to compute the appropriate value, and will store it into the cache by\ncalling \"C->STORE(key, value)\".\n\nHere is a very brief example of a policy module that expires each cache item after ten seconds.\n\npackage Memoize::TenSecondExpire;\n\nsub TIEHASH {\nmy ($package, %args) = @;\nmy $cache = $args{HASH} || {};\nbless $cache => $package;\n}\n\nsub EXISTS {\nmy ($cache, $key) = @;\nif (exists $cache->{$key} &&\n$cache->{$key}{EXPIRETIME} > time) {\nreturn 1\n} else {\nreturn 0; # Do NOT return `undef' here.\n}\n}\n\nsub FETCH {\nmy ($cache, $key) = @;\nreturn $cache->{$key}{VALUE};\n}\n\nsub STORE {\nmy ($cache, $key, $newvalue) = @;\n$cache->{$key}{VALUE} = $newvalue;\n$cache->{$key}{EXPIRETIME} = time + 10;\n}\n\nTo use this expiration policy, the user would say\n\nuse Memoize;\ntie my %cache10sec => 'Memoize::TenSecondExpire';\nmemoize 'function', SCALARCACHE => [HASH => \\%cache10sec];\n\nMemoize would then call \"function\" whenever a cached value was entirely absent or was older than\nten seconds.\n\nYou should always support a \"HASH\" argument to \"TIEHASH\" that ties the underlying cache so that\nthe user can specify that the cache is also persistent or that it has some other interesting\nsemantics. The example above demonstrates how to do this, as does \"Memoize::Expire\".\n\nAnother sample module, Memoize::Saves, is available in a separate distribution on CPAN. It\nimplements a policy that allows you to specify that certain function values would always be\nlooked up afresh. See the documentation for details.\n\n### ALTERNATIVES\n\nBrent Powers has a \"Memoize::ExpireLRU\" module that was designed to work with Memoize and\nprovides expiration of least-recently-used data. The cache is held at a fixed number of entries,\nand when new data comes in, the least-recently used data is expired. See\n.\n\nJoshua Chamas's Tie::Cache module may be useful as an expiration manager. (If you try this, let\nme know how it works out.)\n\nIf you develop any useful expiration managers that you think should be distributed with Memoize,\nplease let me know.\n\n### CAVEATS\n\nThis module is experimental, and may contain bugs. Please report bugs to the address below.\n\nNumber-of-uses is stored as a 16-bit unsigned integer, so can't exceed 65535.\n\nBecause of clock granularity, expiration times may occur up to one second sooner than you\nexpect. For example, suppose you store a value with a lifetime of ten seconds, and you store it\nat 12:00:00.998 on a certain day. Memoize will look at the clock and see 12:00:00. Then 9.01\nseconds later, at 12:00:10.008 you try to read it back. Memoize will look at the clock and see\n12:00:10 and conclude that the value has expired. This will probably not occur if you have\n\"Time::HiRes\" installed.\n\n### AUTHOR\n\nMark-Jason Dominus (mjd-perl-memoize+@plover.com)\n\nMike Cariaso provided valuable insight into the best way to solve this problem.\n\n### SEE ALSO\n\n#### perl\n\nThe Memoize man page.\n\nhttp://www.plover.com/~mjd/perl/Memoize/ (for news and updates)\n\nI maintain a mailing list on which I occasionally announce new versions of Memoize. The list is\nfor announcements only, not discussion. To join, send an empty message to\nmjd-perl-memoize-request@Plover.com.\n\n" } ], "structuredContent": { "command": "Memoize::Expire", "section": "", "mode": "perldoc", "summary": "Memoize::Expire - Plug-in module for automatic expiration of memoized values", "synopsis": "use Memoize;\nuse Memoize::Expire;\ntie my %cache => 'Memoize::Expire',\nLIFETIME => $lifetime, # In seconds\nNUMUSES => $nuses;\nmemoize 'function', SCALARCACHE => [HASH => \\%cache ];", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 8, "subsections": [] }, { "name": "DESCRIPTION", "lines": 51, "subsections": [] }, { "name": "INTERFACE", "lines": 96, "subsections": [] }, { "name": "ALTERNATIVES", "lines": 11, "subsections": [] }, { "name": "CAVEATS", "lines": 11, "subsections": [] }, { "name": "AUTHOR", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 1, "subsections": [ { "name": "perl", "lines": 8 } ] } ], "sections": { "NAME": { "content": "Memoize::Expire - Plug-in module for automatic expiration of memoized values\n", "subsections": [] }, "SYNOPSIS": { "content": "use Memoize;\nuse Memoize::Expire;\ntie my %cache => 'Memoize::Expire',\nLIFETIME => $lifetime, # In seconds\nNUMUSES => $nuses;\n\nmemoize 'function', SCALARCACHE => [HASH => \\%cache ];\n", "subsections": [] }, "DESCRIPTION": { "content": "Memoize::Expire is a plug-in module for Memoize. It allows the cached values for memoized\nfunctions to expire automatically. This manual assumes you are already familiar with the Memoize\nmodule. If not, you should study that manual carefully first, paying particular attention to the\nHASH feature.\n\nMemoize::Expire is a layer of software that you can insert in between Memoize itself and\nwhatever underlying package implements the cache. The layer presents a hash variable whose\nvalues expire whenever they get too old, have been used too often, or both. You tell \"Memoize\"\nto use this forgetful hash as its cache instead of the default, which is an ordinary hash.\n\nTo specify a real-time timeout, supply the \"LIFETIME\" option with a numeric value. Cached data\nwill expire after this many seconds, and will be looked up afresh when it expires. When a data\nitem is looked up afresh, its lifetime is reset.\n\nIf you specify \"NUMUSES\" with an argument of *n*, then each cached data item will be discarded\nand looked up afresh after the *n*th time you access it. When a data item is looked up afresh,\nits number of uses is reset.\n\nIf you specify both arguments, data will be discarded from the cache when either expiration\ncondition holds.\n\nMemoize::Expire uses a real hash internally to store the cached data. You can use the \"HASH\"\noption to Memoize::Expire to supply a tied hash in place of the ordinary hash that\nMemoize::Expire will normally use. You can use this feature to add Memoize::Expire as a layer in\nbetween a persistent disk hash and Memoize. If you do this, you get a persistent disk cache\nwhose entries expire automatically. For example:\n\n# Memoize\n# |\n# Memoize::Expire enforces data expiration policy\n# |\n# DBFile implements persistence of data in a disk file\n# |\n# Disk file\n\nuse Memoize;\nuse Memoize::Expire;\nuse DBFile;\n\n# Set up persistence\ntie my %diskcache => 'DBFile', $filename, OCREAT|ORDWR, 0666];\n\n# Set up expiration policy, supplying persistent hash as a target\ntie my %cache => 'Memoize::Expire',\nLIFETIME => $lifetime, # In seconds\nNUMUSES => $nuses,\nHASH => \\%diskcache;\n\n# Set up memoization, supplying expiring persistent hash for cache\nmemoize 'function', SCALARCACHE => [ HASH => \\%cache ];\n", "subsections": [] }, "INTERFACE": { "content": "There is nothing special about Memoize::Expire. It is just an example. If you don't like the\npolicy that it implements, you are free to write your own expiration policy module that\nimplements whatever policy you desire. Here is how to do that. Let us suppose that your module\nwill be named MyExpirePolicy.\n\nShort summary: You need to create a package that defines four methods:\n\nTIEHASH\nConstruct and return cache object.\n\nEXISTS\nGiven a function argument, is the corresponding function value in the cache, and if so, is\nit fresh enough to use?\n\nFETCH\nGiven a function argument, look up the corresponding function value in the cache and return\nit.\n\nSTORE\nGiven a function argument and the corresponding function value, store them into the cache.\n\nCLEAR\n(Optional.) Flush the cache completely.\n\nThe user who wants the memoization cache to be expired according to your policy will say so by\nwriting\n\ntie my %cache => 'MyExpirePolicy', args...;\nmemoize 'function', SCALARCACHE => [HASH => \\%cache];\n\nThis will invoke \"MyExpirePolicy->TIEHASH(args)\". MyExpirePolicy::TIEHASH should do whatever is\nappropriate to set up the cache, and it should return the cache object to the caller.\n\nFor example, MyExpirePolicy::TIEHASH might create an object that contains a regular Perl hash\n(which it will to store the cached values) and some extra information about the arguments and\nhow old the data is and things like that. Let us call this object `C'.\n\nWhen Memoize needs to check to see if an entry is in the cache already, it will invoke\n\"C->EXISTS(key)\". \"key\" is the normalized function argument. MyExpirePolicy::EXISTS should\nreturn 0 if the key is not in the cache, or if it has expired, and 1 if an unexpired value is in\nthe cache. It should *not* return \"undef\", because there is a bug in some versions of Perl that\nwill cause a spurious FETCH if the EXISTS method returns \"undef\".\n\nIf your EXISTS function returns true, Memoize will try to fetch the cached value by invoking\n\"C->FETCH(key)\". MyExpirePolicy::FETCH should return the cached value. Otherwise, Memoize will\ncall the memoized function to compute the appropriate value, and will store it into the cache by\ncalling \"C->STORE(key, value)\".\n\nHere is a very brief example of a policy module that expires each cache item after ten seconds.\n\npackage Memoize::TenSecondExpire;\n\nsub TIEHASH {\nmy ($package, %args) = @;\nmy $cache = $args{HASH} || {};\nbless $cache => $package;\n}\n\nsub EXISTS {\nmy ($cache, $key) = @;\nif (exists $cache->{$key} &&\n$cache->{$key}{EXPIRETIME} > time) {\nreturn 1\n} else {\nreturn 0; # Do NOT return `undef' here.\n}\n}\n\nsub FETCH {\nmy ($cache, $key) = @;\nreturn $cache->{$key}{VALUE};\n}\n\nsub STORE {\nmy ($cache, $key, $newvalue) = @;\n$cache->{$key}{VALUE} = $newvalue;\n$cache->{$key}{EXPIRETIME} = time + 10;\n}\n\nTo use this expiration policy, the user would say\n\nuse Memoize;\ntie my %cache10sec => 'Memoize::TenSecondExpire';\nmemoize 'function', SCALARCACHE => [HASH => \\%cache10sec];\n\nMemoize would then call \"function\" whenever a cached value was entirely absent or was older than\nten seconds.\n\nYou should always support a \"HASH\" argument to \"TIEHASH\" that ties the underlying cache so that\nthe user can specify that the cache is also persistent or that it has some other interesting\nsemantics. The example above demonstrates how to do this, as does \"Memoize::Expire\".\n\nAnother sample module, Memoize::Saves, is available in a separate distribution on CPAN. It\nimplements a policy that allows you to specify that certain function values would always be\nlooked up afresh. See the documentation for details.\n", "subsections": [] }, "ALTERNATIVES": { "content": "Brent Powers has a \"Memoize::ExpireLRU\" module that was designed to work with Memoize and\nprovides expiration of least-recently-used data. The cache is held at a fixed number of entries,\nand when new data comes in, the least-recently used data is expired. See\n.\n\nJoshua Chamas's Tie::Cache module may be useful as an expiration manager. (If you try this, let\nme know how it works out.)\n\nIf you develop any useful expiration managers that you think should be distributed with Memoize,\nplease let me know.\n", "subsections": [] }, "CAVEATS": { "content": "This module is experimental, and may contain bugs. Please report bugs to the address below.\n\nNumber-of-uses is stored as a 16-bit unsigned integer, so can't exceed 65535.\n\nBecause of clock granularity, expiration times may occur up to one second sooner than you\nexpect. For example, suppose you store a value with a lifetime of ten seconds, and you store it\nat 12:00:00.998 on a certain day. Memoize will look at the clock and see 12:00:00. Then 9.01\nseconds later, at 12:00:10.008 you try to read it back. Memoize will look at the clock and see\n12:00:10 and conclude that the value has expired. This will probably not occur if you have\n\"Time::HiRes\" installed.\n", "subsections": [] }, "AUTHOR": { "content": "Mark-Jason Dominus (mjd-perl-memoize+@plover.com)\n\nMike Cariaso provided valuable insight into the best way to solve this problem.\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "perl", "content": "The Memoize man page.\n\nhttp://www.plover.com/~mjd/perl/Memoize/ (for news and updates)\n\nI maintain a mailing list on which I occasionally announce new versions of Memoize. The list is\nfor announcements only, not discussion. To join, send an empty message to\nmjd-perl-memoize-request@Plover.com.\n" } ] } } } }