IO::As...:Epoll(3pm)

💖 IO::Async::Loop::Epoll — the manual, but make it make sense 💖

okay so bestie, this page is IO::Async::Loop::Epoll(3pm), from the User Contributed Perl Documentation corner of the world. it's giving linux-girlie performance magic, and honestly? obsessed.

---

✨ NAME ✨

"IO::Async::Loop::Epoll" — it's how you use "IO::Async" with "epoll" on Linux. that's the whole vibe. 🐧

---

🌸 SYNOPSIS 🌸

here's the little starter pack, verbatim, no notes:

use IO::Async::Loop::Epoll;

use IO::Async::Stream;
use IO::Async::Signal;

my $loop = IO::Async::Loop::Epoll->new;

$loop->add( IO::Async::Stream->new(
      read_handle => \*STDIN,
      on_read => sub {
         my ( $self, $buffref ) = @_;
         while( $$buffref =~ s/^(.*)\r?\n// ) {
            print "You said: $1\n";
         }
      },
) );

$loop->add( IO::Async::Signal->new(
      name => 'INT',
      on_receipt => sub {
         print "SIGINT, will now quit\n";
         $loop->stop;
      },
) );

$loop->run;

read from stdin, catch that SIGINT, run the loop. it's iconic, it's simple, it eats. 💅

---

🦋 DESCRIPTION 🦋

so this class is a subclass of IO::Async::Loop, and what it does is use epoll(7) on Linux to do the read-ready and write-ready tests, so you get the whole O(1) high-performance multiplexing situation from Linux's epoll_pwait(2) syscall. no cap. 🔥

the "epoll" Linux subsystem keeps a persistent registration system, meaning better performance can be achieved in programs that are out here juggling a large number of filehandles. each epoll_pwait(2) syscall only has an overhead proportional to the number of ready filehandles, rather than the total number being watched. so like — the more you're watching, the more this matters. for more detail, go read the epoll(7) manpage, bestie. 📚

this class uses the epoll_pwait(2) system call, which atomically switches the process's signal mask, performs a wait exactly as epoll_wait(2) would, then switches it back. the way this works means a process can block the signals it cares about, but switch in an empty signal mask during the poll, so it can handle file IO and signals concurrently. it's giving multitasking main character energy, fr fr. ✨

---

🎀 CONSTRUCTOR 🎀

new

$loop = IO::Async::Loop::Epoll->new();

this function returns a new instance of a "IO::Async::Loop::Epoll" object. that's it, that's the whole thing. brand new loop, fresh out the box. 🫶

---

👑 METHODS 👑

since this is a subclass of IO::Async::Loop, all of its methods are inherited. except where noted below, all of the class's methods behave identically to "IO::Async::Loop". so like, don't stress, you already know them. 💜

loop_once

$count = $loop->loop_once( $timeout );

this method calls epoll_pwait(2), and processes the results of that call. it returns the total number of "IO::Async::Notifier" callbacks invoked — or "undef" if the underlying epoll_pwait() method returned an error. and if the epoll_pwait() was interrupted by a signal, then 0 is returned instead. three possible outcomes, keep track bestie. 🌈

---

🌟 SEE ALSO 🌟

• Linux::Epoll — O(1) multiplexing for Linux
• IO::Async::Loop::Poll — use IO::Async with poll(2)

---

💌 AUTHOR 💌

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service, king. 🙇‍♀️

---

and that's the page!! perl v5.40.1, dated 2025-05-17 — so this is the version you're reading right now, and she's serving. go write some async code, bestie, you're literally gonna slay. 💖✨🎀🦋🌸💅