Tie::R...::Weak(3pm)

💖 Tie::RefHash::Weak 💖

hiii bestie 🫶 so you've landed on Tie::RefHash::Weak(3pm) — yes that's the real name, this is a User Contributed Perl Documentation page, and no I'm not gonna make you read it alone. we're doing this together. sit down, hydrate, let's go ✨

---

🌸 NAME 🌸

Tie::RefHash::Weak — it's a Tie::RefHash subclass, except the references living in the keys are weakened. that's the whole personality. that's the vibe. 💅

---

🎀 SYNOPSIS 🎀

use Tie::RefHash::Weak;
tie my %h, 'Tie::RefHash::Weak';

# OR:

use Tie::RefHash::Weak 'fieldhash';
fieldhash my %h;

{ # new scope
        my $val = "foo";

        $h{\$val} = "bar"; # key is weak ref

        print join(", ", keys %h); # contains \$val, returns regular reference
}
# $val goes out of scope, refcount goes to zero
# weak references to \$val are now undefined

keys %h; # no longer contains \$val

# see also Tie::RefHash

look at that little scoped block doing its thing 👀 the key is a weak ref, $val dips out of scope, refcount hits zero, and suddenly the weak refs to \$val are just… undefined. and then keys %h says nope, not here anymore. it's giving automatic cleanup, it's giving main character energy 🔥

---

🦋 DESCRIPTION 🦋

okay so Tie::RefHash lets you access hashes by reference. super useful when you're indexing by object, for example. iconic behavior, love that for you.

but here's the problem — with Tie::RefHash, and specifically with cross indexing, sometimes your index should not be holding strong references to the objects. Tie::RefHash's internal structures contain strong references to the key, and it gives you no convenient way to make those references weak. 😭 like ma'am please.

and that's literally why this subclass exists: this subclass of Tie::RefHash has weak keys instead of strong ones. the values are left completely unaltered — so bestie, you have to make sure there are no strong references in there yourself. that part is on you, no cap. 🫡

---

✨ FUNCTIONS ✨

for compatibility with Hash::Util::FieldHash, this module will — upon request — export the following two functions. and yes you may also write:

use Tie::RefHash::Weak ':all';

🌈 fieldhash %hash

this ties the hash and returns a reference to it. that's it. that's the function. short king 👑

🌈 fieldhashes \%hash1, \%hash2 ...

this ties each hash that's passed to it as a reference. it returns the list of references in list context, or the number of hashes in scalar context. context-sensitive, we love a flexible icon 💅

---

🔥 THREAD SAFETY 🔥

Tie::RefHash version 1.32 and above have correct handling of threads — specifically with respect to changing reference addresses. big deal, actually.

so if your module requires Tie::RefHash::Weak to be thread aware, you need to depend on both Tie::RefHash::Weak and Tie::RefHash version 1.32 (or later). two dependencies, one dream 🫶

but wait — version 0.02 and later of Tie::RefHash::Weak depend on a thread-safe version of Tie::RefHash anyway, so if you're using the latest version this should already be taken care of for you. you're covered, babe. relax. 😌

---

💀 5.10.0 COMPATIBILITY 💀

okay so this one's a little scary but it's handled. due to a minor change in Perl 5.10.0, a bug in the handling of magic freeing was uncovered — causing segmentation faults. 😭💀

this has been patched but not released yet, as of 0.08. so like… patched, yes, shipped, no. noted. 🫡

---

🙈 CAVEAT 🙈

you can use an LVALUE reference (such as "\substr ...") as a hash key. but due to a bug in perl — see http://rt.perl.org/rt3/Public/Bug/Display.html?id=46943 — it might not be possible to weaken a reference to it.

and if that happens? the hash element will never be deleted automatically. never ever. it just lives there forever. ghost tenant. 👻

---

👑 AUTHORS 👑

• Yuval Kogman <nothingmuch@woobling.org>
• some maintenance by Hans Dieter Pearcey <hdp@pobox.com>

---

💜 COPYRIGHT & LICENSE 💜

Copyright (c) 2004 Yuval Kogman. All rights reserved
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.

---

🍓 SEE ALSO 🍓

• Tie::RefHash
• Class::DBI (the live object cache)
• "Perl_magic_killbackrefs" in mg.c

---

and that's the whole page bestie!! this one's from perl v5.32.0, dated 2021-01-06, and it's filed under Tie::R...::Weak(3pm) 💖 go forth and weaken those refs responsibly. periodt. 💅✨