GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  GENEZZO::PUSHHASH::PUSHHASH (3)

.ds Aq ’

NAME

Genezzo::PushHash::PushHash.pm - an impure virtual class module that defines a "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.

CONTENTS

SYNOPSIS



 use Genezzo::PushHash::PushHash;

 my %tied_hash = ();

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

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

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

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



DESCRIPTION

While standard perl hashes are a form of associative array, where the user supplies a key/value pair, a PushHash is more like a multiset which generates its own unique key for each element. The preferred usage is to use the HPush method, which returns the new key, but you can use the PUSH pseudo key to generate a new key, e.g.:

$tied_hash{PUSH} = new value;

Note that the result of the underlying STORE only returns the pushed value, not the new key. Also, expressions like:

my $pushval = tied_hash{PUSH} = new value;

can be problematic, since the tie may try to return a FETCH of key PUSH, which will not work.

WHY

Push hashes can be used to restructure code based upon references to anonymous hashes or arrays in order to facilitate the persistent storage of data structures. Also, they are useful for implementing shared data structures or data structures with transactional update semantics, where you would want concurrent access and quick unique key generation. In addition, they can be used to create data structures larger than main memory, or handle cases where multiple keys or key traversal mechanisms get mapped to the same data. In other words, they are similar to SQL database ties or tied DB hashes, but potentially more flexible and extensible.

FUNCTIONS

PushHashes support all standard hash operations, with the exception that you cannot create or insert a user key — you must push new entries and use the generated key or basic iteration to retrieve your data. It also supports two additional methods, HPush and HCount. Note that these methods are associated with the tie value (i.e. the blessed ref for the PushHash class), not the tied hash.
HPush HPush returns the new key for each pushed value, or an undef if the append fails. It only accepts a single argument, not a list.

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

Note that there is not a corresponding pop operation, since the generic PushHash does not define an ordering on the contents of the hash.

HCount Returns the count of items in the hash — equivalent to an array FETCHSIZE, i.e. scalar(@array).

    Why use a distinctive HPush function versus an array-like PUSH?

HPush is designed to support quick appends of a single value to a push-hash and return the new key, or return an undef if the push fails. The basic perl push appends a LIST and returns the new number of elements in the array.
Ease of obtaining new key value HPush returns the new key in a single operation, while push returns the size of the array. Unlike an array, the pushhash implementation does not have to generate keys that are simple ascending integers, so returning the number of elements in a hash would require extra operations to obtain the new key. The classic push works well for arrays since the number of elements in an array is essentially the offset of the new key.
Ease of failure detection If HPush fails, it returns an undef. Push requires an extra calculation to compare the returned count with the previous fetchsize to see if the push succeeded.
Efficiency For a standard push, you should be able to determine if it fails by checking the array size before and after the push. However, for many hash implementations, counting all the elements in the data structure may be very expensive. One example is a disk-based persistent hash, where the count may require a reading a file to count the entries. For large or complex data structures, returning the local information that an append failed should be much cheaper than calculating the number of valid entries twice.

    Why use a distinctive HCount function versus an array-like FETCHSIZE?

The distinction is subtle. An array FETCHSIZE is a cheap operation that just returns the number of elements in the array. HCount is a potentially expensive operation that returns the number of valid data elements in the pushhash. For the example of the disk-based persistent hash, the HCount could involve reading multiple files on disk and special operations to distinguish between valid and deleted data.

    EXPORT

RADIXPOINT - by default .. A separator for a multipart key.

AUTHOR

Jeffrey I. Cohen, jcohen@genezzo.com

SEE ALSO

perl(1).

Copyright (c) 2003, 2004 Jeffrey I Cohen. All rights reserved.



    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA



Address bug reports and comments to: jcohen@genezzo.com

For more information, please visit the Genezzo homepage at <http://www.genezzo.com>

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 GENEZZO::PUSHHASH::PUSHHASH (3) 2005-07-19

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.