Cache::File::Heap3pm

Usage

  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);

Overview

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.