# info > Cache::File::Heap

---
type: CommandReference
command: Cache::File::Heap
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `$heap = Cache::File::Heap->new($dbfile)` — Create and open a heap file.
- `$heap->add($key, $val)` — Add a key-value pair to the heap.
- `($key, $val) = $heap->minimum` — Get the smallest key-value pair without removal.
- `($key, $val) = $heap->extract_minimum` — Get and remove the smallest key-value pair.
- `$heap->delete($key, $val)` — Remove a specific key-value pair.
- `($key, $vals) = $heap->minimum_dup` — Get smallest key and all values.
- `($key, $vals) = $heap->extract_minimum_dup` — Get and remove smallest key and all values.
- `$heap->open($dbfile)` — Open a database file.
- `$heap->close()` — Close the heap.

## Name

Cache::File::Heap - A file based heap for use by [Cache::File](http://localhost/phpMan.php/perldoc/Cache%3A%3AFile/markdown)

## Synopsis

perl
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);
## Options

### Constructor

- `new([$dbfile])` — Creates a new heap object. If `$dbfile` is specified, opens the database during construction. Returns a blessed reference or `undef` on failure.

### Instance Methods

- `open($dbfile)` — Opens the specified database file.
- `close()` — Closes a previously opened heap database. Automatically called when the heap reference is destroyed.
- `add($key, $val)` — Adds a key-value pair to the heap. Key must be a number, value any scalar. Dies on failure (use `eval` to catch).
- `delete($key, $val)` — Removes a key-value pair from the heap. Returns 1 if found and removed, 0 otherwise.
- `minimum()` — In list context, returns the smallest key and value pair. In scalar context, returns only the key. Numerical comparison is used.
- `minimum_dup()` — In list context, returns the smallest key and an array reference containing all values for that key. In scalar context, returns only the key.
- `extract_minimum()` — Like `minimum()`, but the key-value pair is removed from the heap.
- `extract_minimum_dup()` — Like `minimum_dup()`, but all values for that key are removed from the heap.

## See Also

[Cache::File](http://localhost/phpMan.php/perldoc/Cache%3A%3AFile/markdown)