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

Comparing libev/ev.3 (file contents):
Revision 1.99 by root, Mon Jun 10 00:14:23 2013 UTC vs.
Revision 1.115 by root, Wed Jun 26 00:01:46 2019 UTC

1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) 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
… …
36.el\{\ 36.el\{\
37. ds -- \|\(em\| 37. ds -- \|\(em\|
38. ds PI \(*p 38. ds PI \(*p
39. ds L" `` 39. ds L" ``
40. ds R" '' 40. ds R" ''
41. ds C`
42. ds C'
41'br\} 43'br\}
42.\" 44.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform. 45.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq 46.ie \n(.g .ds Aq \(aq
45.el .ds Aq ' 47.el .ds Aq '
46.\" 48.\"
47.\" 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
48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49.\" 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
50.\" output yourself in some meaningful fashion. 52.\" output yourself in some meaningful fashion.
51.ie \nF \{\ 53.\"
54.\" Avoid warning from groff about undefined register 'F'.
52. de IX 55.de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
54.. 56..
55. nr % 0 57.nr rF 0
56. rr F 58.if \n(.g .if rF .nr rF 1
59.if (\n(rF:(\n(.g==0)) \{\
60. if \nF \{\
61. de IX
62. tm Index:\\$1\t\\n%\t"\\$2"
63..
64. if !\nF==2 \{\
65. nr % 0
66. nr F 2
67. \}
68. \}
57.\} 69.\}
58.el \{\ 70.rr rF
59. de IX
60..
61.\}
62.\" 71.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 72.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts. 73.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff 74. \" fudge factors for nroff and troff
66.if n \{\ 75.if n \{\
… …
122.\} 131.\}
123.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
124.\" ======================================================================== 133.\" ========================================================================
125.\" 134.\"
126.IX Title "LIBEV 3" 135.IX Title "LIBEV 3"
127.TH LIBEV 3 "2013-06-07" "libev-4.15" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-06-25" "libev-4.25" "libev - high performance full featured event loop"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
130.if n .ad l 139.if n .ad l
131.nh 140.nh
132.SH "NAME" 141.SH "NAME"
… …
134.SH "SYNOPSIS" 143.SH "SYNOPSIS"
135.IX Header "SYNOPSIS" 144.IX Header "SYNOPSIS"
136.Vb 1 145.Vb 1
137\& #include <ev.h> 146\& #include <ev.h>
138.Ve 147.Ve
139.SS "\s-1EXAMPLE\s0 \s-1PROGRAM\s0" 148.SS "\s-1EXAMPLE PROGRAM\s0"
140.IX Subsection "EXAMPLE PROGRAM" 149.IX Subsection "EXAMPLE PROGRAM"
141.Vb 2 150.Vb 2
142\& // a single header file is required 151\& // a single header file is required
143\& #include <ev.h> 152\& #include <ev.h>
144\& 153\&
… …
212throughout this document. 221throughout this document.
213.SH "WHAT TO READ WHEN IN A HURRY" 222.SH "WHAT TO READ WHEN IN A HURRY"
214.IX Header "WHAT TO READ WHEN IN A HURRY" 223.IX Header "WHAT TO READ WHEN IN A HURRY"
215This manual tries to be very detailed, but unfortunately, this also makes 224This manual tries to be very detailed, but unfortunately, this also makes
216it very long. If you just want to know the basics of libev, I suggest 225it very long. If you just want to know the basics of libev, I suggest
217reading \*(L"\s-1ANATOMY\s0 \s-1OF\s0 A \s-1WATCHER\s0\*(R", then the \*(L"\s-1EXAMPLE\s0 \s-1PROGRAM\s0\*(R" above and 226reading \*(L"\s-1ANATOMY OF A WATCHER\*(R"\s0, then the \*(L"\s-1EXAMPLE PROGRAM\*(R"\s0 above and
218look up the missing functions in \*(L"\s-1GLOBAL\s0 \s-1FUNCTIONS\s0\*(R" and the \f(CW\*(C`ev_io\*(C'\fR and 227look up the missing functions in \*(L"\s-1GLOBAL FUNCTIONS\*(R"\s0 and the \f(CW\*(C`ev_io\*(C'\fR and
219\&\f(CW\*(C`ev_timer\*(C'\fR sections in \*(L"\s-1WATCHER\s0 \s-1TYPES\s0\*(R". 228\&\f(CW\*(C`ev_timer\*(C'\fR sections in \*(L"\s-1WATCHER TYPES\*(R"\s0.
220.SH "ABOUT LIBEV" 229.SH "ABOUT LIBEV"
221.IX Header "ABOUT LIBEV" 230.IX Header "ABOUT LIBEV"
222Libev is an event loop: you register interest in certain events (such as a 231Libev is an event loop: you register interest in certain events (such as a
223file descriptor being readable or a timeout occurring), and it will manage 232file descriptor being readable or a timeout occurring), and it will manage
224these event sources and provide your program with events. 233these event sources and provide your program with events.
… …
231watchers\fR, which are relatively small C structures you initialise with the 240watchers\fR, which are relatively small C structures you initialise with the
232details 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
233watcher. 242watcher.
234.SS "\s-1FEATURES\s0" 243.SS "\s-1FEATURES\s0"
235.IX Subsection "FEATURES" 244.IX Subsection "FEATURES"
236Libev 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
237BSD-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
238for 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
239(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
240inter-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
241timers (\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
242(\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
243change 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
244loop 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
… …
255more info about various configuration options please have a look at 264more info about various configuration options please have a look at
256\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support 265\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support
257for multiple event loops, then all functions taking an initial argument of 266for multiple event loops, then all functions taking an initial argument of
258name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have 267name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have
259this argument. 268this argument.
260.SS "\s-1TIME\s0 \s-1REPRESENTATION\s0" 269.SS "\s-1TIME REPRESENTATION\s0"
261.IX Subsection "TIME REPRESENTATION" 270.IX Subsection "TIME REPRESENTATION"
262Libev represents time as a single floating point number, representing 271Libev represents time as a single floating point number, representing
263the (fractional) number of seconds since the (\s-1POSIX\s0) epoch (in practice 272the (fractional) number of seconds since the (\s-1POSIX\s0) epoch (in practice
264somewhere near the beginning of 1970, details are complicated, don't 273somewhere near the beginning of 1970, details are complicated, don't
265ask). This type is called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use 274ask). This type is called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use
… …
282When 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
283it 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,
284so \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
285the libev caller and need to be fixed there. 294the libev caller and need to be fixed there.
286.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
287Libev 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
288extensive consistency checking code. These do not trigger under normal
289circumstances, as they indicate either a bug in libev or worse. 301trigger under normal circumstances, as they indicate either a bug in libev
302or worse.
290.SH "GLOBAL FUNCTIONS" 303.SH "GLOBAL FUNCTIONS"
291.IX Header "GLOBAL FUNCTIONS" 304.IX Header "GLOBAL FUNCTIONS"
292These functions can be called anytime, even before initialising the 305These functions can be called anytime, even before initialising the
293library in any way. 306library in any way.
294.IP "ev_tstamp ev_time ()" 4 307.IP "ev_tstamp ev_time ()" 4
… …
383.Sp 396.Sp
384You could override this function in high-availability programs to, say, 397You could override this function in high-availability programs to, say,
385free 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,
386or 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.
387.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
388Example: 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
389retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR). 418retries.
390.Sp 419.Sp
391.Vb 6 420.Vb 8
392\& static void * 421\& static void *
393\& persistent_realloc (void *ptr, size_t size) 422\& persistent_realloc (void *ptr, size_t size)
394\& { 423\& {
424\& if (!size)
425\& {
426\& free (ptr);
427\& return 0;
428\& }
429\&
395\& for (;;) 430\& for (;;)
396\& { 431\& {
397\& void *newptr = realloc (ptr, size); 432\& void *newptr = realloc (ptr, size);
398\& 433\&
399\& if (newptr) 434\& if (newptr)
… …
527make 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.
528.Sp 563.Sp
529This 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,
530and 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
531iterations and little real work, but is usually not noticeable (on my 566iterations and little real work, but is usually not noticeable (on my
532GNU/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
533without 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
534\&\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).
535.Sp 571.Sp
536The 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
537forget about forgetting to tell libev about forking) when you use this 573forget about forgetting to tell libev about forking, although you still
538flag. 574have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
539.Sp 575.Sp
540This 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
541environment variable. 577environment variable.
542.ie n .IP """EVFLAG_NOINOTIFY""" 4 578.ie n .IP """EVFLAG_NOINOTIFY""" 4
543.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 579.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
… …
574\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. 610\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
575.Sp 611.Sp
576This 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.
577.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 613.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
578.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
579.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 615.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
580This 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
581libev 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,
582but 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
583using 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
584usually the fastest backend for a low number of (low-numbered :) fds. 620usually the fastest backend for a low number of (low-numbered :) fds.
585.Sp 621.Sp
… …
593This backend maps \f(CW\*(C`EV_READ\*(C'\fR to the \f(CW\*(C`readfds\*(C'\fR set and \f(CW\*(C`EV_WRITE\*(C'\fR to the 629This backend maps \f(CW\*(C`EV_READ\*(C'\fR to the \f(CW\*(C`readfds\*(C'\fR set and \f(CW\*(C`EV_WRITE\*(C'\fR to the
594\&\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
595\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). 631\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
596.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
597.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
598.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)"
599And 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
600than select, but handles sparse fds better and has no artificial 636than select, but handles sparse fds better and has no artificial
601limit 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
602considerably with a lot of inactive fds). It scales similarly to select, 638considerably with a lot of inactive fds). It scales similarly to select,
603i.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
604performance tips. 640performance tips.
605.Sp 641.Sp
606This 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
607\&\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.
608.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 644.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
609.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 645.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
610.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 646.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
611Use 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
612kernels). 648kernels).
613.Sp 649.Sp
614For 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
615it scales phenomenally better. While poll and select usually scale like 651it scales phenomenally better. While poll and select usually scale like
616O(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
… …
662All 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
663faster 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
664the usage. So sad. 700the usage. So sad.
665.Sp 701.Sp
666While nominally embeddable in other event loops, this feature is broken in 702While nominally embeddable in other event loops, this feature is broken in
667all 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.
668.Sp 747.Sp
669This 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
670\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 749\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
671.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
672.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
673.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 752.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
674Kqueue deserves special mention, as at the time of this writing, it 753Kqueue deserves special mention, as at the time this backend was
675was 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
676with anything but sockets and pipes, except on Darwin, where of course 755work reliably with anything but sockets and pipes, except on Darwin,
677it's completely useless). Unlike epoll, however, whose brokenness 756where of course it's completely useless). Unlike epoll, however, whose
678is by design, these kqueue bugs can (and eventually will) be fixed 757brokenness is by design, these kqueue bugs can be (and mostly have been)
679without \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
680\&\*(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
681\&\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
682system like NetBSD. 761known-to-be-good (\-enough) system like NetBSD.
683.Sp 762.Sp
684You 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
685only 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
686the 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.
687.Sp 766.Sp
688It 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
689kernel is more efficient (which says nothing about its actual speed, of 768kernel is more efficient (which says nothing about its actual speed, of
690course). While stopping, setting and starting an I/O watcher does never 769course). While stopping, setting and starting an I/O watcher does never
691cause 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
692two 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
693might 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
694drops fds silently in similarly hard-to-detect cases. 773drops fds silently in similarly hard-to-detect cases.
695.Sp 774.Sp
696This backend usually performs well under most conditions. 775This backend usually performs well under most conditions.
697.Sp 776.Sp
698While nominally embeddable in other event loops, this doesn't work 777While nominally embeddable in other event loops, this doesn't work
699everywhere, so you might need to test for this. And since it is broken 778everywhere, so you might need to test for this. And since it is broken
700almost everywhere, you should only use it when you have a lot of sockets 779almost everywhere, you should only use it when you have a lot of sockets
701(for which it usually works), by embedding it into another event loop 780(for which it usually works), by embedding it into another event loop
702(e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR (but \f(CW\*(C`poll\*(C'\fR is of course 781(e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR (but \f(CW\*(C`poll\*(C'\fR is of course
703also broken on \s-1OS\s0 X)) and, did I mention it, using it only for sockets. 782also broken on \s-1OS X\s0)) and, did I mention it, using it only for sockets.
704.Sp 783.Sp
705This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with 784This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with
706\&\f(CW\*(C`NOTE_EOF\*(C'\fR, and \f(CW\*(C`EV_WRITE\*(C'\fR into an \f(CW\*(C`EVFILT_WRITE\*(C'\fR kevent with 785\&\f(CW\*(C`NOTE_EOF\*(C'\fR, and \f(CW\*(C`EV_WRITE\*(C'\fR into an \f(CW\*(C`EVFILT_WRITE\*(C'\fR kevent with
707\&\f(CW\*(C`NOTE_EOF\*(C'\fR. 786\&\f(CW\*(C`NOTE_EOF\*(C'\fR.
708.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 787.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
… …
712implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets 791implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets
713and is not embeddable, which would limit the usefulness of this backend 792and is not embeddable, which would limit the usefulness of this backend
714immensely. 793immensely.
715.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 794.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
716.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 795.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
717.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" 796.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
718This uses the Solaris 10 event port mechanism. As with everything on Solaris, 797This uses the Solaris 10 event port mechanism. As with everything on Solaris,
719it's really slow, but it still scales very well (O(active_fds)). 798it's really slow, but it still scales very well (O(active_fds)).
720.Sp 799.Sp
721While this backend scales well, it requires one system call per active 800While this backend scales well, it requires one system call per active
722file descriptor per loop iteration. For small and medium numbers of file 801file descriptor per loop iteration. For small and medium numbers of file
… …
776used if available. 855used if available.
777.Sp 856.Sp
778.Vb 1 857.Vb 1
779\& 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);
780.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
781.RE 868.RE
782.IP "ev_loop_destroy (loop)" 4 869.IP "ev_loop_destroy (loop)" 4
783.IX Item "ev_loop_destroy (loop)" 870.IX Item "ev_loop_destroy (loop)"
784Destroys an event loop object (frees all memory and kernel state 871Destroys an event loop object (frees all memory and kernel state
785etc.). 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
… …
801except 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.
802If 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
803and \f(CW\*(C`ev_loop_destroy\*(C'\fR. 890and \f(CW\*(C`ev_loop_destroy\*(C'\fR.
804.IP "ev_loop_fork (loop)" 4 891.IP "ev_loop_fork (loop)" 4
805.IX Item "ev_loop_fork (loop)" 892.IX Item "ev_loop_fork (loop)"
806This 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
807reinitialise the kernel state for backends that have one. Despite the 894to reinitialise the kernel state for backends that have one. Despite
808name, 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
809the 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
810child 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.
811.Sp 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.
902.Sp
812Again, 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
813a 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
814because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things 905because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
815during fork. 906during fork.
816.Sp 907.Sp
817On the other hand, you only need to call this function in the child 908On the other hand, you only need to call this function in the child
… …
1351bug in your program. 1442bug in your program.
1352.Sp 1443.Sp
1353Libev 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
1354example 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
1355callbacks 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
1356the 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
1357programs, 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
1358thing, so beware. 1449thing, so beware.
1359.SS "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" 1450.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1360.IX Subsection "GENERIC WATCHER FUNCTIONS" 1451.IX Subsection "GENERIC WATCHER FUNCTIONS"
1361.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1452.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
1362.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 1453.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
1363.IX Item "ev_init (ev_TYPE *watcher, callback)" 1454.IX Item "ev_init (ev_TYPE *watcher, callback)"
1364This macro initialises the generic portion of a watcher. The contents 1455This macro initialises the generic portion of a watcher. The contents
… …
1472or might not have been clamped to the valid range. 1563or might not have been clamped to the valid range.
1473.Sp 1564.Sp
1474The default priority used by watchers when no priority has been set is 1565The default priority used by watchers when no priority has been set is
1475always \f(CW0\fR, which is supposed to not be too high and not be too low :). 1566always \f(CW0\fR, which is supposed to not be too high and not be too low :).
1476.Sp 1567.Sp
1477See \*(L"\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0\*(R", below, for a more thorough treatment of 1568See \*(L"\s-1WATCHER PRIORITY MODELS\*(R"\s0, below, for a more thorough treatment of
1478priorities. 1569priorities.
1479.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 1570.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
1480.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" 1571.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)"
1481Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither 1572Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither
1482\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback 1573\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback
… …
1502not started in the first place. 1593not started in the first place.
1503.Sp 1594.Sp
1504See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related 1595See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related
1505functions that do not need a watcher. 1596functions that do not need a watcher.
1506.PP 1597.PP
1507See also the \*(L"\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0\*(R" and \*(L"\s-1BUILDING\s0 \s-1YOUR\s0 1598See also the \*(L"\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\*(R"\s0 and \*(L"\s-1BUILDING YOUR
1508\&\s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0\*(R" idioms. 1599OWN COMPOSITE WATCHERS\*(R"\s0 idioms.
1509.SS "\s-1WATCHER\s0 \s-1STATES\s0" 1600.SS "\s-1WATCHER STATES\s0"
1510.IX Subsection "WATCHER STATES" 1601.IX Subsection "WATCHER STATES"
1511There are various watcher states mentioned throughout this manual \- 1602There are various watcher states mentioned throughout this manual \-
1512active, pending and so on. In this section these states and the rules to 1603active, pending and so on. In this section these states and the rules to
1513transition between them will be described in more detail \- and while these 1604transition between them will be described in more detail \- and while these
1514rules might look complicated, they usually do \*(L"the right thing\*(R". 1605rules might look complicated, they usually do \*(L"the right thing\*(R".
… …
1557.Sp 1648.Sp
1558While stopped (and not pending) the watcher is essentially in the 1649While stopped (and not pending) the watcher is essentially in the
1559initialised state, that is, it can be reused, moved, modified in any way 1650initialised state, that is, it can be reused, moved, modified in any way
1560you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR 1651you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR
1561it again). 1652it again).
1562.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" 1653.SS "\s-1WATCHER PRIORITY MODELS\s0"
1563.IX Subsection "WATCHER PRIORITY MODELS" 1654.IX Subsection "WATCHER PRIORITY MODELS"
1564Many event loops support \fIwatcher priorities\fR, which are usually small 1655Many event loops support \fIwatcher priorities\fR, which are usually small
1565integers that influence the ordering of event callback invocation 1656integers that influence the ordering of event callback invocation
1566between watchers in some way, all else being equal. 1657between watchers in some way, all else being equal.
1567.PP 1658.PP
… …
1712But really, best use non-blocking mode. 1803But really, best use non-blocking mode.
1713.PP 1804.PP
1714\fIThe special problem of disappearing file descriptors\fR 1805\fIThe special problem of disappearing file descriptors\fR
1715.IX Subsection "The special problem of disappearing file descriptors" 1806.IX Subsection "The special problem of disappearing file descriptors"
1716.PP 1807.PP
1717Some 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
1718descriptor (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
1719such 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
1720descriptor, but when it goes away, the operating system will silently drop 1811file descriptor, but when it goes away, the operating system will silently
1721this interest. If another file descriptor with the same number then is 1812drop this interest. If another file descriptor with the same number then
1722registered 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,
1723fact, a different file descriptor. 1814in fact, a different file descriptor.
1724.PP 1815.PP
1725To avoid having to explicitly tell libev about such cases, libev follows 1816To avoid having to explicitly tell libev about such cases, libev follows
1726the 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
1727will assume that this is potentially a new file descriptor, otherwise 1818will assume that this is potentially a new file descriptor, otherwise
1728it 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
… …
1765wish to read \- you would first have to request some data. 1856wish to read \- you would first have to request some data.
1766.PP 1857.PP
1767Since files are typically not-so-well supported by advanced notification 1858Since files are typically not-so-well supported by advanced notification
1768mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect 1859mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect
1769to files, even though you should not use it. The reason for this is 1860to files, even though you should not use it. The reason for this is
1770convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT\s0, which is 1861convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT,\s0 which is
1771usually a tty, often a pipe, but also sometimes files or special devices 1862usually a tty, often a pipe, but also sometimes files or special devices
1772(for example, \f(CW\*(C`epoll\*(C'\fR on Linux works with \fI/dev/random\fR but not with 1863(for example, \f(CW\*(C`epoll\*(C'\fR on Linux works with \fI/dev/random\fR but not with
1773\&\fI/dev/urandom\fR), and even though the file might better be served with 1864\&\fI/dev/urandom\fR), and even though the file might better be served with
1774asynchronous I/O instead of with non-blocking I/O, it is still useful when 1865asynchronous I/O instead of with non-blocking I/O, it is still useful when
1775it \*(L"just works\*(R" instead of freezing. 1866it \*(L"just works\*(R" instead of freezing.
1776.PP 1867.PP
1777So avoid file descriptors pointing to files when you know it (e.g. use 1868So avoid file descriptors pointing to files when you know it (e.g. use
1778libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT\s0, or 1869libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT,\s0 or
1779when you rarely read from a file instead of from a socket, and want to 1870when you rarely read from a file instead of from a socket, and want to
1780reuse the same code path. 1871reuse the same code path.
1781.PP 1872.PP
1782\fIThe special problem of fork\fR 1873\fIThe special problem of fork\fR
1783.IX Subsection "The special problem of fork" 1874.IX Subsection "The special problem of fork"
1784.PP 1875.PP
1785Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1876Some backends (epoll, kqueue, probably linuxaio) do not support \f(CW\*(C`fork ()\*(C'\fR
1786useless behaviour. Libev fully supports fork, but needs to be told about 1877at all or exhibit useless behaviour. Libev fully supports fork, but needs
1787it 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.
1788.PP 1880.PP
1789To 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
1790()\*(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
1791\&\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.
1792.PP 1884.PP
1793\fIThe special problem of \s-1SIGPIPE\s0\fR 1885\fIThe special problem of \s-1SIGPIPE\s0\fR
1794.IX Subsection "The special problem of SIGPIPE" 1886.IX Subsection "The special problem of SIGPIPE"
1795.PP 1887.PP
1796While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR: 1888While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR:
1797when 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
1798sent 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
1799this is sensible behaviour, for daemons, this is usually undesirable. 1891this is sensible behaviour, for daemons, this is usually undesirable.
1800.PP 1892.PP
1801So when you encounter spurious, unexplained daemon exits, make sure you 1893So when you encounter spurious, unexplained daemon exits, make sure you
1802ignore \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
1803somewhere, as that would have given you a big clue). 1895somewhere, as that would have given you a big clue).
1804.PP 1896.PP
1805\fIThe special problem of \fIaccept()\fIing when you can't\fR 1897\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1806.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"
1807.PP 1899.PP
1808Many 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,
1809found 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
1810connection from the pending queue in all error cases. 1902connection from the pending queue in all error cases.
… …
2152.PP 2244.PP
2153The 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
2154time. 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
2155of the event triggering whatever timeout you are modifying/starting. If 2247of the event triggering whatever timeout you are modifying/starting. If
2156you 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
2157timeout 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:
2158.PP 2251.PP
2159.Vb 1 2252.Vb 1
2160\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.); 2253\& ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.);
2161.Ve 2254.Ve
2162.PP 2255.PP
2163If 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
2164update 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
2165()\*(C'\fR. 2258()\*(C'\fR, although that will push the event time of all outstanding events
2259further into the future.
2166.PP 2260.PP
2167\fIThe special problem of unsynchronised clocks\fR 2261\fIThe special problem of unsynchronised clocks\fR
2168.IX Subsection "The special problem of unsynchronised clocks" 2262.IX Subsection "The special problem of unsynchronised clocks"
2169.PP 2263.PP
2170Modern systems have a variety of clocks \- libev itself uses the normal 2264Modern systems have a variety of clocks \- libev itself uses the normal
… …
2235.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)"
2236.PD 0 2330.PD 0
2237.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
2238.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)"
2239.PD 2333.PD
2240Configure 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
2241is \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
2242reached. If it is positive, then the timer will automatically be 2336automatically be stopped once the timeout is reached. If it is positive,
2243configured 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
2244until stopped manually. 2338seconds later, again, and again, until stopped manually.
2245.Sp 2339.Sp
2246The 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
2247you 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
2248trigger at exactly 10 second intervals. If, however, your program cannot 2342trigger at exactly 10 second intervals. If, however, your program cannot
2249keep 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
… …
2331Periodic 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
2332(and unfortunately a bit complex). 2426(and unfortunately a bit complex).
2333.PP 2427.PP
2334Unlike \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
2335relative time, the physical time that passes) but on wall clock time 2429relative time, the physical time that passes) but on wall clock time
2336(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
2337difference 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
2338time, 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
2339wrist-watch). 2433wrist-watch).
2340.PP 2434.PP
2341You can tell a periodic watcher to trigger after some specific point 2435You can tell a periodic watcher to trigger after some specific point
… …
2346\&\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
2347it, as it uses a relative timeout). 2441it, as it uses a relative timeout).
2348.PP 2442.PP
2349\&\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
2350timers, 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
2351other 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
2352those cannot react to time jumps. 2446watchers, as those cannot react to time jumps.
2353.PP 2447.PP
2354As 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
2355point 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
2356timers become ready during the same loop iteration then the ones with 2450timers become ready during the same loop iteration then the ones with
2357earlier 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
… …
2418In 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
2419ignored. Instead, each time the periodic watcher gets scheduled, the 2513ignored. Instead, each time the periodic watcher gets scheduled, the
2420reschedule callback will be called with the watcher as first, and the 2514reschedule callback will be called with the watcher as first, and the
2421current time as second argument. 2515current time as second argument.
2422.Sp 2516.Sp
2423\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\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,
2424or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2518or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2425allowed by documentation here\fR. 2519allowed by documentation here\fR.
2426.Sp 2520.Sp
2427If 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
2428it 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
… …
2446.Sp 2540.Sp
2447\&\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
2448equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2542equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2449.Sp 2543.Sp
2450This 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
2451triggers 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
2452next 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
2453you 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
2454reason 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).
2455.RE 2569.RE
2456.RS 4 2570.RS 4
2457.RE 2571.RE
2458.IP "ev_periodic_again (loop, ev_periodic *)" 4 2572.IP "ev_periodic_again (loop, ev_periodic *)" 4
2459.IX Item "ev_periodic_again (loop, ev_periodic *)" 2573.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
2544only 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
2545default 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
2546\&\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
2547the 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.
2548.PP 2662.PP
2549When the first watcher gets started will libev actually register something 2663Only after the first watcher for a signal is started will libev actually
2550with 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
2551you 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.
2552.PP 2666.PP
2553If possible and supported, libev will install its handlers with 2667If possible and supported, libev will install its handlers with
2554\&\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
2555not 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
2556interrupted 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
… …
2617The signal the watcher watches out for. 2731The signal the watcher watches out for.
2618.PP 2732.PP
2619\fIExamples\fR 2733\fIExamples\fR
2620.IX Subsection "Examples" 2734.IX Subsection "Examples"
2621.PP 2735.PP
2622Example: Try to exit cleanly on \s-1SIGINT\s0. 2736Example: Try to exit cleanly on \s-1SIGINT.\s0
2623.PP 2737.PP
2624.Vb 5 2738.Vb 5
2625\& static void 2739\& static void
2626\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2740\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
2627\& { 2741\& {
… …
2784compilation environment, which means that on systems with large file 2898compilation environment, which means that on systems with large file
2785support disabled by default, you get the 32 bit version of the stat 2899support disabled by default, you get the 32 bit version of the stat
2786structure. When using the library from programs that change the \s-1ABI\s0 to 2900structure. When using the library from programs that change the \s-1ABI\s0 to
2787use 64 bit file offsets the programs will fail. In that case you have to 2901use 64 bit file offsets the programs will fail. In that case you have to
2788compile libev with the same flags to get binary compatibility. This is 2902compile libev with the same flags to get binary compatibility. This is
2789obviously the case with any flags that change the \s-1ABI\s0, but the problem is 2903obviously the case with any flags that change the \s-1ABI,\s0 but the problem is
2790most noticeably displayed with ev_stat and large file support. 2904most noticeably displayed with ev_stat and large file support.
2791.PP 2905.PP
2792The solution for this is to lobby your distribution maker to make large 2906The solution for this is to lobby your distribution maker to make large
2793file interfaces available by default (as e.g. FreeBSD does) and not 2907file interfaces available by default (as e.g. FreeBSD does) and not
2794optional. Libev cannot simply switch on large file support because it has 2908optional. Libev cannot simply switch on large file support because it has
… …
3039.IX Subsection "ev_prepare and ev_check - customise your event loop!" 3153.IX Subsection "ev_prepare and ev_check - customise your event loop!"
3040Prepare and check watchers are often (but not always) used in pairs: 3154Prepare and check watchers are often (but not always) used in pairs:
3041prepare watchers get invoked before the process blocks and check watchers 3155prepare watchers get invoked before the process blocks and check watchers
3042afterwards. 3156afterwards.
3043.PP 3157.PP
3044You \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
3045the 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
3046watchers. 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,
3047rationale 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
3048those 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
3049\&\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
3050called in pairs bracketing the blocking call. 3164kind they will always be called in pairs bracketing the blocking call.
3051.PP 3165.PP
3052Their main purpose is to integrate other event mechanisms into libev and 3166Their main purpose is to integrate other event mechanisms into libev and
3053their 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
3054variable changes, implement your own watchers, integrate net-snmp or a 3168variable changes, implement your own watchers, integrate net-snmp or a
3055coroutine library and lots more. They are also occasionally useful if 3169coroutine library and lots more. They are also occasionally useful if
… …
3225.Ve 3339.Ve
3226.PP 3340.PP
3227Method 4: Do not use a prepare or check watcher because the module you 3341Method 4: Do not use a prepare or check watcher because the module you
3228want to embed is not flexible enough to support it. Instead, you can 3342want to embed is not flexible enough to support it. Instead, you can
3229override their poll function. The drawback with this solution is that the 3343override their poll function. The drawback with this solution is that the
3230main loop is now no longer controllable by \s-1EV\s0. The \f(CW\*(C`Glib::EV\*(C'\fR module uses 3344main loop is now no longer controllable by \s-1EV.\s0 The \f(CW\*(C`Glib::EV\*(C'\fR module uses
3231this approach, effectively embedding \s-1EV\s0 as a client into the horrible 3345this approach, effectively embedding \s-1EV\s0 as a client into the horrible
3232libglib event loop. 3346libglib event loop.
3233.PP 3347.PP
3234.Vb 4 3348.Vb 4
3235\& static gint 3349\& static gint
… …
3349.PP 3463.PP
3350.Vb 3 3464.Vb 3
3351\& struct ev_loop *loop_hi = ev_default_init (0); 3465\& struct ev_loop *loop_hi = ev_default_init (0);
3352\& struct ev_loop *loop_lo = 0; 3466\& struct ev_loop *loop_lo = 0;
3353\& ev_embed embed; 3467\& ev_embed embed;
3354\& 3468\&
3355\& // see if there is a chance of getting one that works 3469\& // see if there is a chance of getting one that works
3356\& // (remember that a flags value of 0 means autodetection) 3470\& // (remember that a flags value of 0 means autodetection)
3357\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3471\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
3358\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3472\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
3359\& : 0; 3473\& : 0;
… …
3375.PP 3489.PP
3376.Vb 3 3490.Vb 3
3377\& struct ev_loop *loop = ev_default_init (0); 3491\& struct ev_loop *loop = ev_default_init (0);
3378\& struct ev_loop *loop_socket = 0; 3492\& struct ev_loop *loop_socket = 0;
3379\& ev_embed embed; 3493\& ev_embed embed;
3380\& 3494\&
3381\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3495\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
3382\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3496\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
3383\& { 3497\& {
3384\& ev_embed_init (&embed, 0, loop_socket); 3498\& ev_embed_init (&embed, 0, loop_socket);
3385\& ev_embed_start (loop, &embed); 3499\& ev_embed_start (loop, &embed);
… …
3402of course. 3516of course.
3403.PP 3517.PP
3404\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
3405.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?"
3406.PP 3520.PP
3407Most 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
3408up/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
3409sequence should be handled by libev without any problems. 3523sequence should be handled by libev without any problems.
3410.PP 3524.PP
3411This changes when the application actually wants to do event handling 3525This changes when the application actually wants to do event handling
3412in 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
… …
3629is 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
3630notification, and the callback being invoked. 3744notification, and the callback being invoked.
3631.SH "OTHER FUNCTIONS" 3745.SH "OTHER FUNCTIONS"
3632.IX Header "OTHER FUNCTIONS" 3746.IX Header "OTHER FUNCTIONS"
3633There are some other functions of possible interest. Described. Here. Now. 3747There are some other functions of possible interest. Described. Here. Now.
3634.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
3635.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)"
3636This 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
3637callback on whichever event happens first and automatically stops both 3751callback on whichever event happens first and automatically stops both
3638watchers. 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
3639or timeout without having to allocate/configure/start/stop/free one or 3753or timeout without having to allocate/configure/start/stop/free one or
3640more watchers yourself. 3754more watchers yourself.
… …
3652\&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMER\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR 3766\&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMER\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR
3653value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR 3767value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR
3654a timeout and an io event at the same time \- you probably should give io 3768a timeout and an io event at the same time \- you probably should give io
3655events precedence. 3769events precedence.
3656.Sp 3770.Sp
3657Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0. 3771Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO.\s0
3658.Sp 3772.Sp
3659.Vb 7 3773.Vb 7
3660\& static void stdin_ready (int revents, void *arg) 3774\& static void stdin_ready (int revents, void *arg)
3661\& { 3775\& {
3662\& if (revents & EV_READ) 3776\& if (revents & EV_READ)
… …
3678.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3792.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
3679.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)" 3793.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)"
3680This section explains some common idioms that are not immediately 3794This section explains some common idioms that are not immediately
3681obvious. Note that examples are sprinkled over the whole manual, and this 3795obvious. Note that examples are sprinkled over the whole manual, and this
3682section only contains stuff that wouldn't fit anywhere else. 3796section only contains stuff that wouldn't fit anywhere else.
3683.SS "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" 3797.SS "\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\s0"
3684.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" 3798.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
3685Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read 3799Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read
3686or modify at any time: libev will completely ignore it. This can be used 3800or modify at any time: libev will completely ignore it. This can be used
3687to associate arbitrary data with your watcher. If you need more data and 3801to associate arbitrary data with your watcher. If you need more data and
3688don't want to allocate memory separately and store a pointer to it in that 3802don't want to allocate memory separately and store a pointer to it in that
… …
3714\& } 3828\& }
3715.Ve 3829.Ve
3716.PP 3830.PP
3717More interesting and less C\-conformant ways of casting your callback 3831More interesting and less C\-conformant ways of casting your callback
3718function type instead have been omitted. 3832function type instead have been omitted.
3719.SS "\s-1BUILDING\s0 \s-1YOUR\s0 \s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0" 3833.SS "\s-1BUILDING YOUR OWN COMPOSITE WATCHERS\s0"
3720.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS" 3834.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS"
3721Another common scenario is to use some data structure with multiple 3835Another common scenario is to use some data structure with multiple
3722embedded watchers, in effect creating your own watcher that combines 3836embedded watchers, in effect creating your own watcher that combines
3723multiple libev event sources into one \*(L"super-watcher\*(R": 3837multiple libev event sources into one \*(L"super-watcher\*(R":
3724.PP 3838.PP
… …
3752\& { 3866\& {
3753\& struct my_biggy big = (struct my_biggy *) 3867\& struct my_biggy big = (struct my_biggy *)
3754\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3868\& (((char *)w) \- offsetof (struct my_biggy, t2));
3755\& } 3869\& }
3756.Ve 3870.Ve
3757.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0" 3871.SS "\s-1AVOIDING FINISHING BEFORE RETURNING\s0"
3758.IX Subsection "AVOIDING FINISHING BEFORE RETURNING" 3872.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3759Often you have structures like this in event-based programs: 3873Often you have structures like this in event-based programs:
3760.PP 3874.PP
3761.Vb 4 3875.Vb 4
3762\& callback () 3876\& callback ()
… …
3795\& ev_feed_event (EV_A_ watcher, 0); 3909\& ev_feed_event (EV_A_ watcher, 0);
3796.Ve 3910.Ve
3797.PP 3911.PP
3798This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is 3912This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3799invoked, while not delaying callback invocation too much. 3913invoked, while not delaying callback invocation too much.
3800.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0" 3914.SS "\s-1MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS\s0"
3801.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" 3915.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3802Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3916Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3803\&\fImodal\fR interaction, which is most easily implemented by recursively 3917\&\fImodal\fR interaction, which is most easily implemented by recursively
3804invoking \f(CW\*(C`ev_run\*(C'\fR. 3918invoking \f(CW\*(C`ev_run\*(C'\fR.
3805.PP 3919.PP
… …
3837\& exit_main_loop = 1; 3951\& exit_main_loop = 1;
3838\& 3952\&
3839\& // exit both 3953\& // exit both
3840\& exit_main_loop = exit_nested_loop = 1; 3954\& exit_main_loop = exit_nested_loop = 1;
3841.Ve 3955.Ve
3842.SS "\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0" 3956.SS "\s-1THREAD LOCKING EXAMPLE\s0"
3843.IX Subsection "THREAD LOCKING EXAMPLE" 3957.IX Subsection "THREAD LOCKING EXAMPLE"
3844Here is a fictitious example of how to run an event loop in a different 3958Here is a fictitious example of how to run an event loop in a different
3845thread from where callbacks are being invoked and watchers are 3959thread from where callbacks are being invoked and watchers are
3846created/added/removed. 3960created/added/removed.
3847.PP 3961.PP
… …
3988.PP 4102.PP
3989Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise 4103Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise
3990an event loop currently blocking in the kernel will have no knowledge 4104an event loop currently blocking in the kernel will have no knowledge
3991about the newly added timer. By waking up the loop it will pick up any new 4105about the newly added timer. By waking up the loop it will pick up any new
3992watchers in the next event loop iteration. 4106watchers in the next event loop iteration.
3993.SS "\s-1THREADS\s0, \s-1COROUTINES\s0, \s-1CONTINUATIONS\s0, \s-1QUEUES\s0... \s-1INSTEAD\s0 \s-1OF\s0 \s-1CALLBACKS\s0" 4107.SS "\s-1THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS\s0"
3994.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS" 4108.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS"
3995While the overhead of a callback that e.g. schedules a thread is small, it 4109While the overhead of a callback that e.g. schedules a thread is small, it
3996is still an overhead. If you embed libev, and your main usage is with some 4110is still an overhead. If you embed libev, and your main usage is with some
3997kind of threads or coroutines, you might want to customise libev so that 4111kind of threads or coroutines, you might want to customise libev so that
3998doesn't need callbacks anymore. 4112doesn't need callbacks anymore.
… …
4034You can do similar tricks if you have, say, threads with an event queue \- 4148You can do similar tricks if you have, say, threads with an event queue \-
4035instead of storing a coroutine, you store the queue object and instead of 4149instead of storing a coroutine, you store the queue object and instead of
4036switching to a coroutine, you push the watcher onto the queue and notify 4150switching to a coroutine, you push the watcher onto the queue and notify
4037any waiters. 4151any waiters.
4038.PP 4152.PP
4039To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two 4153To embed libev, see \*(L"\s-1EMBEDDING\*(R"\s0, but in short, it's easiest to create two
4040files, \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:
4041.PP 4155.PP
4042.Vb 4 4156.Vb 4
4043\& // my_ev.h 4157\& // my_ev.h
4044\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4158\& #define EV_CB_DECLARE(type) struct my_coro *cb;
4045\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb); 4159\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb)
4046\& #include "../libev/ev.h" 4160\& #include "../libev/ev.h"
4047\& 4161\&
4048\& // my_ev.c 4162\& // my_ev.c
4049\& #define EV_H "my_ev.h" 4163\& #define EV_H "my_ev.h"
4050\& #include "../libev/ev.c" 4164\& #include "../libev/ev.c"
… …
4090The 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
4091libev 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
4092will work fine. 4206will work fine.
4093.PP 4207.PP
4094Proper exception specifications might have to be added to callbacks passed 4208Proper exception specifications might have to be added to callbacks passed
4095to libev: exceptions may be thrown only from watcher callbacks, all 4209to libev: exceptions may be thrown only from watcher callbacks, all other
4096other callbacks (allocator, syserr, loop acquire/release and periodic 4210callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4097reschedule 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
4098()\*(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
4099and \*(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:
4100.PP 4214.PP
4101.Vb 6 4215.Vb 6
4102\& static void 4216\& static void
4103\& fatal_error (const char *msg) EV_THROW 4217\& fatal_error (const char *msg) EV_NOEXCEPT
4104\& { 4218\& {
4105\& perror (msg); 4219\& perror (msg);
4106\& abort (); 4220\& abort ();
4107\& } 4221\& }
4108\& 4222\&
… …
4236\& void operator() (ev::io &w, int revents) 4350\& void operator() (ev::io &w, int revents)
4237\& { 4351\& {
4238\& ... 4352\& ...
4239\& } 4353\& }
4240\& } 4354\& }
4241\& 4355\&
4242\& myfunctor f; 4356\& myfunctor f;
4243\& 4357\&
4244\& ev::io w; 4358\& ev::io w;
4245\& w.set (&f); 4359\& w.set (&f);
4246.Ve 4360.Ve
… …
4339there are additional modules that implement libev-compatible interfaces 4453there are additional modules that implement libev-compatible interfaces
4340to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays), 4454to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays),
4341\&\f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the \f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR 4455\&\f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the \f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR
4342and \f(CW\*(C`EV::Glib\*(C'\fR). 4456and \f(CW\*(C`EV::Glib\*(C'\fR).
4343.Sp 4457.Sp
4344It can be found and installed via \s-1CPAN\s0, its homepage is at 4458It can be found and installed via \s-1CPAN,\s0 its homepage is at
4345<http://software.schmorp.de/pkg/EV>. 4459<http://software.schmorp.de/pkg/EV>.
4346.IP "Python" 4 4460.IP "Python" 4
4347.IX Item "Python" 4461.IX Item "Python"
4348Python bindings can be found at <http://code.google.com/p/pyev/>. It 4462Python bindings can be found at <http://code.google.com/p/pyev/>. It
4349seems to be quite complete and well-documented. 4463seems to be quite complete and well-documented.
… …
4357Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR 4471Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4358makes rev work even on mingw. 4472makes rev work even on mingw.
4359.IP "Haskell" 4 4473.IP "Haskell" 4
4360.IX Item "Haskell" 4474.IX Item "Haskell"
4361A haskell binding to libev is available at 4475A haskell binding to libev is available at
4362http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>. 4476<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>.
4363.IP "D" 4 4477.IP "D" 4
4364.IX Item "D" 4478.IX Item "D"
4365Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4479Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4366be found at <http://www.llucax.com.ar/proj/ev.d/index.html>. 4480be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4367.IP "Ocaml" 4 4481.IP "Ocaml" 4
4368.IX Item "Ocaml" 4482.IX Item "Ocaml"
4369Erkki Seppala has written Ocaml bindings for libev, to be found at 4483Erkki Seppala has written Ocaml bindings for libev, to be found at
4370http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 4484<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
4371.IP "Lua" 4 4485.IP "Lua" 4
4372.IX Item "Lua" 4486.IX Item "Lua"
4373Brian Maher has written a partial interface to libev for lua (at the 4487Brian Maher has written a partial interface to libev for lua (at the
4374time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4488time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4375http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. 4489<http://github.com/brimworks/lua\-ev>.
4376.IP "Javascript" 4 4490.IP "Javascript" 4
4377.IX Item "Javascript" 4491.IX Item "Javascript"
4378Node.js (<http://nodejs.org>) uses libev as the underlying event library. 4492Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4379.IP "Others" 4 4493.IP "Others" 4
4380.IX Item "Others" 4494.IX Item "Others"
… …
4469.SS "\s-1FILESETS\s0" 4583.SS "\s-1FILESETS\s0"
4470.IX Subsection "FILESETS" 4584.IX Subsection "FILESETS"
4471Depending on what features you need you need to include one or more sets of files 4585Depending on what features you need you need to include one or more sets of files
4472in your application. 4586in your application.
4473.PP 4587.PP
4474\fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR 4588\fI\s-1CORE EVENT LOOP\s0\fR
4475.IX Subsection "CORE EVENT LOOP" 4589.IX Subsection "CORE EVENT LOOP"
4476.PP 4590.PP
4477To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual 4591To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual
4478configuration (no autoconf): 4592configuration (no autoconf):
4479.PP 4593.PP
… …
4506\& ev_vars.h 4620\& ev_vars.h
4507\& ev_wrap.h 4621\& ev_wrap.h
4508\& 4622\&
4509\& ev_win32.c required on win32 platforms only 4623\& ev_win32.c required on win32 platforms only
4510\& 4624\&
4511\& ev_select.c only when select backend is enabled (which is enabled by default) 4625\& ev_select.c only when select backend is enabled
4512\& ev_poll.c only when poll backend is enabled (disabled by default) 4626\& ev_poll.c only when poll backend is enabled
4513\& 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
4514\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4629\& ev_kqueue.c only when the kqueue backend is enabled
4515\& ev_port.c only when the solaris port backend is enabled (disabled by default) 4630\& ev_port.c only when the solaris port backend is enabled
4516.Ve 4631.Ve
4517.PP 4632.PP
4518\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4633\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4519to compile this single file. 4634to compile this single file.
4520.PP 4635.PP
4521\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR 4636\fI\s-1LIBEVENT COMPATIBILITY API\s0\fR
4522.IX Subsection "LIBEVENT COMPATIBILITY API" 4637.IX Subsection "LIBEVENT COMPATIBILITY API"
4523.PP 4638.PP
4524To include the libevent compatibility \s-1API\s0, also include: 4639To include the libevent compatibility \s-1API,\s0 also include:
4525.PP 4640.PP
4526.Vb 1 4641.Vb 1
4527\& #include "event.c" 4642\& #include "event.c"
4528.Ve 4643.Ve
4529.PP 4644.PP
… …
4531.PP 4646.PP
4532.Vb 1 4647.Vb 1
4533\& #include "event.h" 4648\& #include "event.h"
4534.Ve 4649.Ve
4535.PP 4650.PP
4536in the files that want to use the libevent \s-1API\s0. This also includes \fIev.h\fR. 4651in the files that want to use the libevent \s-1API.\s0 This also includes \fIev.h\fR.
4537.PP 4652.PP
4538You need the following additional files for this: 4653You need the following additional files for this:
4539.PP 4654.PP
4540.Vb 2 4655.Vb 2
4541\& event.h 4656\& event.h
4542\& event.c 4657\& event.c
4543.Ve 4658.Ve
4544.PP 4659.PP
4545\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR 4660\fI\s-1AUTOCONF SUPPORT\s0\fR
4546.IX Subsection "AUTOCONF SUPPORT" 4661.IX Subsection "AUTOCONF SUPPORT"
4547.PP 4662.PP
4548Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in 4663Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in
4549whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your 4664whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your
4550\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then 4665\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then
… …
4553For this of course you need the m4 file: 4668For this of course you need the m4 file:
4554.PP 4669.PP
4555.Vb 1 4670.Vb 1
4556\& libev.m4 4671\& libev.m4
4557.Ve 4672.Ve
4558.SS "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0" 4673.SS "\s-1PREPROCESSOR SYMBOLS/MACROS\s0"
4559.IX Subsection "PREPROCESSOR SYMBOLS/MACROS" 4674.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
4560Libev can be configured via a variety of preprocessor symbols you have to 4675Libev can be configured via a variety of preprocessor symbols you have to
4561define before including (or compiling) any of its files. The default in 4676define before including (or compiling) any of its files. The default in
4562the absence of autoconf is documented for every option. 4677the absence of autoconf is documented for every option.
4563.PP 4678.PP
4564Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI\s0, and can have different 4679Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI,\s0 and can have different
4565values when compiling libev vs. including \fIev.h\fR, so it is permissible 4680values when compiling libev vs. including \fIev.h\fR, so it is permissible
4566to redefine them before including \fIev.h\fR without breaking compatibility 4681to redefine them before including \fIev.h\fR without breaking compatibility
4567to a compiled library. All other symbols change the \s-1ABI\s0, which means all 4682to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4568users of libev and the libev code itself must be compiled with compatible 4683users of libev and the libev code itself must be compiled with compatible
4569settings. 4684settings.
4570.IP "\s-1EV_COMPAT3\s0 (h)" 4 4685.IP "\s-1EV_COMPAT3\s0 (h)" 4
4571.IX Item "EV_COMPAT3 (h)" 4686.IX Item "EV_COMPAT3 (h)"
4572Backwards compatibility is a major concern for libev. This is why this 4687Backwards compatibility is a major concern for libev. This is why this
… …
4699If defined to be \f(CW1\fR, libev will compile in support for the Linux 4814If defined to be \f(CW1\fR, libev will compile in support for the Linux
4700\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4815\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4701otherwise another method will be used as fallback. This is the preferred 4816otherwise another method will be used as fallback. This is the preferred
4702backend for GNU/Linux systems. If undefined, it will be enabled if the 4817backend for GNU/Linux systems. If undefined, it will be enabled if the
4703headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4818headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4819.IP "\s-1EV_USE_LINUXAIO\s0" 4
4820.IX Item "EV_USE_LINUXAIO"
4821If defined to be \f(CW1\fR, libev will compile in support for the Linux
4822aio backend. Due to it's currenbt limitations it has to be requested
4823explicitly. If undefined, it will be enabled on linux, otherwise
4824disabled.
4704.IP "\s-1EV_USE_KQUEUE\s0" 4 4825.IP "\s-1EV_USE_KQUEUE\s0" 4
4705.IX Item "EV_USE_KQUEUE" 4826.IX Item "EV_USE_KQUEUE"
4706If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4827If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4707\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4828\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4708otherwise another method will be used as fallback. This is the preferred 4829otherwise another method will be used as fallback. This is the preferred
… …
4796all the priorities, so having many of them (hundreds) uses a lot of space 4917all the priorities, so having many of them (hundreds) uses a lot of space
4797and time, so using the defaults of five priorities (\-2 .. +2) is usually 4918and time, so using the defaults of five priorities (\-2 .. +2) is usually
4798fine. 4919fine.
4799.Sp 4920.Sp
4800If your embedding application does not need any priorities, defining these 4921If your embedding application does not need any priorities, defining these
4801both to \f(CW0\fR will save some memory and \s-1CPU\s0. 4922both to \f(CW0\fR will save some memory and \s-1CPU.\s0
4802.IP "\s-1EV_PERIODIC_ENABLE\s0, \s-1EV_IDLE_ENABLE\s0, \s-1EV_EMBED_ENABLE\s0, \s-1EV_STAT_ENABLE\s0, \s-1EV_PREPARE_ENABLE\s0, \s-1EV_CHECK_ENABLE\s0, \s-1EV_FORK_ENABLE\s0, \s-1EV_SIGNAL_ENABLE\s0, \s-1EV_ASYNC_ENABLE\s0, \s-1EV_CHILD_ENABLE\s0." 4 4923.IP "\s-1EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, EV_ASYNC_ENABLE, EV_CHILD_ENABLE.\s0" 4
4803.IX Item "EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, EV_ASYNC_ENABLE, EV_CHILD_ENABLE." 4924.IX Item "EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, EV_ASYNC_ENABLE, EV_CHILD_ENABLE."
4804If undefined or defined to be \f(CW1\fR (and the platform supports it), then 4925If undefined or defined to be \f(CW1\fR (and the platform supports it), then
4805the respective watcher type is supported. If defined to be \f(CW0\fR, then it 4926the respective watcher type is supported. If defined to be \f(CW0\fR, then it
4806is not. Disabling watcher types mainly saves code size. 4927is not. Disabling watcher types mainly saves code size.
4807.IP "\s-1EV_FEATURES\s0" 4 4928.IP "\s-1EV_FEATURES\s0" 4
… …
4965called. If set to \f(CW2\fR, then the internal verification code will be 5086called. If set to \f(CW2\fR, then the internal verification code will be
4966called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5087called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
4967verification code will be called very frequently, which will slow down 5088verification code will be called very frequently, which will slow down
4968libev considerably. 5089libev considerably.
4969.Sp 5090.Sp
5091Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5092disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5093.Sp
4970The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5094The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
4971will be \f(CW0\fR. 5095will be \f(CW0\fR.
4972.IP "\s-1EV_COMMON\s0" 4 5096.IP "\s-1EV_COMMON\s0" 4
4973.IX Item "EV_COMMON" 5097.IX Item "EV_COMMON"
4974By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 5098By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
… …
4995and the way callbacks are invoked and set. Must expand to a struct member 5119and the way callbacks are invoked and set. Must expand to a struct member
4996definition and a statement, respectively. See the \fIev.h\fR header file for 5120definition and a statement, respectively. See the \fIev.h\fR header file for
4997their default definitions. One possible use for overriding these is to 5121their default definitions. One possible use for overriding these is to
4998avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5122avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
4999method calls instead of plain function calls in \*(C+. 5123method calls instead of plain function calls in \*(C+.
5000.SS "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0" 5124.SS "\s-1EXPORTED API SYMBOLS\s0"
5001.IX Subsection "EXPORTED API SYMBOLS" 5125.IX Subsection "EXPORTED API SYMBOLS"
5002If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of 5126If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5003exported symbols, you can use the provided \fISymbol.*\fR files which list 5127exported symbols, you can use the provided \fISymbol.*\fR files which list
5004all public symbols, one per line: 5128all public symbols, one per line:
5005.PP 5129.PP
… …
5059\& #include "ev_cpp.h" 5183\& #include "ev_cpp.h"
5060\& #include "ev.c" 5184\& #include "ev.c"
5061.Ve 5185.Ve
5062.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5186.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5063.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5187.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5064.SS "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0" 5188.SS "\s-1THREADS AND COROUTINES\s0"
5065.IX Subsection "THREADS AND COROUTINES" 5189.IX Subsection "THREADS AND COROUTINES"
5066\fI\s-1THREADS\s0\fR 5190\fI\s-1THREADS\s0\fR
5067.IX Subsection "THREADS" 5191.IX Subsection "THREADS"
5068.PP 5192.PP
5069All libev functions are reentrant and thread-safe unless explicitly 5193All libev functions are reentrant and thread-safe unless explicitly
… …
5115An example use would be to communicate signals or other events that only 5239An example use would be to communicate signals or other events that only
5116work in the default loop by registering the signal watcher with the 5240work in the default loop by registering the signal watcher with the
5117default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop 5241default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop
5118watcher callback into the event loop interested in the signal. 5242watcher callback into the event loop interested in the signal.
5119.PP 5243.PP
5120See also \*(L"\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0\*(R". 5244See also \*(L"\s-1THREAD LOCKING EXAMPLE\*(R"\s0.
5121.PP 5245.PP
5122\fI\s-1COROUTINES\s0\fR 5246\fI\s-1COROUTINES\s0\fR
5123.IX Subsection "COROUTINES" 5247.IX Subsection "COROUTINES"
5124.PP 5248.PP
5125Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"): 5249Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"):
… …
5130that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. 5254that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
5131.PP 5255.PP
5132Care has been taken to ensure that libev does not keep local state inside 5256Care has been taken to ensure that libev does not keep local state inside
5133\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as 5257\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as
5134they do not call any callbacks. 5258they do not call any callbacks.
5135.SS "\s-1COMPILER\s0 \s-1WARNINGS\s0" 5259.SS "\s-1COMPILER WARNINGS\s0"
5136.IX Subsection "COMPILER WARNINGS" 5260.IX Subsection "COMPILER WARNINGS"
5137Depending on your compiler and compiler settings, you might get no or a 5261Depending on your compiler and compiler settings, you might get no or a
5138lot of warnings when compiling libev code. Some people are apparently 5262lot of warnings when compiling libev code. Some people are apparently
5139scared by this. 5263scared by this.
5140.PP 5264.PP
… …
5192.PP 5316.PP
5193If you need, for some reason, empty reports from valgrind for your project 5317If you need, for some reason, empty reports from valgrind for your project
5194I suggest using suppression lists. 5318I suggest using suppression lists.
5195.SH "PORTABILITY NOTES" 5319.SH "PORTABILITY NOTES"
5196.IX Header "PORTABILITY NOTES" 5320.IX Header "PORTABILITY NOTES"
5197.SS "\s-1GNU/LINUX\s0 32 \s-1BIT\s0 \s-1LIMITATIONS\s0" 5321.SS "\s-1GNU/LINUX 32 BIT LIMITATIONS\s0"
5198.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS" 5322.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS"
5199GNU/Linux is the only common platform that supports 64 bit file/large file 5323GNU/Linux is the only common platform that supports 64 bit file/large file
5200interfaces but \fIdisables\fR them by default. 5324interfaces but \fIdisables\fR them by default.
5201.PP 5325.PP
5202That means that libev compiled in the default environment doesn't support 5326That means that libev compiled in the default environment doesn't support
5203files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers. 5327files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers.
5204.PP 5328.PP
5205Unfortunately, many programs try to work around this GNU/Linux issue 5329Unfortunately, many programs try to work around this GNU/Linux issue
5206by enabling the large file \s-1API\s0, which makes them incompatible with the 5330by enabling the large file \s-1API,\s0 which makes them incompatible with the
5207standard libev compiled for their system. 5331standard libev compiled for their system.
5208.PP 5332.PP
5209Likewise, libev cannot enable the large file \s-1API\s0 itself as this would 5333Likewise, libev cannot enable the large file \s-1API\s0 itself as this would
5210suddenly make it incompatible to the default compile time environment, 5334suddenly make it incompatible to the default compile time environment,
5211i.e. all programs not using special compile switches. 5335i.e. all programs not using special compile switches.
5212.SS "\s-1OS/X\s0 \s-1AND\s0 \s-1DARWIN\s0 \s-1BUGS\s0" 5336.SS "\s-1OS/X AND DARWIN BUGS\s0"
5213.IX Subsection "OS/X AND DARWIN BUGS" 5337.IX Subsection "OS/X AND DARWIN BUGS"
5214The whole thing is a bug if you ask me \- basically any system interface 5338The whole thing is a bug if you ask me \- basically any system interface
5215you touch is broken, whether it is locales, poll, kqueue or even the 5339you touch is broken, whether it is locales, poll, kqueue or even the
5216OpenGL drivers. 5340OpenGL drivers.
5217.PP 5341.PP
… …
5239.PP 5363.PP
5240\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5364\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5241.IX Subsection "select is buggy" 5365.IX Subsection "select is buggy"
5242.PP 5366.PP
5243All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5367All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5244one up as well: On \s-1OS/X\s0, \f(CW\*(C`select\*(C'\fR actively limits the number of file 5368one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5245descriptors you can pass in to 1024 \- your program suddenly crashes when 5369descriptors you can pass in to 1024 \- your program suddenly crashes when
5246you use more. 5370you use more.
5247.PP 5371.PP
5248There is an undocumented \*(L"workaround\*(R" for this \- defining 5372There is an undocumented \*(L"workaround\*(R" for this \- defining
5249\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5373\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
5250work on \s-1OS/X\s0. 5374work on \s-1OS/X.\s0
5251.SS "\s-1SOLARIS\s0 \s-1PROBLEMS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5375.SS "\s-1SOLARIS PROBLEMS AND WORKAROUNDS\s0"
5252.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS" 5376.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS"
5253\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR 5377\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR
5254.IX Subsection "errno reentrancy" 5378.IX Subsection "errno reentrancy"
5255.PP 5379.PP
5256The default compile environment on Solaris is unfortunately so 5380The default compile environment on Solaris is unfortunately so
… …
5273great. 5397great.
5274.PP 5398.PP
5275If you can't get it to work, you can try running the program by setting 5399If you can't get it to work, you can try running the program by setting
5276the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and 5400the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and
5277\&\f(CW\*(C`select\*(C'\fR backends. 5401\&\f(CW\*(C`select\*(C'\fR backends.
5278.SS "\s-1AIX\s0 \s-1POLL\s0 \s-1BUG\s0" 5402.SS "\s-1AIX POLL BUG\s0"
5279.IX Subsection "AIX POLL BUG" 5403.IX Subsection "AIX POLL BUG"
5280\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around 5404\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around
5281this by trying to avoid the poll backend altogether (i.e. it's not even 5405this by trying to avoid the poll backend altogether (i.e. it's not even
5282compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine 5406compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine
5283with large bitsets on \s-1AIX\s0, and \s-1AIX\s0 is dead anyway. 5407with large bitsets on \s-1AIX,\s0 and \s-1AIX\s0 is dead anyway.
5284.SS "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5408.SS "\s-1WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS\s0"
5285.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" 5409.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
5286\fIGeneral issues\fR 5410\fIGeneral issues\fR
5287.IX Subsection "General issues" 5411.IX Subsection "General issues"
5288.PP 5412.PP
5289Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev 5413Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
… …
5358\& #define EV_USE_SELECT 1 5482\& #define EV_USE_SELECT 1
5359\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 5483\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
5360.Ve 5484.Ve
5361.PP 5485.PP
5362Note that winsockets handling of fd sets is O(n), so you can easily get a 5486Note that winsockets handling of fd sets is O(n), so you can easily get a
5363complexity in the O(nA\*^X) range when using win32. 5487complexity in the O(nX) range when using win32.
5364.PP 5488.PP
5365\fILimited number of file descriptors\fR 5489\fILimited number of file descriptors\fR
5366.IX Subsection "Limited number of file descriptors" 5490.IX Subsection "Limited number of file descriptors"
5367.PP 5491.PP
5368Windows has numerous arbitrary (and low) limits on things. 5492Windows has numerous arbitrary (and low) limits on things.
… …
5384by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR 5508by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR
5385(another arbitrary limit), but is broken in many versions of the Microsoft 5509(another arbitrary limit), but is broken in many versions of the Microsoft
5386runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets 5510runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets
5387(depending on windows version and/or the phase of the moon). To get more, 5511(depending on windows version and/or the phase of the moon). To get more,
5388you need to wrap all I/O functions and provide your own fd management, but 5512you need to wrap all I/O functions and provide your own fd management, but
5389the cost of calling select (O(nA\*^X)) will likely make this unworkable. 5513the cost of calling select (O(nX)) will likely make this unworkable.
5390.SS "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\s0" 5514.SS "\s-1PORTABILITY REQUIREMENTS\s0"
5391.IX Subsection "PORTABILITY REQUIREMENTS" 5515.IX Subsection "PORTABILITY REQUIREMENTS"
5392In addition to a working ISO-C implementation and of course the 5516In addition to a working ISO-C implementation and of course the
5393backend-specific APIs, libev relies on a few additional extensions: 5517backend-specific APIs, libev relies on a few additional extensions:
5394.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4 5518.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4
5395.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 5519.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4
5396.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." 5520.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *."
5397Libev assumes not only that all watcher pointers have the same internal 5521Libev assumes not only that all watcher pointers have the same internal
5398structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also 5522structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5399assumes that the same (machine) code can be used to call any watcher 5523assumes that the same (machine) code can be used to call any watcher
5400callback: The watcher callbacks have different type signatures, but libev 5524callback: The watcher callbacks have different type signatures, but libev
5401calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5525calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5526.IP "null pointers and integer zero are represented by 0 bytes" 4
5527.IX Item "null pointers and integer zero are represented by 0 bytes"
5528Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
5529relies on this setting pointers and integers to null.
5402.IP "pointer accesses must be thread-atomic" 4 5530.IP "pointer accesses must be thread-atomic" 4
5403.IX Item "pointer accesses must be thread-atomic" 5531.IX Item "pointer accesses must be thread-atomic"
5404Accessing a pointer value must be atomic, it must both be readable and 5532Accessing a pointer value must be atomic, it must both be readable and
5405writable in one piece \- this is the case on all current architectures. 5533writable in one piece \- this is the case on all current architectures.
5406.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 5534.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4
… …
5424except the initial one, and run the signal handling loop in the initial 5552except the initial one, and run the signal handling loop in the initial
5425thread as well. 5553thread as well.
5426.ie n .IP """long"" must be large enough for common memory allocation sizes" 4 5554.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
5427.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 5555.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
5428.IX Item "long must be large enough for common memory allocation sizes" 5556.IX Item "long must be large enough for common memory allocation sizes"
5429To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5557To improve portability and simplify its \s-1API,\s0 libev uses \f(CW\*(C`long\*(C'\fR internally
5430instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5558instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX
5431systems (Microsoft...) this might be unexpectedly low, but is still at 5559systems (Microsoft...) this might be unexpectedly low, but is still at
5432least 31 bits everywhere, which is enough for hundreds of millions of 5560least 31 bits everywhere, which is enough for hundreds of millions of
5433watchers. 5561watchers.
5434.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 5562.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
… …
5436.IX Item "double must hold a time value in seconds with enough accuracy" 5564.IX Item "double must hold a time value in seconds with enough accuracy"
5437The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to 5565The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
5438have at least 51 bits of mantissa (and 9 bits of exponent), which is 5566have at least 51 bits of mantissa (and 9 bits of exponent), which is
5439good enough for at least into the year 4000 with millisecond accuracy 5567good enough for at least into the year 4000 with millisecond accuracy
5440(the design goal for libev). This requirement is overfulfilled by 5568(the design goal for libev). This requirement is overfulfilled by
5441implementations using \s-1IEEE\s0 754, which is basically all existing ones. 5569implementations using \s-1IEEE 754,\s0 which is basically all existing ones.
5442.Sp 5570.Sp
5443With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the 5571With \s-1IEEE 754\s0 doubles, you get microsecond accuracy until at least the
5444year 2255 (and millisecond accuracy till the year 287396 \- by then, libev 5572year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5445is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or 5573is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5446something like that, just kidding). 5574something like that, just kidding).
5447.PP 5575.PP
5448If you know of other additional requirements drop me a note. 5576If you know of other additional requirements drop me a note.
… …
5510calls in the current loop iteration and the loop is currently 5638calls in the current loop iteration and the loop is currently
5511blocked. Checking for async and signal events involves iterating over all 5639blocked. Checking for async and signal events involves iterating over all
5512running async watchers or all signal numbers. 5640running async watchers or all signal numbers.
5513.SH "PORTING FROM LIBEV 3.X TO 4.X" 5641.SH "PORTING FROM LIBEV 3.X TO 4.X"
5514.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5642.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5515The major version 4 introduced some incompatible changes to the \s-1API\s0. 5643The major version 4 introduced some incompatible changes to the \s-1API.\s0
5516.PP 5644.PP
5517At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5645At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
5518for all changes, so most programs should still compile. The compatibility 5646for all changes, so most programs should still compile. The compatibility
5519layer might be removed in later versions of libev, so better update to the 5647layer might be removed in later versions of libev, so better update to the
5520new \s-1API\s0 early than late. 5648new \s-1API\s0 early than late.
5521.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5649.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5522.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5650.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5523.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5651.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5524The backward compatibility mechanism can be controlled by 5652The backward compatibility mechanism can be controlled by
5525\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R" 5653\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR SYMBOLS/MACROS\*(R"\s0 in the \*(L"\s-1EMBEDDING\*(R"\s0
5526section. 5654section.
5527.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5655.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5528.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5656.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5529.IX Item "ev_default_destroy and ev_default_fork have been removed" 5657.IX Item "ev_default_destroy and ev_default_fork have been removed"
5530These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5658These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts:
… …
5570.SH "GLOSSARY" 5698.SH "GLOSSARY"
5571.IX Header "GLOSSARY" 5699.IX Header "GLOSSARY"
5572.IP "active" 4 5700.IP "active" 4
5573.IX Item "active" 5701.IX Item "active"
5574A watcher is active as long as it has been started and not yet stopped. 5702A watcher is active as long as it has been started and not yet stopped.
5575See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5703See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5576.IP "application" 4 5704.IP "application" 4
5577.IX Item "application" 5705.IX Item "application"
5578In this document, an application is whatever is using libev. 5706In this document, an application is whatever is using libev.
5579.IP "backend" 4 5707.IP "backend" 4
5580.IX Item "backend" 5708.IX Item "backend"
… …
5607The model used to describe how an event loop handles and processes 5735The model used to describe how an event loop handles and processes
5608watchers and events. 5736watchers and events.
5609.IP "pending" 4 5737.IP "pending" 4
5610.IX Item "pending" 5738.IX Item "pending"
5611A watcher is pending as soon as the corresponding event has been 5739A watcher is pending as soon as the corresponding event has been
5612detected. See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5740detected. See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5613.IP "real time" 4 5741.IP "real time" 4
5614.IX Item "real time" 5742.IX Item "real time"
5615The physical time that is observed. It is apparently strictly monotonic :) 5743The physical time that is observed. It is apparently strictly monotonic :)
5616.IP "wall-clock time" 4 5744.IP "wall-clock time" 4
5617.IX Item "wall-clock time" 5745.IX Item "wall-clock time"

Diff Legend

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