info > Cache::File::Heap

man perldoc info pydoc3 ri search

📝 NAME

Cache::File::Heap - A file based heap for use by Cache::File

🚀 Quick Reference

Use Case	Command	Description
Create a new heap object	Cache::File::Heap->new('/path/to/heap')	Opens or creates a heap database file
Add a key-value pair	$heap->add($key, $val)	Inserts a numeric key and scalar value
Get the smallest key-value pair	$heap->minimum()	Returns the minimum key and its value (list context)
Extract the smallest pair	$heap->extract_minimum()	Removes and returns the minimum key-value pair
Delete a specific pair	$heap->delete($key, $val)	Removes a key-value pair, returns 1 if found
Get all values for the smallest key	$heap->minimum_dup()	Returns the smallest key and an array ref of all its values
Extract all values for the smallest key	$heap->extract_minimum_dup()	Removes and returns the smallest key and all its values

📋 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 AT leishman.org>
Based on work by DeWitt Clinton <dewitt AT 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 $

perl v5.32.0 2021-01-01 Cache::File::Heap(3pm)

📝 NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION 🔧 CONSTRUCTOR 🛠️ METHODS 🔗 SEE ALSO 👤 AUTHOR ©️ COPYRIGHT