# phpman > perldoc > Cache::File::Heap

## NAME
    [Cache::File::Heap](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile%3A%3AHeap/markdown) - A file based heap for use by [Cache::File](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile/markdown)

## SYNOPSIS
      use [Cache::File::Heap](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile%3A%3AHeap/markdown);

      $heap = [Cache::File::Heap](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile%3A%3AHeap/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile%3A%3AHeap/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile%3A%3AHeap/markdown)
    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](https://www.chedong.com/phpMan.php/perldoc/Cache%3A%3AFile/markdown)

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