NAME

Tie::Hash::MultiKeyCache - aged cache or fifo

SYNOPSIS

This module is an extension of Tie::Hash::MultiKey and it iherits all of the methods and characteristics of the parent module. Only the methods unique to this module are shown here. See Tie::Hash::MultiKey for complete documentation.

  use Tie::Hash::MultiKeyCache;

  $thm = tie %h, 'Tie::Hash::MultiKeyCache',
		SIZE	=> n,
		ADDKEY	=> false,
		DELKEY	=> false;
  or

  $thm = tie %h, 'Tie::Hash::MultiKeyCache',
		SIZE	=> n,
		FIFO	=> true,

  $rv      = $thm->lock($key);
  $rv      = $thm->unlock($key);
  $size    = $thm->cacheSize();
  $oldsize = $thm->newSize();

DESCRIPTION

This module provides a setable fixed size CACHE implemented as a hash with multiple keys per value. In normal use as new values are added to the CACHE and the CACHE size is exceeded, the least used items will drop from the CACHE. Particular items may be locked into the CACHE so they never expire.

The CACHE may also be configured as a FIFO where the first items added to the CACHE are the first to drop out when size is exceeded. As in the recent use scenario, items LOCKED into CACHE will not be dropped.

• $thm = tie %h, 'Tie::Hash::MultiKeyCache',

  SIZE	=> n,
  ADDKEY	=> false, # optional
  DELKEY	=> false; # optional
  FIFO	=> true;  # optional
    over rides ADD,DEL KEY

  The arguments beyond the package name may be specified as a hash as shown or as a reference to a hash.

  $thm = tie %h $package, { SIZE => n, options... }

  Creates a CACHE of maximum SIZE value elements and returns a method pointer. Default operation refreshes cache positioning for an element when a ADD Key or DELETE Key operation is performed. To disable this feature, provide ADDKEY and/or DELKEY with a false value.

    input:	hash,
  		cachesize
    returns:	method pointer

  The method pointer may also be accessed later with:

  $thm = tied(%h);

• $rv = $thm->lock($key);

  Locks the value item into CACHE via any key in the value item's key set.

    input:	any key associated with value
    return:	true on success
  		false if the key does not exist

• $rv = $thm->unlock($key);

  Unlocks the value item via any key in the value item's key set. No operation is performed if the value item is not locked in CACHE.

    input:	any key associated with value
    return:	true on success
  		false if the key does not exist

• $size = $thm->cacheSize;

  Returns the set size of the CACHE. This may not be the same as the number of items in the CACHE. See: Tie::Hash::MultiKey $thm->size;

  input:	none
  returns:	set size of the CACHE

• $oldsize = $thm->newSize($newsize);

  Sets the maximum size of the CACHE to a new size and returns the old size. A CACHE flush is performed if the new CACHE is smaller than the actual size of the current CACHE. However, items locked in CACHE will not be flushed if their number exceeds the new size parameter.

AUTHOR

Michael Robinton, <miker@cpan.org>

COPYRIGHT

Copyright 2014, Michael Robinton

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

Tie::Hash, Tie::Hash::MultiKey