Linux::FD::Event(3pm)

💖 Linux::FD::Event 💖

okay bestie, welcome to Linux::FD::Event — it's a Perl module (yes, a (3pm) manpage, we're in library territory not command territory, iykyk) and it's literally the cutest little bridge between your Perl code and the Linux kernel's eventfd thing. 🌸

---

✨ VERSION ✨

version <code>0.017</code> — she's a specific girlie, don't forget it 💅

---

🦋 SYNOPSIS 🦋

look at her. she's tiny. she's powerful. she's giving main character energy:

use Linux::FD::Event;

my $foo = Linux::FD::Event->new(42);
if (fork) {
    say $foo->get while sleep 1
}
else {
    $foo->add($_) while <>;
}

like?? parent process sits there vibing and printing, child process reads lines from stdin and pokes the counter. iconic behavior fr fr 🎀

---

🌈 DESCRIPTION 🌈

so here's the tea ☕ — this module makes an eventfd object, which is a thing that userspace apps can use as an event wait/notify mechanism, and the kernel itself can use it to notify userspace apps that events happened. teamwork!! 🤝

inside this object lives an unsigned 64-bit integer counter, and the kernel is the one maintaining it. the kernel is the responsible one. the counter is the chaos.

it's got two modes: default and semaphore. and the way they differ? it's only in the get behavior. that's it. that's the whole difference. described below, obviously, because we don't gatekeep. ✨

---

👑 METHODS 👑

💜 new($initial_value, @flags)

creates a shiny new eventfd filehandler for you. the counter gets initialized with whatever value you put in $initial_value. 💖

@flags is optional (a whole list of them!), and rn it's limited to these two:

• 'non-blocking' — requires Linux 2.6.27 ⭐
• 'semaphore' — requires Linux 2.6.30 ⭐

🍓 get()

okay so here's where it gets juicy:

if the eventfd counter has a non-zero value, and 'semaphore' is not set, then a get returns a 64 bit unsigned integer containing that value — and then the counter's value gets reset to zero. poof. gone. 💀

if 'semaphore' is set, it instead decrements the counter by one and returns one. just the one. one single lil guy.

in either case, if the counter is zero at the time of the get, then the call either:

• blocks until the counter becomes non-zero, or
• fails with the error EAGAIN if the file handle has been made non-blocking.

no cap: if you made it non-blocking, it is NOT going to wait for you. it will simply say EAGAIN and leave. 🙈

🧚 add($value)

an add call adds the 64 bit unsigned integer value $value to the counter. simple. cute. effective. 💅

the max value that may be stored in the counter is the largest unsigned 64-bit value minus 1 — that's 0xfffffffffffffffe. write that down bestie. 📝

if the addition would push the counter's value past that maximum, then the add either:

• blocks until a get is performed on the file descriptor, or
• fails with the error EAGAIN if the file descriptor has been made non-blocking.

and one more thing, because it's important: an add will fail with the error EINVAL if you attempt to write the value 0xffffffffffffffff. that specific number. she's forbidden. do not try her. 🚫

---

🌟 AUTHOR 🌟

Leon Timmermans <leont@cpan.org> — the legend, the icon, the moment 👑

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2010 by Leon Timmermans.

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 cutie is from the perl v5.40.1 docs, dated 2025-04-19, and she ate. go build something with an eventfd and text me when it works 💖✨🌸🦋