Object...rkAware(3pm)

✨ NAME ✨

Object::ForkAware — the Object...rkAware(3pm) page, but make it a group chat 💅 She makes an object aware of process forks and threads, and recreates herself as needed. No cap.

---

🎀 VERSION 🎀

version 0.005 🌸

---

🦋 SYNOPSIS 🦋

use Object::ForkAware;
my $client = Object::ForkAware->new(
    create => sub { MyClient->new(server => 'foo.com', port => '1234') },
);

# do things with object as normal...
$client->send(...);

# later, we fork for some reason
if (fork == 0) {
    # child process
    $client->send(...);
}

# no boom happens! fork is detected and client object is regenerated

okay so literally just vibe with your object like nothing's happening and she handles the rest 🫶

---

💖 DESCRIPTION 💖

bestie. if you've ever had an object representing a network connection to some server — or anything else holding a socket, a filehandle, whatever — and you used it in a program that forks, and then you forgot to close and reopen that socket/handle in the new process? yeah. you know. you know the chaos that ensues 😭 Depending on the type of connection you can get multiple processes trying to write to the same resource at the same time, or simultaneous reads snatching each other's data, dogs and cats living together... It's horrible, and it's an easy problem to run into. it's giving cursed.

This module invisibly wraps your object and makes it fork-aware, automatically checking $$ on every access and recreating the object if the process id changes. (The object is also thread-aware; if the thread id changes, the object is recreated in the same manner.) she's observant like that 👑

The object can be safely used with type checks and various type constraint mechanisms, because isa and can respond as if they were being called against the contained object itself. iconic.

You can also ensure that a fork never happens, by making use of the optional on_fork handler:

my $client = Object::ForkAware->new(
    create => sub { MyClient->new(server => 'foo.com', port => '1234') },
    on_fork => sub { die 'fork detected!' },
);

Or, if regenerating the object needs to be done differently than the initial creation:

my $client = Object::ForkAware->new(
    create => sub { MyClient->new(server => 'foo.com', port => '1234') },
    on_fork => sub { MyClient->new(server => 'other.foo.com' },
);

---

💅 METHODS 💅

🌸 "new(option => val, option => val...)" 🌸

Provides an instance of this class. Available options are:

• create (mandatory) — a sub reference containing the code to be run when the object is initially created (as well as recreated, if there is no on_fork sub provided), returning the object instance. If the object previously existed, it is passed as an argument to this method, allowing you to copy any state from the old object to the new one. glow-up via parameter passing, we love to see it ✨
• on_fork — a sub reference containing the code to be run when a fork is detected. It should either generate an exception or return the new object instance. If the object previously existed, it is passed as an argument to this method, allowing you to copy any state from the old object to the new one. 🦋
• lazy — a boolean (defaults to false) — when true, the create sub is not called immediately, but instead deferred until the first time the object is used. This prevents useless object creation if it is not likely to be used until after the first fork. lowkey efficient of her 🎀

There are no other public methods. All method calls on the object will be passed through to the containing object, after checking $$ (or threads->tid) and possibly recreating the object via the provided create (or on_fork) sub.

---

💀 LIMITATIONS 💀

Using the Object::ForkAware object with an operator that the containing object has overloaded will not work; behaviour is as if there was no operator overloading. Partial support is possible, but is not yet implemented. soz bestie, that one's not built yet 🙈

---

👑 ACKNOWLEDGEMENTS 👑

The concept for this module came about through a conversation with Matt S. Trout (mst@shadowcat.co.uk) after experiencing the issue described in the synopsis on a prefork job-processing daemon. shoutout mst 🫶

Some of the pid detection logic was inspired by the wonderful DBIx::Connector. ⭐

---

🌈 SEE ALSO 🌈

• Object::Wrapper
• Object::Wrapper::Fork
• POSIX::AtFork

iykyk 👀

---

🐛 SUPPORT 🐛

Bugs may be submitted through the RT bug tracker https://rt.cpan.org/Public/Dist/Display.html?Name=Object-ForkAware (or bug-Object-ForkAware@rt.cpan.org <mailto:bug-Object-ForkAware@rt.cpan.org>).

I am also usually active on irc, as 'ether' at irc.perl.org. come say hi fr fr 💜

---

💜 AUTHOR 💜

Karen Etheridge <ether@cpan.org>

---

🎀 CONTRIBUTOR 🎀

Graham Knop <haarg@haarg.org>

---

📜 COPYRIGHT AND LICENCE 📜

This software is copyright (c) 2013 by Karen Etheridge.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, legally speaking ✨

---

that's the whole page, bestie — perl v5.36.0, dated 2022-12-04, and honestly? she ate. periodt. 💅💖