NAME

Cache::Weak - weak reference cache

VERSION

This documentation refers to Cache::Weak version 1.0.2

SYNOPSIS

        use Cache::Weak;
        my $cache = Cache::Weak->new();

DESCRIPTION

This cache will store it's objects without increase the reference count. This can be used for caching without interfere in objects DESTROY mechanism, since the reference in this cache won't count.

CONSTRUCTOR

You can pass a number of options to the constructor to specify things like namespace, etc. This is done by passing an inline hash (or hashref):

        my $cache = Cache::Weak->new( namespace => 'foo' );

See "PROPERTIES" below for a list of all available properties that can be set.

METHODS

set
        $cache->set($key, $object);

Store specified key/value pair in cache. Value must be a reference.

get
        my $object = $cache->get($key);

Search cache for given key. Returns undef if not found.

exists
        my $bool = $cache->exists($key);

Returns a boolean value to indicate whether there is any data present in the cache for specified entry.

remove
        $cache->remove($key)

Clear the data for specified entry from the cache.

purge
        $cache->purge();

Weak references are not removed from the cache when last "real" object goes out of scope. This means that over time the cache will grow in memory. purge() will remove all dead references from cache. Usually you don't have to run purge() manually: purging is done automatically. By default, this happens every 1000 object loads, but you can change that default by setting the 'auto_purge_interval' and 'auto_purge' properties.

clear
        $cache->clear();

Removes all entries from cache.

count
        $cache->count();

Returns the number of entries in the cache.

PROPERTIES

namespace
        my $current_ns = $cache->namespace();

The namespace associated with this cache. Defaults to "_" if not explicitly set.

auto_purge_interval
        $cache->auto_purge_interval(5000);

Sets number of cache object loads before auto purging is automatically performed. Default is 1000.

auto_purge
        $cache->auto_purge(0); # turn off auto purge

If this option is true, then the auto purge interval will be checked on every set().

DEPENDENCIES

This module requires weak references support in your system. To find out if your system supports weak references, you can run this on the command line:

        perl -e 'use Scalar::Util qw(weaken)'

If you get an error message about weak references not being implemented, this module would not work.

SEE ALSO

http://github.com/esobchenko/cache-weak/ this module on GitHub.

http://en.wikipedia.org/wiki/Weak_reference about weak references.

Scalar::Util for information about weak references in Perl.

Object::Mapper for an example of this module in use.

LICENSE AND COPYRIGHT

Copyright 2008, Eugen Sobchenko <ejs@cpan.org>

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