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

Comparing libev/ev.3 (file contents):
Revision 1.103 by root, Fri May 1 17:23:34 2015 UTC vs.
Revision 1.126 by root, Sat Jun 3 08:53:03 2023 UTC

1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) 1.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
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-05-01" "libev-4.19" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2023-05-15" "libev-4.33" "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) when you use this 573forget about forgetting to tell libev about forking, although you still
547flag. 574have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
548.Sp 575.Sp
549This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR 576This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
550environment variable. 577environment variable.
551.ie n .IP """EVFLAG_NOINOTIFY""" 4 578.ie n .IP """EVFLAG_NOINOTIFY""" 4
552.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 579.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
… …
579want 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
580unblocking the signals. 607unblocking the signals.
581.Sp 608.Sp
582It'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
583\&\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.
584.Sp 618.Sp
585This 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.
586.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 622.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
587.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
588.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 624.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
589This 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
590libev 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,
591but 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
592using 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
593usually the fastest backend for a low number of (low-numbered :) fds. 629usually the fastest backend for a low number of (low-numbered :) fds.
594.Sp 630.Sp
… …
603\&\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
604\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). 640\&\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 641.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 642.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)" 643.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 644And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
609than select, but handles sparse fds better and has no artificial 645than select, but handles sparse fds better and has no artificial
610limit 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
611considerably with a lot of inactive fds). It scales similarly to select, 647considerably 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 648i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
613performance tips. 649performance tips.
… …
615This 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
616\&\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.
617.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 653.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
618.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 654.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
619.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 655.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
620Use 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
621kernels). 657kernels).
622.Sp 658.Sp
623For 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
624it scales phenomenally better. While poll and select usually scale like 660it 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 661O(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 707All 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 708faster than epoll for maybe up to a hundred file descriptors, depending on
673the usage. So sad. 709the usage. So sad.
674.Sp 710.Sp
675While nominally embeddable in other event loops, this feature is broken in 711While nominally embeddable in other event loops, this feature is broken in
676all 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.
677.Sp 756.Sp
678This 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
679\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 758\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
680.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
681.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
682.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 761.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
683Kqueue deserves special mention, as at the time of this writing, it 762Kqueue deserves special mention, as at the time this backend was
684was 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
685with anything but sockets and pipes, except on Darwin, where of course 764work reliably with anything but sockets and pipes, except on Darwin,
686it's completely useless). Unlike epoll, however, whose brokenness 765where of course it's completely useless). Unlike epoll, however, whose
687is by design, these kqueue bugs can (and eventually will) be fixed 766brokenness 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 767fixed 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 768being \*(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) 769in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a
691system like NetBSD. 770known-to-be-good (\-enough) system like NetBSD.
692.Sp 771.Sp
693You 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
694only 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
695the 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.
696.Sp 775.Sp
697It 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
698kernel is more efficient (which says nothing about its actual speed, of 777kernel is more efficient (which says nothing about its actual speed, of
699course). While stopping, setting and starting an I/O watcher does never 778course). 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 779cause 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 780two 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 781might have to leak fds on fork, but it's more sane than epoll) and it
703drops fds silently in similarly hard-to-detect cases. 782drops fds silently in similarly hard-to-detect cases.
704.Sp 783.Sp
705This backend usually performs well under most conditions. 784This backend usually performs well under most conditions.
706.Sp 785.Sp
707While nominally embeddable in other event loops, this doesn't work 786While nominally embeddable in other event loops, this doesn't work
… …
722and is not embeddable, which would limit the usefulness of this backend 801and is not embeddable, which would limit the usefulness of this backend
723immensely. 802immensely.
724.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 803.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
725.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 804.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
726.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" 805.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
727This uses the Solaris 10 event port mechanism. As with everything on Solaris, 806This uses the Solaris 10 event port mechanism. As with everything on
728it's really slow, but it still scales very well (O(active_fds)). 807Solaris, it's really slow, but it still scales very well (O(active_fds)).
729.Sp 808.Sp
730While this backend scales well, it requires one system call per active 809While this backend scales well, it requires one system call per active
731file descriptor per loop iteration. For small and medium numbers of file 810file descriptor per loop iteration. For small and medium numbers of file
732descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend 811descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend
733might perform better. 812might perform better.
… …
784Example: 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
785used if available. 864used if available.
786.Sp 865.Sp
787.Vb 1 866.Vb 1
788\& 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);
789.Ve 876.Ve
790.RE 877.RE
791.IP "ev_loop_destroy (loop)" 4 878.IP "ev_loop_destroy (loop)" 4
792.IX Item "ev_loop_destroy (loop)" 879.IX Item "ev_loop_destroy (loop)"
793Destroys an event loop object (frees all memory and kernel state 880Destroys an event loop object (frees all memory and kernel state
… …
816to reinitialise the kernel state for backends that have one. Despite 903to reinitialise the kernel state for backends that have one. Despite
817the name, you can call it anytime you are allowed to start or stop 904the name, you can call it anytime you are allowed to start or stop
818watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most 905watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
819sense after forking, in the child process. You \fImust\fR call it (or use 906sense after forking, in the child process. You \fImust\fR call it (or use
820\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 907\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
908.Sp
909In addition, if you want to reuse a loop (via this function or
910\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR.
821.Sp 911.Sp
822Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 912Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
823a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is 913a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
824because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things 914because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
825during fork. 915during fork.
… …
997\& \- Queue all expired timers. 1087\& \- Queue all expired timers.
998\& \- Queue all expired periodics. 1088\& \- Queue all expired periodics.
999\& \- Queue all idle watchers with priority higher than that of pending events. 1089\& \- Queue all idle watchers with priority higher than that of pending events.
1000\& \- Queue all check watchers. 1090\& \- Queue all check watchers.
1001\& \- Call all queued watchers in reverse order (i.e. check watchers first). 1091\& \- Call all queued watchers in reverse order (i.e. check watchers first).
1002\& Signals and child watchers are implemented as I/O watchers, and will 1092\& Signals, async and child watchers are implemented as I/O watchers, and
1003\& be handled here by queueing them when their watcher gets executed. 1093\& will be handled here by queueing them when their watcher gets executed.
1004\& \- If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT 1094\& \- If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT
1005\& were used, or there are no active watchers, goto FINISH, otherwise 1095\& were used, or there are no active watchers, goto FINISH, otherwise
1006\& continue with step LOOP. 1096\& continue with step LOOP.
1007\& FINISH: 1097\& FINISH:
1008\& \- Reset the ev_break status iff it was EVBREAK_ONE. 1098\& \- Reset the ev_break status iff it was EVBREAK_ONE.
… …
1259with 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
1260*)\*(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
1261corresponding 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.
1262.PP 1352.PP
1263As 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
1264must not touch the values stored in it. Most specifically you must never 1354must not touch the values stored in it except when explicitly documented
1265reinitialise 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.
1266.PP 1357.PP
1267Each and every callback receives the event loop pointer as first, the 1358Each and every callback receives the event loop pointer as first, the
1268registered watcher structure as second, and a bitset of received events as 1359registered watcher structure as second, and a bitset of received events as
1269third argument. 1360third argument.
1270.PP 1361.PP
… …
1361bug in your program. 1452bug in your program.
1362.Sp 1453.Sp
1363Libev 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
1364example 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
1365callbacks 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
1366the 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
1367programs, 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
1368thing, so beware. 1459thing, so beware.
1369.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" 1460.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1370.IX Subsection "GENERIC WATCHER FUNCTIONS" 1461.IX Subsection "GENERIC WATCHER FUNCTIONS"
1371.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1462.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
… …
1441therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. 1532therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function.
1442.IP "bool ev_is_active (ev_TYPE *watcher)" 4 1533.IP "bool ev_is_active (ev_TYPE *watcher)" 4
1443.IX Item "bool ev_is_active (ev_TYPE *watcher)" 1534.IX Item "bool ev_is_active (ev_TYPE *watcher)"
1444Returns a true value iff the watcher is active (i.e. it has been started 1535Returns a true value iff the watcher is active (i.e. it has been started
1445and not yet been stopped). As long as a watcher is active you must not modify 1536and not yet been stopped). As long as a watcher is active you must not modify
1446it. 1537it unless documented otherwise.
1538.Sp
1539Obviously, it is safe to call this on an active watcher, or actually any
1540watcher that is initialised.
1447.IP "bool ev_is_pending (ev_TYPE *watcher)" 4 1541.IP "bool ev_is_pending (ev_TYPE *watcher)" 4
1448.IX Item "bool ev_is_pending (ev_TYPE *watcher)" 1542.IX Item "bool ev_is_pending (ev_TYPE *watcher)"
1449Returns a true value iff the watcher is pending, (i.e. it has outstanding 1543Returns a true value iff the watcher is pending, (i.e. it has outstanding
1450events but its callback has not yet been invoked). As long as a watcher 1544events but its callback has not yet been invoked). As long as a watcher
1451is pending (but not active) you must not call an init function on it (but 1545is pending (but not active) you must not call an init function on it (but
1452\&\f(CW\*(C`ev_TYPE_set\*(C'\fR is safe), you must not change its priority, and you must 1546\&\f(CW\*(C`ev_TYPE_set\*(C'\fR is safe), you must not change its priority, and you must
1453make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR 1547make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR
1454it). 1548it).
1549.Sp
1550It is safe to call this on any watcher in any state as long as it is
1551initialised.
1455.IP "callback ev_cb (ev_TYPE *watcher)" 4 1552.IP "callback ev_cb (ev_TYPE *watcher)" 4
1456.IX Item "callback ev_cb (ev_TYPE *watcher)" 1553.IX Item "callback ev_cb (ev_TYPE *watcher)"
1457Returns the callback currently set on the watcher. 1554Returns the callback currently set on the watcher.
1458.IP "ev_set_cb (ev_TYPE *watcher, callback)" 4 1555.IP "ev_set_cb (ev_TYPE *watcher, callback)" 4
1459.IX Item "ev_set_cb (ev_TYPE *watcher, callback)" 1556.IX Item "ev_set_cb (ev_TYPE *watcher, callback)"
… …
1472from being executed (except for \f(CW\*(C`ev_idle\*(C'\fR watchers). 1569from being executed (except for \f(CW\*(C`ev_idle\*(C'\fR watchers).
1473.Sp 1570.Sp
1474If you need to suppress invocation when higher priority events are pending 1571If you need to suppress invocation when higher priority events are pending
1475you need to look at \f(CW\*(C`ev_idle\*(C'\fR watchers, which provide this functionality. 1572you need to look at \f(CW\*(C`ev_idle\*(C'\fR watchers, which provide this functionality.
1476.Sp 1573.Sp
1477You \fImust not\fR change the priority of a watcher as long as it is active or 1574You \fImust not\fR change the priority of a watcher as long as it is active
1478pending. 1575or pending. Reading the priority with \f(CW\*(C`ev_priority\*(C'\fR is fine in any state.
1479.Sp 1576.Sp
1480Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is 1577Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is
1481fine, as long as you do not mind that the priority value you query might 1578fine, as long as you do not mind that the priority value you query might
1482or might not have been clamped to the valid range. 1579or might not have been clamped to the valid range.
1483.Sp 1580.Sp
… …
1502callback to be invoked, which can be accomplished with this function. 1599callback to be invoked, which can be accomplished with this function.
1503.IP "ev_feed_event (loop, ev_TYPE *watcher, int revents)" 4 1600.IP "ev_feed_event (loop, ev_TYPE *watcher, int revents)" 4
1504.IX Item "ev_feed_event (loop, ev_TYPE *watcher, int revents)" 1601.IX Item "ev_feed_event (loop, ev_TYPE *watcher, int revents)"
1505Feeds the given event set into the event loop, as if the specified event 1602Feeds the given event set into the event loop, as if the specified event
1506had happened for the specified watcher (which must be a pointer to an 1603had happened for the specified watcher (which must be a pointer to an
1507initialised but not necessarily started event watcher). Obviously you must 1604initialised but not necessarily started event watcher, though it can be
1508not free the watcher as long as it has pending events. 1605active). Obviously you must not free the watcher as long as it has pending
1606events.
1509.Sp 1607.Sp
1510Stopping the watcher, letting libev invoke it, or calling 1608Stopping the watcher, letting libev invoke it, or calling
1511\&\f(CW\*(C`ev_clear_pending\*(C'\fR will clear the pending event, even if the watcher was 1609\&\f(CW\*(C`ev_clear_pending\*(C'\fR will clear the pending event, even if the watcher was
1512not started in the first place. 1610not started in the first place.
1513.Sp 1611.Sp
… …
1534\&\f(CW\*(C`ev_TYPE_init\*(C'\fR again. 1632\&\f(CW\*(C`ev_TYPE_init\*(C'\fR again.
1535.IP "started/running/active" 4 1633.IP "started/running/active" 4
1536.IX Item "started/running/active" 1634.IX Item "started/running/active"
1537Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes 1635Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes
1538property of the event loop, and is actively waiting for events. While in 1636property of the event loop, and is actively waiting for events. While in
1539this state it cannot be accessed (except in a few documented ways), moved, 1637this state it cannot be accessed (except in a few documented ways, such as
1540freed or anything else \- the only legal thing is to keep a pointer to it, 1638stoping it), moved, freed or anything else \- the only legal thing is to
1541and call libev functions on it that are documented to work on active watchers. 1639keep a pointer to it, and call libev functions on it that are documented
1640to work on active watchers.
1641.Sp
1642As a rule of thumb, before accessing a member or calling any function on
1643a watcher, it should be stopped (or freshly initialised). If that is not
1644convenient, you can check the documentation for that function or member to
1645see if it is safe to use on an active watcher.
1542.IP "pending" 4 1646.IP "pending" 4
1543.IX Item "pending" 1647.IX Item "pending"
1544If a watcher is active and libev determines that an event it is interested 1648If a watcher is active and libev determines that an event it is interested
1545in has occurred (such as a timer expiring), it will become pending. It will 1649in has occurred (such as a timer expiring), it will become pending. It
1546stay in this pending state until either it is stopped or its callback is 1650will stay in this pending state until either it is explicitly stopped or
1547about to be invoked, so it is not normally pending inside the watcher 1651its callback is about to be invoked, so it is not normally pending inside
1548callback. 1652the watcher callback.
1549.Sp 1653.Sp
1550The watcher might or might not be active while it is pending (for example, 1654Generally, the watcher might or might not be active while it is pending
1551an expired non-repeating timer can be pending but no longer active). If it 1655(for example, an expired non-repeating timer can be pending but no longer
1552is stopped, it can be freely accessed (e.g. by calling \f(CW\*(C`ev_TYPE_set\*(C'\fR), 1656active). If it is pending but not active, it can be freely accessed (e.g.
1553but it is still property of the event loop at this time, so cannot be 1657by calling \f(CW\*(C`ev_TYPE_set\*(C'\fR), but it is still property of the event loop at
1554moved, freed or reused. And if it is active the rules described in the 1658this time, so cannot be moved, freed or reused. And if it is active the
1555previous item still apply. 1659rules described in the previous item still apply.
1660.Sp
1661Explicitly stopping a watcher will also clear the pending state
1662unconditionally, so it is safe to stop a watcher and then free it.
1556.Sp 1663.Sp
1557It is also possible to feed an event on a watcher that is not active (e.g. 1664It is also possible to feed an event on a watcher that is not active (e.g.
1558via \f(CW\*(C`ev_feed_event\*(C'\fR), in which case it becomes pending without being 1665via \f(CW\*(C`ev_feed_event\*(C'\fR), in which case it becomes pending without being
1559active. 1666active.
1560.IP "stopped" 4 1667.IP "stopped" 4
… …
1573.IX Subsection "WATCHER PRIORITY MODELS" 1680.IX Subsection "WATCHER PRIORITY MODELS"
1574Many event loops support \fIwatcher priorities\fR, which are usually small 1681Many event loops support \fIwatcher priorities\fR, which are usually small
1575integers that influence the ordering of event callback invocation 1682integers that influence the ordering of event callback invocation
1576between watchers in some way, all else being equal. 1683between watchers in some way, all else being equal.
1577.PP 1684.PP
1578In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its 1685In libev, watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its
1579description for the more technical details such as the actual priority 1686description for the more technical details such as the actual priority
1580range. 1687range.
1581.PP 1688.PP
1582There are two common ways how these these priorities are being interpreted 1689There are two common ways how these these priorities are being interpreted
1583by event loops: 1690by event loops:
… …
1677.IX Header "WATCHER TYPES" 1784.IX Header "WATCHER TYPES"
1678This section describes each watcher in detail, but will not repeat 1785This section describes each watcher in detail, but will not repeat
1679information given in the last section. Any initialisation/set macros, 1786information given in the last section. Any initialisation/set macros,
1680functions and members specific to the watcher type are explained. 1787functions and members specific to the watcher type are explained.
1681.PP 1788.PP
1682Members are additionally marked with either \fI[read\-only]\fR, meaning that, 1789Most members are additionally marked with either \fI[read\-only]\fR, meaning
1683while the watcher is active, you can look at the member and expect some 1790that, while the watcher is active, you can look at the member and expect
1684sensible content, but you must not modify it (you can modify it while the 1791some sensible content, but you must not modify it (you can modify it while
1685watcher is stopped to your hearts content), or \fI[read\-write]\fR, which 1792the watcher is stopped to your hearts content), or \fI[read\-write]\fR, which
1686means you can expect it to have some sensible content while the watcher 1793means you can expect it to have some sensible content while the watcher is
1687is active, but you can also modify it. Modifying it may not do something 1794active, but you can also modify it (within the same thread as the event
1795loop, i.e. without creating data races). Modifying it may not do something
1688sensible or take immediate effect (or do anything at all), but libev will 1796sensible or take immediate effect (or do anything at all), but libev will
1689not crash or malfunction in any way. 1797not crash or malfunction in any way.
1798.PP
1799In any case, the documentation for each member will explain what the
1800effects are, and if there are any additional access restrictions.
1690.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" 1801.ie n .SS """ev_io"" \- is this file descriptor readable or writable?"
1691.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" 1802.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?"
1692.IX Subsection "ev_io - is this file descriptor readable or writable?" 1803.IX Subsection "ev_io - is this file descriptor readable or writable?"
1693I/O watchers check whether a file descriptor is readable or writable 1804I/O watchers check whether a file descriptor is readable or writable
1694in each iteration of the event loop, or, more precisely, when reading 1805in each iteration of the event loop, or, more precisely, when reading
… …
1722But really, best use non-blocking mode. 1833But really, best use non-blocking mode.
1723.PP 1834.PP
1724\fIThe special problem of disappearing file descriptors\fR 1835\fIThe special problem of disappearing file descriptors\fR
1725.IX Subsection "The special problem of disappearing file descriptors" 1836.IX Subsection "The special problem of disappearing file descriptors"
1726.PP 1837.PP
1727Some backends (e.g. kqueue, epoll) need to be told about closing a file 1838Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1728descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1839a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1729such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1840means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1730descriptor, but when it goes away, the operating system will silently drop 1841file descriptor, but when it goes away, the operating system will silently
1731this interest. If another file descriptor with the same number then is 1842drop this interest. If another file descriptor with the same number then
1732registered with libev, there is no efficient way to see that this is, in 1843is registered with libev, there is no efficient way to see that this is,
1733fact, a different file descriptor. 1844in fact, a different file descriptor.
1734.PP 1845.PP
1735To avoid having to explicitly tell libev about such cases, libev follows 1846To avoid having to explicitly tell libev about such cases, libev follows
1736the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1847the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1737will assume that this is potentially a new file descriptor, otherwise 1848will assume that this is potentially a new file descriptor, otherwise
1738it is assumed that the file descriptor stays the same. That means that 1849it is assumed that the file descriptor stays the same. That means that
… …
1790reuse the same code path. 1901reuse the same code path.
1791.PP 1902.PP
1792\fIThe special problem of fork\fR 1903\fIThe special problem of fork\fR
1793.IX Subsection "The special problem of fork" 1904.IX Subsection "The special problem of fork"
1794.PP 1905.PP
1795Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1906Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1796useless behaviour. Libev fully supports fork, but needs to be told about 1907at all or exhibit useless behaviour. Libev fully supports fork, but needs
1797it in the child if you want to continue to use it in the child. 1908to be told about it in the child if you want to continue to use it in the
1909child.
1798.PP 1910.PP
1799To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1911To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1800()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1912()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1801\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1913\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1802.PP 1914.PP
… …
1807when writing to a pipe whose other end has been closed, your program gets 1919when writing to a pipe whose other end has been closed, your program gets
1808sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs 1920sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1809this is sensible behaviour, for daemons, this is usually undesirable. 1921this is sensible behaviour, for daemons, this is usually undesirable.
1810.PP 1922.PP
1811So when you encounter spurious, unexplained daemon exits, make sure you 1923So when you encounter spurious, unexplained daemon exits, make sure you
1812ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon 1924ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1813somewhere, as that would have given you a big clue). 1925somewhere, as that would have given you a big clue).
1814.PP 1926.PP
1815\fIThe special problem of \fIaccept()\fIing when you can't\fR 1927\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1816.IX Subsection "The special problem of accept()ing when you can't" 1928.IX Subsection "The special problem of accept()ing when you can't"
1817.PP 1929.PP
1818Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, 1930Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
1819found in post\-2004 Linux) have the peculiar behaviour of not removing a 1931found in post\-2004 Linux) have the peculiar behaviour of not removing a
1820connection from the pending queue in all error cases. 1932connection from the pending queue in all error cases.
1821.PP 1933.PP
1822For example, larger servers often run out of file descriptors (because 1934For example, larger servers often run out of file descriptors (because
1823of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not 1935of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
1859.PD 0 1971.PD 0
1860.IP "ev_io_set (ev_io *, int fd, int events)" 4 1972.IP "ev_io_set (ev_io *, int fd, int events)" 4
1861.IX Item "ev_io_set (ev_io *, int fd, int events)" 1973.IX Item "ev_io_set (ev_io *, int fd, int events)"
1862.PD 1974.PD
1863Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to 1975Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
1864receive 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 1976receive 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
1865\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. 1977\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR or \f(CW0\fR, to express the desire to receive the given
1978events.
1979.Sp
1980Note that setting the \f(CW\*(C`events\*(C'\fR to \f(CW0\fR and starting the watcher is
1981supported, but not specially optimized \- if your program sometimes happens
1982to generate this combination this is fine, but if it is easy to avoid
1983starting an io watcher watching for no events you should do so.
1984.IP "ev_io_modify (ev_io *, int events)" 4
1985.IX Item "ev_io_modify (ev_io *, int events)"
1986Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the requested events. Using this
1987might be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR
1988still refers to the same underlying file description, something it cannot
1989do when using \f(CW\*(C`ev_io_set\*(C'\fR.
1866.IP "int fd [read\-only]" 4 1990.IP "int fd [no\-modify]" 4
1867.IX Item "int fd [read-only]" 1991.IX Item "int fd [no-modify]"
1868The file descriptor being watched. 1992The file descriptor being watched. While it can be read at any time, you
1993must not modify this member even when the watcher is stopped \- always use
1994\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
1869.IP "int events [read\-only]" 4 1995.IP "int events [no\-modify]" 4
1870.IX Item "int events [read-only]" 1996.IX Item "int events [no-modify]"
1871The events being watched. 1997The set of events the fd is being watched for, among other flags. Remember
1998that this is a bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events &
1999EV_READ\*(C'\fR, and similarly for \f(CW\*(C`EV_WRITE\*(C'\fR.
2000.Sp
2001As with \f(CW\*(C`fd\*(C'\fR, you must not modify this member even when the watcher is
2002stopped, always use \f(CW\*(C`ev_io_set\*(C'\fR or \f(CW\*(C`ev_io_modify\*(C'\fR for that.
1872.PP 2003.PP
1873\fIExamples\fR 2004\fIExamples\fR
1874.IX Subsection "Examples" 2005.IX Subsection "Examples"
1875.PP 2006.PP
1876Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 2007Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
… …
2247.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 2378.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
2248.PD 0 2379.PD 0
2249.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 2380.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
2250.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 2381.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
2251.PD 2382.PD
2252Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR 2383Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
2253is \f(CW0.\fR, then it will automatically be stopped once the timeout is 2384negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
2254reached. If it is positive, then the timer will automatically be 2385automatically be stopped once the timeout is reached. If it is positive,
2255configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, 2386then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
2256until stopped manually. 2387seconds later, again, and again, until stopped manually.
2257.Sp 2388.Sp
2258The timer itself will do a best-effort at avoiding drift, that is, if 2389The timer itself will do a best-effort at avoiding drift, that is, if
2259you configure a timer to trigger every 10 seconds, then it will normally 2390you configure a timer to trigger every 10 seconds, then it will normally
2260trigger at exactly 10 second intervals. If, however, your program cannot 2391trigger at exactly 10 second intervals. If, however, your program cannot
2261keep up with the timer (because it takes longer than those 10 seconds to 2392keep up with the timer (because it takes longer than those 10 seconds to
… …
2343Periodic watchers are also timers of a kind, but they are very versatile 2474Periodic watchers are also timers of a kind, but they are very versatile
2344(and unfortunately a bit complex). 2475(and unfortunately a bit complex).
2345.PP 2476.PP
2346Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or 2477Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or
2347relative time, the physical time that passes) but on wall clock time 2478relative time, the physical time that passes) but on wall clock time
2348(absolute time, the thing you can read on your calender or clock). The 2479(absolute time, the thing you can read on your calendar or clock). The
2349difference is that wall clock time can run faster or slower than real 2480difference is that wall clock time can run faster or slower than real
2350time, and time jumps are not uncommon (e.g. when you adjust your 2481time, and time jumps are not uncommon (e.g. when you adjust your
2351wrist-watch). 2482wrist-watch).
2352.PP 2483.PP
2353You can tell a periodic watcher to trigger after some specific point 2484You can tell a periodic watcher to trigger after some specific point
… …
2358\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting 2489\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
2359it, as it uses a relative timeout). 2490it, as it uses a relative timeout).
2360.PP 2491.PP
2361\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex 2492\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
2362timers, such as triggering an event on each \*(L"midnight, local time\*(R", or 2493timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
2363other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as 2494other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
2364those cannot react to time jumps. 2495watchers, as those cannot react to time jumps.
2365.PP 2496.PP
2366As with timers, the callback is guaranteed to be invoked only when the 2497As with timers, the callback is guaranteed to be invoked only when the
2367point in time where it is supposed to trigger has passed. If multiple 2498point in time where it is supposed to trigger has passed. If multiple
2368timers become ready during the same loop iteration then the ones with 2499timers become ready during the same loop iteration then the ones with
2369earlier time-out values are invoked before ones with later time-out values 2500earlier time-out values are invoked before ones with later time-out values
… …
2430In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2561In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
2431ignored. Instead, each time the periodic watcher gets scheduled, the 2562ignored. Instead, each time the periodic watcher gets scheduled, the
2432reschedule callback will be called with the watcher as first, and the 2563reschedule callback will be called with the watcher as first, and the
2433current time as second argument. 2564current time as second argument.
2434.Sp 2565.Sp
2435\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, 2566\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
2436or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2567or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2437allowed by documentation here\fR. 2568allowed by documentation here\fR.
2438.Sp 2569.Sp
2439If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2570If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
2440it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 2571it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2454It must return the next time to trigger, based on the passed time value 2585It must return the next time to trigger, based on the passed time value
2455(that is, the lowest time value larger than to the second argument). It 2586(that is, the lowest time value larger than to the second argument). It
2456will usually be called just before the callback will be triggered, but 2587will usually be called just before the callback will be triggered, but
2457might be called at other times, too. 2588might be called at other times, too.
2458.Sp 2589.Sp
2459\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or 2590\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
2460equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2591equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2461.Sp 2592.Sp
2462This can be used to create very complex timers, such as a timer that 2593This can be used to create very complex timers, such as a timer that
2463triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the 2594triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2464next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2595the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
2465you do this is, again, up to you (but it is not trivial, which is the main 2596this. Here is a (completely untested, no error checking) example on how to
2466reason I omitted it as an example). 2597do this:
2598.Sp
2599.Vb 1
2600\& #include <time.h>
2601\&
2602\& static ev_tstamp
2603\& my_rescheduler (ev_periodic *w, ev_tstamp now)
2604\& {
2605\& time_t tnow = (time_t)now;
2606\& struct tm tm;
2607\& localtime_r (&tnow, &tm);
2608\&
2609\& tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2610\& ++tm.tm_mday; // midnight next day
2611\&
2612\& return mktime (&tm);
2613\& }
2614.Ve
2615.Sp
2616Note: this code might run into trouble on days that have more then two
2617midnights (beginning and end).
2467.RE 2618.RE
2468.RS 4 2619.RS 4
2469.RE 2620.RE
2470.IP "ev_periodic_again (loop, ev_periodic *)" 4 2621.IP "ev_periodic_again (loop, ev_periodic *)" 4
2471.IX Item "ev_periodic_again (loop, ev_periodic *)" 2622.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
2589The simplest way to ensure that the signal mask is reset in the child is 2740The simplest way to ensure that the signal mask is reset in the child is
2590to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will 2741to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
2591catch fork calls done by libraries (such as the libc) as well. 2742catch fork calls done by libraries (such as the libc) as well.
2592.PP 2743.PP
2593In current versions of libev, the signal will not be blocked indefinitely 2744In current versions of libev, the signal will not be blocked indefinitely
2594unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces 2745unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
2595the window of opportunity for problems, it will not go away, as libev 2746the window of opportunity for problems, it will not go away, as libev
2596\&\fIhas\fR to modify the signal mask, at least temporarily. 2747\&\fIhas\fR to modify the signal mask, at least temporarily.
2597.PP 2748.PP
2598So I can't stress this enough: \fIIf you do not reset your signal mask when 2749So I can't stress this enough: \fIIf you do not reset your signal mask when
2599you expect it to be empty, you have a race condition in your code\fR. This 2750you expect it to be empty, you have a race condition in your code\fR. This
… …
3641is a time window between the event loop checking and resetting the async 3792is a time window between the event loop checking and resetting the async
3642notification, and the callback being invoked. 3793notification, and the callback being invoked.
3643.SH "OTHER FUNCTIONS" 3794.SH "OTHER FUNCTIONS"
3644.IX Header "OTHER FUNCTIONS" 3795.IX Header "OTHER FUNCTIONS"
3645There are some other functions of possible interest. Described. Here. Now. 3796There are some other functions of possible interest. Described. Here. Now.
3646.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 3797.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
3647.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 3798.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
3648This function combines a simple timer and an I/O watcher, calls your 3799This function combines a simple timer and an I/O watcher, calls your
3649callback on whichever event happens first and automatically stops both 3800callback on whichever event happens first and automatically stops both
3650watchers. This is useful if you want to wait for a single event on an fd 3801watchers. This is useful if you want to wait for a single event on an fd
3651or timeout without having to allocate/configure/start/stop/free one or 3802or timeout without having to allocate/configure/start/stop/free one or
3652more watchers yourself. 3803more watchers yourself.
… …
3867.PP 4018.PP
3868First, you need to associate some data with the event loop: 4019First, you need to associate some data with the event loop:
3869.PP 4020.PP
3870.Vb 6 4021.Vb 6
3871\& typedef struct { 4022\& typedef struct {
3872\& mutex_t lock; /* global loop lock */ 4023\& pthread_mutex_t lock; /* global loop lock */
4024\& pthread_t tid;
4025\& pthread_cond_t invoke_cv;
3873\& ev_async async_w; 4026\& ev_async async_w;
3874\& thread_t tid;
3875\& cond_t invoke_cv;
3876\& } userdata; 4027\& } userdata;
3877\& 4028\&
3878\& void prepare_loop (EV_P) 4029\& void prepare_loop (EV_P)
3879\& { 4030\& {
3880\& // for simplicity, we use a static userdata struct. 4031\& // for simplicity, we use a static userdata struct.
3881\& static userdata u; 4032\& static userdata u;
3882\& 4033\&
3883\& ev_async_init (&u\->async_w, async_cb); 4034\& ev_async_init (&u.async_w, async_cb);
3884\& ev_async_start (EV_A_ &u\->async_w); 4035\& ev_async_start (EV_A_ &u.async_w);
3885\& 4036\&
3886\& pthread_mutex_init (&u\->lock, 0); 4037\& pthread_mutex_init (&u.lock, 0);
3887\& pthread_cond_init (&u\->invoke_cv, 0); 4038\& pthread_cond_init (&u.invoke_cv, 0);
3888\& 4039\&
3889\& // now associate this with the loop 4040\& // now associate this with the loop
3890\& ev_set_userdata (EV_A_ u); 4041\& ev_set_userdata (EV_A_ &u);
3891\& ev_set_invoke_pending_cb (EV_A_ l_invoke); 4042\& ev_set_invoke_pending_cb (EV_A_ l_invoke);
3892\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 4043\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3893\& 4044\&
3894\& // then create the thread running ev_run 4045\& // then create the thread running ev_run
3895\& pthread_create (&u\->tid, 0, l_run, EV_A); 4046\& pthread_create (&u.tid, 0, l_run, EV_A);
3896\& } 4047\& }
3897.Ve 4048.Ve
3898.PP 4049.PP
3899The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used 4050The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used
3900solely to wake up the event loop so it takes notice of any new watchers 4051solely to wake up the event loop so it takes notice of any new watchers
… …
4102The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the 4253The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4103libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4254libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4104will work fine. 4255will work fine.
4105.PP 4256.PP
4106Proper exception specifications might have to be added to callbacks passed 4257Proper exception specifications might have to be added to callbacks passed
4107to libev: exceptions may be thrown only from watcher callbacks, all 4258to libev: exceptions may be thrown only from watcher callbacks, all other
4108other callbacks (allocator, syserr, loop acquire/release and periodic 4259callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4109reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4260callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
4110()\*(C'\fR specification. If you have code that needs to be compiled as both C 4261specification. If you have code that needs to be compiled as both C and
4111and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4262\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
4112.PP 4263.PP
4113.Vb 6 4264.Vb 6
4114\& static void 4265\& static void
4115\& fatal_error (const char *msg) EV_THROW 4266\& fatal_error (const char *msg) EV_NOEXCEPT
4116\& { 4267\& {
4117\& perror (msg); 4268\& perror (msg);
4118\& abort (); 4269\& abort ();
4119\& } 4270\& }
4120\& 4271\&
… …
4284gets automatically stopped and restarted when reconfiguring it with this 4435gets automatically stopped and restarted when reconfiguring it with this
4285method. 4436method.
4286.Sp 4437.Sp
4287For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid 4438For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4288clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. 4439clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4440.Sp
4441For \f(CW\*(C`ev::io\*(C'\fR watchers there is an additional \f(CW\*(C`set\*(C'\fR method that acepts a
4442new event mask only, and internally calls \f(CW\*(C`ev_io_modify\*(C'\fR.
4289.IP "w\->start ()" 4 4443.IP "w\->start ()" 4
4290.IX Item "w->start ()" 4444.IX Item "w->start ()"
4291Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4445Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4292constructor already stores the event loop. 4446constructor already stores the event loop.
4293.IP "w\->start ([arguments])" 4 4447.IP "w\->start ([arguments])" 4
… …
4494\& #include "ev.c" 4648\& #include "ev.c"
4495.Ve 4649.Ve
4496.PP 4650.PP
4497This will automatically include \fIev.h\fR, too, and should be done in a 4651This will automatically include \fIev.h\fR, too, and should be done in a
4498single C source file only to provide the function implementations. To use 4652single C source file only to provide the function implementations. To use
4499it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best 4653it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
4500done by writing a wrapper around \fIev.h\fR that you can include instead and 4654done by writing a wrapper around \fIev.h\fR that you can include instead and
4501where you can put other configuration options): 4655where you can put other configuration options):
4502.PP 4656.PP
4503.Vb 2 4657.Vb 2
4504\& #define EV_STANDALONE 1 4658\& #define EV_STANDALONE 1
… …
4518\& ev_vars.h 4672\& ev_vars.h
4519\& ev_wrap.h 4673\& ev_wrap.h
4520\& 4674\&
4521\& ev_win32.c required on win32 platforms only 4675\& ev_win32.c required on win32 platforms only
4522\& 4676\&
4523\& ev_select.c only when select backend is enabled (which is enabled by default) 4677\& ev_select.c only when select backend is enabled
4524\& ev_poll.c only when poll backend is enabled (disabled by default) 4678\& ev_poll.c only when poll backend is enabled
4525\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 4679\& ev_epoll.c only when the epoll backend is enabled
4680\& ev_linuxaio.c only when the linux aio backend is enabled
4681\& ev_iouring.c only when the linux io_uring backend is enabled
4526\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4682\& ev_kqueue.c only when the kqueue backend is enabled
4527\& ev_port.c only when the solaris port backend is enabled (disabled by default) 4683\& ev_port.c only when the solaris port backend is enabled
4528.Ve 4684.Ve
4529.PP 4685.PP
4530\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4686\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4531to compile this single file. 4687to compile this single file.
4532.PP 4688.PP
… …
4577values when compiling libev vs. including \fIev.h\fR, so it is permissible 4733values when compiling libev vs. including \fIev.h\fR, so it is permissible
4578to redefine them before including \fIev.h\fR without breaking compatibility 4734to redefine them before including \fIev.h\fR without breaking compatibility
4579to a compiled library. All other symbols change the \s-1ABI,\s0 which means all 4735to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4580users of libev and the libev code itself must be compiled with compatible 4736users of libev and the libev code itself must be compiled with compatible
4581settings. 4737settings.
4582.IP "\s-1EV_COMPAT3 \s0(h)" 4 4738.IP "\s-1EV_COMPAT3\s0 (h)" 4
4583.IX Item "EV_COMPAT3 (h)" 4739.IX Item "EV_COMPAT3 (h)"
4584Backwards compatibility is a major concern for libev. This is why this 4740Backwards compatibility is a major concern for libev. This is why this
4585release of libev comes with wrappers for the functions and symbols that 4741release of libev comes with wrappers for the functions and symbols that
4586have been renamed between libev version 3 and 4. 4742have been renamed between libev version 3 and 4.
4587.Sp 4743.Sp
… …
4592typedef in that case. 4748typedef in that case.
4593.Sp 4749.Sp
4594In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4750In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4595and in some even more future version the compatibility code will be 4751and in some even more future version the compatibility code will be
4596removed completely. 4752removed completely.
4597.IP "\s-1EV_STANDALONE \s0(h)" 4 4753.IP "\s-1EV_STANDALONE\s0 (h)" 4
4598.IX Item "EV_STANDALONE (h)" 4754.IX Item "EV_STANDALONE (h)"
4599Must always be \f(CW1\fR if you do not use autoconf configuration, which 4755Must always be \f(CW1\fR if you do not use autoconf configuration, which
4600keeps libev from including \fIconfig.h\fR, and it also defines dummy 4756keeps libev from including \fIconfig.h\fR, and it also defines dummy
4601implementations for some libevent functions (such as logging, which is not 4757implementations for some libevent functions (such as logging, which is not
4602supported). It will also not define any of the structs usually found in 4758supported). It will also not define any of the structs usually found in
… …
4643higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). 4799higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR).
4644.IP "\s-1EV_USE_NANOSLEEP\s0" 4 4800.IP "\s-1EV_USE_NANOSLEEP\s0" 4
4645.IX Item "EV_USE_NANOSLEEP" 4801.IX Item "EV_USE_NANOSLEEP"
4646If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 4802If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
4647and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 4803and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
4804.IP "\s-1EV_USE_EVENTFD\s0" 4
4805.IX Item "EV_USE_EVENTFD"
4806If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4807available and will probe for kernel support at runtime. This will improve
4808\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4809If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
48102.7 or newer, otherwise disabled.
4811.IP "\s-1EV_USE_SIGNALFD\s0" 4
4812.IX Item "EV_USE_SIGNALFD"
4813If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`signalfd ()\*(C'\fR is
4814available and will probe for kernel support at runtime. This enables
4815the use of \s-1EVFLAG_SIGNALFD\s0 for faster and simpler signal handling. If
4816undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
48172.7 or newer, otherwise disabled.
4818.IP "\s-1EV_USE_TIMERFD\s0" 4
4819.IX Item "EV_USE_TIMERFD"
4820If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`timerfd ()\*(C'\fR is
4821available and will probe for kernel support at runtime. This allows
4822libev to detect time jumps accurately. If undefined, it will be enabled
4823if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4824\&\f(CW\*(C`TFD_TIMER_CANCEL_ON_SET\*(C'\fR, otherwise disabled.
4648.IP "\s-1EV_USE_EVENTFD\s0" 4 4825.IP "\s-1EV_USE_EVENTFD\s0" 4
4649.IX Item "EV_USE_EVENTFD" 4826.IX Item "EV_USE_EVENTFD"
4650If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is 4827If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4651available and will probe for kernel support at runtime. This will improve 4828available and will probe for kernel support at runtime. This will improve
4652\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. 4829\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
… …
4711If defined to be \f(CW1\fR, libev will compile in support for the Linux 4888If defined to be \f(CW1\fR, libev will compile in support for the Linux
4712\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4889\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4713otherwise another method will be used as fallback. This is the preferred 4890otherwise another method will be used as fallback. This is the preferred
4714backend for GNU/Linux systems. If undefined, it will be enabled if the 4891backend for GNU/Linux systems. If undefined, it will be enabled if the
4715headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4892headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4893.IP "\s-1EV_USE_LINUXAIO\s0" 4
4894.IX Item "EV_USE_LINUXAIO"
4895If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4896backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4897enabled on linux, otherwise disabled.
4898.IP "\s-1EV_USE_IOURING\s0" 4
4899.IX Item "EV_USE_IOURING"
4900If defined to be \f(CW1\fR, libev will compile in support for the Linux
4901io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4902current limitations it has to be requested explicitly. If undefined, it
4903will be enabled on linux, otherwise disabled.
4716.IP "\s-1EV_USE_KQUEUE\s0" 4 4904.IP "\s-1EV_USE_KQUEUE\s0" 4
4717.IX Item "EV_USE_KQUEUE" 4905.IX Item "EV_USE_KQUEUE"
4718If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4906If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4719\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4907\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4720otherwise another method will be used as fallback. This is the preferred 4908otherwise another method will be used as fallback. This is the preferred
… …
4760handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR 4948handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4761watchers. 4949watchers.
4762.Sp 4950.Sp
4763In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4951In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4764(from \fIsignal.h\fR), which is usually good enough on most platforms. 4952(from \fIsignal.h\fR), which is usually good enough on most platforms.
4765.IP "\s-1EV_H \s0(h)" 4 4953.IP "\s-1EV_H\s0 (h)" 4
4766.IX Item "EV_H (h)" 4954.IX Item "EV_H (h)"
4767The name of the \fIev.h\fR header file used to include it. The default if 4955The name of the \fIev.h\fR header file used to include it. The default if
4768undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4956undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4769used to virtually rename the \fIev.h\fR header file in case of conflicts. 4957used to virtually rename the \fIev.h\fR header file in case of conflicts.
4770.IP "\s-1EV_CONFIG_H \s0(h)" 4 4958.IP "\s-1EV_CONFIG_H\s0 (h)" 4
4771.IX Item "EV_CONFIG_H (h)" 4959.IX Item "EV_CONFIG_H (h)"
4772If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4960If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4773\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4961\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4774\&\f(CW\*(C`EV_H\*(C'\fR, above. 4962\&\f(CW\*(C`EV_H\*(C'\fR, above.
4775.IP "\s-1EV_EVENT_H \s0(h)" 4 4963.IP "\s-1EV_EVENT_H\s0 (h)" 4
4776.IX Item "EV_EVENT_H (h)" 4964.IX Item "EV_EVENT_H (h)"
4777Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4965Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4778of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4966of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4779.IP "\s-1EV_PROTOTYPES \s0(h)" 4 4967.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
4780.IX Item "EV_PROTOTYPES (h)" 4968.IX Item "EV_PROTOTYPES (h)"
4781If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4969If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4782prototypes, but still define all the structs and other symbols. This is 4970prototypes, but still define all the structs and other symbols. This is
4783occasionally useful if you want to provide your own wrapper functions 4971occasionally useful if you want to provide your own wrapper functions
4784around libev functions. 4972around libev functions.
… …
4977called. If set to \f(CW2\fR, then the internal verification code will be 5165called. If set to \f(CW2\fR, then the internal verification code will be
4978called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5166called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
4979verification code will be called very frequently, which will slow down 5167verification code will be called very frequently, which will slow down
4980libev considerably. 5168libev considerably.
4981.Sp 5169.Sp
5170Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5171disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5172.Sp
4982The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5173The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
4983will be \f(CW0\fR. 5174will be \f(CW0\fR.
4984.IP "\s-1EV_COMMON\s0" 4 5175.IP "\s-1EV_COMMON\s0" 4
4985.IX Item "EV_COMMON" 5176.IX Item "EV_COMMON"
4986By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 5177By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
… …
4993.Vb 3 5184.Vb 3
4994\& #define EV_COMMON \e 5185\& #define EV_COMMON \e
4995\& SV *self; /* contains this struct */ \e 5186\& SV *self; /* contains this struct */ \e
4996\& SV *cb_sv, *fh /* note no trailing ";" */ 5187\& SV *cb_sv, *fh /* note no trailing ";" */
4997.Ve 5188.Ve
4998.IP "\s-1EV_CB_DECLARE \s0(type)" 4 5189.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
4999.IX Item "EV_CB_DECLARE (type)" 5190.IX Item "EV_CB_DECLARE (type)"
5000.PD 0 5191.PD 0
5001.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4 5192.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
5002.IX Item "EV_CB_INVOKE (watcher, revents)" 5193.IX Item "EV_CB_INVOKE (watcher, revents)"
5003.IP "ev_set_cb (ev, cb)" 4 5194.IP "ev_set_cb (ev, cb)" 4
5004.IX Item "ev_set_cb (ev, cb)" 5195.IX Item "ev_set_cb (ev, cb)"
5005.PD 5196.PD
5006Can be used to change the callback member declaration in each watcher, 5197Can be used to change the callback member declaration in each watcher,
… …
5009their default definitions. One possible use for overriding these is to 5200their default definitions. One possible use for overriding these is to
5010avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5201avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
5011method calls instead of plain function calls in \*(C+. 5202method calls instead of plain function calls in \*(C+.
5012.SS "\s-1EXPORTED API SYMBOLS\s0" 5203.SS "\s-1EXPORTED API SYMBOLS\s0"
5013.IX Subsection "EXPORTED API SYMBOLS" 5204.IX Subsection "EXPORTED API SYMBOLS"
5014If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of 5205If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5015exported symbols, you can use the provided \fISymbol.*\fR files which list 5206exported symbols, you can use the provided \fISymbol.*\fR files which list
5016all public symbols, one per line: 5207all public symbols, one per line:
5017.PP 5208.PP
5018.Vb 2 5209.Vb 2
5019\& Symbols.ev for libev proper 5210\& Symbols.ev for libev proper
… …
5251.PP 5442.PP
5252\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5443\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5253.IX Subsection "select is buggy" 5444.IX Subsection "select is buggy"
5254.PP 5445.PP
5255All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5446All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5256one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file 5447one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5257descriptors you can pass in to 1024 \- your program suddenly crashes when 5448descriptors you can pass in to 1024 \- your program suddenly crashes when
5258you use more. 5449you use more.
5259.PP 5450.PP
5260There is an undocumented \*(L"workaround\*(R" for this \- defining 5451There is an undocumented \*(L"workaround\*(R" for this \- defining
5261\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5452\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
… …
5409Libev assumes not only that all watcher pointers have the same internal 5600Libev assumes not only that all watcher pointers have the same internal
5410structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also 5601structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5411assumes that the same (machine) code can be used to call any watcher 5602assumes that the same (machine) code can be used to call any watcher
5412callback: The watcher callbacks have different type signatures, but libev 5603callback: The watcher callbacks have different type signatures, but libev
5413calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5604calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5605.IP "null pointers and integer zero are represented by 0 bytes" 4
5606.IX Item "null pointers and integer zero are represented by 0 bytes"
5607Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
5608relies on this setting pointers and integers to null.
5414.IP "pointer accesses must be thread-atomic" 4 5609.IP "pointer accesses must be thread-atomic" 4
5415.IX Item "pointer accesses must be thread-atomic" 5610.IX Item "pointer accesses must be thread-atomic"
5416Accessing a pointer value must be atomic, it must both be readable and 5611Accessing a pointer value must be atomic, it must both be readable and
5417writable in one piece \- this is the case on all current architectures. 5612writable in one piece \- this is the case on all current architectures.
5418.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 5613.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4

Diff Legend

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