NAME¶
Cache::File::Heap - A file based heap for use by Cache::File
SYNOPSIS¶
use Cache::File::Heap;
$heap = Cache::File::Heap->new('/path/to/some/heap/file');
$heap->add($key, $val);
($key, $val) = $heap->minimum;
($key, $val) = $heap->extract_minimum;
$heap->delete($key, $val);
DESCRIPTION¶
This module is a wrapper around a Berkeley DB using a btree structure to
implement a heap. It is specifically for use by Cache::File for storing expiry
times (although with a bit of work it could be made more general).
See LIMITATIONS below.
CONSTRUCTOR¶
my $heap = Cache::File::Heap->new( [$dbfile] );
The heap constructor takes an optional argument which is the name of the
database file to open. If specified, it will attempt to open the database
during construction. A new Cache::File::Heap blessed reference will be
returned, or undef if the open failed.
METHODS¶
- $h->open($dbfile)
- Opens the specified database file.
- $h->close()
- Closes a previously opened heap database. Note that the database will be
automatically closed when the heap reference is destroyed.
- $h->add($key, $val)
- Adds a key and value pair to the heap. Currently the key should be a
number, whilst the value may be any scalar. Invokes 'die' on failure (use
eval to catch it).
- $h->delete($key, $val)
- Removes a key and value pair from the heap. Returns 1 if the pair was
found and removed, or 0 otherwise.
- ($key, $val) = $h->minimum()
- In list context, returns the smallest key and value pair from the heap. In
scalar context only the key is returned. Note smallest is defined via a
numerical comparison (hence keys should always be numbers).
- ($key, $vals) = $h->minimum_dup()
- In list context, returns the smallest key and an array reference
containing all the values for that key from the heap. In scalar context
only the key is returned.
- ($key, $val) = $h->extract_minimum()
- As for $h->minimum(), but the key and value pair is removed from
the heap.
- ($key, $vals) = $h->extract_minimum_dup()
- As for $h->minimum_dup(), but all the values are removed from
the heap.
SEE ALSO¶
Cache::File
AUTHOR¶
Chris Leishman <chris@leishman.org>
Based on work by DeWitt Clinton <dewitt@unto.net>
COPYRIGHT¶
Copyright (C) 2003-2006 Chris Leishman. All Rights Reserved.
This module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF
ANY KIND, either expressed or implied. This program is free software; you can
redistribute or modify it under the same terms as Perl itself.
$Id: Heap.pm,v 1.6 2006/01/31 15:23:58 caleishm Exp $