IO::Epoll - Scalable IO Multiplexing for Linux 2.5.44 and higher

       Bruce J Keeler, <bruce@gridpoint.com>

       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.

perl v5.40.0                                       2024-10-20                                     IO::Epoll(3pm)

       The  "IO::Poll"  compatibility code borrows heavily from the "IO::Poll" code itself, which was written by
       Graham Barr.

       The epoll(4) subsystem is a new, (currently) Linux-specific variant of poll(2).  It is 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.

       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".

       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

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

       IO::Epoll also provides methods compatible with IO::Ppoll. 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.

       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.

       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.

epoll_create
       Create a new "epoll" file descriptor by requesting the kernel allocate an event backing store dimensioned
       for "size" descriptors.  The size is not the maximum size of the backing store but just a hint to the
       kernel about how to dimension internal structures.  The returned file descriptor will be used for all the
       subsequent calls to the "epoll" interface.  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, "epoll_create" returns -1 and errno is set appropriately.

   epoll_ctl
       Control 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 desciptor to be watched.

       $eventmask is a bitmask of events defined by "EPOLLIN", "EPOLLOUT", etc.

       When successful, "epoll_ctl" returns 0.  When an error occurs, "epoll_ctl" returns -1 and errno is set
       appropriately.

   epoll_wait
       Wait 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 being 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
       Wait 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. The
       $sigmask parameter should be undef, or an instance of "POSIX::SigSet".

       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.

       events ( IO )
           Returns the event mask which represents the events that happend 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 ti "poll"

       IO::Epoll - Scalable IO Multiplexing for Linux 2.5.44 and higher

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

           # 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);