NAME¶
IO::Epoll - Scalable IO Multiplexing for Linux 2.5.44 and higher
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);
DESCRIPTION¶
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".
LOW-LEVEL API¶
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".
HIGH LEVEL API¶
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.
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.
- 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::Ppoll METHODS¶
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.
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.
COPYRIGHT AND LICENSE¶
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.