NAME

Genezzo::PushHash::hph.pm - an impure virtual class module that defines a *hierarchical* "push hash", a hash that generates its own unique key for each value. Values are "pushed" into the hash, similar to pushing into an array. Hierarchical pushhashes must be supplied with a factory method which manufactures additional pushhashes as necessary.

SYNOPSIS

 use Genezzo::PushHash::hph;

 sub make_fac {
    my $tclass = shift;
    my %args = (
                @_);

    my %td_hash1  = ();

    my $newfunc = 
        sub {
            my $tiehash1 = 
                tie %td_hash1, $tclass, %args;

            return $tiehash1;
        };
    return $newfunc;
 }

 my $fac1 = make_fac('Genezzo::PushHash::PHFixed');

 %args = 
    (
     factory  => $fac1
    );

 my %tied_hash = ();

 my $tie_val = 
    tie %tied_hash, 'Genezzo::PushHash::hph', %args;

 my $newkey = $tie_val->HPush("this is a test");

 $tied_hash{$newkey} = "update this entry";

 my $getcount = $tie_val->HCount();

DESCRIPTION

A hierarchical pushhash (hph) is a pushhash built upon a collection of other pushhashes. A push into the top-level hash is routed into one of the bottom hashes. If the bottom hashes are full (push fails), the top-level pushhash uses the factory method to create or obtain a new pushhash.

The hph uses a split-level identifier scheme to route STOREs and FETCHes to the appropriate bottom level hashes. For example, the top-level hash might have three children identified with integer prefixes 1, 2, and 3. Pushes into hash 1 would return keys 1/1, 1/2, 1/3, etc. until it fills up, at which point the top-level hash would redirect pushes into hash 2, generating keys 2/1, 2/2, 2/3, etc. When key "1/2" is fetched, the top-level hash "splits" the key and directs child hash "1" to fetch key "2". Iteration over keys is similar: the parent interates over the set of child hashes, and each child iterates over its set of keys.

You may construct hierarchical pushhashes of arbitrary depth.

EXPORT

RIDSEP -- (Row) Identifier Separator character - "/" by default.
RIDSEPRX -- Regular Expression for RIDSEP - used to handle case of "." as separator, or other regexp metachars, for internal RID join and split operations.
MAXCOUNT -- no max if -1, else maximum number of elements for this hash

CONCEPTS and INTERNALS - useful for implementors

A hph is constructed of N pushhash "chunks", and the elements of each chunk are referred to as "slices". Typically, one chunk is "current" -- we push into the current chunk until it fills up, at which point the hph attempts to make a new one. Key identifiers are called "rids", and a rid may have multiple parts, e.g. "1/2/3/4". When this rid is split, the first part, "1", is the "chunk number", and the remainder "2/3/4" is the "slice number". The basic implementation uses positive integers for chunk and slice numbers -- zeroes reset the FIRSTKEY/NEXTKEY mechanism and may indicate errors, among other things.

The following methods are private to hph and should only be used in the construction of subclasses and friend classes.

_currchunkno: get the number of the current (active) chunk. NOTE WELL: when constructing push hash classes, remember that "current" has the specific meaning of the insert high-water mark -- the "current" insertion point. It's not necessarily the last chunk that you were using, or the chunk that is currently cached.
_get_current_chunk: return the current chunk
_make_new_chunk: construct a new chunk and return it
_get_a_chunk: given a chunk number, returns the chunk
_get_chunk_and_slice: given a rid, it returns the actual chunk (not the chunk number) and the slice number.
_joinrid/_splitrid: construct and deconstruct rid's from/to the chunknumber and the slice number using the rid separator regular expression.
_First_Chunkno/_Next_Chunkno: methods to iterate over the chunk numbers.

AUTHOR