Ubuntu Manpage: Hash::SharedMem::Handle - handle for efficient shared mutable hash

Provided by: libhash-sharedmem-perl_0.005-1build4_amd64

NAME

       Hash::SharedMem::Handle - handle for efficient shared mutable hash

SYNOPSIS

           use Hash::SharedMem::Handle;

           if(Hash::SharedMem::Handle->referential_handle) { ...

           $shash = Hash::SharedMem::Handle->open($filename, "rwc");

           if($shash->is_readable) { ...
           if($shash->is_writable) { ...
           $mode = $shash->mode;

           if($shash->exists($key)) { ...
           $length = $shash->length($key);
           $value = $shash->get($key);
           $shash->set($key, $newvalue);
           $oldvalue = $shash->gset($key, $newvalue);
           if($shash->cset($key, $chkvalue, $newvalue)) { ...

           if($shash->occupied) { ...
           $count = $shash->count;
           $size = $shash->size;
           $key = $shash->key_min;
           $key = $shash->key_max;
           $key = $shash->key_ge($key);
           $key = $shash->key_gt($key);
           $key = $shash->key_le($key);
           $key = $shash->key_lt($key);
           $keys = $shash->keys_array;
           $keys = $shash->keys_hash;
           $group = $shash->group_get_hash;

           $snap_shash = $shash->snapshot;
           if($shash->is_snapshot) { ...

           $shash->idle;
           $shash->tidy;

           $tally = $shash->tally_get;
           $shash->tally_zero;
           $tally = $shash->tally_gzero;

           tie %shash, "Hash::SharedMem::Handle", $shash;
           tie %shash, "Hash::SharedMem::Handle", $filename, "rwc";

           $shash = tied(%shash);
           if(exists($shash{$key})) { ...
           $value = $shash{$key};
           $shash{$key} = $newvalue;
           $oldvalue = delete($shash{$key});

DESCRIPTION

       An object of this class is a handle referring to a memory-mapped shared hash object of the kind described
       in Hash::SharedMem.  It can be passed to the functions of that module, or the same operations can be
       performed by calling the methods described below.  Uses of the function and method interfaces may be
       intermixed arbitrarily; they are completely equivalent in function.  They are not equivalent in
       performance, however, with the method interface being somewhat slower.

       This class also supplies a tied-hash interface to shared hashes.  The tied interface is much slower than
       the function and method interfaces.  The behaviour of a tied hash more resembles the function and method
       interfaces to shared hashes than it resembles the syntactically-similar use of ordinary Perl hashes.
       Using a non-string as a key will result in an exception, rather than stringification of the key.  Using a
       string containing a non-octet codepoint as a key will also result in an exception, rather than merely
       referring to an absent hash element.

CLASS METHODS

       Hash::SharedMem::Handle->referential_handle
           Returns  a truth value indicating whether each shared hash handle contains a first-class reference to
           the shared hash to which it refers.  See "Filesystem referential integrity"  in  Hash::SharedMem  for
           discussion of the significance of this.

CONSTRUCTOR

       Hash::SharedMem::Handle->open(FILENAME, MODE)
           Opens  and  returns a handle referring to a shared hash object, or "die"s if the shared hash can't be
           opened as specified.  See "shash_open" in Hash::SharedMem for details.

METHODS

       $shash->is_readable
       $shash->is_writable
       $shash->mode
       $shash->exists(KEY)
       $shash->getd(KEY)
       $shash->length(KEY)
       $shash->get(KEY)
       $shash->set(KEY, NEWVALUE)
       $shash->gset(KEY, NEWVALUE)
       $shash->cset(KEY, CHKVALUE, NEWVALUE)
       $shash->occupied
       $shash->count
       $shash->size
       $shash->key_min
       $shash->key_max
       $shash->key_ge(KEY)
       $shash->key_gt(KEY)
       $shash->key_le(KEY)
       $shash->key_lt(KEY)
       $shash->keys_array
       $shash->keys_hash
       $shash->group_get_hash
       $shash->snapshot
       $shash->is_snapshot
       $shash->idle
       $shash->tidy
       $shash->tally_get
       $shash->tally_zero
       $shash->tally_gzero
           These  methods  are  each  equivalent  to   the   corresponding   ""shash_""-prefixed   function   in
           Hash::SharedMem.  See that document for details.

TIE CONSTRUCTORS

       tie(VARIABLE, "Hash::SharedMem::Handle", SHASH)
           VARIABLE  must be a hash variable, and SHASH must be a handle referring to a shared hash object.  The
           call binds the variable to the shared hash, so that the variable provides a view of the  shared  hash
           that resembles an ordinary Perl hash.  The shared hash handle is returned.

       tie(VARIABLE, "Hash::SharedMem::Handle", FILENAME, MODE)
           VARIABLE  must  be  a  hash  variable.  The call opens a handle referring to a shared hash object, as
           described in "shash_open" in Hash::SharedMem, and binds the variable to the shared hash, so that  the
           variable  provides  a  view of the shared hash that resembles an ordinary Perl hash.  The shared hash
           handle is returned.

TIED OPERATORS

For all of these operators, the key of interest (KEY parameter) and values can each be any octet
(Latin-1) string. Strings containing non-octets (Unicode characters above U+FF) and items other than
strings cannot be used as keys or values. If a dualvar (scalar with independent string and numeric
values) is supplied, only its string value will be used.

tied(%SHASH)
Returns the handle via which %SHASH is bound to the shared hash. This is a shared hash handle that
can be used by calling the methods described above or by passing it to the functions of
Hash::SharedMem.

exists($SHASH{KEY})
Returns a truth value indicating whether the specified key is currently present in the shared hash.

$SHASH{KEY}
Returns the value currently referenced by the specified key in the shared hash, or "undef" if the key
is absent.

$SHASH{KEY} = NEWVALUE
Modifies the shared hash so that the specified key henceforth references the specified value. The
new value must be a string.

delete($SHASH{KEY})
Modifies the shared hash so that the specified key is henceforth absent, and returns the value that
the key previously referenced, or "undef" if the key was already absent. This swap is performed
atomically.

scalar(%SHASH)
From Perl 5.25.3 onwards, returns the number of items that are currently in the shared hash. This
matches the behaviour of untied hashes on these Perl versions. Prior to Perl 5.25.3, from Perl 5.8.3
onwards, returns a truth value indicating whether there are currently any items in the shared hash.
Does not supply any additional information corresponding to the hash bucket usage information that
untied hashes supply in this situation. Prior to Perl 5.8.3, returns a meaningless value, due to a
limitation of the tying system.

If the hash is evaluated in a truth value context, with the expectation of this testing whether the
shared hash is occupied, there is a performance concern. Prior to Perl 5.25.3 only the truth value
would be determined, quite cheaply. From Perl 5.25.3 onwards, a more expensive operation is
performed, counting all the keys. If this is a problem, one can evaluate "tied(%SHASH)->occupied" to
explicitly invoke the truth-value-only operation. However, if performance is a concern then the tied
interface is best entirely avoided.

scalar(keys(%SHASH))
scalar(values(%SHASH))
Returns the number of items that are currently in the shared hash.

Due to a limitation of the tying system, the item count is not extracted atomically, but is derived
by means equivalent to a loop using "each". If the set of keys in the shared hash changes during
this process, the count of keys visited (which is what is actually returned) does not necessarily
match any state that the shared hash has ever been in.

each(%SHASH)
Iterates over the shared hash. On each call, returns either the next key (in scalar context) or the
next key and the value that it references (in list context). The iterator state, preserved between
calls, is attached to %SHASH.

The iteration process always visits the keys in lexicographical order. Unlike iteration of untied
hashes, it is safe to make any changes at all to the shared hash content between calls to "each".
Subsequent calls see the new content, and the iteration process resumes with whatever key (in the new
content) follows the key most recently visited (from the old content).

When using "each" in list context, the fetching of the next key and its corresponding value is not an
atomic operation, due to a limitation of the tying system. The key and value are fetched as two
separate operations (each one individually atomic), and it is possible for the shared hash content to
change between them. This is noticeable if the key that was fetched gets deleted before the value is
fetched: it will appear that the value is "undef", which is not a permitted value in a shared hash.

keys(%SHASH)
values(%SHASH)
%SHASH
Enumerates the shared hash's content (keys alone, values alone, or keys with values), and as a side
effect resets the iterator state used by "each". Always returns the content in lexicographical order
of key.

Due to a limitation of the tying system, the content is not extracted atomically, and so the content
returned as a whole does not necessarily match any state that the shared hash has ever been in. The
content is extracted by means equivalent to a loop using "each", and the inconsistencies that may be
seen follow therefrom.

%SHASH = LIST
Setting the entire content of the shared hash (throwing away the previous content) is not supported.

BUGS

       Due to details of the Perl implementation, this object-oriented interface to the shared hash mechanism is
       somewhat  slower  than  the  function interface, and the tied interface is much slower.  The functions in
       Hash::SharedMem are the recommended interface.

       Limitations of the tying system mean that whole-hash operations  (including  iteration  and  enumeration)
       performed  on  shared hashes via the tied interface are not as atomic as they appear.  If it is necessary
       to see a consistent state of a shared hash, one must create and use a snapshot handle.  A snapshot may be
       iterated over or enumerated at leisure via any of the interfaces.

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2014, 2015 PhotoBox Ltd

       Copyright (C) 2014, 2015, 2017 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

       This module is free software; you can redistribute it and/or modify it  under  the  same  terms  as  Perl
       itself.

perl v5.38.2                                       2024-04-01                       Hash::SharedMem::Handle(3pm)