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

Comparing libev/ev.3 (file contents):
Revision 1.104 by root, Sun Dec 20 01:35:55 2015 UTC vs.
Revision 1.117 by root, Fri Dec 20 20:51:46 2019 UTC

1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30) 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 "2015-12-20" "libev-4.20" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-12-20" "libev-4.27" "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)
… …
536make libev check for a fork in each iteration by enabling this flag. 562make libev check for a fork in each iteration by enabling this flag.
537.Sp 563.Sp
538This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, 564This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop,
539and thus this might slow down your event loop if you do a lot of loop 565and thus this might slow down your event loop if you do a lot of loop
540iterations and little real work, but is usually not noticeable (on my 566iterations and little real work, but is usually not noticeable (on my
541GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence 567GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn
542without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has 568sequence without a system call and thus \fIvery\fR fast, but my GNU/Linux
543\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). 569system also has \f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). (Update: glibc
570versions 2.25 apparently removed the \f(CW\*(C`getpid\*(C'\fR optimisation again).
544.Sp 571.Sp
545The big advantage of this flag is that you can forget about fork (and 572The big advantage of this flag is that you can forget about fork (and
546forget about forgetting to tell libev about forking, although you still 573forget about forgetting to tell libev about forking, although you still
547have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag. 574have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
548.Sp 575.Sp
… …
566threads that are not interested in handling them. 593threads that are not interested in handling them.
567.Sp 594.Sp
568Signalfd will not be used by default as this changes your signal mask, and 595Signalfd will not be used by default as this changes your signal mask, and
569there are a lot of shoddy libraries and programs (glib's threadpool for 596there are a lot of shoddy libraries and programs (glib's threadpool for
570example) that can't properly initialise their signal masks. 597example) that can't properly initialise their signal masks.
598.ie n .IP """EVFLAG_NOTIMERFD""" 4
599.el .IP "\f(CWEVFLAG_NOTIMERFD\fR" 4
600.IX Item "EVFLAG_NOTIMERFD"
601When this flag is specified, the libev will avoid using a \f(CW\*(C`timerfd\*(C'\fR to
602detect time jumps. It will still be able to detect time jumps, but takes
603longer and has a lower accuracy in doing so, but saves a file descriptor
604per loop.
571.ie n .IP """EVFLAG_NOSIGMASK""" 4 605.ie n .IP """EVFLAG_NOSIGMASK""" 4
572.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4 606.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4
573.IX Item "EVFLAG_NOSIGMASK" 607.IX Item "EVFLAG_NOSIGMASK"
574When this flag is specified, then libev will avoid to modify the signal 608When this flag is specified, then libev will avoid to modify the signal
575mask. Specifically, this means you have to make sure signals are unblocked 609mask. Specifically, this means you have to make sure signals are unblocked
… …
584.Sp 618.Sp
585This flag's behaviour will become the default in future versions of libev. 619This flag's behaviour will become the default in future versions of libev.
586.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 620.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
587.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 621.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
588.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 622.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
589This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 623This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
590libev tries to roll its own fd_set with no limits on the number of fds, 624libev tries to roll its own fd_set with no limits on the number of fds,
591but if that fails, expect a fairly low limit on the number of fds when 625but if that fails, expect a fairly low limit on the number of fds when
592using this backend. It doesn't scale too well (O(highest_fd)), but its 626using this backend. It doesn't scale too well (O(highest_fd)), but its
593usually the fastest backend for a low number of (low-numbered :) fds. 627usually the fastest backend for a low number of (low-numbered :) fds.
594.Sp 628.Sp
… …
603\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the 637\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the
604\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). 638\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
605.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 639.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
606.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 640.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
607.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 641.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
608And this is your standard \fIpoll\fR\|(2) backend. It's more complicated 642And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
609than select, but handles sparse fds better and has no artificial 643than select, but handles sparse fds better and has no artificial
610limit on the number of fds you can use (except it will slow down 644limit on the number of fds you can use (except it will slow down
611considerably with a lot of inactive fds). It scales similarly to select, 645considerably with a lot of inactive fds). It scales similarly to select,
612i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for 646i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
613performance tips. 647performance tips.
… …
615This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 649This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and
616\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. 650\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
617.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 651.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
618.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 652.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
619.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 653.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
620Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 654Use the Linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
621kernels). 655kernels).
622.Sp 656.Sp
623For few fds, this backend is a bit little slower than poll and select, but 657For few fds, this backend is a bit little slower than poll and select, but
624it scales phenomenally better. While poll and select usually scale like 658it scales phenomenally better. While poll and select usually scale like
625O(total_fds) where total_fds is the total number of fds (or the highest 659O(total_fds) where total_fds is the total number of fds (or the highest
… …
671All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or 705All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or
672faster than epoll for maybe up to a hundred file descriptors, depending on 706faster than epoll for maybe up to a hundred file descriptors, depending on
673the usage. So sad. 707the usage. So sad.
674.Sp 708.Sp
675While nominally embeddable in other event loops, this feature is broken in 709While nominally embeddable in other event loops, this feature is broken in
676all kernel versions tested so far. 710a lot of kernel revisions, but probably(!) works in current versions.
711.Sp
712This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
713\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
714.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4
715.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4
716.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
717Use 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
718only tries to use it in 4.19+).
719.Sp
720This is another Linux train wreck of an event interface.
721.Sp
722If this backend works for you (as of this writing, it was very
723experimental), it is the best event interface available on Linux and might
724be well worth enabling it \- if it isn't available in your kernel this will
725be detected and this backend will be skipped.
726.Sp
727This backend can batch oneshot requests and supports a user-space ring
728buffer to receive events. It also doesn't suffer from most of the design
729problems of epoll (such as not being able to remove event sources from
730the epoll set), and generally sounds too good to be true. Because, this
731being the Linux kernel, of course it suffers from a whole new set of
732limitations, forcing you to fall back to epoll, inheriting all its design
733issues.
734.Sp
735For one, it is not easily embeddable (but probably could be done using
736an event fd at some extra overhead). It also is subject to a system wide
737limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR. If no \s-1AIO\s0
738requests are left, this backend will be skipped during initialisation, and
739will switch to epoll when the loop is active.
740.Sp
741Most problematic in practice, however, is that not all file descriptors
742work with it. For example, in Linux 5.1, \s-1TCP\s0 sockets, pipes, event fds,
743files, \fI/dev/null\fR and many others are supported, but ttys do not work
744properly (a known bug that the kernel developers don't care about, see
745<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
746(yet?) a generic event polling interface.
747.Sp
748Overall, it seems the Linux developers just don't want it to have a
749generic event handling mechanism other than \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`poll\*(C'\fR.
750.Sp
751To work around all these problem, the current version of libev uses its
752epoll backend as a fallback for file descriptor types that do not work. Or
753falls back completely to epoll if the kernel acts up.
677.Sp 754.Sp
678This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 755This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
679\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 756\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
680.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 757.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
681.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 758.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
682.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 759.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
683Kqueue deserves special mention, as at the time of this writing, it 760Kqueue deserves special mention, as at the time this backend was
684was broken on all BSDs except NetBSD (usually it doesn't work reliably 761implemented, it was broken on all BSDs except NetBSD (usually it doesn't
685with anything but sockets and pipes, except on Darwin, where of course 762work reliably with anything but sockets and pipes, except on Darwin,
686it's completely useless). Unlike epoll, however, whose brokenness 763where of course it's completely useless). Unlike epoll, however, whose
687is by design, these kqueue bugs can (and eventually will) be fixed 764brokenness is by design, these kqueue bugs can be (and mostly have been)
688without \s-1API\s0 changes to existing programs. For this reason it's not being 765fixed without \s-1API\s0 changes to existing programs. For this reason it's not
689\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using 766being \*(L"auto-detected\*(R" on all platforms unless you explicitly specify it
690\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) 767in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a
691system like NetBSD. 768known-to-be-good (\-enough) system like NetBSD.
692.Sp 769.Sp
693You still can embed kqueue into a normal poll or select backend and use it 770You still can embed kqueue into a normal poll or select backend and use it
694only for sockets (after having made sure that sockets work with kqueue on 771only for sockets (after having made sure that sockets work with kqueue on
695the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 772the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
696.Sp 773.Sp
697It scales in the same way as the epoll backend, but the interface to the 774It scales in the same way as the epoll backend, but the interface to the
698kernel is more efficient (which says nothing about its actual speed, of 775kernel is more efficient (which says nothing about its actual speed, of
699course). While stopping, setting and starting an I/O watcher does never 776course). While stopping, setting and starting an I/O watcher does never
700cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 777cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
701two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you 778two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
702might have to leak fd's on fork, but it's more sane than epoll) and it 779might have to leak fds on fork, but it's more sane than epoll) and it
703drops fds silently in similarly hard-to-detect cases. 780drops fds silently in similarly hard-to-detect cases.
704.Sp 781.Sp
705This backend usually performs well under most conditions. 782This backend usually performs well under most conditions.
706.Sp 783.Sp
707While nominally embeddable in other event loops, this doesn't work 784While nominally embeddable in other event loops, this doesn't work
… …
784Example: Use whatever libev has to offer, but make sure that kqueue is 861Example: Use whatever libev has to offer, but make sure that kqueue is
785used if available. 862used if available.
786.Sp 863.Sp
787.Vb 1 864.Vb 1
788\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 865\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
866.Ve
867.Sp
868Example: Similarly, on linux, you mgiht want to take advantage of the
869linux aio backend if possible, but fall back to something else if that
870isn't available.
871.Sp
872.Vb 1
873\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
789.Ve 874.Ve
790.RE 875.RE
791.IP "ev_loop_destroy (loop)" 4 876.IP "ev_loop_destroy (loop)" 4
792.IX Item "ev_loop_destroy (loop)" 877.IX Item "ev_loop_destroy (loop)"
793Destroys an event loop object (frees all memory and kernel state 878Destroys an event loop object (frees all memory and kernel state
… …
1364bug in your program. 1449bug in your program.
1365.Sp 1450.Sp
1366Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1451Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1367example it might indicate that a fd is readable or writable, and if your 1452example it might indicate that a fd is readable or writable, and if your
1368callbacks is well-written it can just attempt the operation and cope with 1453callbacks is well-written it can just attempt the operation and cope with
1369the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1454the error from \fBread()\fR or \fBwrite()\fR. This will not work in multi-threaded
1370programs, though, as the fd could already be closed and reused for another 1455programs, though, as the fd could already be closed and reused for another
1371thing, so beware. 1456thing, so beware.
1372.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" 1457.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1373.IX Subsection "GENERIC WATCHER FUNCTIONS" 1458.IX Subsection "GENERIC WATCHER FUNCTIONS"
1374.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1459.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
… …
1576.IX Subsection "WATCHER PRIORITY MODELS" 1661.IX Subsection "WATCHER PRIORITY MODELS"
1577Many event loops support \fIwatcher priorities\fR, which are usually small 1662Many event loops support \fIwatcher priorities\fR, which are usually small
1578integers that influence the ordering of event callback invocation 1663integers that influence the ordering of event callback invocation
1579between watchers in some way, all else being equal. 1664between watchers in some way, all else being equal.
1580.PP 1665.PP
1581In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its 1666In libev, watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its
1582description for the more technical details such as the actual priority 1667description for the more technical details such as the actual priority
1583range. 1668range.
1584.PP 1669.PP
1585There are two common ways how these these priorities are being interpreted 1670There are two common ways how these these priorities are being interpreted
1586by event loops: 1671by event loops:
… …
1725But really, best use non-blocking mode. 1810But really, best use non-blocking mode.
1726.PP 1811.PP
1727\fIThe special problem of disappearing file descriptors\fR 1812\fIThe special problem of disappearing file descriptors\fR
1728.IX Subsection "The special problem of disappearing file descriptors" 1813.IX Subsection "The special problem of disappearing file descriptors"
1729.PP 1814.PP
1730Some backends (e.g. kqueue, epoll) need to be told about closing a file 1815Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1731descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1816a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1732such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1817means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1733descriptor, but when it goes away, the operating system will silently drop 1818file descriptor, but when it goes away, the operating system will silently
1734this interest. If another file descriptor with the same number then is 1819drop this interest. If another file descriptor with the same number then
1735registered with libev, there is no efficient way to see that this is, in 1820is registered with libev, there is no efficient way to see that this is,
1736fact, a different file descriptor. 1821in fact, a different file descriptor.
1737.PP 1822.PP
1738To avoid having to explicitly tell libev about such cases, libev follows 1823To avoid having to explicitly tell libev about such cases, libev follows
1739the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1824the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1740will assume that this is potentially a new file descriptor, otherwise 1825will assume that this is potentially a new file descriptor, otherwise
1741it is assumed that the file descriptor stays the same. That means that 1826it is assumed that the file descriptor stays the same. That means that
… …
1793reuse the same code path. 1878reuse the same code path.
1794.PP 1879.PP
1795\fIThe special problem of fork\fR 1880\fIThe special problem of fork\fR
1796.IX Subsection "The special problem of fork" 1881.IX Subsection "The special problem of fork"
1797.PP 1882.PP
1798Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1883Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1799useless behaviour. Libev fully supports fork, but needs to be told about 1884at all or exhibit useless behaviour. Libev fully supports fork, but needs
1800it in the child if you want to continue to use it in the child. 1885to be told about it in the child if you want to continue to use it in the
1886child.
1801.PP 1887.PP
1802To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1888To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1803()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1889()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1804\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1890\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1805.PP 1891.PP
… …
1810when writing to a pipe whose other end has been closed, your program gets 1896when writing to a pipe whose other end has been closed, your program gets
1811sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs 1897sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1812this is sensible behaviour, for daemons, this is usually undesirable. 1898this is sensible behaviour, for daemons, this is usually undesirable.
1813.PP 1899.PP
1814So when you encounter spurious, unexplained daemon exits, make sure you 1900So when you encounter spurious, unexplained daemon exits, make sure you
1815ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon 1901ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1816somewhere, as that would have given you a big clue). 1902somewhere, as that would have given you a big clue).
1817.PP 1903.PP
1818\fIThe special problem of \fIaccept()\fIing when you can't\fR 1904\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1819.IX Subsection "The special problem of accept()ing when you can't" 1905.IX Subsection "The special problem of accept()ing when you can't"
1820.PP 1906.PP
1821Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, 1907Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
1822found in post\-2004 Linux) have the peculiar behaviour of not removing a 1908found in post\-2004 Linux) have the peculiar behaviour of not removing a
1823connection from the pending queue in all error cases. 1909connection from the pending queue in all error cases.
1824.PP 1910.PP
1825For example, larger servers often run out of file descriptors (because 1911For example, larger servers often run out of file descriptors (because
1826of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not 1912of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
2250.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 2336.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
2251.PD 0 2337.PD 0
2252.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 2338.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
2253.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 2339.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
2254.PD 2340.PD
2255Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR 2341Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
2256is \f(CW0.\fR, then it will automatically be stopped once the timeout is 2342negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
2257reached. If it is positive, then the timer will automatically be 2343automatically be stopped once the timeout is reached. If it is positive,
2258configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, 2344then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
2259until stopped manually. 2345seconds later, again, and again, until stopped manually.
2260.Sp 2346.Sp
2261The timer itself will do a best-effort at avoiding drift, that is, if 2347The timer itself will do a best-effort at avoiding drift, that is, if
2262you configure a timer to trigger every 10 seconds, then it will normally 2348you configure a timer to trigger every 10 seconds, then it will normally
2263trigger at exactly 10 second intervals. If, however, your program cannot 2349trigger at exactly 10 second intervals. If, however, your program cannot
2264keep up with the timer (because it takes longer than those 10 seconds to 2350keep up with the timer (because it takes longer than those 10 seconds to
… …
2346Periodic watchers are also timers of a kind, but they are very versatile 2432Periodic watchers are also timers of a kind, but they are very versatile
2347(and unfortunately a bit complex). 2433(and unfortunately a bit complex).
2348.PP 2434.PP
2349Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or 2435Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or
2350relative time, the physical time that passes) but on wall clock time 2436relative time, the physical time that passes) but on wall clock time
2351(absolute time, the thing you can read on your calender or clock). The 2437(absolute time, the thing you can read on your calendar or clock). The
2352difference is that wall clock time can run faster or slower than real 2438difference is that wall clock time can run faster or slower than real
2353time, and time jumps are not uncommon (e.g. when you adjust your 2439time, and time jumps are not uncommon (e.g. when you adjust your
2354wrist-watch). 2440wrist-watch).
2355.PP 2441.PP
2356You can tell a periodic watcher to trigger after some specific point 2442You can tell a periodic watcher to trigger after some specific point
… …
2361\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting 2447\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
2362it, as it uses a relative timeout). 2448it, as it uses a relative timeout).
2363.PP 2449.PP
2364\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex 2450\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
2365timers, such as triggering an event on each \*(L"midnight, local time\*(R", or 2451timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
2366other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as 2452other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
2367those cannot react to time jumps. 2453watchers, as those cannot react to time jumps.
2368.PP 2454.PP
2369As with timers, the callback is guaranteed to be invoked only when the 2455As with timers, the callback is guaranteed to be invoked only when the
2370point in time where it is supposed to trigger has passed. If multiple 2456point in time where it is supposed to trigger has passed. If multiple
2371timers become ready during the same loop iteration then the ones with 2457timers become ready during the same loop iteration then the ones with
2372earlier time-out values are invoked before ones with later time-out values 2458earlier time-out values are invoked before ones with later time-out values
… …
2433In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2519In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
2434ignored. Instead, each time the periodic watcher gets scheduled, the 2520ignored. Instead, each time the periodic watcher gets scheduled, the
2435reschedule callback will be called with the watcher as first, and the 2521reschedule callback will be called with the watcher as first, and the
2436current time as second argument. 2522current time as second argument.
2437.Sp 2523.Sp
2438\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, 2524\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
2439or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2525or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2440allowed by documentation here\fR. 2526allowed by documentation here\fR.
2441.Sp 2527.Sp
2442If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2528If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
2443it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 2529it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2457It must return the next time to trigger, based on the passed time value 2543It must return the next time to trigger, based on the passed time value
2458(that is, the lowest time value larger than to the second argument). It 2544(that is, the lowest time value larger than to the second argument). It
2459will usually be called just before the callback will be triggered, but 2545will usually be called just before the callback will be triggered, but
2460might be called at other times, too. 2546might be called at other times, too.
2461.Sp 2547.Sp
2462\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or 2548\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
2463equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2549equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2464.Sp 2550.Sp
2465This can be used to create very complex timers, such as a timer that 2551This can be used to create very complex timers, such as a timer that
2466triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the 2552triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2467next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2553the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
2468you do this is, again, up to you (but it is not trivial, which is the main 2554this. Here is a (completely untested, no error checking) example on how to
2469reason I omitted it as an example). 2555do this:
2556.Sp
2557.Vb 1
2558\& #include <time.h>
2559\&
2560\& static ev_tstamp
2561\& my_rescheduler (ev_periodic *w, ev_tstamp now)
2562\& {
2563\& time_t tnow = (time_t)now;
2564\& struct tm tm;
2565\& localtime_r (&tnow, &tm);
2566\&
2567\& tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2568\& ++tm.tm_mday; // midnight next day
2569\&
2570\& return mktime (&tm);
2571\& }
2572.Ve
2573.Sp
2574Note: this code might run into trouble on days that have more then two
2575midnights (beginning and end).
2470.RE 2576.RE
2471.RS 4 2577.RS 4
2472.RE 2578.RE
2473.IP "ev_periodic_again (loop, ev_periodic *)" 4 2579.IP "ev_periodic_again (loop, ev_periodic *)" 4
2474.IX Item "ev_periodic_again (loop, ev_periodic *)" 2580.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
2592The simplest way to ensure that the signal mask is reset in the child is 2698The simplest way to ensure that the signal mask is reset in the child is
2593to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will 2699to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
2594catch fork calls done by libraries (such as the libc) as well. 2700catch fork calls done by libraries (such as the libc) as well.
2595.PP 2701.PP
2596In current versions of libev, the signal will not be blocked indefinitely 2702In current versions of libev, the signal will not be blocked indefinitely
2597unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces 2703unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
2598the window of opportunity for problems, it will not go away, as libev 2704the window of opportunity for problems, it will not go away, as libev
2599\&\fIhas\fR to modify the signal mask, at least temporarily. 2705\&\fIhas\fR to modify the signal mask, at least temporarily.
2600.PP 2706.PP
2601So I can't stress this enough: \fIIf you do not reset your signal mask when 2707So I can't stress this enough: \fIIf you do not reset your signal mask when
2602you expect it to be empty, you have a race condition in your code\fR. This 2708you expect it to be empty, you have a race condition in your code\fR. This
… …
3644is a time window between the event loop checking and resetting the async 3750is a time window between the event loop checking and resetting the async
3645notification, and the callback being invoked. 3751notification, and the callback being invoked.
3646.SH "OTHER FUNCTIONS" 3752.SH "OTHER FUNCTIONS"
3647.IX Header "OTHER FUNCTIONS" 3753.IX Header "OTHER FUNCTIONS"
3648There are some other functions of possible interest. Described. Here. Now. 3754There are some other functions of possible interest. Described. Here. Now.
3649.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 3755.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
3650.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 3756.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
3651This function combines a simple timer and an I/O watcher, calls your 3757This function combines a simple timer and an I/O watcher, calls your
3652callback on whichever event happens first and automatically stops both 3758callback on whichever event happens first and automatically stops both
3653watchers. This is useful if you want to wait for a single event on an fd 3759watchers. This is useful if you want to wait for a single event on an fd
3654or timeout without having to allocate/configure/start/stop/free one or 3760or timeout without having to allocate/configure/start/stop/free one or
3655more watchers yourself. 3761more watchers yourself.
… …
4105The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the 4211The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4106libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4212libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4107will work fine. 4213will work fine.
4108.PP 4214.PP
4109Proper exception specifications might have to be added to callbacks passed 4215Proper exception specifications might have to be added to callbacks passed
4110to libev: exceptions may be thrown only from watcher callbacks, all 4216to libev: exceptions may be thrown only from watcher callbacks, all other
4111other callbacks (allocator, syserr, loop acquire/release and periodic 4217callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4112reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4218callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
4113()\*(C'\fR specification. If you have code that needs to be compiled as both C 4219specification. If you have code that needs to be compiled as both C and
4114and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4220\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
4115.PP 4221.PP
4116.Vb 6 4222.Vb 6
4117\& static void 4223\& static void
4118\& fatal_error (const char *msg) EV_THROW 4224\& fatal_error (const char *msg) EV_NOEXCEPT
4119\& { 4225\& {
4120\& perror (msg); 4226\& perror (msg);
4121\& abort (); 4227\& abort ();
4122\& } 4228\& }
4123\& 4229\&
… …
4497\& #include "ev.c" 4603\& #include "ev.c"
4498.Ve 4604.Ve
4499.PP 4605.PP
4500This will automatically include \fIev.h\fR, too, and should be done in a 4606This will automatically include \fIev.h\fR, too, and should be done in a
4501single C source file only to provide the function implementations. To use 4607single C source file only to provide the function implementations. To use
4502it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best 4608it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
4503done by writing a wrapper around \fIev.h\fR that you can include instead and 4609done by writing a wrapper around \fIev.h\fR that you can include instead and
4504where you can put other configuration options): 4610where you can put other configuration options):
4505.PP 4611.PP
4506.Vb 2 4612.Vb 2
4507\& #define EV_STANDALONE 1 4613\& #define EV_STANDALONE 1
… …
4521\& ev_vars.h 4627\& ev_vars.h
4522\& ev_wrap.h 4628\& ev_wrap.h
4523\& 4629\&
4524\& ev_win32.c required on win32 platforms only 4630\& ev_win32.c required on win32 platforms only
4525\& 4631\&
4526\& ev_select.c only when select backend is enabled (which is enabled by default) 4632\& ev_select.c only when select backend is enabled
4527\& ev_poll.c only when poll backend is enabled (disabled by default) 4633\& ev_poll.c only when poll backend is enabled
4528\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 4634\& ev_epoll.c only when the epoll backend is enabled
4635\& ev_linuxaio.c only when the linux aio backend is enabled
4636\& ev_iouring.c only when the linux io_uring backend is enabled
4529\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4637\& ev_kqueue.c only when the kqueue backend is enabled
4530\& ev_port.c only when the solaris port backend is enabled (disabled by default) 4638\& ev_port.c only when the solaris port backend is enabled
4531.Ve 4639.Ve
4532.PP 4640.PP
4533\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4641\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4534to compile this single file. 4642to compile this single file.
4535.PP 4643.PP
… …
4580values when compiling libev vs. including \fIev.h\fR, so it is permissible 4688values when compiling libev vs. including \fIev.h\fR, so it is permissible
4581to redefine them before including \fIev.h\fR without breaking compatibility 4689to redefine them before including \fIev.h\fR without breaking compatibility
4582to a compiled library. All other symbols change the \s-1ABI,\s0 which means all 4690to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4583users of libev and the libev code itself must be compiled with compatible 4691users of libev and the libev code itself must be compiled with compatible
4584settings. 4692settings.
4585.IP "\s-1EV_COMPAT3 \s0(h)" 4 4693.IP "\s-1EV_COMPAT3\s0 (h)" 4
4586.IX Item "EV_COMPAT3 (h)" 4694.IX Item "EV_COMPAT3 (h)"
4587Backwards compatibility is a major concern for libev. This is why this 4695Backwards compatibility is a major concern for libev. This is why this
4588release of libev comes with wrappers for the functions and symbols that 4696release of libev comes with wrappers for the functions and symbols that
4589have been renamed between libev version 3 and 4. 4697have been renamed between libev version 3 and 4.
4590.Sp 4698.Sp
… …
4595typedef in that case. 4703typedef in that case.
4596.Sp 4704.Sp
4597In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4705In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4598and in some even more future version the compatibility code will be 4706and in some even more future version the compatibility code will be
4599removed completely. 4707removed completely.
4600.IP "\s-1EV_STANDALONE \s0(h)" 4 4708.IP "\s-1EV_STANDALONE\s0 (h)" 4
4601.IX Item "EV_STANDALONE (h)" 4709.IX Item "EV_STANDALONE (h)"
4602Must always be \f(CW1\fR if you do not use autoconf configuration, which 4710Must always be \f(CW1\fR if you do not use autoconf configuration, which
4603keeps libev from including \fIconfig.h\fR, and it also defines dummy 4711keeps libev from including \fIconfig.h\fR, and it also defines dummy
4604implementations for some libevent functions (such as logging, which is not 4712implementations for some libevent functions (such as logging, which is not
4605supported). It will also not define any of the structs usually found in 4713supported). It will also not define any of the structs usually found in
… …
4646higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). 4754higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR).
4647.IP "\s-1EV_USE_NANOSLEEP\s0" 4 4755.IP "\s-1EV_USE_NANOSLEEP\s0" 4
4648.IX Item "EV_USE_NANOSLEEP" 4756.IX Item "EV_USE_NANOSLEEP"
4649If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 4757If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
4650and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 4758and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
4759.IP "\s-1EV_USE_EVENTFD\s0" 4
4760.IX Item "EV_USE_EVENTFD"
4761If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4762available and will probe for kernel support at runtime. This will improve
4763\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4764If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47652.7 or newer, otherwise disabled.
4766.IP "\s-1EV_USE_SIGNALFD\s0" 4
4767.IX Item "EV_USE_SIGNALFD"
4768If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`signalfd ()\*(C'\fR is
4769available and will probe for kernel support at runtime. This enables
4770the use of \s-1EVFLAG_SIGNALFD\s0 for faster and simpler signal handling. If
4771undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47722.7 or newer, otherwise disabled.
4773.IP "\s-1EV_USE_TIMERFD\s0" 4
4774.IX Item "EV_USE_TIMERFD"
4775If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`timerfd ()\*(C'\fR is
4776available and will probe for kernel support at runtime. This allows
4777libev to detect time jumps accurately. If undefined, it will be enabled
4778if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4779\&\f(CW\*(C`TFD_TIMER_CANCEL_ON_SET\*(C'\fR, otherwise disabled.
4651.IP "\s-1EV_USE_EVENTFD\s0" 4 4780.IP "\s-1EV_USE_EVENTFD\s0" 4
4652.IX Item "EV_USE_EVENTFD" 4781.IX Item "EV_USE_EVENTFD"
4653If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is 4782If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4654available and will probe for kernel support at runtime. This will improve 4783available and will probe for kernel support at runtime. This will improve
4655\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. 4784\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
… …
4714If defined to be \f(CW1\fR, libev will compile in support for the Linux 4843If defined to be \f(CW1\fR, libev will compile in support for the Linux
4715\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4844\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4716otherwise another method will be used as fallback. This is the preferred 4845otherwise another method will be used as fallback. This is the preferred
4717backend for GNU/Linux systems. If undefined, it will be enabled if the 4846backend for GNU/Linux systems. If undefined, it will be enabled if the
4718headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4847headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4848.IP "\s-1EV_USE_LINUXAIO\s0" 4
4849.IX Item "EV_USE_LINUXAIO"
4850If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4851backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4852enabled on linux, otherwise disabled.
4853.IP "\s-1EV_USE_IOURING\s0" 4
4854.IX Item "EV_USE_IOURING"
4855If defined to be \f(CW1\fR, libev will compile in support for the Linux
4856io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4857current limitations it has to be requested explicitly. If undefined, it
4858will be enabled on linux, otherwise disabled.
4719.IP "\s-1EV_USE_KQUEUE\s0" 4 4859.IP "\s-1EV_USE_KQUEUE\s0" 4
4720.IX Item "EV_USE_KQUEUE" 4860.IX Item "EV_USE_KQUEUE"
4721If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4861If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4722\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4862\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4723otherwise another method will be used as fallback. This is the preferred 4863otherwise another method will be used as fallback. This is the preferred
… …
4763handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR 4903handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4764watchers. 4904watchers.
4765.Sp 4905.Sp
4766In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4906In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4767(from \fIsignal.h\fR), which is usually good enough on most platforms. 4907(from \fIsignal.h\fR), which is usually good enough on most platforms.
4768.IP "\s-1EV_H \s0(h)" 4 4908.IP "\s-1EV_H\s0 (h)" 4
4769.IX Item "EV_H (h)" 4909.IX Item "EV_H (h)"
4770The name of the \fIev.h\fR header file used to include it. The default if 4910The name of the \fIev.h\fR header file used to include it. The default if
4771undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4911undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4772used to virtually rename the \fIev.h\fR header file in case of conflicts. 4912used to virtually rename the \fIev.h\fR header file in case of conflicts.
4773.IP "\s-1EV_CONFIG_H \s0(h)" 4 4913.IP "\s-1EV_CONFIG_H\s0 (h)" 4
4774.IX Item "EV_CONFIG_H (h)" 4914.IX Item "EV_CONFIG_H (h)"
4775If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4915If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4776\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4916\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4777\&\f(CW\*(C`EV_H\*(C'\fR, above. 4917\&\f(CW\*(C`EV_H\*(C'\fR, above.
4778.IP "\s-1EV_EVENT_H \s0(h)" 4 4918.IP "\s-1EV_EVENT_H\s0 (h)" 4
4779.IX Item "EV_EVENT_H (h)" 4919.IX Item "EV_EVENT_H (h)"
4780Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4920Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4781of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4921of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4782.IP "\s-1EV_PROTOTYPES \s0(h)" 4 4922.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
4783.IX Item "EV_PROTOTYPES (h)" 4923.IX Item "EV_PROTOTYPES (h)"
4784If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4924If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4785prototypes, but still define all the structs and other symbols. This is 4925prototypes, but still define all the structs and other symbols. This is
4786occasionally useful if you want to provide your own wrapper functions 4926occasionally useful if you want to provide your own wrapper functions
4787around libev functions. 4927around libev functions.
… …
4980called. If set to \f(CW2\fR, then the internal verification code will be 5120called. If set to \f(CW2\fR, then the internal verification code will be
4981called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5121called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
4982verification code will be called very frequently, which will slow down 5122verification code will be called very frequently, which will slow down
4983libev considerably. 5123libev considerably.
4984.Sp 5124.Sp
5125Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5126disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5127.Sp
4985The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5128The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
4986will be \f(CW0\fR. 5129will be \f(CW0\fR.
4987.IP "\s-1EV_COMMON\s0" 4 5130.IP "\s-1EV_COMMON\s0" 4
4988.IX Item "EV_COMMON" 5131.IX Item "EV_COMMON"
4989By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 5132By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
… …
4996.Vb 3 5139.Vb 3
4997\& #define EV_COMMON \e 5140\& #define EV_COMMON \e
4998\& SV *self; /* contains this struct */ \e 5141\& SV *self; /* contains this struct */ \e
4999\& SV *cb_sv, *fh /* note no trailing ";" */ 5142\& SV *cb_sv, *fh /* note no trailing ";" */
5000.Ve 5143.Ve
5001.IP "\s-1EV_CB_DECLARE \s0(type)" 4 5144.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
5002.IX Item "EV_CB_DECLARE (type)" 5145.IX Item "EV_CB_DECLARE (type)"
5003.PD 0 5146.PD 0
5004.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4 5147.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
5005.IX Item "EV_CB_INVOKE (watcher, revents)" 5148.IX Item "EV_CB_INVOKE (watcher, revents)"
5006.IP "ev_set_cb (ev, cb)" 4 5149.IP "ev_set_cb (ev, cb)" 4
5007.IX Item "ev_set_cb (ev, cb)" 5150.IX Item "ev_set_cb (ev, cb)"
5008.PD 5151.PD
5009Can be used to change the callback member declaration in each watcher, 5152Can be used to change the callback member declaration in each watcher,
… …
5012their default definitions. One possible use for overriding these is to 5155their default definitions. One possible use for overriding these is to
5013avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5156avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
5014method calls instead of plain function calls in \*(C+. 5157method calls instead of plain function calls in \*(C+.
5015.SS "\s-1EXPORTED API SYMBOLS\s0" 5158.SS "\s-1EXPORTED API SYMBOLS\s0"
5016.IX Subsection "EXPORTED API SYMBOLS" 5159.IX Subsection "EXPORTED API SYMBOLS"
5017If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of 5160If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5018exported symbols, you can use the provided \fISymbol.*\fR files which list 5161exported symbols, you can use the provided \fISymbol.*\fR files which list
5019all public symbols, one per line: 5162all public symbols, one per line:
5020.PP 5163.PP
5021.Vb 2 5164.Vb 2
5022\& Symbols.ev for libev proper 5165\& Symbols.ev for libev proper
… …
5254.PP 5397.PP
5255\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5398\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5256.IX Subsection "select is buggy" 5399.IX Subsection "select is buggy"
5257.PP 5400.PP
5258All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5401All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5259one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file 5402one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5260descriptors you can pass in to 1024 \- your program suddenly crashes when 5403descriptors you can pass in to 1024 \- your program suddenly crashes when
5261you use more. 5404you use more.
5262.PP 5405.PP
5263There is an undocumented \*(L"workaround\*(R" for this \- defining 5406There is an undocumented \*(L"workaround\*(R" for this \- defining
5264\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5407\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
… …
5412Libev assumes not only that all watcher pointers have the same internal 5555Libev assumes not only that all watcher pointers have the same internal
5413structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also 5556structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5414assumes that the same (machine) code can be used to call any watcher 5557assumes that the same (machine) code can be used to call any watcher
5415callback: The watcher callbacks have different type signatures, but libev 5558callback: The watcher callbacks have different type signatures, but libev
5416calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5559calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5560.IP "null pointers and integer zero are represented by 0 bytes" 4
5561.IX Item "null pointers and integer zero are represented by 0 bytes"
5562Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
5563relies on this setting pointers and integers to null.
5417.IP "pointer accesses must be thread-atomic" 4 5564.IP "pointer accesses must be thread-atomic" 4
5418.IX Item "pointer accesses must be thread-atomic" 5565.IX Item "pointer accesses must be thread-atomic"
5419Accessing a pointer value must be atomic, it must both be readable and 5566Accessing a pointer value must be atomic, it must both be readable and
5420writable in one piece \- this is the case on all current architectures. 5567writable in one piece \- this is the case on all current architectures.
5421.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 5568.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4

Diff Legend

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