1Cache::File::Heap(3)  User Contributed Perl Documentation Cache::File::Heap(3)
2
3
4

NAME

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

SYNOPSIS

9         use Cache::File::Heap;
10
11         $heap = Cache::File::Heap->new('/path/to/some/heap/file');
12         $heap->add($key, $val);
13         ($key, $val) = $heap->minimum;
14         ($key, $val) = $heap->extract_minimum;
15         $heap->delete($key, $val);
16

DESCRIPTION

18       This module is a wrapper around a Berkeley DB using a btree structure
19       to implement a heap.  It is specifically for use by Cache::File for
20       storing expiry times (although with a bit of work it could be made more
21       general).
22
23       See LIMITATIONS below.
24

CONSTRUCTOR

26         my $heap = Cache::File::Heap->new( [$dbfile] );
27
28       The heap constructor takes an optional argument which is the name of
29       the database file to open.  If specified, it will attempt to open the
30       database during construction.  A new Cache::File::Heap blessed
31       reference will be returned, or undef if the open failed.
32

METHODS

34       $h->open($dbfile)
35           Opens the specified database file.
36
37       $h->close()
38           Closes a previously opened heap database.  Note that the database
39           will be automatically closed when the heap reference is destroyed.
40
41       $h->add($key, $val)
42           Adds a key and value pair to the heap.  Currently the key should be
43           a number, whilst the value may be any scalar.  Invokes 'die' on
44           failure (use eval to catch it).
45
46       $h->delete($key, $val)
47           Removes a key and value pair from the heap.  Returns 1 if the pair
48           was found and removed, or 0 otherwise.
49
50       ($key, $val) = $h->minimum()
51           In list context, returns the smallest key and value pair from the
52           heap.  In scalar context only the key is returned.  Note smallest
53           is defined via a numerical comparison (hence keys should always be
54           numbers).
55
56       ($key, $vals) = $h->minimum_dup()
57           In list context, returns the smallest key and an array reference
58           containing all the values for that key from the heap.  In scalar
59           context only the key is returned.
60
61       ($key, $val) = $h->extract_minimum()
62           As for $h->minimum(), but the key and value pair is removed from
63           the heap.
64
65       ($key, $vals) = $h->extract_minimum_dup()
66           As for $h->minimum_dup(), but all the values are removed from the
67           heap.
68

SEE ALSO

70       Cache::File
71

AUTHOR

73        Chris Leishman <chris@leishman.org>
74        Based on work by DeWitt Clinton <dewitt@unto.net>
75

77        Copyright (C) 2003-2006 Chris Leishman.  All Rights Reserved.
78
79       This module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
80       KIND, either expressed or implied. This program is free software; you
81       can redistribute or modify it under the same terms as Perl itself.
82
83       $Id: Heap.pm,v 1.6 2006/01/31 15:23:58 caleishm Exp $
84
85
86
87perl v5.12.0                      2006-01-31              Cache::File::Heap(3)
Impressum