NAME

Tie::Cache::LRU - A Least-Recently Used cache

SYNOPSIS

use Tie::Cache::LRU;

tie %cache, 'Tie::Cache::LRU', 500;
tie %cache, 'Tie::Cache::LRU', '400k'; #UNIMPLEMENTED

# Use like a normal hash.

$cache_obj = tied %cache;
$current_size = $cache_obj->curr_size;

$max_size = $cache_obj->max_size;
$cache_obj->max_size($new_size);

DESCRIPTION

NOTE There are no plans to update this module. Please consider using CHI or other caching framework.

This is an implementation of a least-recently used (LRU) cache keeping the cache in RAM.

A LRU cache is similar to the kind of cache used by a web browser. New items are placed into the top of the cache. When the cache grows past its size limit, it throws away items off the bottom. The trick is that whenever an item is -accessed-, it is pulled back to the top. The end result of all this is that items which are frequently accessed tend to stay in the cache.

USAGE

The cache is extremely simple, is just holds a simple scalar. If you want to cache an object, just place it into the cache:

$cache{$obj->id} = $obj;

This doesn't make a copy of the object, it just holds a reference to it. (Note: This means that your object's destructor will not be called until it has fallen out of the cache (and all other references to it have disappeared, of course)!)

If you want to cache an array, place a reference to it in the cache:

$cache{$some_id} = \@array;

Or, if you're worried about the consequences of tossing around references and want to cache a copy instead, you can do something like this:

$cache{$some_id} = [@array];

Tied Interface

tie

tie %cache, 'Tie::Cache::LRU';
tie %cache, 'Tie::Cache::LRU', $cache_size;

This ties a cache to %cache which will hold a maximum of $cache_size keys. If $cache_size is not given it uses a default value, Tie::Cache::LRU->DEFAULT_MAX_SIZE.

If the size is set to 0, the cache is effectively turned off. This is useful for "removing" the cache from a program without having to make deep alterations to the program itself, or for checking performance differences with and without a cache.

All of the expected hash operations (exists, delete, slices, etc...) work on the %cache.

Object Interface

There's a few things you just can't do through the tied interface. To do them, you need to get at the underlying object, which you do with tied().

$cache_obj = tied %cache;

And then you can call a few methods on that object:

max_size

$cache_obj->max_size($size);
$size = $cache_obj->max_size;

An accessor to alter the maximum size of the cache on the fly.

If max_size() is reset, and it is lower than the current size, the cache is immediately truncated.

The size must be an integer greater than or equal to 0.

curr_size

$size = $cache_obj->curr_size;

Returns the current number of items in the cache.

NOTES

This is just a thin subclass of Tie::Cache::LRU::Array.

TODO

Should eventually allow the cache to be in shared memory.

Max size by memory use unimplemented.

COPYRIGHT AND LICENSE

Copyright 1999-2015 by Michael G Schwern <schwern@pobox.com>.

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

See http://dev.perl.org/licenses/

AUTHOR

Michael G Schwern <schwern@pobox.com>.

SEE ALSO

CHI for a more modern cache implementation.

Tie::Cache::LRU::Array, Tie::Cache::LRU::LinkedList, Tie::Cache::LRU::Virtual, Tie::Cache