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

Comparing libev/ev.3 (file contents):
Revision 1.100 by root, Tue Oct 29 12:13:37 2013 UTC vs.
Revision 1.116 by root, Sun Jul 7 06:00:32 2019 UTC

1.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) 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 "2013-10-29" "libev-4.15" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-07-07" "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) 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
… …
584.Sp 611.Sp
585This flag's behaviour will become the default in future versions of libev. 612This flag's behaviour will become the default in future versions of libev.
586.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 613.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
587.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 614.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
588.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 615.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
589This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 616This 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, 617libev 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 618but 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 619using 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. 620usually the fastest backend for a low number of (low-numbered :) fds.
594.Sp 621.Sp
… …
603\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the 630\&\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). 631\&\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 632.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 633.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)" 634.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 635And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
609than select, but handles sparse fds better and has no artificial 636than select, but handles sparse fds better and has no artificial
610limit on the number of fds you can use (except it will slow down 637limit 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, 638considerably 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 639i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
613performance tips. 640performance tips.
… …
615This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 642This 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. 643\&\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 644.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
618.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 645.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
619.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 646.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
620Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 647Use the Linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
621kernels). 648kernels).
622.Sp 649.Sp
623For few fds, this backend is a bit little slower than poll and select, but 650For 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 651it 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 652O(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 698All 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 699faster than epoll for maybe up to a hundred file descriptors, depending on
673the usage. So sad. 700the usage. So sad.
674.Sp 701.Sp
675While nominally embeddable in other event loops, this feature is broken in 702While nominally embeddable in other event loops, this feature is broken in
676all kernel versions tested so far. 703a lot of kernel revisions, but probably(!) works in current versions.
704.Sp
705This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
706\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
707.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4
708.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4
709.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
710Use 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
711only tries to use it in 4.19+).
712.Sp
713This is another Linux train wreck of an event interface.
714.Sp
715If this backend works for you (as of this writing, it was very
716experimental), it is the best event interface available on Linux and might
717be well worth enabling it \- if it isn't available in your kernel this will
718be detected and this backend will be skipped.
719.Sp
720This backend can batch oneshot requests and supports a user-space ring
721buffer to receive events. It also doesn't suffer from most of the design
722problems of epoll (such as not being able to remove event sources from
723the epoll set), and generally sounds too good to be true. Because, this
724being the Linux kernel, of course it suffers from a whole new set of
725limitations, forcing you to fall back to epoll, inheriting all its design
726issues.
727.Sp
728For one, it is not easily embeddable (but probably could be done using
729an event fd at some extra overhead). It also is subject to a system wide
730limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR. If no \s-1AIO\s0
731requests are left, this backend will be skipped during initialisation, and
732will switch to epoll when the loop is active.
733.Sp
734Most problematic in practice, however, is that not all file descriptors
735work with it. For example, in Linux 5.1, \s-1TCP\s0 sockets, pipes, event fds,
736files, \fI/dev/null\fR and many others are supported, but ttys do not work
737properly (a known bug that the kernel developers don't care about, see
738<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
739(yet?) a generic event polling interface.
740.Sp
741Overall, it seems the Linux developers just don't want it to have a
742generic event handling mechanism other than \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`poll\*(C'\fR.
743.Sp
744To work around all these problem, the current version of libev uses its
745epoll backend as a fallback for file descriptor types that do not work. Or
746falls back completely to epoll if the kernel acts up.
677.Sp 747.Sp
678This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 748This 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. 749\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
680.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 750.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 751.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
682.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 752.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
683Kqueue deserves special mention, as at the time of this writing, it 753Kqueue deserves special mention, as at the time this backend was
684was broken on all BSDs except NetBSD (usually it doesn't work reliably 754implemented, it was broken on all BSDs except NetBSD (usually it doesn't
685with anything but sockets and pipes, except on Darwin, where of course 755work reliably with anything but sockets and pipes, except on Darwin,
686it's completely useless). Unlike epoll, however, whose brokenness 756where of course it's completely useless). Unlike epoll, however, whose
687is by design, these kqueue bugs can (and eventually will) be fixed 757brokenness 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 758fixed 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 759being \*(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) 760in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a
691system like NetBSD. 761known-to-be-good (\-enough) system like NetBSD.
692.Sp 762.Sp
693You still can embed kqueue into a normal poll or select backend and use it 763You 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 764only 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. 765the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
696.Sp 766.Sp
697It scales in the same way as the epoll backend, but the interface to the 767It 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 768kernel is more efficient (which says nothing about its actual speed, of
699course). While stopping, setting and starting an I/O watcher does never 769course). 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 770cause 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 771two 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 772might have to leak fds on fork, but it's more sane than epoll) and it
703drops fds silently in similarly hard-to-detect cases. 773drops fds silently in similarly hard-to-detect cases.
704.Sp 774.Sp
705This backend usually performs well under most conditions. 775This backend usually performs well under most conditions.
706.Sp 776.Sp
707While nominally embeddable in other event loops, this doesn't work 777While nominally embeddable in other event loops, this doesn't work
… …
785used if available. 855used if available.
786.Sp 856.Sp
787.Vb 1 857.Vb 1
788\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 858\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
789.Ve 859.Ve
860.Sp
861Example: Similarly, on linux, you mgiht want to take advantage of the
862linux aio backend if possible, but fall back to something else if that
863isn't available.
864.Sp
865.Vb 1
866\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
867.Ve
790.RE 868.RE
791.IP "ev_loop_destroy (loop)" 4 869.IP "ev_loop_destroy (loop)" 4
792.IX Item "ev_loop_destroy (loop)" 870.IX Item "ev_loop_destroy (loop)"
793Destroys an event loop object (frees all memory and kernel state 871Destroys an event loop object (frees all memory and kernel state
794etc.). None of the active event watchers will be stopped in the normal 872etc.). None of the active event watchers will be stopped in the normal
… …
810except in the rare occasion where you really need to free its resources. 888except in the rare occasion where you really need to free its resources.
811If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR 889If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR
812and \f(CW\*(C`ev_loop_destroy\*(C'\fR. 890and \f(CW\*(C`ev_loop_destroy\*(C'\fR.
813.IP "ev_loop_fork (loop)" 4 891.IP "ev_loop_fork (loop)" 4
814.IX Item "ev_loop_fork (loop)" 892.IX Item "ev_loop_fork (loop)"
815This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to 893This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations
816reinitialise the kernel state for backends that have one. Despite the 894to reinitialise the kernel state for backends that have one. Despite
817name, you can call it anytime, but it makes most sense after forking, in 895the name, you can call it anytime you are allowed to start or stop
818the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the 896watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
819child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 897sense after forking, in the child process. You \fImust\fR call it (or use
898\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
899.Sp
900In addition, if you want to reuse a loop (via this function or
901\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR.
820.Sp 902.Sp
821Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 903Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
822a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is 904a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
823because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things 905because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
824during fork. 906during fork.
… …
1360bug in your program. 1442bug in your program.
1361.Sp 1443.Sp
1362Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1444Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1363example it might indicate that a fd is readable or writable, and if your 1445example it might indicate that a fd is readable or writable, and if your
1364callbacks is well-written it can just attempt the operation and cope with 1446callbacks is well-written it can just attempt the operation and cope with
1365the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1447the error from \fBread()\fR or \fBwrite()\fR. This will not work in multi-threaded
1366programs, though, as the fd could already be closed and reused for another 1448programs, though, as the fd could already be closed and reused for another
1367thing, so beware. 1449thing, so beware.
1368.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" 1450.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1369.IX Subsection "GENERIC WATCHER FUNCTIONS" 1451.IX Subsection "GENERIC WATCHER FUNCTIONS"
1370.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1452.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
… …
1721But really, best use non-blocking mode. 1803But really, best use non-blocking mode.
1722.PP 1804.PP
1723\fIThe special problem of disappearing file descriptors\fR 1805\fIThe special problem of disappearing file descriptors\fR
1724.IX Subsection "The special problem of disappearing file descriptors" 1806.IX Subsection "The special problem of disappearing file descriptors"
1725.PP 1807.PP
1726Some backends (e.g. kqueue, epoll) need to be told about closing a file 1808Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1727descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1809a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1728such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1810means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1729descriptor, but when it goes away, the operating system will silently drop 1811file descriptor, but when it goes away, the operating system will silently
1730this interest. If another file descriptor with the same number then is 1812drop this interest. If another file descriptor with the same number then
1731registered with libev, there is no efficient way to see that this is, in 1813is registered with libev, there is no efficient way to see that this is,
1732fact, a different file descriptor. 1814in fact, a different file descriptor.
1733.PP 1815.PP
1734To avoid having to explicitly tell libev about such cases, libev follows 1816To avoid having to explicitly tell libev about such cases, libev follows
1735the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1817the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1736will assume that this is potentially a new file descriptor, otherwise 1818will assume that this is potentially a new file descriptor, otherwise
1737it is assumed that the file descriptor stays the same. That means that 1819it is assumed that the file descriptor stays the same. That means that
… …
1789reuse the same code path. 1871reuse the same code path.
1790.PP 1872.PP
1791\fIThe special problem of fork\fR 1873\fIThe special problem of fork\fR
1792.IX Subsection "The special problem of fork" 1874.IX Subsection "The special problem of fork"
1793.PP 1875.PP
1794Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1876Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1795useless behaviour. Libev fully supports fork, but needs to be told about 1877at all or exhibit useless behaviour. Libev fully supports fork, but needs
1796it in the child if you want to continue to use it in the child. 1878to be told about it in the child if you want to continue to use it in the
1879child.
1797.PP 1880.PP
1798To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1881To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1799()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1882()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1800\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1883\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1801.PP 1884.PP
… …
1806when writing to a pipe whose other end has been closed, your program gets 1889when writing to a pipe whose other end has been closed, your program gets
1807sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs 1890sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1808this is sensible behaviour, for daemons, this is usually undesirable. 1891this is sensible behaviour, for daemons, this is usually undesirable.
1809.PP 1892.PP
1810So when you encounter spurious, unexplained daemon exits, make sure you 1893So when you encounter spurious, unexplained daemon exits, make sure you
1811ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon 1894ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1812somewhere, as that would have given you a big clue). 1895somewhere, as that would have given you a big clue).
1813.PP 1896.PP
1814\fIThe special problem of \fIaccept()\fIing when you can't\fR 1897\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1815.IX Subsection "The special problem of accept()ing when you can't" 1898.IX Subsection "The special problem of accept()ing when you can't"
1816.PP 1899.PP
1817Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, 1900Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
1818found in post\-2004 Linux) have the peculiar behaviour of not removing a 1901found in post\-2004 Linux) have the peculiar behaviour of not removing a
1819connection from the pending queue in all error cases. 1902connection from the pending queue in all error cases.
1820.PP 1903.PP
1821For example, larger servers often run out of file descriptors (because 1904For example, larger servers often run out of file descriptors (because
1822of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not 1905of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
2161.PP 2244.PP
2162The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2245The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
2163time. This is usually the right thing as this timestamp refers to the time 2246time. This is usually the right thing as this timestamp refers to the time
2164of the event triggering whatever timeout you are modifying/starting. If 2247of the event triggering whatever timeout you are modifying/starting. If
2165you suspect event processing to be delayed and you \fIneed\fR to base the 2248you suspect event processing to be delayed and you \fIneed\fR to base the
2166timeout on the current time, use something like this to adjust for this: 2249timeout on the current time, use something like the following to adjust
2250for it:
2167.PP 2251.PP
2168.Vb 1 2252.Vb 1
2169\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.); 2253\& ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.);
2170.Ve 2254.Ve
2171.PP 2255.PP
2172If the event loop is suspended for a long time, you can also force an 2256If the event loop is suspended for a long time, you can also force an
2173update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update 2257update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2174()\*(C'\fR. 2258()\*(C'\fR, although that will push the event time of all outstanding events
2259further into the future.
2175.PP 2260.PP
2176\fIThe special problem of unsynchronised clocks\fR 2261\fIThe special problem of unsynchronised clocks\fR
2177.IX Subsection "The special problem of unsynchronised clocks" 2262.IX Subsection "The special problem of unsynchronised clocks"
2178.PP 2263.PP
2179Modern systems have a variety of clocks \- libev itself uses the normal 2264Modern systems have a variety of clocks \- libev itself uses the normal
… …
2244.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 2329.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
2245.PD 0 2330.PD 0
2246.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 2331.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
2247.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 2332.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
2248.PD 2333.PD
2249Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR 2334Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
2250is \f(CW0.\fR, then it will automatically be stopped once the timeout is 2335negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
2251reached. If it is positive, then the timer will automatically be 2336automatically be stopped once the timeout is reached. If it is positive,
2252configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, 2337then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
2253until stopped manually. 2338seconds later, again, and again, until stopped manually.
2254.Sp 2339.Sp
2255The timer itself will do a best-effort at avoiding drift, that is, if 2340The timer itself will do a best-effort at avoiding drift, that is, if
2256you configure a timer to trigger every 10 seconds, then it will normally 2341you configure a timer to trigger every 10 seconds, then it will normally
2257trigger at exactly 10 second intervals. If, however, your program cannot 2342trigger at exactly 10 second intervals. If, however, your program cannot
2258keep up with the timer (because it takes longer than those 10 seconds to 2343keep up with the timer (because it takes longer than those 10 seconds to
… …
2340Periodic watchers are also timers of a kind, but they are very versatile 2425Periodic watchers are also timers of a kind, but they are very versatile
2341(and unfortunately a bit complex). 2426(and unfortunately a bit complex).
2342.PP 2427.PP
2343Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or 2428Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or
2344relative time, the physical time that passes) but on wall clock time 2429relative time, the physical time that passes) but on wall clock time
2345(absolute time, the thing you can read on your calender or clock). The 2430(absolute time, the thing you can read on your calendar or clock). The
2346difference is that wall clock time can run faster or slower than real 2431difference is that wall clock time can run faster or slower than real
2347time, and time jumps are not uncommon (e.g. when you adjust your 2432time, and time jumps are not uncommon (e.g. when you adjust your
2348wrist-watch). 2433wrist-watch).
2349.PP 2434.PP
2350You can tell a periodic watcher to trigger after some specific point 2435You can tell a periodic watcher to trigger after some specific point
… …
2355\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting 2440\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
2356it, as it uses a relative timeout). 2441it, as it uses a relative timeout).
2357.PP 2442.PP
2358\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex 2443\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
2359timers, such as triggering an event on each \*(L"midnight, local time\*(R", or 2444timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
2360other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as 2445other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
2361those cannot react to time jumps. 2446watchers, as those cannot react to time jumps.
2362.PP 2447.PP
2363As with timers, the callback is guaranteed to be invoked only when the 2448As with timers, the callback is guaranteed to be invoked only when the
2364point in time where it is supposed to trigger has passed. If multiple 2449point in time where it is supposed to trigger has passed. If multiple
2365timers become ready during the same loop iteration then the ones with 2450timers become ready during the same loop iteration then the ones with
2366earlier time-out values are invoked before ones with later time-out values 2451earlier time-out values are invoked before ones with later time-out values
… …
2427In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2512In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
2428ignored. Instead, each time the periodic watcher gets scheduled, the 2513ignored. Instead, each time the periodic watcher gets scheduled, the
2429reschedule callback will be called with the watcher as first, and the 2514reschedule callback will be called with the watcher as first, and the
2430current time as second argument. 2515current time as second argument.
2431.Sp 2516.Sp
2432\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, 2517\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
2433or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2518or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2434allowed by documentation here\fR. 2519allowed by documentation here\fR.
2435.Sp 2520.Sp
2436If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2521If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
2437it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 2522it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2451It must return the next time to trigger, based on the passed time value 2536It must return the next time to trigger, based on the passed time value
2452(that is, the lowest time value larger than to the second argument). It 2537(that is, the lowest time value larger than to the second argument). It
2453will usually be called just before the callback will be triggered, but 2538will usually be called just before the callback will be triggered, but
2454might be called at other times, too. 2539might be called at other times, too.
2455.Sp 2540.Sp
2456\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or 2541\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
2457equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2542equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2458.Sp 2543.Sp
2459This can be used to create very complex timers, such as a timer that 2544This can be used to create very complex timers, such as a timer that
2460triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the 2545triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2461next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2546the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
2462you do this is, again, up to you (but it is not trivial, which is the main 2547this. Here is a (completely untested, no error checking) example on how to
2463reason I omitted it as an example). 2548do this:
2549.Sp
2550.Vb 1
2551\& #include <time.h>
2552\&
2553\& static ev_tstamp
2554\& my_rescheduler (ev_periodic *w, ev_tstamp now)
2555\& {
2556\& time_t tnow = (time_t)now;
2557\& struct tm tm;
2558\& localtime_r (&tnow, &tm);
2559\&
2560\& tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2561\& ++tm.tm_mday; // midnight next day
2562\&
2563\& return mktime (&tm);
2564\& }
2565.Ve
2566.Sp
2567Note: this code might run into trouble on days that have more then two
2568midnights (beginning and end).
2464.RE 2569.RE
2465.RS 4 2570.RS 4
2466.RE 2571.RE
2467.IP "ev_periodic_again (loop, ev_periodic *)" 4 2572.IP "ev_periodic_again (loop, ev_periodic *)" 4
2468.IX Item "ev_periodic_again (loop, ev_periodic *)" 2573.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
2553only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your 2658only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your
2554default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for 2659default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for
2555\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At 2660\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At
2556the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. 2661the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop.
2557.PP 2662.PP
2558When the first watcher gets started will libev actually register something 2663Only after the first watcher for a signal is started will libev actually
2559with the kernel (thus it coexists with your own signal handlers as long as 2664register something with the kernel. It thus coexists with your own signal
2560you don't register any with libev for the same signal). 2665handlers as long as you don't register any with libev for the same signal.
2561.PP 2666.PP
2562If possible and supported, libev will install its handlers with 2667If possible and supported, libev will install its handlers with
2563\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should 2668\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should
2564not be unduly interrupted. If you have a problem with system calls getting 2669not be unduly interrupted. If you have a problem with system calls getting
2565interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher 2670interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher
… …
2586The simplest way to ensure that the signal mask is reset in the child is 2691The simplest way to ensure that the signal mask is reset in the child is
2587to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will 2692to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
2588catch fork calls done by libraries (such as the libc) as well. 2693catch fork calls done by libraries (such as the libc) as well.
2589.PP 2694.PP
2590In current versions of libev, the signal will not be blocked indefinitely 2695In current versions of libev, the signal will not be blocked indefinitely
2591unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces 2696unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
2592the window of opportunity for problems, it will not go away, as libev 2697the window of opportunity for problems, it will not go away, as libev
2593\&\fIhas\fR to modify the signal mask, at least temporarily. 2698\&\fIhas\fR to modify the signal mask, at least temporarily.
2594.PP 2699.PP
2595So I can't stress this enough: \fIIf you do not reset your signal mask when 2700So I can't stress this enough: \fIIf you do not reset your signal mask when
2596you expect it to be empty, you have a race condition in your code\fR. This 2701you expect it to be empty, you have a race condition in your code\fR. This
… …
3048.IX Subsection "ev_prepare and ev_check - customise your event loop!" 3153.IX Subsection "ev_prepare and ev_check - customise your event loop!"
3049Prepare and check watchers are often (but not always) used in pairs: 3154Prepare and check watchers are often (but not always) used in pairs:
3050prepare watchers get invoked before the process blocks and check watchers 3155prepare watchers get invoked before the process blocks and check watchers
3051afterwards. 3156afterwards.
3052.PP 3157.PP
3053You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3158You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR (or similar functions that enter the
3054the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR 3159current event loop) or \f(CW\*(C`ev_loop_fork\*(C'\fR from either \f(CW\*(C`ev_prepare\*(C'\fR or
3055watchers. Other loops than the current one are fine, however. The 3160\&\f(CW\*(C`ev_check\*(C'\fR watchers. Other loops than the current one are fine,
3056rationale behind this is that you do not need to check for recursion in 3161however. The rationale behind this is that you do not need to check
3057those watchers, i.e. the sequence will always be \f(CW\*(C`ev_prepare\*(C'\fR, blocking, 3162for recursion in those watchers, i.e. the sequence will always be
3058\&\f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each kind they will always be 3163\&\f(CW\*(C`ev_prepare\*(C'\fR, blocking, \f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each
3059called in pairs bracketing the blocking call. 3164kind they will always be called in pairs bracketing the blocking call.
3060.PP 3165.PP
3061Their main purpose is to integrate other event mechanisms into libev and 3166Their main purpose is to integrate other event mechanisms into libev and
3062their use is somewhat advanced. They could be used, for example, to track 3167their use is somewhat advanced. They could be used, for example, to track
3063variable changes, implement your own watchers, integrate net-snmp or a 3168variable changes, implement your own watchers, integrate net-snmp or a
3064coroutine library and lots more. They are also occasionally useful if 3169coroutine library and lots more. They are also occasionally useful if
… …
3358.PP 3463.PP
3359.Vb 3 3464.Vb 3
3360\& struct ev_loop *loop_hi = ev_default_init (0); 3465\& struct ev_loop *loop_hi = ev_default_init (0);
3361\& struct ev_loop *loop_lo = 0; 3466\& struct ev_loop *loop_lo = 0;
3362\& ev_embed embed; 3467\& ev_embed embed;
3363\& 3468\&
3364\& // see if there is a chance of getting one that works 3469\& // see if there is a chance of getting one that works
3365\& // (remember that a flags value of 0 means autodetection) 3470\& // (remember that a flags value of 0 means autodetection)
3366\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3471\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
3367\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3472\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
3368\& : 0; 3473\& : 0;
… …
3384.PP 3489.PP
3385.Vb 3 3490.Vb 3
3386\& struct ev_loop *loop = ev_default_init (0); 3491\& struct ev_loop *loop = ev_default_init (0);
3387\& struct ev_loop *loop_socket = 0; 3492\& struct ev_loop *loop_socket = 0;
3388\& ev_embed embed; 3493\& ev_embed embed;
3389\& 3494\&
3390\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3495\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
3391\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3496\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
3392\& { 3497\& {
3393\& ev_embed_init (&embed, 0, loop_socket); 3498\& ev_embed_init (&embed, 0, loop_socket);
3394\& ev_embed_start (loop, &embed); 3499\& ev_embed_start (loop, &embed);
… …
3411of course. 3516of course.
3412.PP 3517.PP
3413\fIThe special problem of life after fork \- how is it possible?\fR 3518\fIThe special problem of life after fork \- how is it possible?\fR
3414.IX Subsection "The special problem of life after fork - how is it possible?" 3519.IX Subsection "The special problem of life after fork - how is it possible?"
3415.PP 3520.PP
3416Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3521Most uses of \f(CW\*(C`fork ()\*(C'\fR consist of forking, then some simple calls to set
3417up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This 3522up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This
3418sequence should be handled by libev without any problems. 3523sequence should be handled by libev without any problems.
3419.PP 3524.PP
3420This changes when the application actually wants to do event handling 3525This changes when the application actually wants to do event handling
3421in the child, or both parent in child, in effect \*(L"continuing\*(R" after the 3526in the child, or both parent in child, in effect \*(L"continuing\*(R" after the
… …
3638is a time window between the event loop checking and resetting the async 3743is a time window between the event loop checking and resetting the async
3639notification, and the callback being invoked. 3744notification, and the callback being invoked.
3640.SH "OTHER FUNCTIONS" 3745.SH "OTHER FUNCTIONS"
3641.IX Header "OTHER FUNCTIONS" 3746.IX Header "OTHER FUNCTIONS"
3642There are some other functions of possible interest. Described. Here. Now. 3747There are some other functions of possible interest. Described. Here. Now.
3643.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 3748.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
3644.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 3749.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
3645This function combines a simple timer and an I/O watcher, calls your 3750This function combines a simple timer and an I/O watcher, calls your
3646callback on whichever event happens first and automatically stops both 3751callback on whichever event happens first and automatically stops both
3647watchers. This is useful if you want to wait for a single event on an fd 3752watchers. This is useful if you want to wait for a single event on an fd
3648or timeout without having to allocate/configure/start/stop/free one or 3753or timeout without having to allocate/configure/start/stop/free one or
3649more watchers yourself. 3754more watchers yourself.
… …
4049files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4154files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
4050.PP 4155.PP
4051.Vb 4 4156.Vb 4
4052\& // my_ev.h 4157\& // my_ev.h
4053\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4158\& #define EV_CB_DECLARE(type) struct my_coro *cb;
4054\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb); 4159\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb)
4055\& #include "../libev/ev.h" 4160\& #include "../libev/ev.h"
4056\& 4161\&
4057\& // my_ev.c 4162\& // my_ev.c
4058\& #define EV_H "my_ev.h" 4163\& #define EV_H "my_ev.h"
4059\& #include "../libev/ev.c" 4164\& #include "../libev/ev.c"
… …
4099The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the 4204The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4100libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4205libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4101will work fine. 4206will work fine.
4102.PP 4207.PP
4103Proper exception specifications might have to be added to callbacks passed 4208Proper exception specifications might have to be added to callbacks passed
4104to libev: exceptions may be thrown only from watcher callbacks, all 4209to libev: exceptions may be thrown only from watcher callbacks, all other
4105other callbacks (allocator, syserr, loop acquire/release and periodic 4210callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4106reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4211callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
4107()\*(C'\fR specification. If you have code that needs to be compiled as both C 4212specification. If you have code that needs to be compiled as both C and
4108and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4213\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
4109.PP 4214.PP
4110.Vb 6 4215.Vb 6
4111\& static void 4216\& static void
4112\& fatal_error (const char *msg) EV_THROW 4217\& fatal_error (const char *msg) EV_NOEXCEPT
4113\& { 4218\& {
4114\& perror (msg); 4219\& perror (msg);
4115\& abort (); 4220\& abort ();
4116\& } 4221\& }
4117\& 4222\&
… …
4245\& void operator() (ev::io &w, int revents) 4350\& void operator() (ev::io &w, int revents)
4246\& { 4351\& {
4247\& ... 4352\& ...
4248\& } 4353\& }
4249\& } 4354\& }
4250\& 4355\&
4251\& myfunctor f; 4356\& myfunctor f;
4252\& 4357\&
4253\& ev::io w; 4358\& ev::io w;
4254\& w.set (&f); 4359\& w.set (&f);
4255.Ve 4360.Ve
… …
4491\& #include "ev.c" 4596\& #include "ev.c"
4492.Ve 4597.Ve
4493.PP 4598.PP
4494This will automatically include \fIev.h\fR, too, and should be done in a 4599This will automatically include \fIev.h\fR, too, and should be done in a
4495single C source file only to provide the function implementations. To use 4600single C source file only to provide the function implementations. To use
4496it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best 4601it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
4497done by writing a wrapper around \fIev.h\fR that you can include instead and 4602done by writing a wrapper around \fIev.h\fR that you can include instead and
4498where you can put other configuration options): 4603where you can put other configuration options):
4499.PP 4604.PP
4500.Vb 2 4605.Vb 2
4501\& #define EV_STANDALONE 1 4606\& #define EV_STANDALONE 1
… …
4515\& ev_vars.h 4620\& ev_vars.h
4516\& ev_wrap.h 4621\& ev_wrap.h
4517\& 4622\&
4518\& ev_win32.c required on win32 platforms only 4623\& ev_win32.c required on win32 platforms only
4519\& 4624\&
4520\& ev_select.c only when select backend is enabled (which is enabled by default) 4625\& ev_select.c only when select backend is enabled
4521\& ev_poll.c only when poll backend is enabled (disabled by default) 4626\& ev_poll.c only when poll backend is enabled
4522\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 4627\& ev_epoll.c only when the epoll backend is enabled
4628\& ev_linuxaio.c only when the linux aio backend is enabled
4629\& ev_iouring.c only when the linux io_uring backend is enabled
4523\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4630\& ev_kqueue.c only when the kqueue backend is enabled
4524\& ev_port.c only when the solaris port backend is enabled (disabled by default) 4631\& ev_port.c only when the solaris port backend is enabled
4525.Ve 4632.Ve
4526.PP 4633.PP
4527\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4634\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4528to compile this single file. 4635to compile this single file.
4529.PP 4636.PP
… …
4574values when compiling libev vs. including \fIev.h\fR, so it is permissible 4681values when compiling libev vs. including \fIev.h\fR, so it is permissible
4575to redefine them before including \fIev.h\fR without breaking compatibility 4682to redefine them before including \fIev.h\fR without breaking compatibility
4576to a compiled library. All other symbols change the \s-1ABI,\s0 which means all 4683to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4577users of libev and the libev code itself must be compiled with compatible 4684users of libev and the libev code itself must be compiled with compatible
4578settings. 4685settings.
4579.IP "\s-1EV_COMPAT3 \s0(h)" 4 4686.IP "\s-1EV_COMPAT3\s0 (h)" 4
4580.IX Item "EV_COMPAT3 (h)" 4687.IX Item "EV_COMPAT3 (h)"
4581Backwards compatibility is a major concern for libev. This is why this 4688Backwards compatibility is a major concern for libev. This is why this
4582release of libev comes with wrappers for the functions and symbols that 4689release of libev comes with wrappers for the functions and symbols that
4583have been renamed between libev version 3 and 4. 4690have been renamed between libev version 3 and 4.
4584.Sp 4691.Sp
… …
4589typedef in that case. 4696typedef in that case.
4590.Sp 4697.Sp
4591In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4698In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4592and in some even more future version the compatibility code will be 4699and in some even more future version the compatibility code will be
4593removed completely. 4700removed completely.
4594.IP "\s-1EV_STANDALONE \s0(h)" 4 4701.IP "\s-1EV_STANDALONE\s0 (h)" 4
4595.IX Item "EV_STANDALONE (h)" 4702.IX Item "EV_STANDALONE (h)"
4596Must always be \f(CW1\fR if you do not use autoconf configuration, which 4703Must always be \f(CW1\fR if you do not use autoconf configuration, which
4597keeps libev from including \fIconfig.h\fR, and it also defines dummy 4704keeps libev from including \fIconfig.h\fR, and it also defines dummy
4598implementations for some libevent functions (such as logging, which is not 4705implementations for some libevent functions (such as logging, which is not
4599supported). It will also not define any of the structs usually found in 4706supported). It will also not define any of the structs usually found in
… …
4708If defined to be \f(CW1\fR, libev will compile in support for the Linux 4815If defined to be \f(CW1\fR, libev will compile in support for the Linux
4709\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4816\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4710otherwise another method will be used as fallback. This is the preferred 4817otherwise another method will be used as fallback. This is the preferred
4711backend for GNU/Linux systems. If undefined, it will be enabled if the 4818backend for GNU/Linux systems. If undefined, it will be enabled if the
4712headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4819headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4820.IP "\s-1EV_USE_LINUXAIO\s0" 4
4821.IX Item "EV_USE_LINUXAIO"
4822If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4823backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4824enabled on linux, otherwise disabled.
4825.IP "\s-1EV_USE_IOURING\s0" 4
4826.IX Item "EV_USE_IOURING"
4827If defined to be \f(CW1\fR, libev will compile in support for the Linux
4828io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4829current limitations it has to be requested explicitly. If undefined, it
4830will be enabled on linux, otherwise disabled.
4713.IP "\s-1EV_USE_KQUEUE\s0" 4 4831.IP "\s-1EV_USE_KQUEUE\s0" 4
4714.IX Item "EV_USE_KQUEUE" 4832.IX Item "EV_USE_KQUEUE"
4715If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4833If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4716\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4834\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4717otherwise another method will be used as fallback. This is the preferred 4835otherwise another method will be used as fallback. This is the preferred
… …
4757handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR 4875handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4758watchers. 4876watchers.
4759.Sp 4877.Sp
4760In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4878In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4761(from \fIsignal.h\fR), which is usually good enough on most platforms. 4879(from \fIsignal.h\fR), which is usually good enough on most platforms.
4762.IP "\s-1EV_H \s0(h)" 4 4880.IP "\s-1EV_H\s0 (h)" 4
4763.IX Item "EV_H (h)" 4881.IX Item "EV_H (h)"
4764The name of the \fIev.h\fR header file used to include it. The default if 4882The name of the \fIev.h\fR header file used to include it. The default if
4765undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4883undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4766used to virtually rename the \fIev.h\fR header file in case of conflicts. 4884used to virtually rename the \fIev.h\fR header file in case of conflicts.
4767.IP "\s-1EV_CONFIG_H \s0(h)" 4 4885.IP "\s-1EV_CONFIG_H\s0 (h)" 4
4768.IX Item "EV_CONFIG_H (h)" 4886.IX Item "EV_CONFIG_H (h)"
4769If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4887If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4770\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4888\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4771\&\f(CW\*(C`EV_H\*(C'\fR, above. 4889\&\f(CW\*(C`EV_H\*(C'\fR, above.
4772.IP "\s-1EV_EVENT_H \s0(h)" 4 4890.IP "\s-1EV_EVENT_H\s0 (h)" 4
4773.IX Item "EV_EVENT_H (h)" 4891.IX Item "EV_EVENT_H (h)"
4774Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4892Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4775of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4893of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4776.IP "\s-1EV_PROTOTYPES \s0(h)" 4 4894.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
4777.IX Item "EV_PROTOTYPES (h)" 4895.IX Item "EV_PROTOTYPES (h)"
4778If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4896If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4779prototypes, but still define all the structs and other symbols. This is 4897prototypes, but still define all the structs and other symbols. This is
4780occasionally useful if you want to provide your own wrapper functions 4898occasionally useful if you want to provide your own wrapper functions
4781around libev functions. 4899around libev functions.
… …
4974called. If set to \f(CW2\fR, then the internal verification code will be 5092called. If set to \f(CW2\fR, then the internal verification code will be
4975called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5093called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
4976verification code will be called very frequently, which will slow down 5094verification code will be called very frequently, which will slow down
4977libev considerably. 5095libev considerably.
4978.Sp 5096.Sp
5097Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5098disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5099.Sp
4979The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5100The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
4980will be \f(CW0\fR. 5101will be \f(CW0\fR.
4981.IP "\s-1EV_COMMON\s0" 4 5102.IP "\s-1EV_COMMON\s0" 4
4982.IX Item "EV_COMMON" 5103.IX Item "EV_COMMON"
4983By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 5104By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
… …
4990.Vb 3 5111.Vb 3
4991\& #define EV_COMMON \e 5112\& #define EV_COMMON \e
4992\& SV *self; /* contains this struct */ \e 5113\& SV *self; /* contains this struct */ \e
4993\& SV *cb_sv, *fh /* note no trailing ";" */ 5114\& SV *cb_sv, *fh /* note no trailing ";" */
4994.Ve 5115.Ve
4995.IP "\s-1EV_CB_DECLARE \s0(type)" 4 5116.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
4996.IX Item "EV_CB_DECLARE (type)" 5117.IX Item "EV_CB_DECLARE (type)"
4997.PD 0 5118.PD 0
4998.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4 5119.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
4999.IX Item "EV_CB_INVOKE (watcher, revents)" 5120.IX Item "EV_CB_INVOKE (watcher, revents)"
5000.IP "ev_set_cb (ev, cb)" 4 5121.IP "ev_set_cb (ev, cb)" 4
5001.IX Item "ev_set_cb (ev, cb)" 5122.IX Item "ev_set_cb (ev, cb)"
5002.PD 5123.PD
5003Can be used to change the callback member declaration in each watcher, 5124Can be used to change the callback member declaration in each watcher,
… …
5006their default definitions. One possible use for overriding these is to 5127their default definitions. One possible use for overriding these is to
5007avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5128avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
5008method calls instead of plain function calls in \*(C+. 5129method calls instead of plain function calls in \*(C+.
5009.SS "\s-1EXPORTED API SYMBOLS\s0" 5130.SS "\s-1EXPORTED API SYMBOLS\s0"
5010.IX Subsection "EXPORTED API SYMBOLS" 5131.IX Subsection "EXPORTED API SYMBOLS"
5011If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of 5132If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5012exported symbols, you can use the provided \fISymbol.*\fR files which list 5133exported symbols, you can use the provided \fISymbol.*\fR files which list
5013all public symbols, one per line: 5134all public symbols, one per line:
5014.PP 5135.PP
5015.Vb 2 5136.Vb 2
5016\& Symbols.ev for libev proper 5137\& Symbols.ev for libev proper
… …
5248.PP 5369.PP
5249\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5370\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5250.IX Subsection "select is buggy" 5371.IX Subsection "select is buggy"
5251.PP 5372.PP
5252All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5373All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5253one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file 5374one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5254descriptors you can pass in to 1024 \- your program suddenly crashes when 5375descriptors you can pass in to 1024 \- your program suddenly crashes when
5255you use more. 5376you use more.
5256.PP 5377.PP
5257There is an undocumented \*(L"workaround\*(R" for this \- defining 5378There is an undocumented \*(L"workaround\*(R" for this \- defining
5258\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5379\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
… …
5406Libev assumes not only that all watcher pointers have the same internal 5527Libev assumes not only that all watcher pointers have the same internal
5407structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also 5528structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5408assumes that the same (machine) code can be used to call any watcher 5529assumes that the same (machine) code can be used to call any watcher
5409callback: The watcher callbacks have different type signatures, but libev 5530callback: The watcher callbacks have different type signatures, but libev
5410calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5531calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5532.IP "null pointers and integer zero are represented by 0 bytes" 4
5533.IX Item "null pointers and integer zero are represented by 0 bytes"
5534Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
5535relies on this setting pointers and integers to null.
5411.IP "pointer accesses must be thread-atomic" 4 5536.IP "pointer accesses must be thread-atomic" 4
5412.IX Item "pointer accesses must be thread-atomic" 5537.IX Item "pointer accesses must be thread-atomic"
5413Accessing a pointer value must be atomic, it must both be readable and 5538Accessing a pointer value must be atomic, it must both be readable and
5414writable in one piece \- this is the case on all current architectures. 5539writable in one piece \- this is the case on all current architectures.
5415.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 5540.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4

Diff Legend

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