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

Comparing libev/ev.3 (file contents):
Revision 1.109 by root, Fri Dec 21 07:03:02 2018 UTC vs.
Revision 1.121 by root, Wed Mar 18 12:21:48 2020 UTC

1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) 1.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
… …
44.\" 44.\"
45.\" Escape single quotes in literal strings from groff's Unicode transform. 45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq 46.ie \n(.g .ds Aq \(aq
47.el .ds Aq ' 47.el .ds Aq '
48.\" 48.\"
49.\" If the F register is turned on, we'll generate index entries on stderr for 49.\" If the F register is >0, we'll generate index entries on stderr for
50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51.\" entries marked with X<> in POD. Of course, you'll have to process the 51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion. 52.\" output yourself in some meaningful fashion.
53.\" 53.\"
54.\" Avoid warning from groff about undefined register 'F'. 54.\" Avoid warning from groff about undefined register 'F'.
55.de IX 55.de IX
56.. 56..
57.nr rF 0 57.nr rF 0
58.if \n(.g .if rF .nr rF 1 58.if \n(.g .if rF .nr rF 1
59.if (\n(rF:(\n(.g==0)) \{ 59.if (\n(rF:(\n(.g==0)) \{\
60. if \nF \{ 60. if \nF \{\
61. de IX 61. de IX
62. tm Index:\\$1\t\\n%\t"\\$2" 62. tm Index:\\$1\t\\n%\t"\\$2"
63.. 63..
64. if !\nF==2 \{ 64. if !\nF==2 \{\
65. nr % 0 65. nr % 0
66. nr F 2 66. nr F 2
67. \} 67. \}
68. \} 68. \}
69.\} 69.\}
… …
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 "2018-12-21" "libev-4.25" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2020-03-12" "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
… …
392.Sp 396.Sp
393You could override this function in high-availability programs to, say, 397You could override this function in high-availability programs to, say,
394free some memory if it cannot allocate memory, to use a special allocator, 398free some memory if it cannot allocate memory, to use a special allocator,
395or even to sleep a while and retry until some memory is available. 399or even to sleep a while and retry until some memory is available.
396.Sp 400.Sp
401Example: The following is the \f(CW\*(C`realloc\*(C'\fR function that libev itself uses
402which should work with \f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions of all kinds and
403is probably a good basis for your own implementation.
404.Sp
405.Vb 5
406\& static void *
407\& ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
408\& {
409\& if (size)
410\& return realloc (ptr, size);
411\&
412\& free (ptr);
413\& return 0;
414\& }
415.Ve
416.Sp
397Example: Replace the libev allocator with one that waits a bit and then 417Example: Replace the libev allocator with one that waits a bit and then
398retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR). 418retries.
399.Sp 419.Sp
400.Vb 6 420.Vb 8
401\& static void * 421\& static void *
402\& persistent_realloc (void *ptr, size_t size) 422\& persistent_realloc (void *ptr, size_t size)
403\& { 423\& {
424\& if (!size)
425\& {
426\& free (ptr);
427\& return 0;
428\& }
429\&
404\& for (;;) 430\& for (;;)
405\& { 431\& {
406\& void *newptr = realloc (ptr, size); 432\& void *newptr = realloc (ptr, size);
407\& 433\&
408\& if (newptr) 434\& if (newptr)
… …
580want 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
581unblocking the signals. 607unblocking the signals.
582.Sp 608.Sp
583It'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
584\&\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.
585.Sp 618.Sp
586This 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.
587.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 622.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
588.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
589.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 624.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
590This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 625This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
591libev 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,
592but if that fails, expect a fairly low limit on the number of fds when 627but if that fails, expect a fairly low limit on the number of fds when
593using this backend. It doesn't scale too well (O(highest_fd)), but its 628using this backend. It doesn't scale too well (O(highest_fd)), but its
594usually the fastest backend for a low number of (low-numbered :) fds. 629usually the fastest backend for a low number of (low-numbered :) fds.
595.Sp 630.Sp
… …
604\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the 639\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the
605\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). 640\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
606.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 641.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
607.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 642.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
608.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 643.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
609And this is your standard \fIpoll\fR\|(2) backend. It's more complicated 644And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
610than select, but handles sparse fds better and has no artificial 645than select, but handles sparse fds better and has no artificial
611limit on the number of fds you can use (except it will slow down 646limit on the number of fds you can use (except it will slow down
612considerably with a lot of inactive fds). It scales similarly to select, 647considerably with a lot of inactive fds). It scales similarly to select,
613i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for 648i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
614performance tips. 649performance tips.
… …
616This 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
617\&\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.
618.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 653.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
619.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 654.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
620.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 655.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
621Use the linux-specific \fIepoll\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
622kernels). 657kernels).
623.Sp 658.Sp
624For 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
625it scales phenomenally better. While poll and select usually scale like 660it scales phenomenally better. While poll and select usually scale like
626O(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
… …
672All 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
673faster 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
674the usage. So sad. 709the usage. So sad.
675.Sp 710.Sp
676While nominally embeddable in other event loops, this feature is broken in 711While nominally embeddable in other event loops, this feature is broken in
677all 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.
678.Sp 756.Sp
679This 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
680\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 758\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
681.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
682.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
683.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 761.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
684Kqueue deserves special mention, as at the time of this writing, it 762Kqueue deserves special mention, as at the time this backend was
685was 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
686with anything but sockets and pipes, except on Darwin, where of course 764work reliably with anything but sockets and pipes, except on Darwin,
687it's completely useless). Unlike epoll, however, whose brokenness 765where of course it's completely useless). Unlike epoll, however, whose
688is by design, these kqueue bugs can (and eventually will) be fixed 766brokenness is by design, these kqueue bugs can be (and mostly have been)
689without \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
690\&\*(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
691\&\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
692system like NetBSD. 770known-to-be-good (\-enough) system like NetBSD.
693.Sp 771.Sp
694You 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
695only 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
696the 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.
697.Sp 775.Sp
698It 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
699kernel is more efficient (which says nothing about its actual speed, of 777kernel is more efficient (which says nothing about its actual speed, of
700course). While stopping, setting and starting an I/O watcher does never 778course). While stopping, setting and starting an I/O watcher does never
701cause 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
702two 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
703might 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
704drops fds silently in similarly hard-to-detect cases. 782drops fds silently in similarly hard-to-detect cases.
705.Sp 783.Sp
706This backend usually performs well under most conditions. 784This backend usually performs well under most conditions.
707.Sp 785.Sp
708While nominally embeddable in other event loops, this doesn't work 786While nominally embeddable in other event loops, this doesn't work
… …
785Example: 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
786used if available. 864used if available.
787.Sp 865.Sp
788.Vb 1 866.Vb 1
789\& 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);
790.Ve 876.Ve
791.RE 877.RE
792.IP "ev_loop_destroy (loop)" 4 878.IP "ev_loop_destroy (loop)" 4
793.IX Item "ev_loop_destroy (loop)" 879.IX Item "ev_loop_destroy (loop)"
794Destroys an event loop object (frees all memory and kernel state 880Destroys an event loop object (frees all memory and kernel state
… …
1263with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher 1349with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher
1264*)\*(C'\fR), and you can stop watching for events at any time by calling the 1350*)\*(C'\fR), and you can stop watching for events at any time by calling the
1265corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR. 1351corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR.
1266.PP 1352.PP
1267As long as your watcher is active (has been started but not stopped) you 1353As long as your watcher is active (has been started but not stopped) you
1268must not touch the values stored in it. Most specifically you must never 1354must not touch the values stored in it except when explicitly documented
1269reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro. 1355otherwise. Most specifically you must never reinitialise it or call its
1356\&\f(CW\*(C`ev_TYPE_set\*(C'\fR macro.
1270.PP 1357.PP
1271Each and every callback receives the event loop pointer as first, the 1358Each and every callback receives the event loop pointer as first, the
1272registered watcher structure as second, and a bitset of received events as 1359registered watcher structure as second, and a bitset of received events as
1273third argument. 1360third argument.
1274.PP 1361.PP
… …
1365bug in your program. 1452bug in your program.
1366.Sp 1453.Sp
1367Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1454Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1368example it might indicate that a fd is readable or writable, and if your 1455example it might indicate that a fd is readable or writable, and if your
1369callbacks is well-written it can just attempt the operation and cope with 1456callbacks is well-written it can just attempt the operation and cope with
1370the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1457the error from \fBread()\fR or \fBwrite()\fR. This will not work in multi-threaded
1371programs, though, as the fd could already be closed and reused for another 1458programs, though, as the fd could already be closed and reused for another
1372thing, so beware. 1459thing, so beware.
1373.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" 1460.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1374.IX Subsection "GENERIC WATCHER FUNCTIONS" 1461.IX Subsection "GENERIC WATCHER FUNCTIONS"
1375.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1462.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
… …
1577.IX Subsection "WATCHER PRIORITY MODELS" 1664.IX Subsection "WATCHER PRIORITY MODELS"
1578Many event loops support \fIwatcher priorities\fR, which are usually small 1665Many event loops support \fIwatcher priorities\fR, which are usually small
1579integers that influence the ordering of event callback invocation 1666integers that influence the ordering of event callback invocation
1580between watchers in some way, all else being equal. 1667between watchers in some way, all else being equal.
1581.PP 1668.PP
1582In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its 1669In libev, watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its
1583description for the more technical details such as the actual priority 1670description for the more technical details such as the actual priority
1584range. 1671range.
1585.PP 1672.PP
1586There are two common ways how these these priorities are being interpreted 1673There are two common ways how these these priorities are being interpreted
1587by event loops: 1674by event loops:
… …
1681.IX Header "WATCHER TYPES" 1768.IX Header "WATCHER TYPES"
1682This section describes each watcher in detail, but will not repeat 1769This section describes each watcher in detail, but will not repeat
1683information given in the last section. Any initialisation/set macros, 1770information given in the last section. Any initialisation/set macros,
1684functions and members specific to the watcher type are explained. 1771functions and members specific to the watcher type are explained.
1685.PP 1772.PP
1686Members are additionally marked with either \fI[read\-only]\fR, meaning that, 1773Most members are additionally marked with either \fI[read\-only]\fR, meaning
1687while the watcher is active, you can look at the member and expect some 1774that, while the watcher is active, you can look at the member and expect
1688sensible content, but you must not modify it (you can modify it while the 1775some sensible content, but you must not modify it (you can modify it while
1689watcher is stopped to your hearts content), or \fI[read\-write]\fR, which 1776the watcher is stopped to your hearts content), or \fI[read\-write]\fR, which
1690means you can expect it to have some sensible content while the watcher 1777means you can expect it to have some sensible content while the watcher is
1691is active, but you can also modify it. Modifying it may not do something 1778active, but you can also modify it (within the same thread as the event
1779loop, i.e. without creating data races). Modifying it may not do something
1692sensible or take immediate effect (or do anything at all), but libev will 1780sensible or take immediate effect (or do anything at all), but libev will
1693not crash or malfunction in any way. 1781not crash or malfunction in any way.
1782.PP
1783In any case, the documentation for each member will explain what the
1784effects are, and if there are any additional access restrictions.
1694.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" 1785.ie n .SS """ev_io"" \- is this file descriptor readable or writable?"
1695.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" 1786.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?"
1696.IX Subsection "ev_io - is this file descriptor readable or writable?" 1787.IX Subsection "ev_io - is this file descriptor readable or writable?"
1697I/O watchers check whether a file descriptor is readable or writable 1788I/O watchers check whether a file descriptor is readable or writable
1698in each iteration of the event loop, or, more precisely, when reading 1789in each iteration of the event loop, or, more precisely, when reading
… …
1726But really, best use non-blocking mode. 1817But really, best use non-blocking mode.
1727.PP 1818.PP
1728\fIThe special problem of disappearing file descriptors\fR 1819\fIThe special problem of disappearing file descriptors\fR
1729.IX Subsection "The special problem of disappearing file descriptors" 1820.IX Subsection "The special problem of disappearing file descriptors"
1730.PP 1821.PP
1731Some backends (e.g. kqueue, epoll) need to be told about closing a file 1822Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1732descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1823a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1733such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1824means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1734descriptor, but when it goes away, the operating system will silently drop 1825file descriptor, but when it goes away, the operating system will silently
1735this interest. If another file descriptor with the same number then is 1826drop this interest. If another file descriptor with the same number then
1736registered with libev, there is no efficient way to see that this is, in 1827is registered with libev, there is no efficient way to see that this is,
1737fact, a different file descriptor. 1828in fact, a different file descriptor.
1738.PP 1829.PP
1739To avoid having to explicitly tell libev about such cases, libev follows 1830To avoid having to explicitly tell libev about such cases, libev follows
1740the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1831the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1741will assume that this is potentially a new file descriptor, otherwise 1832will assume that this is potentially a new file descriptor, otherwise
1742it is assumed that the file descriptor stays the same. That means that 1833it is assumed that the file descriptor stays the same. That means that
… …
1794reuse the same code path. 1885reuse the same code path.
1795.PP 1886.PP
1796\fIThe special problem of fork\fR 1887\fIThe special problem of fork\fR
1797.IX Subsection "The special problem of fork" 1888.IX Subsection "The special problem of fork"
1798.PP 1889.PP
1799Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1890Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1800useless behaviour. Libev fully supports fork, but needs to be told about 1891at all or exhibit useless behaviour. Libev fully supports fork, but needs
1801it in the child if you want to continue to use it in the child. 1892to be told about it in the child if you want to continue to use it in the
1893child.
1802.PP 1894.PP
1803To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1895To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1804()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1896()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1805\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1897\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1806.PP 1898.PP
… …
1811when writing to a pipe whose other end has been closed, your program gets 1903when writing to a pipe whose other end has been closed, your program gets
1812sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs 1904sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1813this is sensible behaviour, for daemons, this is usually undesirable. 1905this is sensible behaviour, for daemons, this is usually undesirable.
1814.PP 1906.PP
1815So when you encounter spurious, unexplained daemon exits, make sure you 1907So when you encounter spurious, unexplained daemon exits, make sure you
1816ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon 1908ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1817somewhere, as that would have given you a big clue). 1909somewhere, as that would have given you a big clue).
1818.PP 1910.PP
1819\fIThe special problem of \fIaccept()\fIing when you can't\fR 1911\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1820.IX Subsection "The special problem of accept()ing when you can't" 1912.IX Subsection "The special problem of accept()ing when you can't"
1821.PP 1913.PP
1822Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, 1914Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
1823found in post\-2004 Linux) have the peculiar behaviour of not removing a 1915found in post\-2004 Linux) have the peculiar behaviour of not removing a
1824connection from the pending queue in all error cases. 1916connection from the pending queue in all error cases.
1825.PP 1917.PP
1826For example, larger servers often run out of file descriptors (because 1918For example, larger servers often run out of file descriptors (because
1827of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not 1919of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
1863.PD 0 1955.PD 0
1864.IP "ev_io_set (ev_io *, int fd, int events)" 4 1956.IP "ev_io_set (ev_io *, int fd, int events)" 4
1865.IX Item "ev_io_set (ev_io *, int fd, int events)" 1957.IX Item "ev_io_set (ev_io *, int fd, int events)"
1866.PD 1958.PD
1867Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to 1959Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
1868receive 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 1960receive 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, both
1869\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. 1961\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR or \f(CW0\fR, to express the desire to receive the given
1962events.
1963.Sp
1964Note that setting the \f(CW\*(C`events\*(C'\fR to \f(CW0\fR and starting the watcher is
1965supported, but not specially optimized \- if your program sometimes happens
1966to generate this combination this is fine, but if it is easy to avoid
1967starting an io watcher watching for no events you should do so.
1968.IP "ev_io_modify (ev_io *, int events)" 4
1969.IX Item "ev_io_modify (ev_io *, int events)"
1970Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the requested events. Using this
1971might be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR
1972still refers to the same underlying file description, something it cannot
1973do when using \f(CW\*(C`ev_io_set\*(C'\fR.
1870.IP "int fd [read\-only]" 4 1974.IP "int fd [no\-modify]" 4
1871.IX Item "int fd [read-only]" 1975.IX Item "int fd [no-modify]"
1872The file descriptor being watched. 1976The file descriptor being watched. While it can be read at any time, you
1977must not modify this member even when the watcher is stopped \- always use
1978\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
1873.IP "int events [read\-only]" 4 1979.IP "int events [no\-modify]" 4
1874.IX Item "int events [read-only]" 1980.IX Item "int events [no-modify]"
1875The events being watched. 1981The set of events the fd is being watched for, among other flags. Remember
1982that this is a bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events &
1983EV_READ\*(C'\fR, and similarly for \f(CW\*(C`EV_WRITE\*(C'\fR.
1984.Sp
1985As with \f(CW\*(C`fd\*(C'\fR, you must not modify this member even when the watcher is
1986stopped, always use \f(CW\*(C`ev_io_set\*(C'\fR or \f(CW\*(C`ev_io_modify\*(C'\fR for that.
1876.PP 1987.PP
1877\fIExamples\fR 1988\fIExamples\fR
1878.IX Subsection "Examples" 1989.IX Subsection "Examples"
1879.PP 1990.PP
1880Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 1991Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
… …
2434In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2545In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
2435ignored. Instead, each time the periodic watcher gets scheduled, the 2546ignored. Instead, each time the periodic watcher gets scheduled, the
2436reschedule callback will be called with the watcher as first, and the 2547reschedule callback will be called with the watcher as first, and the
2437current time as second argument. 2548current time as second argument.
2438.Sp 2549.Sp
2439\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, 2550\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
2440or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2551or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2441allowed by documentation here\fR. 2552allowed by documentation here\fR.
2442.Sp 2553.Sp
2443If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2554If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
2444it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 2555it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2458It must return the next time to trigger, based on the passed time value 2569It must return the next time to trigger, based on the passed time value
2459(that is, the lowest time value larger than to the second argument). It 2570(that is, the lowest time value larger than to the second argument). It
2460will usually be called just before the callback will be triggered, but 2571will usually be called just before the callback will be triggered, but
2461might be called at other times, too. 2572might be called at other times, too.
2462.Sp 2573.Sp
2463\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or 2574\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
2464equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2575equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2465.Sp 2576.Sp
2466This can be used to create very complex timers, such as a timer that 2577This can be used to create very complex timers, such as a timer that
2467triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate 2578triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2468the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for 2579the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
… …
2613The simplest way to ensure that the signal mask is reset in the child is 2724The simplest way to ensure that the signal mask is reset in the child is
2614to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will 2725to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
2615catch fork calls done by libraries (such as the libc) as well. 2726catch fork calls done by libraries (such as the libc) as well.
2616.PP 2727.PP
2617In current versions of libev, the signal will not be blocked indefinitely 2728In current versions of libev, the signal will not be blocked indefinitely
2618unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces 2729unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
2619the window of opportunity for problems, it will not go away, as libev 2730the window of opportunity for problems, it will not go away, as libev
2620\&\fIhas\fR to modify the signal mask, at least temporarily. 2731\&\fIhas\fR to modify the signal mask, at least temporarily.
2621.PP 2732.PP
2622So I can't stress this enough: \fIIf you do not reset your signal mask when 2733So I can't stress this enough: \fIIf you do not reset your signal mask when
2623you expect it to be empty, you have a race condition in your code\fR. This 2734you expect it to be empty, you have a race condition in your code\fR. This
… …
4308gets automatically stopped and restarted when reconfiguring it with this 4419gets automatically stopped and restarted when reconfiguring it with this
4309method. 4420method.
4310.Sp 4421.Sp
4311For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid 4422For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4312clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. 4423clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4424.Sp
4425For \f(CW\*(C`ev::io\*(C'\fR watchers there is an additional \f(CW\*(C`set\*(C'\fR method that acepts a
4426new event mask only, and internally calls \f(CW\*(C`ev_io_modfify\*(C'\fR.
4313.IP "w\->start ()" 4 4427.IP "w\->start ()" 4
4314.IX Item "w->start ()" 4428.IX Item "w->start ()"
4315Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4429Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4316constructor already stores the event loop. 4430constructor already stores the event loop.
4317.IP "w\->start ([arguments])" 4 4431.IP "w\->start ([arguments])" 4
… …
4518\& #include "ev.c" 4632\& #include "ev.c"
4519.Ve 4633.Ve
4520.PP 4634.PP
4521This will automatically include \fIev.h\fR, too, and should be done in a 4635This will automatically include \fIev.h\fR, too, and should be done in a
4522single C source file only to provide the function implementations. To use 4636single C source file only to provide the function implementations. To use
4523it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best 4637it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
4524done by writing a wrapper around \fIev.h\fR that you can include instead and 4638done by writing a wrapper around \fIev.h\fR that you can include instead and
4525where you can put other configuration options): 4639where you can put other configuration options):
4526.PP 4640.PP
4527.Vb 2 4641.Vb 2
4528\& #define EV_STANDALONE 1 4642\& #define EV_STANDALONE 1
… …
4545\& ev_win32.c required on win32 platforms only 4659\& ev_win32.c required on win32 platforms only
4546\& 4660\&
4547\& ev_select.c only when select backend is enabled 4661\& ev_select.c only when select backend is enabled
4548\& ev_poll.c only when poll backend is enabled 4662\& ev_poll.c only when poll backend is enabled
4549\& ev_epoll.c only when the epoll backend is enabled 4663\& ev_epoll.c only when the epoll backend is enabled
4664\& ev_linuxaio.c only when the linux aio backend is enabled
4665\& ev_iouring.c only when the linux io_uring backend is enabled
4550\& ev_kqueue.c only when the kqueue backend is enabled 4666\& ev_kqueue.c only when the kqueue backend is enabled
4551\& ev_port.c only when the solaris port backend is enabled 4667\& ev_port.c only when the solaris port backend is enabled
4552.Ve 4668.Ve
4553.PP 4669.PP
4554\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4670\&\fIev.c\fR includes the backend files directly when enabled, so you only need
… …
4601values when compiling libev vs. including \fIev.h\fR, so it is permissible 4717values when compiling libev vs. including \fIev.h\fR, so it is permissible
4602to redefine them before including \fIev.h\fR without breaking compatibility 4718to redefine them before including \fIev.h\fR without breaking compatibility
4603to a compiled library. All other symbols change the \s-1ABI,\s0 which means all 4719to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4604users of libev and the libev code itself must be compiled with compatible 4720users of libev and the libev code itself must be compiled with compatible
4605settings. 4721settings.
4606.IP "\s-1EV_COMPAT3 \s0(h)" 4 4722.IP "\s-1EV_COMPAT3\s0 (h)" 4
4607.IX Item "EV_COMPAT3 (h)" 4723.IX Item "EV_COMPAT3 (h)"
4608Backwards compatibility is a major concern for libev. This is why this 4724Backwards compatibility is a major concern for libev. This is why this
4609release of libev comes with wrappers for the functions and symbols that 4725release of libev comes with wrappers for the functions and symbols that
4610have been renamed between libev version 3 and 4. 4726have been renamed between libev version 3 and 4.
4611.Sp 4727.Sp
… …
4616typedef in that case. 4732typedef in that case.
4617.Sp 4733.Sp
4618In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4734In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4619and in some even more future version the compatibility code will be 4735and in some even more future version the compatibility code will be
4620removed completely. 4736removed completely.
4621.IP "\s-1EV_STANDALONE \s0(h)" 4 4737.IP "\s-1EV_STANDALONE\s0 (h)" 4
4622.IX Item "EV_STANDALONE (h)" 4738.IX Item "EV_STANDALONE (h)"
4623Must always be \f(CW1\fR if you do not use autoconf configuration, which 4739Must always be \f(CW1\fR if you do not use autoconf configuration, which
4624keeps libev from including \fIconfig.h\fR, and it also defines dummy 4740keeps libev from including \fIconfig.h\fR, and it also defines dummy
4625implementations for some libevent functions (such as logging, which is not 4741implementations for some libevent functions (such as logging, which is not
4626supported). It will also not define any of the structs usually found in 4742supported). It will also not define any of the structs usually found in
… …
4667higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). 4783higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR).
4668.IP "\s-1EV_USE_NANOSLEEP\s0" 4 4784.IP "\s-1EV_USE_NANOSLEEP\s0" 4
4669.IX Item "EV_USE_NANOSLEEP" 4785.IX Item "EV_USE_NANOSLEEP"
4670If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 4786If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
4671and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 4787and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
4788.IP "\s-1EV_USE_EVENTFD\s0" 4
4789.IX Item "EV_USE_EVENTFD"
4790If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4791available and will probe for kernel support at runtime. This will improve
4792\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4793If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47942.7 or newer, otherwise disabled.
4795.IP "\s-1EV_USE_SIGNALFD\s0" 4
4796.IX Item "EV_USE_SIGNALFD"
4797If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`signalfd ()\*(C'\fR is
4798available and will probe for kernel support at runtime. This enables
4799the use of \s-1EVFLAG_SIGNALFD\s0 for faster and simpler signal handling. If
4800undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
48012.7 or newer, otherwise disabled.
4802.IP "\s-1EV_USE_TIMERFD\s0" 4
4803.IX Item "EV_USE_TIMERFD"
4804If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`timerfd ()\*(C'\fR is
4805available and will probe for kernel support at runtime. This allows
4806libev to detect time jumps accurately. If undefined, it will be enabled
4807if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4808\&\f(CW\*(C`TFD_TIMER_CANCEL_ON_SET\*(C'\fR, otherwise disabled.
4672.IP "\s-1EV_USE_EVENTFD\s0" 4 4809.IP "\s-1EV_USE_EVENTFD\s0" 4
4673.IX Item "EV_USE_EVENTFD" 4810.IX Item "EV_USE_EVENTFD"
4674If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is 4811If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4675available and will probe for kernel support at runtime. This will improve 4812available and will probe for kernel support at runtime. This will improve
4676\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. 4813\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
… …
4735If defined to be \f(CW1\fR, libev will compile in support for the Linux 4872If defined to be \f(CW1\fR, libev will compile in support for the Linux
4736\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4873\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4737otherwise another method will be used as fallback. This is the preferred 4874otherwise another method will be used as fallback. This is the preferred
4738backend for GNU/Linux systems. If undefined, it will be enabled if the 4875backend for GNU/Linux systems. If undefined, it will be enabled if the
4739headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4876headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4877.IP "\s-1EV_USE_LINUXAIO\s0" 4
4878.IX Item "EV_USE_LINUXAIO"
4879If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4880backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4881enabled on linux, otherwise disabled.
4882.IP "\s-1EV_USE_IOURING\s0" 4
4883.IX Item "EV_USE_IOURING"
4884If defined to be \f(CW1\fR, libev will compile in support for the Linux
4885io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4886current limitations it has to be requested explicitly. If undefined, it
4887will be enabled on linux, otherwise disabled.
4740.IP "\s-1EV_USE_KQUEUE\s0" 4 4888.IP "\s-1EV_USE_KQUEUE\s0" 4
4741.IX Item "EV_USE_KQUEUE" 4889.IX Item "EV_USE_KQUEUE"
4742If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4890If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4743\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4891\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4744otherwise another method will be used as fallback. This is the preferred 4892otherwise another method will be used as fallback. This is the preferred
… …
4784handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR 4932handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4785watchers. 4933watchers.
4786.Sp 4934.Sp
4787In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4935In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4788(from \fIsignal.h\fR), which is usually good enough on most platforms. 4936(from \fIsignal.h\fR), which is usually good enough on most platforms.
4789.IP "\s-1EV_H \s0(h)" 4 4937.IP "\s-1EV_H\s0 (h)" 4
4790.IX Item "EV_H (h)" 4938.IX Item "EV_H (h)"
4791The name of the \fIev.h\fR header file used to include it. The default if 4939The name of the \fIev.h\fR header file used to include it. The default if
4792undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4940undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4793used to virtually rename the \fIev.h\fR header file in case of conflicts. 4941used to virtually rename the \fIev.h\fR header file in case of conflicts.
4794.IP "\s-1EV_CONFIG_H \s0(h)" 4 4942.IP "\s-1EV_CONFIG_H\s0 (h)" 4
4795.IX Item "EV_CONFIG_H (h)" 4943.IX Item "EV_CONFIG_H (h)"
4796If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4944If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4797\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4945\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4798\&\f(CW\*(C`EV_H\*(C'\fR, above. 4946\&\f(CW\*(C`EV_H\*(C'\fR, above.
4799.IP "\s-1EV_EVENT_H \s0(h)" 4 4947.IP "\s-1EV_EVENT_H\s0 (h)" 4
4800.IX Item "EV_EVENT_H (h)" 4948.IX Item "EV_EVENT_H (h)"
4801Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4949Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4802of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4950of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4803.IP "\s-1EV_PROTOTYPES \s0(h)" 4 4951.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
4804.IX Item "EV_PROTOTYPES (h)" 4952.IX Item "EV_PROTOTYPES (h)"
4805If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4953If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4806prototypes, but still define all the structs and other symbols. This is 4954prototypes, but still define all the structs and other symbols. This is
4807occasionally useful if you want to provide your own wrapper functions 4955occasionally useful if you want to provide your own wrapper functions
4808around libev functions. 4956around libev functions.
… …
5001called. If set to \f(CW2\fR, then the internal verification code will be 5149called. If set to \f(CW2\fR, then the internal verification code will be
5002called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5150called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
5003verification code will be called very frequently, which will slow down 5151verification code will be called very frequently, which will slow down
5004libev considerably. 5152libev considerably.
5005.Sp 5153.Sp
5154Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5155disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5156.Sp
5006The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5157The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
5007will be \f(CW0\fR. 5158will be \f(CW0\fR.
5008.IP "\s-1EV_COMMON\s0" 4 5159.IP "\s-1EV_COMMON\s0" 4
5009.IX Item "EV_COMMON" 5160.IX Item "EV_COMMON"
5010By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 5161By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
… …
5017.Vb 3 5168.Vb 3
5018\& #define EV_COMMON \e 5169\& #define EV_COMMON \e
5019\& SV *self; /* contains this struct */ \e 5170\& SV *self; /* contains this struct */ \e
5020\& SV *cb_sv, *fh /* note no trailing ";" */ 5171\& SV *cb_sv, *fh /* note no trailing ";" */
5021.Ve 5172.Ve
5022.IP "\s-1EV_CB_DECLARE \s0(type)" 4 5173.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
5023.IX Item "EV_CB_DECLARE (type)" 5174.IX Item "EV_CB_DECLARE (type)"
5024.PD 0 5175.PD 0
5025.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4 5176.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
5026.IX Item "EV_CB_INVOKE (watcher, revents)" 5177.IX Item "EV_CB_INVOKE (watcher, revents)"
5027.IP "ev_set_cb (ev, cb)" 4 5178.IP "ev_set_cb (ev, cb)" 4
5028.IX Item "ev_set_cb (ev, cb)" 5179.IX Item "ev_set_cb (ev, cb)"
5029.PD 5180.PD
5030Can be used to change the callback member declaration in each watcher, 5181Can be used to change the callback member declaration in each watcher,
… …
5033their default definitions. One possible use for overriding these is to 5184their default definitions. One possible use for overriding these is to
5034avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5185avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
5035method calls instead of plain function calls in \*(C+. 5186method calls instead of plain function calls in \*(C+.
5036.SS "\s-1EXPORTED API SYMBOLS\s0" 5187.SS "\s-1EXPORTED API SYMBOLS\s0"
5037.IX Subsection "EXPORTED API SYMBOLS" 5188.IX Subsection "EXPORTED API SYMBOLS"
5038If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of 5189If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5039exported symbols, you can use the provided \fISymbol.*\fR files which list 5190exported symbols, you can use the provided \fISymbol.*\fR files which list
5040all public symbols, one per line: 5191all public symbols, one per line:
5041.PP 5192.PP
5042.Vb 2 5193.Vb 2
5043\& Symbols.ev for libev proper 5194\& Symbols.ev for libev proper
… …
5275.PP 5426.PP
5276\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5427\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5277.IX Subsection "select is buggy" 5428.IX Subsection "select is buggy"
5278.PP 5429.PP
5279All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5430All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5280one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file 5431one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5281descriptors you can pass in to 1024 \- your program suddenly crashes when 5432descriptors you can pass in to 1024 \- your program suddenly crashes when
5282you use more. 5433you use more.
5283.PP 5434.PP
5284There is an undocumented \*(L"workaround\*(R" for this \- defining 5435There is an undocumented \*(L"workaround\*(R" for this \- defining
5285\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5436\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines