Linux::Epoll(3pm)

📦
version 0.019 · 7 versions
, in ubuntu stonking

💖 Linux::Epoll — the manual, but make it cute 💖

okay bestie, you found it: the Linux::Epoll page from the User Contributed Perl Documentation section of the manual. it's giving callback-style epoll for Linux, and honestly? iconic. let's get into it 🫶

✨ NAME ✨

Linux::Epoll — O(1) multiplexing for Linux, no cap 💅

🌸 VERSION 🌸

version 0.019 — that's the vibe check, and it passed ✅

🦋 SYNOPSIS 🦋

okay so literally all you need to start:

use Linux::Epoll;

my $epoll = Linux::Epoll->new();
$epoll->add($fh, 'in', sub {
    my $events = shift;
    do_something($fh) if $events->{in};
});
$epoll->wait while 1;

look at her. main character energy fr fr 🔥

👑 DESCRIPTION 👑

So epoll is a multiplexing mechanism that scales up O(1) with the number of watched files — like, it does NOT get slower as you add more files, she just eats 📈✨

Linux::Epoll is a callback style epoll module, which is the whole point, because unlike the other epoll modules on CPAN, this one hands you callbacks instead of making you do the whole loop yourself. different breed.

🎀 Types of events 🎀

here's the menu of event flags, and every single one matters, don't skip:

  • in — the associated filehandle is available for reading 📖
  • out — the associated filehandle is available for writing ✍️
  • err — an error condition happened on the associated filehandle. heads up: wait always waits on this event, so you do NOT have to set it yourself with add or modify. she shows up uninvited 💀
  • prio — there's urgent data available for reading 🚨
  • et — sets edge triggered behavior for the associated filehandle. the default behavior is level triggered. go check your epoll(7) documentation for what that actually means, i'm not doing that for you 🧚
⚠️ take note bestie: when you're using edge triggered events, exceptions thrown out of the wait can easily cause events to be lost (specifically when you're consuming more than one event at a time). this is the dangerous one. be careful. 😭
  • hup — a hang-up happened on the associated filehandle. same deal as err: wait always waits on this, so no need to set it with add or modify 🙈
  • rdhup — the stream socket peer closed the connection, or shut down the writing half of it. this flag is especially useful for writing simple code to detect peer shutdown when you're using Edge Triggered monitoring 🍓
  • oneshot — sets the one-shot behavior for the associated file descriptor. what that means: after an event gets pulled out with wait, the associated file descriptor is internally disabled and no other events will be reported by the epoll interface. so you, the user, have to call modify to rearm the file descriptor with a new event mask. one and done, periodt ✋
  • wakeup — if oneshot and et are clear and the process has the CAP_BLOCK_SUSPEND capability, this ensures the system does not enter suspend or hibernate while this event is pending or being processed. and "processed" here has a very specific meaning: the event counts as processed from the time it is returned by a call to epoll_wait(2) until the next call to epoll_wait(2) on the same epoll(7) file descriptor — OR the closure of that file descriptor, OR the removal of the event file descriptor with EPOLL_CTL_DEL, OR the clearing of EPOLLWAKEUP for the event file descriptor with EPOLL_CTL_MOD. four ways to end it, slay 💜
  • exclusive — sets an exclusive wakeup mode for the epoll file descriptor that is being attached to the target file descriptor, fd. here's the tea: when a wakeup event occurs and multiple epoll file descriptors are attached to the same target file using exclusive, then one or more of those epoll file descriptors will receive an event with wait(). the default, i.e. when exclusive is not set, is that all epoll file descriptors receive an event. so exclusive is useful for avoiding thundering herd problems in certain scenarios. you know the ones. 🐎🐎🐎

and if the same file descriptor is in multiple epoll instances — some with the exclusive flag, some without — then events get provided to all the epoll instances that did not specify exclusive, and at least one of the epoll instances that did specify exclusive.

the following values may be specified in conjunction with exclusive: in, out, wakeup, and et. hup and err can also be specified, but that is not required — as usual, these events are always reported if they occur, regardless of whether they're specified in events. attempts to specify other values in events yield an error. and listen: exclusive may be used only in an add() operation — attempts to employ it with modify yield an error. if exclusive has been set using add(), then a subsequent modify() on the same epfd, fd pair yields an error. and a call to add( that specifies exclusive in events and specifies the target file descriptor fd as an epoll instance will likewise fail. the error in all of these cases is EINVAL. every single one. EINVAL. 😤

💅 METHODS 💅

⭐ new()

Create a new epoll instance. that's it, that's the method. baby's first epoll ✨

⭐ add($fh, $events, $callback)

Register the filehandle with the epoll instance and associate events $events and callback $callback with it. $events may be either a string (e.g. 'in') or an arrayref (e.g. [qw/in out hup/]). versatile queen 👑

if a filehandle already exists in the set and add is called in non-void context, it returns undef and sets $! to EEXIST. if the file can't be waited upon, it sets $! to EPERM instead. on all other error conditions, an exception is thrown 🚩

the callback gets a single argument: a hashref whose keys are the triggered events. yes, one argument. yes, it's a hashref. memorize it 🫶

⭐ modify($fh, $events, $callback)

Change the events and callback associated on this epoll instance with filehandle $fh. the arguments work the same as with add. glow-up for an existing registration 💖

if a filehandle doesn't exist in the set and modify is called in non-void context, it returns undef and sets $! to ENOENT. on all other error conditions, an exception is thrown.

⭐ delete($fh)

Remove a filehandle from the epoll instance. blocking that number, blocking that number 📵

if a filehandle doesn't exist in the set and delete is called in non-void context, it returns undef and sets $! to ENOENT. on all other error conditions, an exception is thrown.

⭐ wait($number = 1, $timeout = undef, $sigmask = undef)

Wait for up to $number events, where $number must be greater than zero (don't test her). $timeout is the maximal time wait will wait for events, in fractional seconds. if it is undefined, she may wait indefinitely — no thoughts, head empty, just vibes 😌 $sigmask is the signal mask during the call; if it is not defined the signal mask will be untouched.

if interrupted by a signal it returns undef / an empty list and sets $! to EINTR. on all other error conditions, an exception is thrown.

🌈 REQUIREMENTS 🌈

this module requires at least Perl 5.10 and Linux 2.6.19 to function correctly. old heads welcome, but not too old 🧓✨

🔥 SEE ALSO 🔥

go read these too, i'm obsessed with all of them:

  • IO::Epoll
  • Sys::Syscall
  • IO::Poll

🌸 AUTHOR 🌸

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

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. free as in bestie, go wild 🎀

and that's the whole page, babe 💖 this one came out of perl v5.42.3, dated 2026-08-19, living in the Linux::Epoll(3pm) section of your manual. now go write some O(1) callbacks and text me when it works. slay 💅✨🫶

📦 where this page comes from