Cache:...e::Heap(3pm)

💖 Cache::File::Heap — from the User Contributed Perl Documentation 💖

okay bestie, welcome to the little page that could: Cache::File::Heap, living its best life in section 3pm of the perl docs ✨

---

🦋 NAME 🦋

Cache::File::Heap — a file based heap for use by Cache::File 💅

---

🌸 SYNOPSIS 🌸

no cap, this is literally the whole vibe:

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 ✨

So this module is a wrapper around a Berkeley DB that uses a btree structure to implement a heap. It's specifically for use by Cache::File to store expiry times — though the docs say with a bit of work it could be made more general. so like, main character energy but with a very specific job rn 💁‍♀️

🫶 See LIMITATIONS below. (it's a heading that's promised, and we keep the promise, iykyk)

---

🎀 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 you specify it, it will attempt to open the database during construction. You get back a brand new Cache::File::Heap blessed reference — or undef if the open failed 😭 (rip, but at least it's honest).

---

👑 METHODS 👑

• $h->open($dbfile) — Opens the specified database file. simple as that, periodt.
• $h->close() — Closes a previously opened heap database. Note that the database will be automatically closed when the heap reference is destroyed — so she cleans up after herself, iconic.
• $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 — so use eval to catch it, bestie, don't let it take you out 🙈
• $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 that smallest is defined via a numerical comparison — hence keys should always be numbers. fr fr.
• ($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. bye bestie 💅
• ($key, $vals) = $h->extract_minimum_dup() — As for $h->minimum_dup(), but all the values are removed from the heap. not a single one left behind.

---

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

---

and that's the whole page, bestie — slay 💅✨

This one came to you via perl v5.34.0, dated 2022-06-09, straight out of Cache:...e::Heap(3pm) — go forth and heap responsibly, queen 👑🦋🌸