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

Comparing libev/ev.3 (file contents):
Revision 1.98 by root, Thu Feb 28 02:17:11 2013 UTC vs.
Revision 1.118 by root, Sat Dec 21 16:11:51 2019 UTC

1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) 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-02-28" "libev-4.11" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-12-21" "libev-4.31" "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)
… …
514.IX Item "EVFLAG_NOENV" 549.IX Item "EVFLAG_NOENV"
515If this flag bit is or'ed into the flag value (or the program runs setuid 550If this flag bit is or'ed into the flag value (or the program runs setuid
516or setgid) then libev will \fInot\fR look at the environment variable 551or setgid) then libev will \fInot\fR look at the environment variable
517\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will 552\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will
518override the flags completely if it is found in the environment. This is 553override the flags completely if it is found in the environment. This is
519useful to try out specific backends to test their performance, or to work 554useful to try out specific backends to test their performance, to work
520around bugs. 555around bugs, or to make libev threadsafe (accessing environment variables
556cannot be done in a threadsafe way, but usually it works if no other
557thread modifies them).
521.ie n .IP """EVFLAG_FORKCHECK""" 4 558.ie n .IP """EVFLAG_FORKCHECK""" 4
522.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 559.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
523.IX Item "EVFLAG_FORKCHECK" 560.IX Item "EVFLAG_FORKCHECK"
524Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also 561Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also
525make 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.
526.Sp 563.Sp
527This 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,
528and 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
529iterations and little real work, but is usually not noticeable (on my 566iterations and little real work, but is usually not noticeable (on my
530GNU/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
531without 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
532\&\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).
533.Sp 571.Sp
534The 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
535forget about forgetting to tell libev about forking) when you use this 573forget about forgetting to tell libev about forking, although you still
536flag. 574have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
537.Sp 575.Sp
538This 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
539environment variable. 577environment variable.
540.ie n .IP """EVFLAG_NOINOTIFY""" 4 578.ie n .IP """EVFLAG_NOINOTIFY""" 4
541.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 579.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
… …
568want to handle signals only in specific threads and want to avoid libev 606want to handle signals only in specific threads and want to avoid libev
569unblocking the signals. 607unblocking the signals.
570.Sp 608.Sp
571It's also required by \s-1POSIX\s0 in a threaded program, as libev calls 609It's also required by \s-1POSIX\s0 in a threaded program, as libev calls
572\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. 610\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
611.ie n .IP """EVFLAG_NOTIMERFD""" 4
612.el .IP "\f(CWEVFLAG_NOTIMERFD\fR" 4
613.IX Item "EVFLAG_NOTIMERFD"
614When this flag is specified, the libev will avoid using a \f(CW\*(C`timerfd\*(C'\fR to
615detect time jumps. It will still be able to detect time jumps, but takes
616longer and has a lower accuracy in doing so, but saves a file descriptor
617per loop.
573.Sp 618.Sp
574This flag's behaviour will become the default in future versions of libev. 619The current implementation only tries to use a \f(CW\*(C`timerfd\*(C'\fR when the first
620\&\f(CW\*(C`ev_periodic\*(C'\fR watcher is started and falls back on other methods if it
621cannot be created, but this behaviour might change in the future.
575.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 622.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
576.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 623.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
577.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 624.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
578This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 625This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
579libev tries to roll its own fd_set with no limits on the number of fds, 626libev tries to roll its own fd_set with no limits on the number of fds,
580but if that fails, expect a fairly low limit on the number of fds when 627but if that fails, expect a fairly low limit on the number of fds when
581using this backend. It doesn't scale too well (O(highest_fd)), but its 628using this backend. It doesn't scale too well (O(highest_fd)), but its
582usually the fastest backend for a low number of (low-numbered :) fds. 629usually the fastest backend for a low number of (low-numbered :) fds.
583.Sp 630.Sp
… …
591This 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 638This 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
592\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the 639\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the
593\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). 640\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
594.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 641.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
595.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 642.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
596.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 643.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
597And this is your standard \fIpoll\fR\|(2) backend. It's more complicated 644And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
598than select, but handles sparse fds better and has no artificial 645than select, but handles sparse fds better and has no artificial
599limit on the number of fds you can use (except it will slow down 646limit on the number of fds you can use (except it will slow down
600considerably with a lot of inactive fds). It scales similarly to select, 647considerably with a lot of inactive fds). It scales similarly to select,
601i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for 648i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
602performance tips. 649performance tips.
603.Sp 650.Sp
604This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 651This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and
605\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. 652\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
606.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 653.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
607.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 654.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
608.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 655.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
609Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 656Use the Linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
610kernels). 657kernels).
611.Sp 658.Sp
612For few fds, this backend is a bit little slower than poll and select, but 659For few fds, this backend is a bit little slower than poll and select, but
613it scales phenomenally better. While poll and select usually scale like 660it scales phenomenally better. While poll and select usually scale like
614O(total_fds) where total_fds is the total number of fds (or the highest 661O(total_fds) where total_fds is the total number of fds (or the highest
… …
660All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or 707All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or
661faster than epoll for maybe up to a hundred file descriptors, depending on 708faster than epoll for maybe up to a hundred file descriptors, depending on
662the usage. So sad. 709the usage. So sad.
663.Sp 710.Sp
664While nominally embeddable in other event loops, this feature is broken in 711While nominally embeddable in other event loops, this feature is broken in
665all kernel versions tested so far. 712a lot of kernel revisions, but probably(!) works in current versions.
713.Sp
714This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
715\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
716.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4
717.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4
718.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
719Use the Linux-specific Linux \s-1AIO\s0 (\fInot\fR \f(CWaio(7)\fR but \f(CWio_submit(2)\fR) event interface available in post\-4.18 kernels (but libev
720only tries to use it in 4.19+).
721.Sp
722This is another Linux train wreck of an event interface.
723.Sp
724If this backend works for you (as of this writing, it was very
725experimental), it is the best event interface available on Linux and might
726be well worth enabling it \- if it isn't available in your kernel this will
727be detected and this backend will be skipped.
728.Sp
729This backend can batch oneshot requests and supports a user-space ring
730buffer to receive events. It also doesn't suffer from most of the design
731problems of epoll (such as not being able to remove event sources from
732the epoll set), and generally sounds too good to be true. Because, this
733being the Linux kernel, of course it suffers from a whole new set of
734limitations, forcing you to fall back to epoll, inheriting all its design
735issues.
736.Sp
737For one, it is not easily embeddable (but probably could be done using
738an event fd at some extra overhead). It also is subject to a system wide
739limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR. If no \s-1AIO\s0
740requests are left, this backend will be skipped during initialisation, and
741will switch to epoll when the loop is active.
742.Sp
743Most problematic in practice, however, is that not all file descriptors
744work with it. For example, in Linux 5.1, \s-1TCP\s0 sockets, pipes, event fds,
745files, \fI/dev/null\fR and many others are supported, but ttys do not work
746properly (a known bug that the kernel developers don't care about, see
747<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
748(yet?) a generic event polling interface.
749.Sp
750Overall, it seems the Linux developers just don't want it to have a
751generic event handling mechanism other than \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`poll\*(C'\fR.
752.Sp
753To work around all these problem, the current version of libev uses its
754epoll backend as a fallback for file descriptor types that do not work. Or
755falls back completely to epoll if the kernel acts up.
666.Sp 756.Sp
667This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 757This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
668\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 758\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
669.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 759.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
670.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 760.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
671.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 761.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
672Kqueue deserves special mention, as at the time of this writing, it 762Kqueue deserves special mention, as at the time this backend was
673was broken on all BSDs except NetBSD (usually it doesn't work reliably 763implemented, it was broken on all BSDs except NetBSD (usually it doesn't
674with anything but sockets and pipes, except on Darwin, where of course 764work reliably with anything but sockets and pipes, except on Darwin,
675it's completely useless). Unlike epoll, however, whose brokenness 765where of course it's completely useless). Unlike epoll, however, whose
676is by design, these kqueue bugs can (and eventually will) be fixed 766brokenness is by design, these kqueue bugs can be (and mostly have been)
677without \s-1API\s0 changes to existing programs. For this reason it's not being 767fixed without \s-1API\s0 changes to existing programs. For this reason it's not
678\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using 768being \*(L"auto-detected\*(R" on all platforms unless you explicitly specify it
679\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) 769in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a
680system like NetBSD. 770known-to-be-good (\-enough) system like NetBSD.
681.Sp 771.Sp
682You still can embed kqueue into a normal poll or select backend and use it 772You still can embed kqueue into a normal poll or select backend and use it
683only for sockets (after having made sure that sockets work with kqueue on 773only for sockets (after having made sure that sockets work with kqueue on
684the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 774the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
685.Sp 775.Sp
686It scales in the same way as the epoll backend, but the interface to the 776It scales in the same way as the epoll backend, but the interface to the
687kernel is more efficient (which says nothing about its actual speed, of 777kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 778course). While stopping, setting and starting an I/O watcher does never
689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 779cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you 780two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
691might have to leak fd's on fork, but it's more sane than epoll) and it 781might have to leak fds on fork, but it's more sane than epoll) and it
692drops fds silently in similarly hard-to-detect cases. 782drops fds silently in similarly hard-to-detect cases.
693.Sp 783.Sp
694This backend usually performs well under most conditions. 784This backend usually performs well under most conditions.
695.Sp 785.Sp
696While nominally embeddable in other event loops, this doesn't work 786While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 787everywhere, so you might need to test for this. And since it is broken
698almost everywhere, you should only use it when you have a lot of sockets 788almost everywhere, you should only use it when you have a lot of sockets
699(for which it usually works), by embedding it into another event loop 789(for which it usually works), by embedding it into another event loop
700(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 790(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
701also broken on \s-1OS\s0 X)) and, did I mention it, using it only for sockets. 791also broken on \s-1OS X\s0)) and, did I mention it, using it only for sockets.
702.Sp 792.Sp
703This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with 793This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with
704\&\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 794\&\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
705\&\f(CW\*(C`NOTE_EOF\*(C'\fR. 795\&\f(CW\*(C`NOTE_EOF\*(C'\fR.
706.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 796.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
… …
710implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets 800implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets
711and is not embeddable, which would limit the usefulness of this backend 801and is not embeddable, which would limit the usefulness of this backend
712immensely. 802immensely.
713.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 803.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
714.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 804.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
715.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" 805.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
716This uses the Solaris 10 event port mechanism. As with everything on Solaris, 806This uses the Solaris 10 event port mechanism. As with everything on Solaris,
717it's really slow, but it still scales very well (O(active_fds)). 807it's really slow, but it still scales very well (O(active_fds)).
718.Sp 808.Sp
719While this backend scales well, it requires one system call per active 809While this backend scales well, it requires one system call per active
720file descriptor per loop iteration. For small and medium numbers of file 810file descriptor per loop iteration. For small and medium numbers of file
… …
774used if available. 864used if available.
775.Sp 865.Sp
776.Vb 1 866.Vb 1
777\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 867\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
778.Ve 868.Ve
869.Sp
870Example: Similarly, on linux, you mgiht want to take advantage of the
871linux aio backend if possible, but fall back to something else if that
872isn't available.
873.Sp
874.Vb 1
875\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
876.Ve
779.RE 877.RE
780.IP "ev_loop_destroy (loop)" 4 878.IP "ev_loop_destroy (loop)" 4
781.IX Item "ev_loop_destroy (loop)" 879.IX Item "ev_loop_destroy (loop)"
782Destroys an event loop object (frees all memory and kernel state 880Destroys an event loop object (frees all memory and kernel state
783etc.). None of the active event watchers will be stopped in the normal 881etc.). None of the active event watchers will be stopped in the normal
… …
799except in the rare occasion where you really need to free its resources. 897except in the rare occasion where you really need to free its resources.
800If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR 898If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR
801and \f(CW\*(C`ev_loop_destroy\*(C'\fR. 899and \f(CW\*(C`ev_loop_destroy\*(C'\fR.
802.IP "ev_loop_fork (loop)" 4 900.IP "ev_loop_fork (loop)" 4
803.IX Item "ev_loop_fork (loop)" 901.IX Item "ev_loop_fork (loop)"
804This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to 902This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations
805reinitialise the kernel state for backends that have one. Despite the 903to reinitialise the kernel state for backends that have one. Despite
806name, you can call it anytime, but it makes most sense after forking, in 904the name, you can call it anytime you are allowed to start or stop
807the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the 905watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
808child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 906sense after forking, in the child process. You \fImust\fR call it (or use
907\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
809.Sp 908.Sp
909In addition, if you want to reuse a loop (via this function or
910\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR.
911.Sp
810Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 912Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
811a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is 913a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
812because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things 914because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
813during fork. 915during fork.
814.Sp 916.Sp
815On the other hand, you only need to call this function in the child 917On the other hand, you only need to call this function in the child
… …
1349bug in your program. 1451bug in your program.
1350.Sp 1452.Sp
1351Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1453Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1352example it might indicate that a fd is readable or writable, and if your 1454example it might indicate that a fd is readable or writable, and if your
1353callbacks is well-written it can just attempt the operation and cope with 1455callbacks is well-written it can just attempt the operation and cope with
1354the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1456the error from \fBread()\fR or \fBwrite()\fR. This will not work in multi-threaded
1355programs, though, as the fd could already be closed and reused for another 1457programs, though, as the fd could already be closed and reused for another
1356thing, so beware. 1458thing, so beware.
1357.SS "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" 1459.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1358.IX Subsection "GENERIC WATCHER FUNCTIONS" 1460.IX Subsection "GENERIC WATCHER FUNCTIONS"
1359.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1461.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
1360.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 1462.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
1361.IX Item "ev_init (ev_TYPE *watcher, callback)" 1463.IX Item "ev_init (ev_TYPE *watcher, callback)"
1362This macro initialises the generic portion of a watcher. The contents 1464This macro initialises the generic portion of a watcher. The contents
… …
1470or might not have been clamped to the valid range. 1572or might not have been clamped to the valid range.
1471.Sp 1573.Sp
1472The default priority used by watchers when no priority has been set is 1574The default priority used by watchers when no priority has been set is
1473always \f(CW0\fR, which is supposed to not be too high and not be too low :). 1575always \f(CW0\fR, which is supposed to not be too high and not be too low :).
1474.Sp 1576.Sp
1475See \*(L"\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0\*(R", below, for a more thorough treatment of 1577See \*(L"\s-1WATCHER PRIORITY MODELS\*(R"\s0, below, for a more thorough treatment of
1476priorities. 1578priorities.
1477.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 1579.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
1478.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" 1580.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)"
1479Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither 1581Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither
1480\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback 1582\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback
… …
1500not started in the first place. 1602not started in the first place.
1501.Sp 1603.Sp
1502See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related 1604See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related
1503functions that do not need a watcher. 1605functions that do not need a watcher.
1504.PP 1606.PP
1505See 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 1607See also the \*(L"\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\*(R"\s0 and \*(L"\s-1BUILDING YOUR
1506\&\s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0\*(R" idioms. 1608OWN COMPOSITE WATCHERS\*(R"\s0 idioms.
1507.SS "\s-1WATCHER\s0 \s-1STATES\s0" 1609.SS "\s-1WATCHER STATES\s0"
1508.IX Subsection "WATCHER STATES" 1610.IX Subsection "WATCHER STATES"
1509There are various watcher states mentioned throughout this manual \- 1611There are various watcher states mentioned throughout this manual \-
1510active, pending and so on. In this section these states and the rules to 1612active, pending and so on. In this section these states and the rules to
1511transition between them will be described in more detail \- and while these 1613transition between them will be described in more detail \- and while these
1512rules might look complicated, they usually do \*(L"the right thing\*(R". 1614rules might look complicated, they usually do \*(L"the right thing\*(R".
… …
1555.Sp 1657.Sp
1556While stopped (and not pending) the watcher is essentially in the 1658While stopped (and not pending) the watcher is essentially in the
1557initialised state, that is, it can be reused, moved, modified in any way 1659initialised state, that is, it can be reused, moved, modified in any way
1558you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR 1660you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR
1559it again). 1661it again).
1560.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" 1662.SS "\s-1WATCHER PRIORITY MODELS\s0"
1561.IX Subsection "WATCHER PRIORITY MODELS" 1663.IX Subsection "WATCHER PRIORITY MODELS"
1562Many event loops support \fIwatcher priorities\fR, which are usually small 1664Many event loops support \fIwatcher priorities\fR, which are usually small
1563integers that influence the ordering of event callback invocation 1665integers that influence the ordering of event callback invocation
1564between watchers in some way, all else being equal. 1666between watchers in some way, all else being equal.
1565.PP 1667.PP
1566In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its 1668In libev, watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its
1567description for the more technical details such as the actual priority 1669description for the more technical details such as the actual priority
1568range. 1670range.
1569.PP 1671.PP
1570There are two common ways how these these priorities are being interpreted 1672There are two common ways how these these priorities are being interpreted
1571by event loops: 1673by event loops:
… …
1710But really, best use non-blocking mode. 1812But really, best use non-blocking mode.
1711.PP 1813.PP
1712\fIThe special problem of disappearing file descriptors\fR 1814\fIThe special problem of disappearing file descriptors\fR
1713.IX Subsection "The special problem of disappearing file descriptors" 1815.IX Subsection "The special problem of disappearing file descriptors"
1714.PP 1816.PP
1715Some backends (e.g. kqueue, epoll) need to be told about closing a file 1817Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1716descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1818a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1717such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1819means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1718descriptor, but when it goes away, the operating system will silently drop 1820file descriptor, but when it goes away, the operating system will silently
1719this interest. If another file descriptor with the same number then is 1821drop this interest. If another file descriptor with the same number then
1720registered with libev, there is no efficient way to see that this is, in 1822is registered with libev, there is no efficient way to see that this is,
1721fact, a different file descriptor. 1823in fact, a different file descriptor.
1722.PP 1824.PP
1723To avoid having to explicitly tell libev about such cases, libev follows 1825To avoid having to explicitly tell libev about such cases, libev follows
1724the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1826the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1725will assume that this is potentially a new file descriptor, otherwise 1827will assume that this is potentially a new file descriptor, otherwise
1726it is assumed that the file descriptor stays the same. That means that 1828it is assumed that the file descriptor stays the same. That means that
… …
1763wish to read \- you would first have to request some data. 1865wish to read \- you would first have to request some data.
1764.PP 1866.PP
1765Since files are typically not-so-well supported by advanced notification 1867Since files are typically not-so-well supported by advanced notification
1766mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect 1868mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect
1767to files, even though you should not use it. The reason for this is 1869to files, even though you should not use it. The reason for this is
1768convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT\s0, which is 1870convenience: sometimes you want to watch \s-1STDIN\s0 or \s-1STDOUT,\s0 which is
1769usually a tty, often a pipe, but also sometimes files or special devices 1871usually a tty, often a pipe, but also sometimes files or special devices
1770(for example, \f(CW\*(C`epoll\*(C'\fR on Linux works with \fI/dev/random\fR but not with 1872(for example, \f(CW\*(C`epoll\*(C'\fR on Linux works with \fI/dev/random\fR but not with
1771\&\fI/dev/urandom\fR), and even though the file might better be served with 1873\&\fI/dev/urandom\fR), and even though the file might better be served with
1772asynchronous I/O instead of with non-blocking I/O, it is still useful when 1874asynchronous I/O instead of with non-blocking I/O, it is still useful when
1773it \*(L"just works\*(R" instead of freezing. 1875it \*(L"just works\*(R" instead of freezing.
1774.PP 1876.PP
1775So avoid file descriptors pointing to files when you know it (e.g. use 1877So avoid file descriptors pointing to files when you know it (e.g. use
1776libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT\s0, or 1878libeio), but use them when it is convenient, e.g. for \s-1STDIN/STDOUT,\s0 or
1777when you rarely read from a file instead of from a socket, and want to 1879when you rarely read from a file instead of from a socket, and want to
1778reuse the same code path. 1880reuse the same code path.
1779.PP 1881.PP
1780\fIThe special problem of fork\fR 1882\fIThe special problem of fork\fR
1781.IX Subsection "The special problem of fork" 1883.IX Subsection "The special problem of fork"
1782.PP 1884.PP
1783Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1885Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1784useless behaviour. Libev fully supports fork, but needs to be told about 1886at all or exhibit useless behaviour. Libev fully supports fork, but needs
1785it in the child if you want to continue to use it in the child. 1887to be told about it in the child if you want to continue to use it in the
1888child.
1786.PP 1889.PP
1787To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1890To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1788()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1891()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1789\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1892\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1790.PP 1893.PP
1791\fIThe special problem of \s-1SIGPIPE\s0\fR 1894\fIThe special problem of \s-1SIGPIPE\s0\fR
1792.IX Subsection "The special problem of SIGPIPE" 1895.IX Subsection "The special problem of SIGPIPE"
1793.PP 1896.PP
1794While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR: 1897While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR:
1795when writing to a pipe whose other end has been closed, your program gets 1898when writing to a pipe whose other end has been closed, your program gets
1796sent a \s-1SIGPIPE\s0, which, by default, aborts your program. For most programs 1899sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1797this is sensible behaviour, for daemons, this is usually undesirable. 1900this is sensible behaviour, for daemons, this is usually undesirable.
1798.PP 1901.PP
1799So when you encounter spurious, unexplained daemon exits, make sure you 1902So when you encounter spurious, unexplained daemon exits, make sure you
1800ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon 1903ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1801somewhere, as that would have given you a big clue). 1904somewhere, as that would have given you a big clue).
1802.PP 1905.PP
1803\fIThe special problem of \fIaccept()\fIing when you can't\fR 1906\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1804.IX Subsection "The special problem of accept()ing when you can't" 1907.IX Subsection "The special problem of accept()ing when you can't"
1805.PP 1908.PP
1806Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example, 1909Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
1807found in post\-2004 Linux) have the peculiar behaviour of not removing a 1910found in post\-2004 Linux) have the peculiar behaviour of not removing a
1808connection from the pending queue in all error cases. 1911connection from the pending queue in all error cases.
… …
2150.PP 2253.PP
2151The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2254The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
2152time. This is usually the right thing as this timestamp refers to the time 2255time. This is usually the right thing as this timestamp refers to the time
2153of the event triggering whatever timeout you are modifying/starting. If 2256of the event triggering whatever timeout you are modifying/starting. If
2154you suspect event processing to be delayed and you \fIneed\fR to base the 2257you suspect event processing to be delayed and you \fIneed\fR to base the
2155timeout on the current time, use something like this to adjust for this: 2258timeout on the current time, use something like the following to adjust
2259for it:
2156.PP 2260.PP
2157.Vb 1 2261.Vb 1
2158\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.); 2262\& ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.);
2159.Ve 2263.Ve
2160.PP 2264.PP
2161If the event loop is suspended for a long time, you can also force an 2265If the event loop is suspended for a long time, you can also force an
2162update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update 2266update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2163()\*(C'\fR. 2267()\*(C'\fR, although that will push the event time of all outstanding events
2268further into the future.
2164.PP 2269.PP
2165\fIThe special problem of unsynchronised clocks\fR 2270\fIThe special problem of unsynchronised clocks\fR
2166.IX Subsection "The special problem of unsynchronised clocks" 2271.IX Subsection "The special problem of unsynchronised clocks"
2167.PP 2272.PP
2168Modern systems have a variety of clocks \- libev itself uses the normal 2273Modern systems have a variety of clocks \- libev itself uses the normal
… …
2233.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 2338.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
2234.PD 0 2339.PD 0
2235.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 2340.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
2236.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 2341.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
2237.PD 2342.PD
2238Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR 2343Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
2239is \f(CW0.\fR, then it will automatically be stopped once the timeout is 2344negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
2240reached. If it is positive, then the timer will automatically be 2345automatically be stopped once the timeout is reached. If it is positive,
2241configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, 2346then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
2242until stopped manually. 2347seconds later, again, and again, until stopped manually.
2243.Sp 2348.Sp
2244The timer itself will do a best-effort at avoiding drift, that is, if 2349The timer itself will do a best-effort at avoiding drift, that is, if
2245you configure a timer to trigger every 10 seconds, then it will normally 2350you configure a timer to trigger every 10 seconds, then it will normally
2246trigger at exactly 10 second intervals. If, however, your program cannot 2351trigger at exactly 10 second intervals. If, however, your program cannot
2247keep up with the timer (because it takes longer than those 10 seconds to 2352keep up with the timer (because it takes longer than those 10 seconds to
… …
2329Periodic watchers are also timers of a kind, but they are very versatile 2434Periodic watchers are also timers of a kind, but they are very versatile
2330(and unfortunately a bit complex). 2435(and unfortunately a bit complex).
2331.PP 2436.PP
2332Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or 2437Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or
2333relative time, the physical time that passes) but on wall clock time 2438relative time, the physical time that passes) but on wall clock time
2334(absolute time, the thing you can read on your calender or clock). The 2439(absolute time, the thing you can read on your calendar or clock). The
2335difference is that wall clock time can run faster or slower than real 2440difference is that wall clock time can run faster or slower than real
2336time, and time jumps are not uncommon (e.g. when you adjust your 2441time, and time jumps are not uncommon (e.g. when you adjust your
2337wrist-watch). 2442wrist-watch).
2338.PP 2443.PP
2339You can tell a periodic watcher to trigger after some specific point 2444You can tell a periodic watcher to trigger after some specific point
… …
2344\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting 2449\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
2345it, as it uses a relative timeout). 2450it, as it uses a relative timeout).
2346.PP 2451.PP
2347\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex 2452\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
2348timers, such as triggering an event on each \*(L"midnight, local time\*(R", or 2453timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
2349other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as 2454other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
2350those cannot react to time jumps. 2455watchers, as those cannot react to time jumps.
2351.PP 2456.PP
2352As with timers, the callback is guaranteed to be invoked only when the 2457As with timers, the callback is guaranteed to be invoked only when the
2353point in time where it is supposed to trigger has passed. If multiple 2458point in time where it is supposed to trigger has passed. If multiple
2354timers become ready during the same loop iteration then the ones with 2459timers become ready during the same loop iteration then the ones with
2355earlier time-out values are invoked before ones with later time-out values 2460earlier time-out values are invoked before ones with later time-out values
… …
2416In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2521In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
2417ignored. Instead, each time the periodic watcher gets scheduled, the 2522ignored. Instead, each time the periodic watcher gets scheduled, the
2418reschedule callback will be called with the watcher as first, and the 2523reschedule callback will be called with the watcher as first, and the
2419current time as second argument. 2524current time as second argument.
2420.Sp 2525.Sp
2421\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, ever, 2526\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
2422or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2527or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2423allowed by documentation here\fR. 2528allowed by documentation here\fR.
2424.Sp 2529.Sp
2425If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2530If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
2426it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 2531it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2444.Sp 2549.Sp
2445\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or 2550\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
2446equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2551equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2447.Sp 2552.Sp
2448This can be used to create very complex timers, such as a timer that 2553This can be used to create very complex timers, such as a timer that
2449triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the 2554triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2450next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2555the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
2451you do this is, again, up to you (but it is not trivial, which is the main 2556this. Here is a (completely untested, no error checking) example on how to
2452reason I omitted it as an example). 2557do this:
2558.Sp
2559.Vb 1
2560\& #include <time.h>
2561\&
2562\& static ev_tstamp
2563\& my_rescheduler (ev_periodic *w, ev_tstamp now)
2564\& {
2565\& time_t tnow = (time_t)now;
2566\& struct tm tm;
2567\& localtime_r (&tnow, &tm);
2568\&
2569\& tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2570\& ++tm.tm_mday; // midnight next day
2571\&
2572\& return mktime (&tm);
2573\& }
2574.Ve
2575.Sp
2576Note: this code might run into trouble on days that have more then two
2577midnights (beginning and end).
2453.RE 2578.RE
2454.RS 4 2579.RS 4
2455.RE 2580.RE
2456.IP "ev_periodic_again (loop, ev_periodic *)" 4 2581.IP "ev_periodic_again (loop, ev_periodic *)" 4
2457.IX Item "ev_periodic_again (loop, ev_periodic *)" 2582.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
2542only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your 2667only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your
2543default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for 2668default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for
2544\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At 2669\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At
2545the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. 2670the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop.
2546.PP 2671.PP
2547When the first watcher gets started will libev actually register something 2672Only after the first watcher for a signal is started will libev actually
2548with the kernel (thus it coexists with your own signal handlers as long as 2673register something with the kernel. It thus coexists with your own signal
2549you don't register any with libev for the same signal). 2674handlers as long as you don't register any with libev for the same signal.
2550.PP 2675.PP
2551If possible and supported, libev will install its handlers with 2676If possible and supported, libev will install its handlers with
2552\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should 2677\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should
2553not be unduly interrupted. If you have a problem with system calls getting 2678not be unduly interrupted. If you have a problem with system calls getting
2554interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher 2679interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher
… …
2615The signal the watcher watches out for. 2740The signal the watcher watches out for.
2616.PP 2741.PP
2617\fIExamples\fR 2742\fIExamples\fR
2618.IX Subsection "Examples" 2743.IX Subsection "Examples"
2619.PP 2744.PP
2620Example: Try to exit cleanly on \s-1SIGINT\s0. 2745Example: Try to exit cleanly on \s-1SIGINT.\s0
2621.PP 2746.PP
2622.Vb 5 2747.Vb 5
2623\& static void 2748\& static void
2624\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2749\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
2625\& { 2750\& {
… …
2782compilation environment, which means that on systems with large file 2907compilation environment, which means that on systems with large file
2783support disabled by default, you get the 32 bit version of the stat 2908support disabled by default, you get the 32 bit version of the stat
2784structure. When using the library from programs that change the \s-1ABI\s0 to 2909structure. When using the library from programs that change the \s-1ABI\s0 to
2785use 64 bit file offsets the programs will fail. In that case you have to 2910use 64 bit file offsets the programs will fail. In that case you have to
2786compile libev with the same flags to get binary compatibility. This is 2911compile libev with the same flags to get binary compatibility. This is
2787obviously the case with any flags that change the \s-1ABI\s0, but the problem is 2912obviously the case with any flags that change the \s-1ABI,\s0 but the problem is
2788most noticeably displayed with ev_stat and large file support. 2913most noticeably displayed with ev_stat and large file support.
2789.PP 2914.PP
2790The solution for this is to lobby your distribution maker to make large 2915The solution for this is to lobby your distribution maker to make large
2791file interfaces available by default (as e.g. FreeBSD does) and not 2916file interfaces available by default (as e.g. FreeBSD does) and not
2792optional. Libev cannot simply switch on large file support because it has 2917optional. Libev cannot simply switch on large file support because it has
… …
3037.IX Subsection "ev_prepare and ev_check - customise your event loop!" 3162.IX Subsection "ev_prepare and ev_check - customise your event loop!"
3038Prepare and check watchers are often (but not always) used in pairs: 3163Prepare and check watchers are often (but not always) used in pairs:
3039prepare watchers get invoked before the process blocks and check watchers 3164prepare watchers get invoked before the process blocks and check watchers
3040afterwards. 3165afterwards.
3041.PP 3166.PP
3042You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3167You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR (or similar functions that enter the
3043the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR 3168current event loop) or \f(CW\*(C`ev_loop_fork\*(C'\fR from either \f(CW\*(C`ev_prepare\*(C'\fR or
3044watchers. Other loops than the current one are fine, however. The 3169\&\f(CW\*(C`ev_check\*(C'\fR watchers. Other loops than the current one are fine,
3045rationale behind this is that you do not need to check for recursion in 3170however. The rationale behind this is that you do not need to check
3046those watchers, i.e. the sequence will always be \f(CW\*(C`ev_prepare\*(C'\fR, blocking, 3171for recursion in those watchers, i.e. the sequence will always be
3047\&\f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each kind they will always be 3172\&\f(CW\*(C`ev_prepare\*(C'\fR, blocking, \f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each
3048called in pairs bracketing the blocking call. 3173kind they will always be called in pairs bracketing the blocking call.
3049.PP 3174.PP
3050Their main purpose is to integrate other event mechanisms into libev and 3175Their main purpose is to integrate other event mechanisms into libev and
3051their use is somewhat advanced. They could be used, for example, to track 3176their use is somewhat advanced. They could be used, for example, to track
3052variable changes, implement your own watchers, integrate net-snmp or a 3177variable changes, implement your own watchers, integrate net-snmp or a
3053coroutine library and lots more. They are also occasionally useful if 3178coroutine library and lots more. They are also occasionally useful if
… …
3223.Ve 3348.Ve
3224.PP 3349.PP
3225Method 4: Do not use a prepare or check watcher because the module you 3350Method 4: Do not use a prepare or check watcher because the module you
3226want to embed is not flexible enough to support it. Instead, you can 3351want to embed is not flexible enough to support it. Instead, you can
3227override their poll function. The drawback with this solution is that the 3352override their poll function. The drawback with this solution is that the
3228main loop is now no longer controllable by \s-1EV\s0. The \f(CW\*(C`Glib::EV\*(C'\fR module uses 3353main loop is now no longer controllable by \s-1EV.\s0 The \f(CW\*(C`Glib::EV\*(C'\fR module uses
3229this approach, effectively embedding \s-1EV\s0 as a client into the horrible 3354this approach, effectively embedding \s-1EV\s0 as a client into the horrible
3230libglib event loop. 3355libglib event loop.
3231.PP 3356.PP
3232.Vb 4 3357.Vb 4
3233\& static gint 3358\& static gint
… …
3347.PP 3472.PP
3348.Vb 3 3473.Vb 3
3349\& struct ev_loop *loop_hi = ev_default_init (0); 3474\& struct ev_loop *loop_hi = ev_default_init (0);
3350\& struct ev_loop *loop_lo = 0; 3475\& struct ev_loop *loop_lo = 0;
3351\& ev_embed embed; 3476\& ev_embed embed;
3352\& 3477\&
3353\& // see if there is a chance of getting one that works 3478\& // see if there is a chance of getting one that works
3354\& // (remember that a flags value of 0 means autodetection) 3479\& // (remember that a flags value of 0 means autodetection)
3355\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3480\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
3356\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3481\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
3357\& : 0; 3482\& : 0;
… …
3373.PP 3498.PP
3374.Vb 3 3499.Vb 3
3375\& struct ev_loop *loop = ev_default_init (0); 3500\& struct ev_loop *loop = ev_default_init (0);
3376\& struct ev_loop *loop_socket = 0; 3501\& struct ev_loop *loop_socket = 0;
3377\& ev_embed embed; 3502\& ev_embed embed;
3378\& 3503\&
3379\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3504\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
3380\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3505\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
3381\& { 3506\& {
3382\& ev_embed_init (&embed, 0, loop_socket); 3507\& ev_embed_init (&embed, 0, loop_socket);
3383\& ev_embed_start (loop, &embed); 3508\& ev_embed_start (loop, &embed);
… …
3400of course. 3525of course.
3401.PP 3526.PP
3402\fIThe special problem of life after fork \- how is it possible?\fR 3527\fIThe special problem of life after fork \- how is it possible?\fR
3403.IX Subsection "The special problem of life after fork - how is it possible?" 3528.IX Subsection "The special problem of life after fork - how is it possible?"
3404.PP 3529.PP
3405Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3530Most uses of \f(CW\*(C`fork ()\*(C'\fR consist of forking, then some simple calls to set
3406up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This 3531up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This
3407sequence should be handled by libev without any problems. 3532sequence should be handled by libev without any problems.
3408.PP 3533.PP
3409This changes when the application actually wants to do event handling 3534This changes when the application actually wants to do event handling
3410in the child, or both parent in child, in effect \*(L"continuing\*(R" after the 3535in the child, or both parent in child, in effect \*(L"continuing\*(R" after the
… …
3627is a time window between the event loop checking and resetting the async 3752is a time window between the event loop checking and resetting the async
3628notification, and the callback being invoked. 3753notification, and the callback being invoked.
3629.SH "OTHER FUNCTIONS" 3754.SH "OTHER FUNCTIONS"
3630.IX Header "OTHER FUNCTIONS" 3755.IX Header "OTHER FUNCTIONS"
3631There are some other functions of possible interest. Described. Here. Now. 3756There are some other functions of possible interest. Described. Here. Now.
3632.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 3757.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
3633.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 3758.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
3634This function combines a simple timer and an I/O watcher, calls your 3759This function combines a simple timer and an I/O watcher, calls your
3635callback on whichever event happens first and automatically stops both 3760callback on whichever event happens first and automatically stops both
3636watchers. This is useful if you want to wait for a single event on an fd 3761watchers. This is useful if you want to wait for a single event on an fd
3637or timeout without having to allocate/configure/start/stop/free one or 3762or timeout without having to allocate/configure/start/stop/free one or
3638more watchers yourself. 3763more watchers yourself.
… …
3650\&\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 3775\&\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
3651value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR 3776value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR
3652a timeout and an io event at the same time \- you probably should give io 3777a timeout and an io event at the same time \- you probably should give io
3653events precedence. 3778events precedence.
3654.Sp 3779.Sp
3655Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0. 3780Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO.\s0
3656.Sp 3781.Sp
3657.Vb 7 3782.Vb 7
3658\& static void stdin_ready (int revents, void *arg) 3783\& static void stdin_ready (int revents, void *arg)
3659\& { 3784\& {
3660\& if (revents & EV_READ) 3785\& if (revents & EV_READ)
… …
3676.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3801.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
3677.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)" 3802.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)"
3678This section explains some common idioms that are not immediately 3803This section explains some common idioms that are not immediately
3679obvious. Note that examples are sprinkled over the whole manual, and this 3804obvious. Note that examples are sprinkled over the whole manual, and this
3680section only contains stuff that wouldn't fit anywhere else. 3805section only contains stuff that wouldn't fit anywhere else.
3681.SS "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" 3806.SS "\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\s0"
3682.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" 3807.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
3683Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read 3808Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read
3684or modify at any time: libev will completely ignore it. This can be used 3809or modify at any time: libev will completely ignore it. This can be used
3685to associate arbitrary data with your watcher. If you need more data and 3810to associate arbitrary data with your watcher. If you need more data and
3686don't want to allocate memory separately and store a pointer to it in that 3811don't want to allocate memory separately and store a pointer to it in that
… …
3712\& } 3837\& }
3713.Ve 3838.Ve
3714.PP 3839.PP
3715More interesting and less C\-conformant ways of casting your callback 3840More interesting and less C\-conformant ways of casting your callback
3716function type instead have been omitted. 3841function type instead have been omitted.
3717.SS "\s-1BUILDING\s0 \s-1YOUR\s0 \s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0" 3842.SS "\s-1BUILDING YOUR OWN COMPOSITE WATCHERS\s0"
3718.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS" 3843.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS"
3719Another common scenario is to use some data structure with multiple 3844Another common scenario is to use some data structure with multiple
3720embedded watchers, in effect creating your own watcher that combines 3845embedded watchers, in effect creating your own watcher that combines
3721multiple libev event sources into one \*(L"super-watcher\*(R": 3846multiple libev event sources into one \*(L"super-watcher\*(R":
3722.PP 3847.PP
… …
3750\& { 3875\& {
3751\& struct my_biggy big = (struct my_biggy *) 3876\& struct my_biggy big = (struct my_biggy *)
3752\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3877\& (((char *)w) \- offsetof (struct my_biggy, t2));
3753\& } 3878\& }
3754.Ve 3879.Ve
3755.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0" 3880.SS "\s-1AVOIDING FINISHING BEFORE RETURNING\s0"
3756.IX Subsection "AVOIDING FINISHING BEFORE RETURNING" 3881.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3757Often you have structures like this in event-based programs: 3882Often you have structures like this in event-based programs:
3758.PP 3883.PP
3759.Vb 4 3884.Vb 4
3760\& callback () 3885\& callback ()
… …
3793\& ev_feed_event (EV_A_ watcher, 0); 3918\& ev_feed_event (EV_A_ watcher, 0);
3794.Ve 3919.Ve
3795.PP 3920.PP
3796This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is 3921This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3797invoked, while not delaying callback invocation too much. 3922invoked, while not delaying callback invocation too much.
3798.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0" 3923.SS "\s-1MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS\s0"
3799.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" 3924.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3800Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3925Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3801\&\fImodal\fR interaction, which is most easily implemented by recursively 3926\&\fImodal\fR interaction, which is most easily implemented by recursively
3802invoking \f(CW\*(C`ev_run\*(C'\fR. 3927invoking \f(CW\*(C`ev_run\*(C'\fR.
3803.PP 3928.PP
… …
3835\& exit_main_loop = 1; 3960\& exit_main_loop = 1;
3836\& 3961\&
3837\& // exit both 3962\& // exit both
3838\& exit_main_loop = exit_nested_loop = 1; 3963\& exit_main_loop = exit_nested_loop = 1;
3839.Ve 3964.Ve
3840.SS "\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0" 3965.SS "\s-1THREAD LOCKING EXAMPLE\s0"
3841.IX Subsection "THREAD LOCKING EXAMPLE" 3966.IX Subsection "THREAD LOCKING EXAMPLE"
3842Here is a fictitious example of how to run an event loop in a different 3967Here is a fictitious example of how to run an event loop in a different
3843thread from where callbacks are being invoked and watchers are 3968thread from where callbacks are being invoked and watchers are
3844created/added/removed. 3969created/added/removed.
3845.PP 3970.PP
… …
3986.PP 4111.PP
3987Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise 4112Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise
3988an event loop currently blocking in the kernel will have no knowledge 4113an event loop currently blocking in the kernel will have no knowledge
3989about the newly added timer. By waking up the loop it will pick up any new 4114about the newly added timer. By waking up the loop it will pick up any new
3990watchers in the next event loop iteration. 4115watchers in the next event loop iteration.
3991.SS "\s-1THREADS\s0, \s-1COROUTINES\s0, \s-1CONTINUATIONS\s0, \s-1QUEUES\s0... \s-1INSTEAD\s0 \s-1OF\s0 \s-1CALLBACKS\s0" 4116.SS "\s-1THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS\s0"
3992.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS" 4117.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS"
3993While the overhead of a callback that e.g. schedules a thread is small, it 4118While the overhead of a callback that e.g. schedules a thread is small, it
3994is still an overhead. If you embed libev, and your main usage is with some 4119is still an overhead. If you embed libev, and your main usage is with some
3995kind of threads or coroutines, you might want to customise libev so that 4120kind of threads or coroutines, you might want to customise libev so that
3996doesn't need callbacks anymore. 4121doesn't need callbacks anymore.
… …
4032You can do similar tricks if you have, say, threads with an event queue \- 4157You can do similar tricks if you have, say, threads with an event queue \-
4033instead of storing a coroutine, you store the queue object and instead of 4158instead of storing a coroutine, you store the queue object and instead of
4034switching to a coroutine, you push the watcher onto the queue and notify 4159switching to a coroutine, you push the watcher onto the queue and notify
4035any waiters. 4160any waiters.
4036.PP 4161.PP
4037To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two 4162To embed libev, see \*(L"\s-1EMBEDDING\*(R"\s0, but in short, it's easiest to create two
4038files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4163files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
4039.PP 4164.PP
4040.Vb 4 4165.Vb 4
4041\& // my_ev.h 4166\& // my_ev.h
4042\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4167\& #define EV_CB_DECLARE(type) struct my_coro *cb;
4043\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb); 4168\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb)
4044\& #include "../libev/ev.h" 4169\& #include "../libev/ev.h"
4045\& 4170\&
4046\& // my_ev.c 4171\& // my_ev.c
4047\& #define EV_H "my_ev.h" 4172\& #define EV_H "my_ev.h"
4048\& #include "../libev/ev.c" 4173\& #include "../libev/ev.c"
… …
4088The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the 4213The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4089libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4214libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4090will work fine. 4215will work fine.
4091.PP 4216.PP
4092Proper exception specifications might have to be added to callbacks passed 4217Proper exception specifications might have to be added to callbacks passed
4093to libev: exceptions may be thrown only from watcher callbacks, all 4218to libev: exceptions may be thrown only from watcher callbacks, all other
4094other callbacks (allocator, syserr, loop acquire/release and periodic 4219callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4095reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4220callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
4096()\*(C'\fR specification. If you have code that needs to be compiled as both C 4221specification. If you have code that needs to be compiled as both C and
4097and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4222\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
4098.PP 4223.PP
4099.Vb 6 4224.Vb 6
4100\& static void 4225\& static void
4101\& fatal_error (const char *msg) EV_THROW 4226\& fatal_error (const char *msg) EV_NOEXCEPT
4102\& { 4227\& {
4103\& perror (msg); 4228\& perror (msg);
4104\& abort (); 4229\& abort ();
4105\& } 4230\& }
4106\& 4231\&
… …
4234\& void operator() (ev::io &w, int revents) 4359\& void operator() (ev::io &w, int revents)
4235\& { 4360\& {
4236\& ... 4361\& ...
4237\& } 4362\& }
4238\& } 4363\& }
4239\& 4364\&
4240\& myfunctor f; 4365\& myfunctor f;
4241\& 4366\&
4242\& ev::io w; 4367\& ev::io w;
4243\& w.set (&f); 4368\& w.set (&f);
4244.Ve 4369.Ve
… …
4337there are additional modules that implement libev-compatible interfaces 4462there are additional modules that implement libev-compatible interfaces
4338to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays), 4463to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays),
4339\&\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 4464\&\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
4340and \f(CW\*(C`EV::Glib\*(C'\fR). 4465and \f(CW\*(C`EV::Glib\*(C'\fR).
4341.Sp 4466.Sp
4342It can be found and installed via \s-1CPAN\s0, its homepage is at 4467It can be found and installed via \s-1CPAN,\s0 its homepage is at
4343<http://software.schmorp.de/pkg/EV>. 4468<http://software.schmorp.de/pkg/EV>.
4344.IP "Python" 4 4469.IP "Python" 4
4345.IX Item "Python" 4470.IX Item "Python"
4346Python bindings can be found at <http://code.google.com/p/pyev/>. It 4471Python bindings can be found at <http://code.google.com/p/pyev/>. It
4347seems to be quite complete and well-documented. 4472seems to be quite complete and well-documented.
… …
4355Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR 4480Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4356makes rev work even on mingw. 4481makes rev work even on mingw.
4357.IP "Haskell" 4 4482.IP "Haskell" 4
4358.IX Item "Haskell" 4483.IX Item "Haskell"
4359A haskell binding to libev is available at 4484A haskell binding to libev is available at
4360http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>. 4485<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>.
4361.IP "D" 4 4486.IP "D" 4
4362.IX Item "D" 4487.IX Item "D"
4363Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4488Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4364be found at <http://www.llucax.com.ar/proj/ev.d/index.html>. 4489be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4365.IP "Ocaml" 4 4490.IP "Ocaml" 4
4366.IX Item "Ocaml" 4491.IX Item "Ocaml"
4367Erkki Seppala has written Ocaml bindings for libev, to be found at 4492Erkki Seppala has written Ocaml bindings for libev, to be found at
4368http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 4493<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
4369.IP "Lua" 4 4494.IP "Lua" 4
4370.IX Item "Lua" 4495.IX Item "Lua"
4371Brian Maher has written a partial interface to libev for lua (at the 4496Brian Maher has written a partial interface to libev for lua (at the
4372time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4497time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4373http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. 4498<http://github.com/brimworks/lua\-ev>.
4374.IP "Javascript" 4 4499.IP "Javascript" 4
4375.IX Item "Javascript" 4500.IX Item "Javascript"
4376Node.js (<http://nodejs.org>) uses libev as the underlying event library. 4501Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4377.IP "Others" 4 4502.IP "Others" 4
4378.IX Item "Others" 4503.IX Item "Others"
… …
4467.SS "\s-1FILESETS\s0" 4592.SS "\s-1FILESETS\s0"
4468.IX Subsection "FILESETS" 4593.IX Subsection "FILESETS"
4469Depending on what features you need you need to include one or more sets of files 4594Depending on what features you need you need to include one or more sets of files
4470in your application. 4595in your application.
4471.PP 4596.PP
4472\fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR 4597\fI\s-1CORE EVENT LOOP\s0\fR
4473.IX Subsection "CORE EVENT LOOP" 4598.IX Subsection "CORE EVENT LOOP"
4474.PP 4599.PP
4475To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual 4600To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual
4476configuration (no autoconf): 4601configuration (no autoconf):
4477.PP 4602.PP
… …
4504\& ev_vars.h 4629\& ev_vars.h
4505\& ev_wrap.h 4630\& ev_wrap.h
4506\& 4631\&
4507\& ev_win32.c required on win32 platforms only 4632\& ev_win32.c required on win32 platforms only
4508\& 4633\&
4509\& ev_select.c only when select backend is enabled (which is enabled by default) 4634\& ev_select.c only when select backend is enabled
4510\& ev_poll.c only when poll backend is enabled (disabled by default) 4635\& ev_poll.c only when poll backend is enabled
4511\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 4636\& ev_epoll.c only when the epoll backend is enabled
4637\& ev_linuxaio.c only when the linux aio backend is enabled
4638\& ev_iouring.c only when the linux io_uring backend is enabled
4512\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4639\& ev_kqueue.c only when the kqueue backend is enabled
4513\& ev_port.c only when the solaris port backend is enabled (disabled by default) 4640\& ev_port.c only when the solaris port backend is enabled
4514.Ve 4641.Ve
4515.PP 4642.PP
4516\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4643\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4517to compile this single file. 4644to compile this single file.
4518.PP 4645.PP
4519\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR 4646\fI\s-1LIBEVENT COMPATIBILITY API\s0\fR
4520.IX Subsection "LIBEVENT COMPATIBILITY API" 4647.IX Subsection "LIBEVENT COMPATIBILITY API"
4521.PP 4648.PP
4522To include the libevent compatibility \s-1API\s0, also include: 4649To include the libevent compatibility \s-1API,\s0 also include:
4523.PP 4650.PP
4524.Vb 1 4651.Vb 1
4525\& #include "event.c" 4652\& #include "event.c"
4526.Ve 4653.Ve
4527.PP 4654.PP
… …
4529.PP 4656.PP
4530.Vb 1 4657.Vb 1
4531\& #include "event.h" 4658\& #include "event.h"
4532.Ve 4659.Ve
4533.PP 4660.PP
4534in the files that want to use the libevent \s-1API\s0. This also includes \fIev.h\fR. 4661in the files that want to use the libevent \s-1API.\s0 This also includes \fIev.h\fR.
4535.PP 4662.PP
4536You need the following additional files for this: 4663You need the following additional files for this:
4537.PP 4664.PP
4538.Vb 2 4665.Vb 2
4539\& event.h 4666\& event.h
4540\& event.c 4667\& event.c
4541.Ve 4668.Ve
4542.PP 4669.PP
4543\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR 4670\fI\s-1AUTOCONF SUPPORT\s0\fR
4544.IX Subsection "AUTOCONF SUPPORT" 4671.IX Subsection "AUTOCONF SUPPORT"
4545.PP 4672.PP
4546Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in 4673Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in
4547whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your 4674whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your
4548\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then 4675\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then
… …
4551For this of course you need the m4 file: 4678For this of course you need the m4 file:
4552.PP 4679.PP
4553.Vb 1 4680.Vb 1
4554\& libev.m4 4681\& libev.m4
4555.Ve 4682.Ve
4556.SS "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0" 4683.SS "\s-1PREPROCESSOR SYMBOLS/MACROS\s0"
4557.IX Subsection "PREPROCESSOR SYMBOLS/MACROS" 4684.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
4558Libev can be configured via a variety of preprocessor symbols you have to 4685Libev can be configured via a variety of preprocessor symbols you have to
4559define before including (or compiling) any of its files. The default in 4686define before including (or compiling) any of its files. The default in
4560the absence of autoconf is documented for every option. 4687the absence of autoconf is documented for every option.
4561.PP 4688.PP
4562Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI\s0, and can have different 4689Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI,\s0 and can have different
4563values when compiling libev vs. including \fIev.h\fR, so it is permissible 4690values when compiling libev vs. including \fIev.h\fR, so it is permissible
4564to redefine them before including \fIev.h\fR without breaking compatibility 4691to redefine them before including \fIev.h\fR without breaking compatibility
4565to a compiled library. All other symbols change the \s-1ABI\s0, which means all 4692to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4566users of libev and the libev code itself must be compiled with compatible 4693users of libev and the libev code itself must be compiled with compatible
4567settings. 4694settings.
4568.IP "\s-1EV_COMPAT3\s0 (h)" 4 4695.IP "\s-1EV_COMPAT3\s0 (h)" 4
4569.IX Item "EV_COMPAT3 (h)" 4696.IX Item "EV_COMPAT3 (h)"
4570Backwards compatibility is a major concern for libev. This is why this 4697Backwards compatibility is a major concern for libev. This is why this
… …
4629higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). 4756higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR).
4630.IP "\s-1EV_USE_NANOSLEEP\s0" 4 4757.IP "\s-1EV_USE_NANOSLEEP\s0" 4
4631.IX Item "EV_USE_NANOSLEEP" 4758.IX Item "EV_USE_NANOSLEEP"
4632If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 4759If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
4633and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 4760and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
4761.IP "\s-1EV_USE_EVENTFD\s0" 4
4762.IX Item "EV_USE_EVENTFD"
4763If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4764available and will probe for kernel support at runtime. This will improve
4765\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4766If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47672.7 or newer, otherwise disabled.
4768.IP "\s-1EV_USE_SIGNALFD\s0" 4
4769.IX Item "EV_USE_SIGNALFD"
4770If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`signalfd ()\*(C'\fR is
4771available and will probe for kernel support at runtime. This enables
4772the use of \s-1EVFLAG_SIGNALFD\s0 for faster and simpler signal handling. If
4773undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47742.7 or newer, otherwise disabled.
4775.IP "\s-1EV_USE_TIMERFD\s0" 4
4776.IX Item "EV_USE_TIMERFD"
4777If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`timerfd ()\*(C'\fR is
4778available and will probe for kernel support at runtime. This allows
4779libev to detect time jumps accurately. If undefined, it will be enabled
4780if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4781\&\f(CW\*(C`TFD_TIMER_CANCEL_ON_SET\*(C'\fR, otherwise disabled.
4634.IP "\s-1EV_USE_EVENTFD\s0" 4 4782.IP "\s-1EV_USE_EVENTFD\s0" 4
4635.IX Item "EV_USE_EVENTFD" 4783.IX Item "EV_USE_EVENTFD"
4636If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is 4784If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4637available and will probe for kernel support at runtime. This will improve 4785available and will probe for kernel support at runtime. This will improve
4638\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. 4786\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
… …
4697If defined to be \f(CW1\fR, libev will compile in support for the Linux 4845If defined to be \f(CW1\fR, libev will compile in support for the Linux
4698\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4846\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4699otherwise another method will be used as fallback. This is the preferred 4847otherwise another method will be used as fallback. This is the preferred
4700backend for GNU/Linux systems. If undefined, it will be enabled if the 4848backend for GNU/Linux systems. If undefined, it will be enabled if the
4701headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4849headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4850.IP "\s-1EV_USE_LINUXAIO\s0" 4
4851.IX Item "EV_USE_LINUXAIO"
4852If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4853backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4854enabled on linux, otherwise disabled.
4855.IP "\s-1EV_USE_IOURING\s0" 4
4856.IX Item "EV_USE_IOURING"
4857If defined to be \f(CW1\fR, libev will compile in support for the Linux
4858io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4859current limitations it has to be requested explicitly. If undefined, it
4860will be enabled on linux, otherwise disabled.
4702.IP "\s-1EV_USE_KQUEUE\s0" 4 4861.IP "\s-1EV_USE_KQUEUE\s0" 4
4703.IX Item "EV_USE_KQUEUE" 4862.IX Item "EV_USE_KQUEUE"
4704If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4863If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4705\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4864\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4706otherwise another method will be used as fallback. This is the preferred 4865otherwise another method will be used as fallback. This is the preferred
… …
4794all the priorities, so having many of them (hundreds) uses a lot of space 4953all the priorities, so having many of them (hundreds) uses a lot of space
4795and time, so using the defaults of five priorities (\-2 .. +2) is usually 4954and time, so using the defaults of five priorities (\-2 .. +2) is usually
4796fine. 4955fine.
4797.Sp 4956.Sp
4798If your embedding application does not need any priorities, defining these 4957If your embedding application does not need any priorities, defining these
4799both to \f(CW0\fR will save some memory and \s-1CPU\s0. 4958both to \f(CW0\fR will save some memory and \s-1CPU.\s0
4800.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 4959.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
4801.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." 4960.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."
4802If undefined or defined to be \f(CW1\fR (and the platform supports it), then 4961If undefined or defined to be \f(CW1\fR (and the platform supports it), then
4803the respective watcher type is supported. If defined to be \f(CW0\fR, then it 4962the respective watcher type is supported. If defined to be \f(CW0\fR, then it
4804is not. Disabling watcher types mainly saves code size. 4963is not. Disabling watcher types mainly saves code size.
4805.IP "\s-1EV_FEATURES\s0" 4 4964.IP "\s-1EV_FEATURES\s0" 4
… …
4963called. If set to \f(CW2\fR, then the internal verification code will be 5122called. If set to \f(CW2\fR, then the internal verification code will be
4964called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5123called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
4965verification code will be called very frequently, which will slow down 5124verification code will be called very frequently, which will slow down
4966libev considerably. 5125libev considerably.
4967.Sp 5126.Sp
5127Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5128disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5129.Sp
4968The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5130The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
4969will be \f(CW0\fR. 5131will be \f(CW0\fR.
4970.IP "\s-1EV_COMMON\s0" 4 5132.IP "\s-1EV_COMMON\s0" 4
4971.IX Item "EV_COMMON" 5133.IX Item "EV_COMMON"
4972By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 5134By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
… …
4993and the way callbacks are invoked and set. Must expand to a struct member 5155and the way callbacks are invoked and set. Must expand to a struct member
4994definition and a statement, respectively. See the \fIev.h\fR header file for 5156definition and a statement, respectively. See the \fIev.h\fR header file for
4995their default definitions. One possible use for overriding these is to 5157their default definitions. One possible use for overriding these is to
4996avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5158avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
4997method calls instead of plain function calls in \*(C+. 5159method calls instead of plain function calls in \*(C+.
4998.SS "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0" 5160.SS "\s-1EXPORTED API SYMBOLS\s0"
4999.IX Subsection "EXPORTED API SYMBOLS" 5161.IX Subsection "EXPORTED API SYMBOLS"
5000If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of 5162If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5001exported symbols, you can use the provided \fISymbol.*\fR files which list 5163exported symbols, you can use the provided \fISymbol.*\fR files which list
5002all public symbols, one per line: 5164all public symbols, one per line:
5003.PP 5165.PP
… …
5057\& #include "ev_cpp.h" 5219\& #include "ev_cpp.h"
5058\& #include "ev.c" 5220\& #include "ev.c"
5059.Ve 5221.Ve
5060.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5222.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5061.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5223.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5062.SS "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0" 5224.SS "\s-1THREADS AND COROUTINES\s0"
5063.IX Subsection "THREADS AND COROUTINES" 5225.IX Subsection "THREADS AND COROUTINES"
5064\fI\s-1THREADS\s0\fR 5226\fI\s-1THREADS\s0\fR
5065.IX Subsection "THREADS" 5227.IX Subsection "THREADS"
5066.PP 5228.PP
5067All libev functions are reentrant and thread-safe unless explicitly 5229All libev functions are reentrant and thread-safe unless explicitly
… …
5113An example use would be to communicate signals or other events that only 5275An example use would be to communicate signals or other events that only
5114work in the default loop by registering the signal watcher with the 5276work in the default loop by registering the signal watcher with the
5115default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop 5277default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop
5116watcher callback into the event loop interested in the signal. 5278watcher callback into the event loop interested in the signal.
5117.PP 5279.PP
5118See also \*(L"\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0\*(R". 5280See also \*(L"\s-1THREAD LOCKING EXAMPLE\*(R"\s0.
5119.PP 5281.PP
5120\fI\s-1COROUTINES\s0\fR 5282\fI\s-1COROUTINES\s0\fR
5121.IX Subsection "COROUTINES" 5283.IX Subsection "COROUTINES"
5122.PP 5284.PP
5123Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"): 5285Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"):
… …
5128that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. 5290that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
5129.PP 5291.PP
5130Care has been taken to ensure that libev does not keep local state inside 5292Care has been taken to ensure that libev does not keep local state inside
5131\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as 5293\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as
5132they do not call any callbacks. 5294they do not call any callbacks.
5133.SS "\s-1COMPILER\s0 \s-1WARNINGS\s0" 5295.SS "\s-1COMPILER WARNINGS\s0"
5134.IX Subsection "COMPILER WARNINGS" 5296.IX Subsection "COMPILER WARNINGS"
5135Depending on your compiler and compiler settings, you might get no or a 5297Depending on your compiler and compiler settings, you might get no or a
5136lot of warnings when compiling libev code. Some people are apparently 5298lot of warnings when compiling libev code. Some people are apparently
5137scared by this. 5299scared by this.
5138.PP 5300.PP
… …
5190.PP 5352.PP
5191If you need, for some reason, empty reports from valgrind for your project 5353If you need, for some reason, empty reports from valgrind for your project
5192I suggest using suppression lists. 5354I suggest using suppression lists.
5193.SH "PORTABILITY NOTES" 5355.SH "PORTABILITY NOTES"
5194.IX Header "PORTABILITY NOTES" 5356.IX Header "PORTABILITY NOTES"
5195.SS "\s-1GNU/LINUX\s0 32 \s-1BIT\s0 \s-1LIMITATIONS\s0" 5357.SS "\s-1GNU/LINUX 32 BIT LIMITATIONS\s0"
5196.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS" 5358.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS"
5197GNU/Linux is the only common platform that supports 64 bit file/large file 5359GNU/Linux is the only common platform that supports 64 bit file/large file
5198interfaces but \fIdisables\fR them by default. 5360interfaces but \fIdisables\fR them by default.
5199.PP 5361.PP
5200That means that libev compiled in the default environment doesn't support 5362That means that libev compiled in the default environment doesn't support
5201files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers. 5363files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers.
5202.PP 5364.PP
5203Unfortunately, many programs try to work around this GNU/Linux issue 5365Unfortunately, many programs try to work around this GNU/Linux issue
5204by enabling the large file \s-1API\s0, which makes them incompatible with the 5366by enabling the large file \s-1API,\s0 which makes them incompatible with the
5205standard libev compiled for their system. 5367standard libev compiled for their system.
5206.PP 5368.PP
5207Likewise, libev cannot enable the large file \s-1API\s0 itself as this would 5369Likewise, libev cannot enable the large file \s-1API\s0 itself as this would
5208suddenly make it incompatible to the default compile time environment, 5370suddenly make it incompatible to the default compile time environment,
5209i.e. all programs not using special compile switches. 5371i.e. all programs not using special compile switches.
5210.SS "\s-1OS/X\s0 \s-1AND\s0 \s-1DARWIN\s0 \s-1BUGS\s0" 5372.SS "\s-1OS/X AND DARWIN BUGS\s0"
5211.IX Subsection "OS/X AND DARWIN BUGS" 5373.IX Subsection "OS/X AND DARWIN BUGS"
5212The whole thing is a bug if you ask me \- basically any system interface 5374The whole thing is a bug if you ask me \- basically any system interface
5213you touch is broken, whether it is locales, poll, kqueue or even the 5375you touch is broken, whether it is locales, poll, kqueue or even the
5214OpenGL drivers. 5376OpenGL drivers.
5215.PP 5377.PP
… …
5237.PP 5399.PP
5238\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5400\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5239.IX Subsection "select is buggy" 5401.IX Subsection "select is buggy"
5240.PP 5402.PP
5241All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5403All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5242one up as well: On \s-1OS/X\s0, \f(CW\*(C`select\*(C'\fR actively limits the number of file 5404one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5243descriptors you can pass in to 1024 \- your program suddenly crashes when 5405descriptors you can pass in to 1024 \- your program suddenly crashes when
5244you use more. 5406you use more.
5245.PP 5407.PP
5246There is an undocumented \*(L"workaround\*(R" for this \- defining 5408There is an undocumented \*(L"workaround\*(R" for this \- defining
5247\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5409\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
5248work on \s-1OS/X\s0. 5410work on \s-1OS/X.\s0
5249.SS "\s-1SOLARIS\s0 \s-1PROBLEMS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5411.SS "\s-1SOLARIS PROBLEMS AND WORKAROUNDS\s0"
5250.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS" 5412.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS"
5251\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR 5413\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR
5252.IX Subsection "errno reentrancy" 5414.IX Subsection "errno reentrancy"
5253.PP 5415.PP
5254The default compile environment on Solaris is unfortunately so 5416The default compile environment on Solaris is unfortunately so
… …
5271great. 5433great.
5272.PP 5434.PP
5273If you can't get it to work, you can try running the program by setting 5435If you can't get it to work, you can try running the program by setting
5274the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and 5436the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and
5275\&\f(CW\*(C`select\*(C'\fR backends. 5437\&\f(CW\*(C`select\*(C'\fR backends.
5276.SS "\s-1AIX\s0 \s-1POLL\s0 \s-1BUG\s0" 5438.SS "\s-1AIX POLL BUG\s0"
5277.IX Subsection "AIX POLL BUG" 5439.IX Subsection "AIX POLL BUG"
5278\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around 5440\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around
5279this by trying to avoid the poll backend altogether (i.e. it's not even 5441this by trying to avoid the poll backend altogether (i.e. it's not even
5280compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine 5442compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine
5281with large bitsets on \s-1AIX\s0, and \s-1AIX\s0 is dead anyway. 5443with large bitsets on \s-1AIX,\s0 and \s-1AIX\s0 is dead anyway.
5282.SS "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5444.SS "\s-1WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS\s0"
5283.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" 5445.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
5284\fIGeneral issues\fR 5446\fIGeneral issues\fR
5285.IX Subsection "General issues" 5447.IX Subsection "General issues"
5286.PP 5448.PP
5287Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev 5449Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
… …
5356\& #define EV_USE_SELECT 1 5518\& #define EV_USE_SELECT 1
5357\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 5519\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
5358.Ve 5520.Ve
5359.PP 5521.PP
5360Note that winsockets handling of fd sets is O(n), so you can easily get a 5522Note that winsockets handling of fd sets is O(n), so you can easily get a
5361complexity in the O(nA\*^X) range when using win32. 5523complexity in the O(nX) range when using win32.
5362.PP 5524.PP
5363\fILimited number of file descriptors\fR 5525\fILimited number of file descriptors\fR
5364.IX Subsection "Limited number of file descriptors" 5526.IX Subsection "Limited number of file descriptors"
5365.PP 5527.PP
5366Windows has numerous arbitrary (and low) limits on things. 5528Windows has numerous arbitrary (and low) limits on things.
… …
5382by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR 5544by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR
5383(another arbitrary limit), but is broken in many versions of the Microsoft 5545(another arbitrary limit), but is broken in many versions of the Microsoft
5384runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets 5546runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets
5385(depending on windows version and/or the phase of the moon). To get more, 5547(depending on windows version and/or the phase of the moon). To get more,
5386you need to wrap all I/O functions and provide your own fd management, but 5548you need to wrap all I/O functions and provide your own fd management, but
5387the cost of calling select (O(nA\*^X)) will likely make this unworkable. 5549the cost of calling select (O(nX)) will likely make this unworkable.
5388.SS "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\s0" 5550.SS "\s-1PORTABILITY REQUIREMENTS\s0"
5389.IX Subsection "PORTABILITY REQUIREMENTS" 5551.IX Subsection "PORTABILITY REQUIREMENTS"
5390In addition to a working ISO-C implementation and of course the 5552In addition to a working ISO-C implementation and of course the
5391backend-specific APIs, libev relies on a few additional extensions: 5553backend-specific APIs, libev relies on a few additional extensions:
5392.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4 5554.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4
5393.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 5555.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4
5394.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." 5556.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *."
5395Libev assumes not only that all watcher pointers have the same internal 5557Libev assumes not only that all watcher pointers have the same internal
5396structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also 5558structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5397assumes that the same (machine) code can be used to call any watcher 5559assumes that the same (machine) code can be used to call any watcher
5398callback: The watcher callbacks have different type signatures, but libev 5560callback: The watcher callbacks have different type signatures, but libev
5399calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5561calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5562.IP "null pointers and integer zero are represented by 0 bytes" 4
5563.IX Item "null pointers and integer zero are represented by 0 bytes"
5564Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
5565relies on this setting pointers and integers to null.
5400.IP "pointer accesses must be thread-atomic" 4 5566.IP "pointer accesses must be thread-atomic" 4
5401.IX Item "pointer accesses must be thread-atomic" 5567.IX Item "pointer accesses must be thread-atomic"
5402Accessing a pointer value must be atomic, it must both be readable and 5568Accessing a pointer value must be atomic, it must both be readable and
5403writable in one piece \- this is the case on all current architectures. 5569writable in one piece \- this is the case on all current architectures.
5404.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 5570.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4
… …
5422except the initial one, and run the signal handling loop in the initial 5588except the initial one, and run the signal handling loop in the initial
5423thread as well. 5589thread as well.
5424.ie n .IP """long"" must be large enough for common memory allocation sizes" 4 5590.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
5425.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 5591.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
5426.IX Item "long must be large enough for common memory allocation sizes" 5592.IX Item "long must be large enough for common memory allocation sizes"
5427To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5593To improve portability and simplify its \s-1API,\s0 libev uses \f(CW\*(C`long\*(C'\fR internally
5428instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5594instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX
5429systems (Microsoft...) this might be unexpectedly low, but is still at 5595systems (Microsoft...) this might be unexpectedly low, but is still at
5430least 31 bits everywhere, which is enough for hundreds of millions of 5596least 31 bits everywhere, which is enough for hundreds of millions of
5431watchers. 5597watchers.
5432.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 5598.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
… …
5434.IX Item "double must hold a time value in seconds with enough accuracy" 5600.IX Item "double must hold a time value in seconds with enough accuracy"
5435The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to 5601The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
5436have at least 51 bits of mantissa (and 9 bits of exponent), which is 5602have at least 51 bits of mantissa (and 9 bits of exponent), which is
5437good enough for at least into the year 4000 with millisecond accuracy 5603good enough for at least into the year 4000 with millisecond accuracy
5438(the design goal for libev). This requirement is overfulfilled by 5604(the design goal for libev). This requirement is overfulfilled by
5439implementations using \s-1IEEE\s0 754, which is basically all existing ones. 5605implementations using \s-1IEEE 754,\s0 which is basically all existing ones.
5440.Sp 5606.Sp
5441With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the 5607With \s-1IEEE 754\s0 doubles, you get microsecond accuracy until at least the
5442year 2255 (and millisecond accuracy till the year 287396 \- by then, libev 5608year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5443is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or 5609is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5444something like that, just kidding). 5610something like that, just kidding).
5445.PP 5611.PP
5446If you know of other additional requirements drop me a note. 5612If you know of other additional requirements drop me a note.
… …
5508calls in the current loop iteration and the loop is currently 5674calls in the current loop iteration and the loop is currently
5509blocked. Checking for async and signal events involves iterating over all 5675blocked. Checking for async and signal events involves iterating over all
5510running async watchers or all signal numbers. 5676running async watchers or all signal numbers.
5511.SH "PORTING FROM LIBEV 3.X TO 4.X" 5677.SH "PORTING FROM LIBEV 3.X TO 4.X"
5512.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5678.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5513The major version 4 introduced some incompatible changes to the \s-1API\s0. 5679The major version 4 introduced some incompatible changes to the \s-1API.\s0
5514.PP 5680.PP
5515At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5681At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
5516for all changes, so most programs should still compile. The compatibility 5682for all changes, so most programs should still compile. The compatibility
5517layer might be removed in later versions of libev, so better update to the 5683layer might be removed in later versions of libev, so better update to the
5518new \s-1API\s0 early than late. 5684new \s-1API\s0 early than late.
5519.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5685.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5520.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5686.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5521.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5687.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5522The backward compatibility mechanism can be controlled by 5688The backward compatibility mechanism can be controlled by
5523\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R" 5689\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR SYMBOLS/MACROS\*(R"\s0 in the \*(L"\s-1EMBEDDING\*(R"\s0
5524section. 5690section.
5525.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5691.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5526.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5692.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5527.IX Item "ev_default_destroy and ev_default_fork have been removed" 5693.IX Item "ev_default_destroy and ev_default_fork have been removed"
5528These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5694These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts:
… …
5568.SH "GLOSSARY" 5734.SH "GLOSSARY"
5569.IX Header "GLOSSARY" 5735.IX Header "GLOSSARY"
5570.IP "active" 4 5736.IP "active" 4
5571.IX Item "active" 5737.IX Item "active"
5572A watcher is active as long as it has been started and not yet stopped. 5738A watcher is active as long as it has been started and not yet stopped.
5573See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5739See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5574.IP "application" 4 5740.IP "application" 4
5575.IX Item "application" 5741.IX Item "application"
5576In this document, an application is whatever is using libev. 5742In this document, an application is whatever is using libev.
5577.IP "backend" 4 5743.IP "backend" 4
5578.IX Item "backend" 5744.IX Item "backend"
… …
5605The model used to describe how an event loop handles and processes 5771The model used to describe how an event loop handles and processes
5606watchers and events. 5772watchers and events.
5607.IP "pending" 4 5773.IP "pending" 4
5608.IX Item "pending" 5774.IX Item "pending"
5609A watcher is pending as soon as the corresponding event has been 5775A watcher is pending as soon as the corresponding event has been
5610detected. See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5776detected. See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5611.IP "real time" 4 5777.IP "real time" 4
5612.IX Item "real time" 5778.IX Item "real time"
5613The physical time that is observed. It is apparently strictly monotonic :) 5779The physical time that is observed. It is apparently strictly monotonic :)
5614.IP "wall-clock time" 4 5780.IP "wall-clock time" 4
5615.IX Item "wall-clock time" 5781.IX Item "wall-clock time"

Diff Legend

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