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 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.5 2005/10/20 12:52:03 caleishm Exp $