IO::Epoll(3pm)

📦
version 0.03 · 6 versions
, in ubuntu stonking

💖 IO::Epoll 💖

okay bestie, so this whole page is about IO::Epoll — Scalable IO Multiplexing for Linux 2.5.44 and higher. yes that's the name, and yes it's lowkey iconic. it lives in the User Contributed Perl Documentation, and this is literally the IO::Epoll(3pm) page. let's get into it 🦋

✨ SYNOPSIS ✨

# Low level interface
use IO::Epoll;

$epfd = epoll_create(10);

epoll_ctl($epfd, EPOLL_CTL_ADD, fileno STDIN, EPOLLIN) >= 0
    || die "epoll_ctl: $!\n";
epoll_ctl($epfd, ...);

$events = epoll_wait($epfd, 10, 1000); # Max 10 events returned, 1s timeout

# High level IO::Poll emulation layer
use IO::EPoll qw(:compat);

$poll = new IO::Epoll;

$poll->mask($input_handle => POLLIN);
$poll->mask($output_handle => POLLOUT);

$poll->poll($timeout);

$ev = $poll->events($input);

(and yes, notice the use IO::EPoll qw(:compat); casing up there — that's verbatim, don't come for me, copy it exactly as shown 💅)

🌈 DESCRIPTION 🌈

so the epoll(4) subsystem is a new — and currently Linux-specific — variant of poll(2). it's giving scalabilitea. it's designed to offer O(1) scalability over large numbers of watched file descriptors. you will need at least version 2.5.44 of Linux to use this module, and you might need to upgrade your C library. heads up bestie, that's a real requirement, not a vibe ✨

the epoll(2) API comprises four system calls: epoll_create(2), epoll_ctl(2), epoll_wait(2) and epoll_pwait(2). IO::Epoll provides a low-level API which closely matches the underlying system calls. it also provides a higher-level layer designed to emulate the behavior of IO::Poll and IO::Ppoll. dual threat. main character energy honestly 👑

🔥 LOW-LEVEL API 🔥

🎀 epoll_create 🎀

creates a new epoll file descriptor by requesting the kernel allocate an event backing store dimensioned for size descriptors. and no, size is not the maximum size of the backing store — it's literally just a hint to the kernel about how to dimension internal structures. (the kernel is the one making the decisions here, we're just giving suggestions 💅) the returned file descriptor will be used for all the subsequent calls to the epoll interface. and the file descriptor returned by epoll_create must be closed by using POSIX::close.

$epfd = epoll_create(15);
...
POSIX::close($epfd);

when successful, epoll_create returns a positive integer identifying the descriptor. when an error occurs, it returns -1 and errno is set appropriately. 😭

🦋 epoll_ctl 🦋

controls an epoll descriptor, $epfd, by requesting the operation op be performed on the target file descriptor, fd.

$ret = epoll_ctl($epfd, $op, $fd, $eventmask)
  • $epfd is an epoll descriptor returned from epoll_create.
  • $op is one of EPOLL_CTL_ADD, EPOLL_CTL_MOD or EPOLL_CTL_DEL.
  • $fd is the file descriptor to be watched.
  • $eventmask is a bitmask of events defined by EPOLLIN, EPOLLOUT, etc.

when successful, epoll_ctl returns 0. when an error occurs, it returns -1 and errno is set appropriately. periodt.

💜 epoll_wait 💜

waits for events on the epoll file descriptor $epfd.

$ret = epoll_wait($epfd, $maxevents, $timeout)
  • $epfd is an epoll descriptor returned from epoll_create.
  • $maxevents is an integer specifying the maximum number of events to be returned.
  • $timeout is a timeout, in milliseconds

when successful, epoll_wait returns a reference to an array of events. each event is a two element array: the first element is the file descriptor which triggered the event, and the second is the mask of event types triggered. for example, if epoll_wait returned the following data structure:

[
  [ 0, EPOLLIN ],
  [ 6, EPOLLOUT | EPOLLIN ]
]

then file descriptor 0 would be ready for reading, and fd 4 would be ready for both reading and writing.

on error, epoll_wait returns undef and sets errno appropriately. 💀

🌸 epoll_pwait 🌸

waits for events on the epoll file descriptor $epfd.

$ret = epoll_pwait($epfd, $maxevents, $timeout, $sigmask)

identical to epoll_wait, except that the kernel will atomically swap the current signal mask for the process to that supplied in $sigmask, wait for events, then restore it to what it was originally. so clean, so tidy, obsessed 🫶 the $sigmask parameter should be undef, or an instance of POSIX::SigSet.

⭐ HIGH LEVEL API ⭐

IO::Epoll provides an object oriented API designed to be a drop-in replacement for IO::Poll. go read the documentation for that module for more information, iykyk.

👑 METHODS 👑

  • mask ( IO [, EVENT_MASK ] ) — if EVENT_MASK is given, then, if EVENT_MASK is non-zero, IO is added to the list of file descriptors and the next call to poll will check for any event specified in EVENT_MASK. if EVENT_MASK is zero then IO will be removed from the list of file descriptors.

if EVENT_MASK is not given then the return value will be the current event mask value for IO.

  • poll ( [ TIMEOUT ] ) — call the system level poll routine. if TIMEOUT is not specified then the call will block. returns the number of handles which had events happen, or -1 on error. TIMEOUT is in seconds and may be fractional. (fractional?? she's flexible, we love that 💅)
  • events ( IO ) — returns the event mask which represents the events that happened on IO during the last call to poll.
  • remove ( IO ) — remove IO from the list of file descriptors for the next poll.
  • handles( [ EVENT_MASK ] ) — returns a list of handles. if EVENT_MASK is not given then a list of all handles known will be returned. if EVENT_MASK is given then a list of handles will be returned which had one of the events specified by EVENT_MASK happen during the last call to poll.

🧚 IO::Ppoll METHODS 🧚

IO::Epoll also provides methods compatible with IO::Ppoll. the way that works: when any of these methods are called, the IO::Epoll object switches up to IO::Ppoll-compatible mode, and will use the epoll_pwait(2) system call when the poll method is invoked. it's a whole glow-up ✨

  • sigmask — returns the POSIX::SigSet object in which the signal mask is stored. since this is a reference to the object used in the call to epoll_pwait(2), any modifications made to it will be reflected in the signal mask given to the system call. (yes bestie, it's live — edits show up everywhere, no cap.)
  • sigmask_add ( SIGNALS ) — adds the given signals to the signal mask. these signals will be blocked during the poll call.
  • sigmask_del ( SIGNALS ) — removes the given signals from the signal mask. these signals will not be blocked during the poll call, and may be delivered while poll is waiting.
  • sigmask_ismember ( SIGNAL ) — tests if the given signal is present in the signal mask.

💖 Exportable constants 💖

exported by default:

EPOLLERR
EPOLLET
EPOLLHUP
EPOLLIN
EPOLLMSG
EPOLLOUT
EPOLLPRI
EPOLLRDBAND
EPOLLRDNORM
EPOLLWRBAND
EPOLLWRNORM
EPOLL_CTL_ADD
EPOLL_CTL_DEL
EPOLL_CTL_MOD

exported by the :compat tag:

POLLNVAL
POLLIN
POLLOUT
POLLERR
POLLHUP
POLLPRI
POLLRDNORM
POLLWRNORM
POLLRDBAND
POLLWRBAND

🌈 SEE ALSO 🌈

IO::Poll IO::Select IO::Ppoll epoll(4) epoll_create(2) epoll_ctl(2) epoll_wait(2) epoll_pwait(2)

💜 AUTHOR 💜

Bruce J Keeler, <bruce@gridpoint.com>

🎀 CREDITS 🎀

the IO::Poll compatibility code borrows heavily from the IO::Poll code itself, which was written by Graham Barr. giving credit where credit is due, as we always do 🫶

Copyright (C) 2004 by Bruce J. Keeler Portions Copyright (C) 1997-8 Graham Barr <gbarr@pobox.com>

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

okay that's the whole page bestie, you ate 💅 the version on this is perl v5.42.3, dated 2026-08-19, and it's filed under IO::Epoll(3pm) — mwah, go build something scalable 🦋🌸✨

📦 where this page comes from