.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Linux::Epoll 3pm"
.TH Linux::Epoll 3pm "2021-01-31" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Linux::Epoll \- O(1) multiplexing for Linux
.SH "VERSION"
.IX Header "VERSION"
version 0.018
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Linux::Epoll;
\&
\& my $epoll = Linux::Epoll\->new();
\& $epoll\->add($fh, \*(Aqin\*(Aq, sub {
\&     my $events = shift;
\&     do_something($fh) if $events\->{in};
\& });
\& $epoll\->wait while 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Epoll is a multiplexing mechanism that scales up O(1) with number of watched files. Linux::Epoll is a callback style epoll module, unlike other epoll modules available on \s-1CPAN.\s0
.SS "Types of events"
.IX Subsection "Types of events"
.IP "\(bu" 4
in
.Sp
The associated filehandle is available for reading.
.IP "\(bu" 4
out
.Sp
The associated filehandle is available for writing.
.IP "\(bu" 4
err
.Sp
An error condition has happened on the associated filehandle. \f(CW\*(C`wait\*(C'\fR will always wait on this event, it is not necessary to set this with \f(CW\*(C`add\*(C'\fR or \f(CW\*(C`modify\*(C'\fR.
.IP "\(bu" 4
prio
.Sp
There is urgent data available for reading.
.IP "\(bu" 4
et
.Sp
Set edge triggered behavior for the associated filehandle. The default behavior is level triggered. See you \fBepoll\fR\|(7) documentation for more information on what this means.
.Sp
Take note that when using edge triggered events, exceptions out of the wait can easily cause events to be lost (when consuming to more than one event at a time).
.IP "\(bu" 4
hup
.Sp
A hang-up has happened on the associated filehandle. \f(CW\*(C`wait\*(C'\fR will always wait on this event, it is not necessary to set this with \f(CW\*(C`add\*(C'\fR or \f(CW\*(C`modify\*(C'\fR.
.IP "\(bu" 4
rdhup
.Sp
Stream socket peer closed the connection, or shut down the writing half of connection. This flag is especially useful for writing simple code to detect peer shutdown when using Edge Triggered monitoring.
.IP "\(bu" 4
oneshot
.Sp
Sets the one-shot behavior for the associated file descriptor. This means that after an event is pulled out with \f(CW\*(C`wait\*(C'\fR the associated file descriptor is internally disabled and no other events will be reported by the epoll interface. The user must call \f(CW\*(C`modify\*(C'\fR to rearm the file descriptor with a new event mask.
.IP "\(bu" 4
wakeup
.Sp
If \f(CW\*(C`oneshot\*(C'\fR and \f(CW\*(C`et\*(C'\fR are clear and the process has the \f(CW\*(C`CAP_BLOCK_SUSPEND\*(C'\fR capability, ensure that the system does not enter \*(L"suspend\*(R" or \*(L"hibernate\*(R" while this event is pending or being processed. The event is considered as being \*(L"processed\*(R" from the time when it is returned by a call to \fBepoll_wait\fR\|(2) until the next call to \fBepoll_wait\fR\|(2) on the same \fBepoll\fR\|(7) file descriptor, the closure of that file descriptor, the removal of the event file descriptor with \s-1EPOLL_CTL_DEL,\s0 or the clearing of \s-1EPOLLWAKEUP\s0 for the event file descriptor with \s-1EPOLL_CTL_MOD.\s0
.IP "\(bu" 4
exclusive
.Sp
Sets an exclusive wakeup mode for the epoll file descriptor that is being attached to the target file descriptor, fd. When a wakeup event occurs and multiple epoll file descriptors are attached to the same target file using \f(CW\*(C`exclusive\*(C'\fR, one or more of the epoll file descriptors will receive an event with \f(CW\*(C`wait()\*(C'\fR. The default in this scenario (when \f(CW\*(C`exclusive\*(C'\fR is not set) is for all epoll file descriptors to receive an event. \f(CW\*(C`exclusive\*(C'\fR is thus useful for avoiding thundering herd problems in certain scenarios.
.Sp
If the same file descriptor is in multiple epoll instances, some with the \f(CW\*(C`exclusive\*(C'\fR flag, and others without, then events will be provided to all epoll instances that did not specify \f(CW\*(C`exclusive\*(C'\fR, and at least one of the epoll instances that did specify \f(CW\*(C`exclusive\*(C'\fR.
.Sp
The following values may be specified in conjunction with \f(CW\*(C`exclusive\*(C'\fR: \f(CW\*(C`in\*(C'\fR, \f(CW\*(C`out\*(C'\fR, \f(CW\*(C`wakeup\*(C'\fR, and \f(CW\*(C`et\*(C'\fR. \f(CW\*(C`hup\*(C'\fR and \f(CW\*(C`err\*(C'\fR can also be specified, but this is not required: as usual, these events are always reported if they occur, regardless of whether they are specified in events. Attempts to specify other values in events yield an error. \f(CW\*(C`exclusive\*(C'\fR may be used only in an \f(CW\*(C`add()\*(C'\fR operation; attempts to employ it with \f(CW\*(C`modify\*(C'\fR yield an error. If \f(CW\*(C`exclusive\*(C'\fR has been set using \f(CW\*(C`add()\*(C'\fR, then a subsequent \f(CW\*(C`modify()\*(C'\fR on the same epfd, fd pair yields an error. A call to \f(CW\*(C`add(\*(C'\fR that specifies \f(CW\*(C`exclusive\*(C'\fR in events and specifies the target file descriptor fd as an epoll instance will likewise fail. The error in all of these cases is \f(CW\*(C`EINVAL\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBnew()\fP"
.IX Subsection "new()"
Create a new epoll instance.
.ie n .SS "add($fh, $events, $callback)"
.el .SS "add($fh, \f(CW$events\fP, \f(CW$callback\fP)"
.IX Subsection "add($fh, $events, $callback)"
Register the filehandle with the epoll instance and associate events \f(CW$events\fR and callback \f(CW$callback\fR with it. \f(CW$events\fR may be either a string (e.g. \f(CW\*(Aqin\*(Aq\fR) or an arrayref (e.g. \f(CW\*(C`[qw/in out hup/]\*(C'\fR). If a filehandle already exists in the set and \f(CW\*(C`add\*(C'\fR is called in non-void context, it returns undef and sets \f(CW$!\fR to \f(CW\*(C`EEXIST\*(C'\fR; if the file can't be waited upon it sets \f(CW$!\fR to \f(CW\*(C`EPERM\*(C'\fR instead. On all other error conditions an exception is thrown. The callback gets a single argument, a hashref whose keys are the triggered events.
.ie n .SS "modify($fh, $events, $callback)"
.el .SS "modify($fh, \f(CW$events\fP, \f(CW$callback\fP)"
.IX Subsection "modify($fh, $events, $callback)"
Change the events and callback associated on this epoll instance with filehandle \f(CW$fh\fR. The arguments work the same as with \f(CW\*(C`add\*(C'\fR. If a filehandle doesn't exist in the set and \f(CW\*(C`modify\*(C'\fR is called in non-void context, it returns undef and sets \f(CW$!\fR to \f(CW\*(C`ENOENT\*(C'\fR. On all other error conditions an exception is thrown.
.SS "delete($fh)"
.IX Subsection "delete($fh)"
Remove a filehandle from the epoll instance. If a filehandle doesn't exist in the set and \f(CW\*(C`delete\*(C'\fR is called in non-void context, it returns undef and sets \f(CW$!\fR to \f(CW\*(C`ENOENT\*(C'\fR. On all other error conditions an exception is thrown.
.ie n .SS "wait($number = 1, $timeout = undef, $sigmask = undef)"
.el .SS "wait($number = 1, \f(CW$timeout\fP = undef, \f(CW$sigmask\fP = undef)"
.IX Subsection "wait($number = 1, $timeout = undef, $sigmask = undef)"
Wait for up to \f(CW$number\fR events, where \f(CW$number\fR must be greater than zero. \f(CW$timeout\fR is the maximal time \f(CW\*(C`wait\*(C'\fR will wait for events in fractional seconds. If it is undefined it may wait indefinitely. \f(CW$sigmask\fR 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 \f(CW$!\fR to \f(CW\*(C`EINTR\*(C'\fR. On all other error conditions an exception is thrown.
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
This module requires at least Perl 5.10 and Linux 2.6.19 to function correctly.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
IO::Epoll
.IP "\(bu" 4
Sys::Syscall
.IP "\(bu" 4
IO::Poll
.SH "AUTHOR"
.IX Header "AUTHOR"
Leon Timmermans <leont@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by Leon Timmermans.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.