---
name: "Cache::File::Heap"
section: "3pm"
platform: "linux"
package: "libcache-perl"
version: "2.11-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Cache::File::Heap"
---

# Cache::File::Heap(3pm)

A file based heap for use by Cache::File

## 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 $