| Hash::SharedMem::Handle(3pm) | User Contributed Perl Documentation | Hash::SharedMem::Handle(3pm) |
Hash::SharedMem::Handle - handle for efficient shared mutable hash
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});
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.
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.
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.
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.
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.
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.
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.
Hash::SharedMem
Andrew Main (Zefram) <zefram@fysh.org>
Copyright (C) 2014, 2015 PhotoBox Ltd
Copyright (C) 2014, 2015, 2017 Andrew Main (Zefram) <zefram@fysh.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| 2024-04-01 | perl v5.38.2 |