Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Memoize::Expire(3)     Perl Programmers	Reference Guide	    Memoize::Expire(3)

NAME
       Memoize::Expire - Plug-in module	for automatic expiration of memoized
       values

SYNOPSIS
	 use Memoize;
	 use Memoize::Expire;
	 tie my	%cache => 'Memoize::Expire',
			    LIFETIME =>	$lifetime,    #	In seconds
			    NUM_USES =>	$n_uses;

	 memoize 'function', SCALAR_CACHE => [HASH => \%cache ];

DESCRIPTION
       Memoize::Expire is a plug-in module for Memoize.	 It allows the cached
       values for memoized functions to	expire automatically.  This manual
       assumes you are already familiar	with the Memoize module.  If not, you
       should study that manual	carefully first, paying	particular attention
       to the HASH feature.

       Memoize::Expire is a layer of software that you can insert in between
       Memoize itself and whatever underlying package implements the cache.
       The layer presents a hash variable whose	values expire whenever they
       get too old, have been used too often, or both. You tell	"Memoize" to
       use this	forgetful hash as its cache instead of the default, which is
       an ordinary hash.

       To specify a real-time timeout, supply the "LIFETIME" option with a
       numeric value.  Cached data will	expire after this many seconds,	and
       will be looked up afresh	when it	expires.  When a data item is looked
       up afresh, its lifetime is reset.

       If you specify "NUM_USES" with an argument of n,	then each cached data
       item will be discarded and looked up afresh after the nth time you
       access it.  When	a data item is looked up afresh, its number of uses is
       reset.

       If you specify both arguments, data will	be discarded from the cache
       when either expiration condition	holds.

       Memoize::Expire uses a real hash	internally to store the	cached data.
       You can use the "HASH" option to	Memoize::Expire	to supply a tied hash
       in place	of the ordinary	hash that Memoize::Expire will normally	use.
       You can use this	feature	to add Memoize::Expire as a layer in between a
       persistent disk hash and	Memoize.  If you do this, you get a persistent
       disk cache whose	entries	expire automatically.  For example:

	 #   Memoize
	 #	|
	 #   Memoize::Expire  enforces data expiration policy
	 #	|
	 #   DB_File  implements persistence of	data in	a disk file
	 #	|
	 #   Disk file

	 use Memoize;
	 use Memoize::Expire;
	 use DB_File;

	 # Set up persistence
	 tie my	%disk_cache => 'DB_File', $filename, O_CREAT|O_RDWR, 0666];

	 # Set up expiration policy, supplying persistent hash as a target
	 tie my	%cache => 'Memoize::Expire',
			    LIFETIME =>	$lifetime,    #	In seconds
			    NUM_USES =>	$n_uses,
			    HASH => \%disk_cache;

	 # Set up memoization, supplying expiring persistent hash for cache
	 memoize 'function', SCALAR_CACHE => [ HASH => \%cache ];

INTERFACE
       There is	nothing	special	about Memoize::Expire.	It is just an example.
       If you don't like the policy that it implements,	you are	free to	write
       your own	expiration policy module that implements whatever policy you
       desire.	Here is	how to do that.	 Let us	suppose	that your module will
       be named	MyExpirePolicy.

       Short summary: You need to create a package that	defines	four methods:

	TIEHASH
	   Construct and return	cache object.

	EXISTS
	   Given a function argument, is the corresponding function value in
	   the cache, and if so, is it fresh enough to use?

	FETCH
	   Given a function argument, look up the corresponding	function value
	   in the cache	and return it.

	STORE
	   Given a function argument and the corresponding function value,
	   store them into the cache.

	CLEAR
	   (Optional.)	Flush the cache	completely.

       The user	who wants the memoization cache	to be expired according	to
       your policy will	say so by writing

	 tie my	%cache => 'MyExpirePolicy', args...;
	 memoize 'function', SCALAR_CACHE => [HASH => \%cache];

       This will invoke	"MyExpirePolicy->TIEHASH(args)".
       MyExpirePolicy::TIEHASH should do whatever is appropriate to set	up the
       cache, and it should return the cache object to the caller.

       For example, MyExpirePolicy::TIEHASH might create an object that
       contains	a regular Perl hash (which it will to store the	cached values)
       and some	extra information about	the arguments and how old the data is
       and things like that.  Let us call this object `C'.

       When Memoize needs to check to see if an	entry is in the	cache already,
       it will invoke "C->EXISTS(key)".	 "key" is the normalized function
       argument.  MyExpirePolicy::EXISTS should	return 0 if the	key is not in
       the cache, or if	it has expired,	and 1 if an unexpired value is in the
       cache.  It should not return "undef", because there is a	bug in some
       versions	of Perl	that will cause	a spurious FETCH if the	EXISTS method
       returns "undef".

       If your EXISTS function returns true, Memoize will try to fetch the
       cached value by invoking	"C->FETCH(key)".  MyExpirePolicy::FETCH	should
       return the cached value.	 Otherwise, Memoize will call the memoized
       function	to compute the appropriate value, and will store it into the
       cache by	calling	"C->STORE(key, value)".

       Here is a very brief example of a policy	module that expires each cache
       item after ten seconds.

	       package Memoize::TenSecondExpire;

	       sub TIEHASH {
		 my ($package, %args) =	@_;
		 my $cache = $args{HASH} || {};
		 bless $cache => $package;
	       }

	       sub EXISTS {
		 my ($cache, $key) = @_;
		 if (exists $cache->{$key} &&
		     $cache->{$key}{EXPIRE_TIME} > time) {
		   return 1
		 } else	{
		   return 0;  #	Do NOT return `undef' here.
		 }
	       }

	       sub FETCH {
		 my ($cache, $key) = @_;
		 return	$cache->{$key}{VALUE};
	       }

	       sub STORE {
		 my ($cache, $key, $newvalue) =	@_;
		 $cache->{$key}{VALUE} = $newvalue;
		 $cache->{$key}{EXPIRE_TIME} = time + 10;
	       }

       To use this expiration policy, the user would say

	       use Memoize;
	       tie my %cache10sec => 'Memoize::TenSecondExpire';
	       memoize 'function', SCALAR_CACHE	=> [HASH => \%cache10sec];

       Memoize would then call "function" whenever a cached value was entirely
       absent or was older than	ten seconds.

       You should always support a "HASH" argument to "TIEHASH"	that ties the
       underlying cache	so that	the user can specify that the cache is also
       persistent or that it has some other interesting	semantics.  The
       example above demonstrates how to do this, as does "Memoize::Expire".

       Another sample module, Memoize::Saves, is available in a	separate
       distribution on CPAN.  It implements a policy that allows you to
       specify that certain function values would always be looked up afresh.
       See the documentation for details.

ALTERNATIVES
       Brent Powers has	a "Memoize::ExpireLRU" module that was designed	to
       work with Memoize and provides expiration of least-recently-used	data.
       The cache is held at a fixed number of entries, and when	new data comes
       in, the least-recently used data	is expired.  See
       <http://search.cpan.org/search?mode=module&query=ExpireLRU>.

       Joshua Chamas's Tie::Cache module may be	useful as an expiration
       manager.	 (If you try this, let me know how it works out.)

       If you develop any useful expiration managers that you think should be
       distributed with	Memoize, please	let me know.

CAVEATS
       This module is experimental, and	may contain bugs.  Please report bugs
       to the address below.

       Number-of-uses is stored	as a 16-bit unsigned integer, so can't exceed
       65535.

       Because of clock	granularity, expiration	times may occur	up to one
       second sooner than you expect.  For example, suppose you	store a	value
       with a lifetime of ten seconds, and you store it	at 12:00:00.998	on a
       certain day.  Memoize will look at the clock and	see 12:00:00.  Then
       9.01 seconds later, at 12:00:10.008 you try to read it back.  Memoize
       will look at the	clock and see 12:00:10 and conclude that the value has
       expired.	 This will probably not	occur if you have "Time::HiRes"
       installed.

AUTHOR
       Mark-Jason Dominus (mjd-perl-memoize+@plover.com)

       Mike Cariaso provided valuable insight into the best way	to solve this
       problem.

SEE ALSO
       perl(1)

       The Memoize man page.

       http://www.plover.com/~mjd/perl/Memoize/	 (for news and updates)

       I maintain a mailing list on which I occasionally announce new versions
       of Memoize.  The	list is	for announcements only,	not discussion.	 To
       join, send an empty message to mjd-perl-memoize-request@Plover.com.

perl v5.26.0			  2017-02-28		    Memoize::Expire(3)

NAME | SYNOPSIS | DESCRIPTION | INTERFACE | ALTERNATIVES | CAVEATS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Memoize::Expire&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help