KiokuD...bjects(3pm)

💖 KiokuDB::LiveObjects — the manual, but make it make sense 💖

okay so bestie, you're reading the page for KiokuDB::LiveObjects (that's the 3pm one, the Perl module docs, we love her). She's all about live object set tracking — keeping tabs on which objects are alive, what IDs they're rocking, and which storage entries belong to them. no cap, that's the whole job. ✨

---

🌸 VERSION 🌸

version 0.57 — yes, she's been through some things. she's thriving. 🫶

---

🎀 SYNOPSIS 🎀

here's the vibe, in code:

$live_objects->insert( $entry => $object );

$live_objects->insert( $id => $object );

my $id = $live_objects->object_to_id( $object );

my $obj = $live_objects->id_to_object( $id );

my $scope = $live_objects->new_scope;

look at her go. 💅

---

✨ DESCRIPTION ✨

this object is literally the group chat admin for the live object set. she keeps track of:

• the set of live objects
• their associated IDs
• the storage entries

that's it. that's the whole assignment. she ate. 🔥

---

👑 ATTRIBUTES 👑

clear_leaks

Boolean, and it defaults to false.

if you set it true: when the last known scope gets removed but some objects are still live, those objects get removed from the live object set.

⚠️ but listen — this does NOT prevent leaks. the memory cannot be reclaimed, periodt. all this does is stop stale objects from staying loaded. don't let it gaslight you into thinking your leak is fixed. 💀

leak_tracker

this one is a coderef or an object. either works.

if any objects are leaked (peep "clear_leaks" above for the tea), this is what you use to report them, or to break the circular structure. main character of cleanup, honestly.

• when you hand her an object, the "leaked_objects" method gets called.
• when you hand her a coderef, it just gets invoked with the objects as its arguments.

it fires after "clear_leaks" causes "clear" to be called.

for example, if you wanna break cycles you can use Data::Structure::Util's "circular_off" function:

use Data::Structure::Util qw(circular_off);

$dir->live_objects->leak_tracker(sub {
    my @leaked_objects = @_;
    circular_off($_) for @leaked_objects;
});

so clean, so demure. 🧚

keep_entries

EXPERIMENTAL — yes, she said experimental, don't come for her.

when true (and true is the default, btw), the KiokuDB::Entries loaded from the backend or created by the collapser get kept around.

🫠 heads up: this results in a considerable memory overhead, so it's no longer required. she's keeping it around for nostalgia, not necessity.

---

💅 METHODS 💅

insert

takes pairs — with id or entry as the key, and object as the value — and registers the objects. so, like, $live_objects->insert( $entry => $object ); or $live_objects->insert( $id => $object );. you got this. 🍓

objects_to_ids

object_to_id

given objects, returns their IDs — or undef for objects that aren't registered. (note: the original says "objects which not registered", and honestly? relatable grammar, we keep it. 🙈)

objects_to_entries

object_to_entry

given objects, find the corresponding entries. ✨

ids_to_objects

id_to_object

given IDs, find the corresponding objects. 💖

ids_to_entries

given IDs, find the corresponding entries. 🌈

update_entries

given entries, she replaces the live entries of the corresponding objects with the newly updated ones.

⚠️ the objects must already be in the live object set. no sneaking new ones in, bestie.

this method is called on a successful transaction commit. iconic behaviour, honestly. 👑

new_scope

creates a new KiokuDB::LiveObjects::Scope, with the current scope as its parent. baby scope, meet parent scope. 🦋

current_scope

the current KiokuDB::LiveObjects::Scope instance.

this is the scope into which newly registered objects are pushed. she's the one holding the door open. 🚪✨

new_txn

creates a new KiokuDB::LiveObjects::TXNScope, with the current txn scope as its parent. 💜

txn_scope

the current KiokuDB::LiveObjects::TXNScope. that's her. that's the one. 🎀

clear

forces a clear of the live object set.

this removes all objects and entries, and it can be useful in the case of leaks (to prevent false positives on lookups).

⚠️ but fr, note that this does not actually break the circular structures, so the leak is unresolved — it's just that the objects are no longer considered live by the KiokuDB instance. the problem didn't leave, she just stopped answering its texts. 😭

live_entries

live_objects

live_ids

enumerates the live entries, objects, or ids. pick your flavour. ⭐

rollback_entries

called by "rollback" in KiokuDB::LiveObjects::TXNScope. she doesn't do the calling, she gets called. 💅

remove

removes entries from the live object set. bye bestie. 👋

remove_scope $scope

removes a scope from the set of known scopes.

also calls "detach_scope", and calls "KiokuDB::LiveObjects::Scope/clear" on the scope itself. thorough queen. 🧹✨

detach_scope $scope

detaches $scope if it's the current scope.

this prevents "push" from being called on this scope object implicitly anymore. she's setting a boundary, and honestly? we respect it. 🫶

---

💖 AUTHOR 💖

Yuval Kogman <nothingmuch@woobling.org>

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2014 by Yuval Kogman, Infinity Interactive.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie ✨ this little masterpiece came to you via perl v5.34.0, dated 2022-05-23 — KiokuDB::LiveObjects version 0.57, no cap. go forth and track your live objects responsibly. 💜🎀🦋