ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.3
(Generate patch)

Comparing libev/ev.3 (file contents):
Revision 1.110 by root, Thu Jun 20 22:44:59 2019 UTC vs.
Revision 1.119 by root, Wed Jan 22 02:00:13 2020 UTC

131.\} 131.\}
132.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
133.\" ======================================================================== 133.\" ========================================================================
134.\" 134.\"
135.IX Title "LIBEV 3" 135.IX Title "LIBEV 3"
136.TH LIBEV 3 "2019-06-20" "libev-4.25" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2020-01-22" "libev-4.31" "libev - high performance full featured event loop"
137.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
138.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
139.if n .ad l 139.if n .ad l
140.nh 140.nh
141.SH "NAME" 141.SH "NAME"
240watchers\fR, which are relatively small C structures you initialise with the 240watchers\fR, which are relatively small C structures you initialise with the
241details of the event, and then hand it over to libev by \fIstarting\fR the 241details of the event, and then hand it over to libev by \fIstarting\fR the
242watcher. 242watcher.
243.SS "\s-1FEATURES\s0" 243.SS "\s-1FEATURES\s0"
244.IX Subsection "FEATURES" 244.IX Subsection "FEATURES"
245Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the 245Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific aio and \f(CW\*(C`epoll\*(C'\fR
246BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms 246interfaces, the BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port
247for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface 247mechanisms for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR
248(for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner 248interface (for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner
249inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative 249inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative
250timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling 250timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling
251(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status 251(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status
252change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event 252change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event
253loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and 253loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and
291When libev detects a usage error such as a negative timer interval, then 291When libev detects a usage error such as a negative timer interval, then
292it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism, 292it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism,
293so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in 293so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in
294the libev caller and need to be fixed there. 294the libev caller and need to be fixed there.
295.PP 295.PP
296Via the \f(CW\*(C`EV_FREQUENT\*(C'\fR macro you can compile in and/or enable extensive
297consistency checking code inside libev that can be used to check for
298internal inconsistencies, suually caused by application bugs.
299.PP
296Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions, and also has 300Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions. These do not
297extensive consistency checking code. These do not trigger under normal
298circumstances, as they indicate either a bug in libev or worse. 301trigger under normal circumstances, as they indicate either a bug in libev
302or worse.
299.SH "GLOBAL FUNCTIONS" 303.SH "GLOBAL FUNCTIONS"
300.IX Header "GLOBAL FUNCTIONS" 304.IX Header "GLOBAL FUNCTIONS"
301These functions can be called anytime, even before initialising the 305These functions can be called anytime, even before initialising the
302library in any way. 306library in any way.
303.IP "ev_tstamp ev_time ()" 4 307.IP "ev_tstamp ev_time ()" 4
602want to handle signals only in specific threads and want to avoid libev 606want to handle signals only in specific threads and want to avoid libev
603unblocking the signals. 607unblocking the signals.
604.Sp 608.Sp
605It's also required by \s-1POSIX\s0 in a threaded program, as libev calls 609It's also required by \s-1POSIX\s0 in a threaded program, as libev calls
606\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. 610\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
611.ie n .IP """EVFLAG_NOTIMERFD""" 4
612.el .IP "\f(CWEVFLAG_NOTIMERFD\fR" 4
613.IX Item "EVFLAG_NOTIMERFD"
614When this flag is specified, the libev will avoid using a \f(CW\*(C`timerfd\*(C'\fR to
615detect time jumps. It will still be able to detect time jumps, but takes
616longer and has a lower accuracy in doing so, but saves a file descriptor
617per loop.
607.Sp 618.Sp
608This flag's behaviour will become the default in future versions of libev. 619The current implementation only tries to use a \f(CW\*(C`timerfd\*(C'\fR when the first
620\&\f(CW\*(C`ev_periodic\*(C'\fR watcher is started and falls back on other methods if it
621cannot be created, but this behaviour might change in the future.
609.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 622.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
610.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 623.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
611.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 624.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
612This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 625This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
613libev tries to roll its own fd_set with no limits on the number of fds, 626libev tries to roll its own fd_set with no limits on the number of fds,
638This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 651This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and
639\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. 652\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
640.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 653.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
641.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 654.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
642.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 655.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
643Use the linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 656Use the Linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
644kernels). 657kernels).
645.Sp 658.Sp
646For few fds, this backend is a bit little slower than poll and select, but 659For few fds, this backend is a bit little slower than poll and select, but
647it scales phenomenally better. While poll and select usually scale like 660it scales phenomenally better. While poll and select usually scale like
648O(total_fds) where total_fds is the total number of fds (or the highest 661O(total_fds) where total_fds is the total number of fds (or the highest
694All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or 707All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or
695faster than epoll for maybe up to a hundred file descriptors, depending on 708faster than epoll for maybe up to a hundred file descriptors, depending on
696the usage. So sad. 709the usage. So sad.
697.Sp 710.Sp
698While nominally embeddable in other event loops, this feature is broken in 711While nominally embeddable in other event loops, this feature is broken in
699all kernel versions tested so far. 712a lot of kernel revisions, but probably(!) works in current versions.
713.Sp
714This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
715\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
716.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4
717.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4
718.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
719Use the Linux-specific Linux \s-1AIO\s0 (\fInot\fR \f(CWaio(7)\fR but \f(CWio_submit(2)\fR) event interface available in post\-4.18 kernels (but libev
720only tries to use it in 4.19+).
721.Sp
722This is another Linux train wreck of an event interface.
723.Sp
724If this backend works for you (as of this writing, it was very
725experimental), it is the best event interface available on Linux and might
726be well worth enabling it \- if it isn't available in your kernel this will
727be detected and this backend will be skipped.
728.Sp
729This backend can batch oneshot requests and supports a user-space ring
730buffer to receive events. It also doesn't suffer from most of the design
731problems of epoll (such as not being able to remove event sources from
732the epoll set), and generally sounds too good to be true. Because, this
733being the Linux kernel, of course it suffers from a whole new set of
734limitations, forcing you to fall back to epoll, inheriting all its design
735issues.
736.Sp
737For one, it is not easily embeddable (but probably could be done using
738an event fd at some extra overhead). It also is subject to a system wide
739limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR. If no \s-1AIO\s0
740requests are left, this backend will be skipped during initialisation, and
741will switch to epoll when the loop is active.
742.Sp
743Most problematic in practice, however, is that not all file descriptors
744work with it. For example, in Linux 5.1, \s-1TCP\s0 sockets, pipes, event fds,
745files, \fI/dev/null\fR and many others are supported, but ttys do not work
746properly (a known bug that the kernel developers don't care about, see
747<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
748(yet?) a generic event polling interface.
749.Sp
750Overall, it seems the Linux developers just don't want it to have a
751generic event handling mechanism other than \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`poll\*(C'\fR.
752.Sp
753To work around all these problem, the current version of libev uses its
754epoll backend as a fallback for file descriptor types that do not work. Or
755falls back completely to epoll if the kernel acts up.
700.Sp 756.Sp
701This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 757This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
702\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 758\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
703.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 759.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
704.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 760.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
705.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 761.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
706Kqueue deserves special mention, as at the time of this writing, it 762Kqueue deserves special mention, as at the time this backend was
707was broken on all BSDs except NetBSD (usually it doesn't work reliably 763implemented, it was broken on all BSDs except NetBSD (usually it doesn't
708with anything but sockets and pipes, except on Darwin, where of course 764work reliably with anything but sockets and pipes, except on Darwin,
709it's completely useless). Unlike epoll, however, whose brokenness 765where of course it's completely useless). Unlike epoll, however, whose
710is by design, these kqueue bugs can (and eventually will) be fixed 766brokenness is by design, these kqueue bugs can be (and mostly have been)
711without \s-1API\s0 changes to existing programs. For this reason it's not being 767fixed without \s-1API\s0 changes to existing programs. For this reason it's not
712\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using 768being \*(L"auto-detected\*(R" on all platforms unless you explicitly specify it
713\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) 769in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a
714system like NetBSD. 770known-to-be-good (\-enough) system like NetBSD.
715.Sp 771.Sp
716You still can embed kqueue into a normal poll or select backend and use it 772You still can embed kqueue into a normal poll or select backend and use it
717only for sockets (after having made sure that sockets work with kqueue on 773only for sockets (after having made sure that sockets work with kqueue on
718the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 774the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
719.Sp 775.Sp
720It scales in the same way as the epoll backend, but the interface to the 776It scales in the same way as the epoll backend, but the interface to the
721kernel is more efficient (which says nothing about its actual speed, of 777kernel is more efficient (which says nothing about its actual speed, of
722course). While stopping, setting and starting an I/O watcher does never 778course). While stopping, setting and starting an I/O watcher does never
723cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 779cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
724two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you 780two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
725might have to leak fd's on fork, but it's more sane than epoll) and it 781might have to leak fds on fork, but it's more sane than epoll) and it
726drops fds silently in similarly hard-to-detect cases. 782drops fds silently in similarly hard-to-detect cases.
727.Sp 783.Sp
728This backend usually performs well under most conditions. 784This backend usually performs well under most conditions.
729.Sp 785.Sp
730While nominally embeddable in other event loops, this doesn't work 786While nominally embeddable in other event loops, this doesn't work
807Example: Use whatever libev has to offer, but make sure that kqueue is 863Example: Use whatever libev has to offer, but make sure that kqueue is
808used if available. 864used if available.
809.Sp 865.Sp
810.Vb 1 866.Vb 1
811\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 867\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
868.Ve
869.Sp
870Example: Similarly, on linux, you mgiht want to take advantage of the
871linux aio backend if possible, but fall back to something else if that
872isn't available.
873.Sp
874.Vb 1
875\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
812.Ve 876.Ve
813.RE 877.RE
814.IP "ev_loop_destroy (loop)" 4 878.IP "ev_loop_destroy (loop)" 4
815.IX Item "ev_loop_destroy (loop)" 879.IX Item "ev_loop_destroy (loop)"
816Destroys an event loop object (frees all memory and kernel state 880Destroys an event loop object (frees all memory and kernel state
1599.IX Subsection "WATCHER PRIORITY MODELS" 1663.IX Subsection "WATCHER PRIORITY MODELS"
1600Many event loops support \fIwatcher priorities\fR, which are usually small 1664Many event loops support \fIwatcher priorities\fR, which are usually small
1601integers that influence the ordering of event callback invocation 1665integers that influence the ordering of event callback invocation
1602between watchers in some way, all else being equal. 1666between watchers in some way, all else being equal.
1603.PP 1667.PP
1604In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its 1668In libev, watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its
1605description for the more technical details such as the actual priority 1669description for the more technical details such as the actual priority
1606range. 1670range.
1607.PP 1671.PP
1608There are two common ways how these these priorities are being interpreted 1672There are two common ways how these these priorities are being interpreted
1609by event loops: 1673by event loops:
1703.IX Header "WATCHER TYPES" 1767.IX Header "WATCHER TYPES"
1704This section describes each watcher in detail, but will not repeat 1768This section describes each watcher in detail, but will not repeat
1705information given in the last section. Any initialisation/set macros, 1769information given in the last section. Any initialisation/set macros,
1706functions and members specific to the watcher type are explained. 1770functions and members specific to the watcher type are explained.
1707.PP 1771.PP
1708Members are additionally marked with either \fI[read\-only]\fR, meaning that, 1772Most members are additionally marked with either \fI[read\-only]\fR, meaning
1709while the watcher is active, you can look at the member and expect some 1773that, while the watcher is active, you can look at the member and expect
1710sensible content, but you must not modify it (you can modify it while the 1774some sensible content, but you must not modify it (you can modify it while
1711watcher is stopped to your hearts content), or \fI[read\-write]\fR, which 1775the watcher is stopped to your hearts content), or \fI[read\-write]\fR, which
1712means you can expect it to have some sensible content while the watcher 1776means you can expect it to have some sensible content while the watcher
1713is active, but you can also modify it. Modifying it may not do something 1777is active, but you can also modify it. Modifying it may not do something
1714sensible or take immediate effect (or do anything at all), but libev will 1778sensible or take immediate effect (or do anything at all), but libev will
1715not crash or malfunction in any way. 1779not crash or malfunction in any way.
1780.PP
1781In any case, the documentation for each member will explain what the
1782effects are, and if there are any additional access restrictions.
1716.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" 1783.ie n .SS """ev_io"" \- is this file descriptor readable or writable?"
1717.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" 1784.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?"
1718.IX Subsection "ev_io - is this file descriptor readable or writable?" 1785.IX Subsection "ev_io - is this file descriptor readable or writable?"
1719I/O watchers check whether a file descriptor is readable or writable 1786I/O watchers check whether a file descriptor is readable or writable
1720in each iteration of the event loop, or, more precisely, when reading 1787in each iteration of the event loop, or, more precisely, when reading
1748But really, best use non-blocking mode. 1815But really, best use non-blocking mode.
1749.PP 1816.PP
1750\fIThe special problem of disappearing file descriptors\fR 1817\fIThe special problem of disappearing file descriptors\fR
1751.IX Subsection "The special problem of disappearing file descriptors" 1818.IX Subsection "The special problem of disappearing file descriptors"
1752.PP 1819.PP
1753Some backends (e.g. kqueue, epoll) need to be told about closing a file 1820Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1754descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1821a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1755such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1822means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1756descriptor, but when it goes away, the operating system will silently drop 1823file descriptor, but when it goes away, the operating system will silently
1757this interest. If another file descriptor with the same number then is 1824drop this interest. If another file descriptor with the same number then
1758registered with libev, there is no efficient way to see that this is, in 1825is registered with libev, there is no efficient way to see that this is,
1759fact, a different file descriptor. 1826in fact, a different file descriptor.
1760.PP 1827.PP
1761To avoid having to explicitly tell libev about such cases, libev follows 1828To avoid having to explicitly tell libev about such cases, libev follows
1762the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1829the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1763will assume that this is potentially a new file descriptor, otherwise 1830will assume that this is potentially a new file descriptor, otherwise
1764it is assumed that the file descriptor stays the same. That means that 1831it is assumed that the file descriptor stays the same. That means that
1816reuse the same code path. 1883reuse the same code path.
1817.PP 1884.PP
1818\fIThe special problem of fork\fR 1885\fIThe special problem of fork\fR
1819.IX Subsection "The special problem of fork" 1886.IX Subsection "The special problem of fork"
1820.PP 1887.PP
1821Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1888Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1822useless behaviour. Libev fully supports fork, but needs to be told about 1889at all or exhibit useless behaviour. Libev fully supports fork, but needs
1823it in the child if you want to continue to use it in the child. 1890to be told about it in the child if you want to continue to use it in the
1891child.
1824.PP 1892.PP
1825To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1893To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1826()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1894()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1827\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1895\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1828.PP 1896.PP
1887.IX Item "ev_io_set (ev_io *, int fd, int events)" 1955.IX Item "ev_io_set (ev_io *, int fd, int events)"
1888.PD 1956.PD
1889Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to 1957Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
1890receive events for and \f(CW\*(C`events\*(C'\fR is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or 1958receive events for and \f(CW\*(C`events\*(C'\fR is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or
1891\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. 1959\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events.
1960.IP "ev_io_modify (ev_io *, int events)" 4
1961.IX Item "ev_io_modify (ev_io *, int events)"
1962Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the event mask. Using this might
1963be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR still
1964refers to the same underlying file description, something it cannot do
1965when using \f(CW\*(C`ev_io_set\*(C'\fR.
1892.IP "int fd [read\-only]" 4 1966.IP "int fd [no\-modify]" 4
1893.IX Item "int fd [read-only]" 1967.IX Item "int fd [no-modify]"
1894The file descriptor being watched. 1968The file descriptor being watched. While it can be read at any time, you
1969must not modify this member even when the watcher is stopped \- always use
1970\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
1895.IP "int events [read\-only]" 4 1971.IP "int events [no\-modify]" 4
1896.IX Item "int events [read-only]" 1972.IX Item "int events [no-modify]"
1897The events being watched. 1973The set of events being watched, among other flags. This field is a
1974bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events & EV_READ\*(C'\fR, and
1975similarly for \f(CW\*(C`EV_WRITE\*(C'\fR.
1976.Sp
1977As with \f(CW\*(C`fd\*(C'\fR, you must not modify this member even when the watcher is
1978stopped, always use \f(CW\*(C`ev_io_set\*(C'\fR or \f(CW\*(C`ev_io_modify\*(C'\fR for that.
1898.PP 1979.PP
1899\fIExamples\fR 1980\fIExamples\fR
1900.IX Subsection "Examples" 1981.IX Subsection "Examples"
1901.PP 1982.PP
1902Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 1983Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
4567\& ev_win32.c required on win32 platforms only 4648\& ev_win32.c required on win32 platforms only
4568\& 4649\&
4569\& ev_select.c only when select backend is enabled 4650\& ev_select.c only when select backend is enabled
4570\& ev_poll.c only when poll backend is enabled 4651\& ev_poll.c only when poll backend is enabled
4571\& ev_epoll.c only when the epoll backend is enabled 4652\& ev_epoll.c only when the epoll backend is enabled
4653\& ev_linuxaio.c only when the linux aio backend is enabled
4654\& ev_iouring.c only when the linux io_uring backend is enabled
4572\& ev_kqueue.c only when the kqueue backend is enabled 4655\& ev_kqueue.c only when the kqueue backend is enabled
4573\& ev_port.c only when the solaris port backend is enabled 4656\& ev_port.c only when the solaris port backend is enabled
4574.Ve 4657.Ve
4575.PP 4658.PP
4576\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4659\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4689higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). 4772higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR).
4690.IP "\s-1EV_USE_NANOSLEEP\s0" 4 4773.IP "\s-1EV_USE_NANOSLEEP\s0" 4
4691.IX Item "EV_USE_NANOSLEEP" 4774.IX Item "EV_USE_NANOSLEEP"
4692If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 4775If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
4693and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 4776and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
4777.IP "\s-1EV_USE_EVENTFD\s0" 4
4778.IX Item "EV_USE_EVENTFD"
4779If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4780available and will probe for kernel support at runtime. This will improve
4781\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4782If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47832.7 or newer, otherwise disabled.
4784.IP "\s-1EV_USE_SIGNALFD\s0" 4
4785.IX Item "EV_USE_SIGNALFD"
4786If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`signalfd ()\*(C'\fR is
4787available and will probe for kernel support at runtime. This enables
4788the use of \s-1EVFLAG_SIGNALFD\s0 for faster and simpler signal handling. If
4789undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47902.7 or newer, otherwise disabled.
4791.IP "\s-1EV_USE_TIMERFD\s0" 4
4792.IX Item "EV_USE_TIMERFD"
4793If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`timerfd ()\*(C'\fR is
4794available and will probe for kernel support at runtime. This allows
4795libev to detect time jumps accurately. If undefined, it will be enabled
4796if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4797\&\f(CW\*(C`TFD_TIMER_CANCEL_ON_SET\*(C'\fR, otherwise disabled.
4694.IP "\s-1EV_USE_EVENTFD\s0" 4 4798.IP "\s-1EV_USE_EVENTFD\s0" 4
4695.IX Item "EV_USE_EVENTFD" 4799.IX Item "EV_USE_EVENTFD"
4696If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is 4800If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4697available and will probe for kernel support at runtime. This will improve 4801available and will probe for kernel support at runtime. This will improve
4698\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. 4802\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4757If defined to be \f(CW1\fR, libev will compile in support for the Linux 4861If defined to be \f(CW1\fR, libev will compile in support for the Linux
4758\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4862\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4759otherwise another method will be used as fallback. This is the preferred 4863otherwise another method will be used as fallback. This is the preferred
4760backend for GNU/Linux systems. If undefined, it will be enabled if the 4864backend for GNU/Linux systems. If undefined, it will be enabled if the
4761headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4865headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4866.IP "\s-1EV_USE_LINUXAIO\s0" 4
4867.IX Item "EV_USE_LINUXAIO"
4868If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4869backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4870enabled on linux, otherwise disabled.
4871.IP "\s-1EV_USE_IOURING\s0" 4
4872.IX Item "EV_USE_IOURING"
4873If defined to be \f(CW1\fR, libev will compile in support for the Linux
4874io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4875current limitations it has to be requested explicitly. If undefined, it
4876will be enabled on linux, otherwise disabled.
4762.IP "\s-1EV_USE_KQUEUE\s0" 4 4877.IP "\s-1EV_USE_KQUEUE\s0" 4
4763.IX Item "EV_USE_KQUEUE" 4878.IX Item "EV_USE_KQUEUE"
4764If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4879If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4765\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4880\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4766otherwise another method will be used as fallback. This is the preferred 4881otherwise another method will be used as fallback. This is the preferred
5022in. If set to \f(CW1\fR, then verification code will be compiled in, but not 5137in. If set to \f(CW1\fR, then verification code will be compiled in, but not
5023called. If set to \f(CW2\fR, then the internal verification code will be 5138called. If set to \f(CW2\fR, then the internal verification code will be
5024called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5139called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
5025verification code will be called very frequently, which will slow down 5140verification code will be called very frequently, which will slow down
5026libev considerably. 5141libev considerably.
5142.Sp
5143Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5144disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5027.Sp 5145.Sp
5028The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5146The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
5029will be \f(CW0\fR. 5147will be \f(CW0\fR.
5030.IP "\s-1EV_COMMON\s0" 4 5148.IP "\s-1EV_COMMON\s0" 4
5031.IX Item "EV_COMMON" 5149.IX Item "EV_COMMON"

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines