Hash::...:Handle(3pm)

📦

version 0.005 · 5 versions

✨ Hash::SharedMem::Handle ✨ <small>(that's the Hash::...:Handle(3pm) page bestie 💅)</small>

okay so this page is part of the User Contributed Perl Documentation — a whole section of docs written by actual humans, not the Perl core girlies 🫶. Pull up a chair, grab a boba, and let's talk about handles for shared mutable hashes. no cap, this one's a banger.

🌸 NAME 🌸

Hash::SharedMem::Handle — it's the handle for efficient shared mutable hash. that's it. that's the name. iconic 💖

🌈 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});

look at all those possibilities. the range. the versatility. we love a multi-talented king 👑

💜 DESCRIPTION 💜

so an object of this class is a handle that refers to a memory-mapped shared hash object — the kind of thing described over in Hash::SharedMem. you can hand it straight to the functions of that module, or you can do the exact same stuff by calling the methods below. mix and match however you want, fr fr — the function interface and the method interface are completely equivalent in function.

but bestie… they are not equivalent in performance. 😭 the method interface is somewhat slower. so it's giving convenience, not speed.

this class also hooks you up with a tied-hash interface to shared hashes. and listen. the tied interface is much slower than both the function and the method interfaces. 💀 also — and this is important — the behaviour of a tied hash here more resembles the function and method interfaces to shared hashes than it resembles the syntactically-similar use of ordinary Perl hashes. it looks like a regular hash, but it is not one, okay??

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.

so like. it does not play. 🎀

🦋 CLASS METHODS 🦋

Hash::SharedMem::Handle->referential_handle — returns a truth value telling you whether each shared hash handle contains a first-class reference to the shared hash it refers to. for the whole discussion of why that matters, go read "Filesystem referential integrity" in Hash::SharedMem. iykyk 🧚

⭐ CONSTRUCTOR ⭐

Hash::SharedMem::Handle->open(FILENAME, MODE) — opens a shared hash object and returns a handle pointing at it. and if the shared hash can't be opened the way you asked? it dies. no notes. the deets live in "shash_open" in Hash::SharedMem. 💅

✨ METHODS ✨

one bullet each, babes, we keep it tidy:

$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

and the tea on all of them: each one of these methods is equivalent to the corresponding shash_-prefixed function in Hash::SharedMem. that's the whole vibe. go read that document for details, bestie, it's all there. 🫶

🎀 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 gives you 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, exactly as described in "shash_open" in Hash::SharedMem, and binds the variable to the shared hash so the variable gives you a view of the shared hash that resembles an ordinary Perl hash. 🪄 the shared hash handle is returned.

👑 TIED OPERATORS 👑

heads up for every single one of these operators: the key of interest (that's the KEY parameter) and the values can each be any octet (Latin-1) string. but —

strings containing non-octets (Unicode characters above U+FF) cannot be used as keys or values
items other than strings cannot be used as keys or values
if you hand it a dualvar (a scalar with independent string and numeric values), only its string value will be used. the numeric side is getting ignored, sorry girl 🙈

tied(%SHASH) — returns the handle via which %SHASH is bound to the shared hash. it's a shared hash handle, so you can call the methods above on it or pass it to the functions of Hash::SharedMem. ✨
exists($SHASH{KEY}) — returns a truth value saying 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 the specified key henceforth references the specified value. the new value must be a string. 📝
delete($SHASH{KEY}) — modifies the shared hash so the specified key is henceforth absent, and returns the value that the key previously referenced, or undef if the key was already absent. and this swap is performed atomically. slay. 💅
scalar(%SHASH)

ooh okay this one has lore. from Perl 5.25.3 onwards, it returns the number of items currently in the shared hash — matching the behaviour of untied hashes on those Perl versions. before Perl 5.25.3, starting from Perl 5.8.3 onwards, it returns a truth value indicating whether there are currently any items in the shared hash. either way it does not supply any additional information corresponding to the hash bucket usage information that untied hashes supply in this situation. and prior to Perl 5.8.3, it returns a meaningless value, due to a limitation of the tying system. 😭 rip.

⚠️ performance warning bestie, listen up: 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 that's a problem, you 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. like, just don't. 💀

scalar(keys(%SHASH))
scalar(values(%SHASH))

returns the number of items that are currently in the shared hash.

but — due to a limitation of the tying system, the item count is not extracted atomically. it's derived by means equivalent to a loop using each. so if the set of keys in the shared hash changes during this process, the count of keys visited (which is what's actually returned) doesn't necessarily match any state that the shared hash has ever been in. 🫠 yes really.

each(%SHASH)

iterates over the shared hash. on each call it returns either the next key (in scalar context) or the next key and the value it references (in list context). the iterator state is preserved between calls and it's attached to %SHASH. 🦋

the iteration process always visits the keys in lexicographical order. and 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). main character energy honestly ✨

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's possible for the shared hash content to change between them. you'll notice this 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 it resets the iterator state used by each. always returns the content in lexicographical order of key. 🔤

and yes, due to a limitation of the tying system, the content is not extracted atomically, so the content returned as a whole doesn't 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 you may see follow from that. it's giving "vibes-based snapshot".

%SHASH = LIST

setting the entire content of the shared hash (throwing away the previous content) is not supported. nope. not a thing. don't try it. 🙅‍♀️

💀 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. periodt.
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 you need to see a consistent state of a shared hash, you must create and use a snapshot handle. a snapshot may be iterated over or enumerated at leisure via any of the interfaces. 👑

🌈 SEE ALSO 🌈

Hash::SharedMem

💖 AUTHOR 💖

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

🎀 COPYRIGHT 🎀

💅 LICENSE 💅

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

okay bestie that's the whole page, we ate and left no crumbs 🍓✨ this was Hash::...:Handle(3pm) from the User Contributed Perl Documentation, delivered to you by perl v5.42.3 and dated 2026-08-20. go forth and handle your shared hashes responsibly, ily 💜🦋🌸

📦 where this page comes from

ubuntu stonking: libhash-sharedmem-perl 0.005-1build6 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms