.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Cache::BDB 3pm" .TH Cache::BDB 3pm "2018-09-22" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Cache::BDB \- An object caching wrapper around BerkeleyDB .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 6 \& use Cache::BDB; \& my %options = ( \& cache_root => "/tmp/caches", \& namespace => "Some::Namespace", \& default_expires_in => 300, # seconds \& ); \& \& my $cache = Cache::BDB\->new(%options); \& \& # \& # [myshellprompt:~]$ find /tmp/caches \& # /tmp/caches/Some::Namespace/ \& # /tmp/caches/Some::Namespace/Some::Namespace.db \& # /tmp/caches/Some::Namespace/_\|_db.001 \& # /tmp/caches/Some::Namespace/_\|_db.002 \& # /tmp/caches/Some::Namespace/_\|_db.003 \& # \& \& $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, \e%some_hash); \& $cache\->set(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq); \& $cache\->set(20, $obj, 10); \& \& $cache\->add(21, \*(Aqwhatever\*(Aq); # works, nothing with the key \*(Aq21\*(Aq set yet. \& $cache\->add(21, \*(Aqcoffeepot\*(Aq); # fails, can only add() something that hasn\*(Aqt \& # yet been set \& \& $cache\->replace(21, \*(Aqshoelace\*(Aq); # replaces the data \*(Aqwhatever\*(Aq with \& # \*(Aqshoelace\*(Aq \& $cache\->replace(7, \*(Aqtattoo\*(Aq); # fails key/value pair was never set() or \& # add()ed previously \& \& my $h = $cache\->get(1); # $h and \e%some_hash contain the same data \& my $bar = $cache\->get(\*(Aqfoo\*(Aq); # $bar eq \*(Aqbar\*(Aq; \& 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; \& \& my $hr = $cache\->get_bulk(); \& \& # $hr = {1 => {contents_of => \*(Aq%some_hash\*(Aq}, \& # 21 => \*(Aqshoelace\*(Aq }; \& \& $cache\->close(); # close the cache object .Ve .SH "DESCRIPTION" .IX Header "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 \&\fBCache::Cache\fR\-like interface as much as possible, though it may differ here and there. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" I've been developing using a very recent version of Berkeley \s-1DB\s0 (v4.4.20) and BerkeleyDB (v0.27). I'm pretty sure that most of the functionality the module relies on is available in Berkeley \s-1DB\s0 version 3 and higher, but so far I have not tested with older versions. I'm open to making version specific concessions if necessary. If at all possible, I would advise you to upgrade both Berkeley \s-1DB\s0 and BerkeleyDB to their latest respective versions. .PP Cache::BDB currently serializes everything it stores with Storable. .SH "PERFORMANCE" .IX Header "PERFORMANCE" The intent of this module is to supply great performance with a reasonably feature rich \s-1API.\s0 There is no way this module can compete with, say, using BerkeleyDB directly, and 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 \&\fBhttp://cpan.robm.fastmail.fm/cache_perf.html\fR. I've included a patch which adds Cache::BDB to the benchmark. .SH "LOCKING" .IX Header "LOCKING" All Cache::BDB environments are opened with the \s-1DB_INIT_CDB\s0 flag. This enables multiple\-reader/single\-writer locking handled entirely by the Berkeley \s-1DB\s0 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. .PP Important: it is a bad idea to share a single Cache::BDB object across multiple processes or threads. Doing so is bound to cause you pain. Instead, have your thread/process instantiate its own Cache::BDB object. It is safe to have them all pointing at the same cache file. .SH "CACHE FILES" .IX Header "CACHE FILES" For every new \fBCache::BDB\fR object, a Berkeley \s-1DB\s0 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 multiple cache database files to share a single environment, and its also possible for multiple cache databases to share a single database file. See the \s-1SYNOPSIS\s0 above for a quick view of what you are likeley to find on the filesystem for a cache. Cache::BDB uses BerkeleyDB exclusively with regard to files, so if you have questions about whats in those files, you might familiarize yourself further with Berkeley \s-1DB.\s0 .SH "USAGE" .IX Header "USAGE" .IP "\fBnew\fR(%options)" 4 .IX Item "new(%options)" .RS 4 .PD 0 .IP "\(bu" 4 .PD cache_root .Sp Specify the top level directory to store cache and related files in. This parameter is required. Keep in mind that \fBCache::BDB\fR uses a \&\fBBerkeleyDB\fR environment object so more than one file will be written for each cache. .IP "\(bu" 4 cache_file .Sp If you want to tell \fBCache::BDB\fR exactly which file to use for your cache, specify it here. This parameter is required if you plan to use the env_lock option and/or if you want to have multiple logical databases (namespaces) in a single physical file. If unspecified, \&\fBCach::BDB\fR will create its database file using the \&\fBnamespace\fR. \fBcache_file\fR should be relative to your cache_root, not fully-qualified, i.e. .Sp .Vb 3 \& my %options = ( cache_root => \*(Aq/some/location/for/caching/\*(Aq, \& cache_file => \*(Aqwhatever.db\*(Aq, \& namespace => \*(AqMyObjects\*(Aq); .Ve .Sp This gives you, among other files, /some/location/for/caching/whatever.db. Your logical database inside of 'whatever.db' will be named with 'MyObject'. If you were to then instantiate another Cache::BDB with the following: .Sp .Vb 3 \& my %options = ( cache_root => \*(Aq/some/location/for/caching/\*(Aq, \& cache_file => \*(Aqwhatever.db\*(Aq, \& namespace => \*(AqMyOtherObjects\*(Aq); .Ve .Sp You would now have two logical caches in one physical file, which is ok, but see \fBnamespace\fR below for a better idea. .IP "\(bu" 4 namespace .Sp Your \fBnamespace\fR tells \fBCache::BDB\fR where to store cache data under the \fBcache_root\fR if no \fBcache_file\fR is specified or what to call the database in the multi-database file if \fBcache_file\fR is specified. It is a required parameter. For clarity, it might be best to instantiate \&\fBCache::BDB\fR objects like so: .Sp .Vb 3 \& my $namespace = \*(AqMyObjects\*(Aq; \& my %options = ( cache_root => "/some/location/for/caching/$namespace", \& namespace => $namespace ); .Ve .Sp Unlike the examples given above under cache_file, this allows you to locate a single cache type in its own directory, which gives you more flexibility to nuke it wholesale or move things around a little. .IP "\(bu" 4 type .Sp Cache::BDB allows you to select the type of Berkeley \s-1DB\s0 storage mechanism to use. Your choices are Hash, Btree, and Recno. Queue isn't supported. I haven't tested the three supported types extensively. The default, if unspecified, is Btree, and this is probably good enough for most applications. Note that if a cache is created as one type it must remain that type. If you instantiate a Cache::BDB object with one type (or use the default), and then attempt to connect to the same cache with a newly instantiated object that uses a different type, you will get a warning, and Cache::BDB will be nice and connect you to the cache with its original type. .Sp Important: up until Berkeley \s-1DB 4.4\s0.x, it has not been possible to shrink the physical size of a database file, which means that, technically, your cache files will never get smaller even if you delete everything from them. \s-1HOWEVER,\s0 with 4.4.x this functionality is now possiblye but it will only work with the Btree type. As soon as this is available in the BerkeleyDB.pm wrapper (soon I'm told), I'll be releasing a version with some options to allow this. Point being, this may be a good reason to stick with Btree. .Sp For more info, see http://www.sleepycat.com/docs/ref/am_conf/intro.html. .IP "\(bu" 4 env_lock .Sp If multiple databases (same or different files) are opened using the same Berkeley \s-1DB\s0 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 \s-1DB\s0 attempts a read/write lock. This flag must be specified for every database opened under this environment. Note: this is very untested in Cache::BDB, and I don't know how necessary it is. .IP "\(bu" 4 default_expires_in .Sp Time (in seconds) that cached objects should live. If set to 0, objects never expire. See \fBset\fR to enable a per-object value. .IP "\(bu" 4 auto_purge_interval .Sp Time (in seconds) that the cached objects will be purged by one or both of the \fBauto_purge\fR types (get/set). If set to 0, auto purge is disabled. Note, of course, that objects won't actually be purged until some event actually takes place that will call purge (set or get), so if this is set to 300 but no gets or sets are called for more than 300 seconds, the items haven't actually been purged yet. .IP "\(bu" 4 auto_purge_on_set .Sp If this item is true and \fBauto_purge_interval\fR is greater than 0, calling the \fBset\fR method will first purge any expired records from the cache. .IP "\(bu" 4 auto_purge_on_get .Sp If this item is true and \fBauto_purge_interval\fR is greater than 0, calling the \fBget\fR method will first purge any expired records from the cache. .IP "\(bu" 4 purge_on_init .Sp If set to a true value, purge will be called before the constructor returns. .IP "\(bu" 4 purge_on_destroy .Sp If set to a true value, purge will be called before the object goes out of scope. .IP "\(bu" 4 clear_on_init .Sp If set to a true value, clear will be called before the constructor returns. .IP "\(bu" 4 clear_on_destroy .Sp If set to a true value, clear will be called before the object goes out of scope. .IP "\(bu" 4 disable_compact .Sp Disable database compactions for clear, purge, delete and remove methods. See \fB\s-1DATABASE SIZE\s0\fR below for more information on database compaction. .IP "\(bu" 4 disable_auto_purge .Sp As a courtesy, Cache::BDB will automatically \fIremove()\fR any expired cache item you \fIget()\fR before returning undef. This is handy if you don't feel the need to do a lot of explicit cache purging, but if you only want purge, remove, delete or clear to actually delete cache items, you can disable this functionality by passing in disable_auto_purge with any true value. .RE .RS 4 .RE .IP "\fBclose\fR()" 4 .IX Item "close()" Explicitly close the connection to the cache. A good idea. Essentially the same as undef'ing the object (explicitly calls \s-1DESTROY\s0). .IP "\fBnamespace\fR()" 4 .IX Item "namespace()" This read only method returns the namespace that the cache object is currently associated with. .IP "\fBauto_purge_interval\fR($seconds)" 4 .IX Item "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 \fBauto_purge\fR methodss. If set to 0, automatic purging is disabled. .IP "\fBauto_purge_on_set\fR(1/0)" 4 .IX Item "auto_purge_on_set(1/0)" Enable/disable auto purge when \fBset\fR is called. .IP "\fBauto_purge_on_get\fR(1/0)" 4 .IX Item "auto_purge_on_get(1/0)" Enable/disable auto purge when \fBget\fR is called. .ie n .IP "\fBset\fR($key, $value, [$seconds])" 4 .el .IP "\fBset\fR($key, \f(CW$value\fR, [$seconds])" 4 .IX Item "set($key, $value, [$seconds])" Store an item ($value) with the associated \f(CW$key\fR. Time to live (in seconds) can be optionally set with a third argument. Returns true on success. .ie n .IP "\fBadd\fR($key, $value, [$seconds])" 4 .el .IP "\fBadd\fR($key, \f(CW$value\fR, [$seconds])" 4 .IX Item "add($key, $value, [$seconds])" Only \fBset\fR in the cache if the key doesn't already exist. .ie n .IP "\fBreplace\fR($key, $value, [$seconds])" 4 .el .IP "\fBreplace\fR($key, \f(CW$value\fR, [$seconds])" 4 .IX Item "replace($key, $value, [$seconds])" Only \fBset\fR in the cache if the key does exist. .IP "\fBget\fR($key)" 4 .IX Item "get($key)" Locate and return the data associated with \f(CW$key\fR. Returns the object associated with \f(CW$key\fR or undef if the data doesn't exist. If \&\fBauto_purge_on_get\fR is enabled, the cache will be purged before attempting to locate the item. .IP "\fBget_bulk\fR()" 4 .IX Item "get_bulk()" Returns a hash reference containing every unexpired item from the cache key'ed on their cache id. This can be useful if your keys aren't always available or if you just want to use the cache as a convenient way to dump data in chunks. .Sp The result looks something like this: .Sp .Vb 1 \& my $h = $cache\->get_bulk(); \& \& # $h = { 123 => "bird and bee", \& # 456 => "monkeys with sticks", \& # 789 => "take whats mine", \& # }; .Ve .IP "\fBremove\fR($key)" 4 .IX Item "remove($key)" Removes the cache element specified by \f(CW$key\fR if it exists. Returns true for success. .IP "\fBdelete\fR($key)" 4 .IX Item "delete($key)" Same as \fIremove()\fR .IP "\fBclear\fR()" 4 .IX Item "clear()" Completely clear out the cache and compact the underlying database. Returns the number of cached items removed. .IP "\fBcount\fR()" 4 .IX Item "count()" Returns the number of items in the cache. .IP "\fBsize\fR()" 4 .IX Item "size()" Return the size (in bytes) of all the cached items. This call relies on the availability of \fBDevel::Size\fR. If its not found, you'll get a warning and \fIsize()\fR will simply return 0. Currently the size is calculated every time this is called by using \&\fBDevel::Size::total_size\fR, so it may be expensive for large caches. In the future size-aware options and functionality may be available, but for now you'll need to implement this outside of Cache::BDB if you need it. .IP "\fBpurge\fR()" 4 .IX Item "purge()" Purge expired items from the cache. Returns the number of items purged. .IP "\fBis_expired\fR($key)" 4 .IX Item "is_expired($key)" Returns true if the data pointed to by \f(CW$key\fR is expired based on its stored expiration time. Returns false if the data isn't expired *or* if the data doesn't exist. .SH "DATABASE SIZE" .IX Header "DATABASE SIZE" (See http://www.sleepycat.com/docs/ref/am_misc/diskspace.html) .PP Before Berkeley \s-1DB\s0 release 4.4 it was not possible to return freed space in a database file. This means that no matter how many items you delete, your file will still retain its size, and continue to grow as you add more items. The only way to get the file size back down was to dump the database to a file and reload it into a new database file. This may or may not be a problem for your application, but keep in mind that your cache will continue to get bigger and, for example, your operating system may have a maximum file size limit. .PP In 4.4, Sleepycat introduced the ability to free unused space. BerkeleyDB 0.29 exposes this functionality in the perl wrapper. If you are using these versions or better and have chosen the Btree database type (the default for Cache::BDB), your caches will automatically be compacted when items are purged, removed/deleted, or if clear is called. You can disable the automatic compaction of cache files by initializing your Cache::BDB object with the disable_compact parameter set to any true value. In my tests so far, however, database compaction does not appear to affect performance significantly, and may save you from a headache down the road. .SH "AUTHOR" .IX Header "AUTHOR" Josh Rotenberg, \f(CW\*(C`\*(C'\fR .SH "TODO" .IX Header "TODO" * Make data storage scheme configurable (Storable, \s-1YAML,\s0 Data::Dumper, or callback based) .PP * Split storage between meta and data for faster operations on meta data. .PP * Add some size/count aware features. .PP * Create some examples. .PP * Fix \fIfork()\fR'ing tests. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-cache\-bdb at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Cache::BDB .Ve .PP You can also look for information at: .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "SEE ALSO" .IX Header "SEE ALSO" BerkeleyDB .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Baldur Kristinsson Sandy Jensen .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2006 Josh Rotenberg, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.