NAME

Cache::BDB - An object caching wrapper around BerkeleyDB

SYNOPSIS

use Cache::BDB;
my %options = (
   cache_root => "/tmp",
   namespace => "Some::Namespace",
   default_expires_in => 300, # seconds
);

my $cache = Cache::BDB->new(%options);

$cache->namespace(); # returns "Some::Namespace", read only
$cache->default_expires_in(); # returns 300
$cache->default_expires_in(600); # change it to 600

$cache->set(1, \%some_hash);
$cache->set('foo', 'bar');
$cache->set(20, $obj, 10);

my $h = $cache->get(1); # $h and \%some_hash contain the same data
my $bar = $cache->get('foo'); # $bar eq 'bar';
my $obj = $cache->get(20); # returns the blessed object

$cache->count() == 3;
# assuming 10 seconds has passed ...
$cache->is_expired(20); # returns true ..
$cache->purge();
$cache->get(20); # returns undef
$cache->count() == 2;

undef $cache; # close the cache object

DESCRIPTION

This module implements a caching layer around BerkeleyDB for object persistence. It implements the basic methods necessary to add, retrieve, and remove objects. The main advantage over other caching modules is performance. I've attempted to stick with a Cache::Cache like interface as much as possible.

PERFORMANCE

The intent of this module is to supply great performance with a reasonably feature rich API. There is no way this module can compete with, say, using BerkeleyDB directly, but if you don't need any kind of expiration, automatic purging, etc, that will more than likely be much faster. If you'd like to compare the speed of some other caching modules, have a look at http://cpan.robm.fastmail.fm/cache_perf.html. I've included a patch which adds Cache::BDB to the benchmark.

LOCKING

All cache Berkeley DB environments are opened with the DB_INIT_CDB flag. This enables multiple-reader/single-writer locking handled entirely by the Berkeley DB internals at either the database or environment level. See http://www.sleepycat.com/docs/ref/cam/intro.html for more information on what this means for locking.

CACHE FILES

For every new Cache::BDB object, a Berkeley DB Environment is created (or reused if it already exists). This means that even for a single cache object, at least 4 files need to be created, three for the environment and at least one for the actual data in the cache. Its possible for mutliple cache database files to share a single environment, and its also possible for multiple cache databases to share a single database file.

USAGE

new(%options)

* cache_root

Specify the top level directory to store cache and related files in. This parameter is required. Keep in mind that Cache::BDB uses a BerkeleyDB environment object so more than one file will be written for each cache.

* cache_file

If you want to tell Cache::BDB exactly which file to use for your cache, specify it here. This paramater is required if you plan to use the env_lock option and/or if you want to have multiple databases in single file. If unspecified, Cach::BDB will create its database file using the namespace.

* namespace

Your namespace tells Cache::BDB where to store cache data under the cache_root if no cache_file is specified or what to call the database in the multi-database file if cache_file is specified. It is a required parameter.

* env_lock

If multiple databases (same or different files) are opened using the same Berkeley DB environment, its possible to turn on environment level locking rather than file level locking. This may be advantageous if you have two separate but related caches. By passing in the env_lock parameter with any true value, the environment will be created in such a way that any databases created under its control will all lock whenever Berkeley DB attempts a read/write lock. This flag must be specified for every database opened under this environment.

* default_expires_in

Time (in seconds) that cached objects should live. If set to 0, objects never expire. See set to enable a per-object value.

* auto_purge_interval

Time (in seconds) that the cached will be purged by one or both of the auto_purge types (get/set). If set to 0, auto purge is disabled.

* auto_purge_on_set

If this item is true and auto_purge_interval is greater than 0, calling the set method will first purge any expired records from the cache.

* auto_purge_on_get

If this item is true and auto_purge_interval is greater than 0, calling the get method will first purge any expired records from the cache.

* purge_on_init

If set to a true value, purge will be called before the constructor returns.

* purge_on_destroy

If set to a true value, purge will be called before the object goes out of scope.

* clear_on_init

If set to a true value, clear will be called before the constructor returns.

* clear_on_destroy

If set to a true value, clear will be called before the object goes out of scope.

namespace()

This read only method returns the namespace that the cache object is currently associated with.

auto_purge_interval($seconds)

Set/get the length of time (in seconds) that the cache object will wait before calling one or both of the auto_purge methodss. If set to 0, automatic purging is disabled.

auto_purge_on_set(1/0)

Enable/disable auto purge when set is called.

auto_purge_on_get(1/0)

Enable/disable auto purge when get is called.

set($key, $value, [$seconds])

Store an item ($value) with the associated $key. Time to live (in seconds) can be optionally set with a third argument.

get($key)

Locate and return the data associated with $key. Returns undef if the data doesn't exist. If auto_purge_on_get is enabled, the cache will be purged before attempting to locate the item.

remove($key)

Removes the cache element specified by $key if it exists.

clear()

Completely clear out the cache.

count

Returns the number of items in the cache.

size

Currently broken. Return the size (in bytes) of all the cached items. In the future, maybe a callback can be set that calculates the size of the data however the user wants, and that data stored upon set in the meta data.

purge

Purge expired items from the cache.

is_expired($key)

Returns true if the data pointed to by $key is expired based on its stored expiration time.

AUTHOR

Josh Rotenberg, <joshrotenberg at gmail.com>

TODO

* Make data storage scheme configurable (Storable, YAML, Data::Dumper, or callback based)

* Split storage between meta and data for faster operations on meta data.

* Add some size/count aware features.

* Solve the perpetually growing db file problem inherent in Berkeley DB by allowing atomic mv/unlink/whatever of cachefiles, possibly some kind of cache meta options like 'unlink_on_init'.

* Create some examples.

* Fix fork()'ing tests.

BUGS

Please report any bugs or feature requests to bug-cache-bdb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Cache-BDB. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Cache::BDB

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Cache-BDB

• CPAN Ratings

  http://cpanratings.perl.org/d/Cache-BDB

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Cache-BDB

• Search CPAN

  http://search.cpan.org/dist/Cache-BDB

ACKNOWLEDGEMENTS

Baldur Kristinsson

COPYRIGHT & LICENSE

Copyright 2006 Josh Rotenberg, all rights reserved.

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

1;

__END__

cpanm Cache::BDB

perl -MCPAN -e shell
install Cache::BDB