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

Comparing libev/ev.3 (file contents):
Revision 1.102 by root, Fri Sep 5 16:00:17 2014 UTC vs.
Revision 1.113 by root, Mon Jun 24 19:53:47 2019 UTC

1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) 1.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
… …
44.\" 44.\"
45.\" Escape single quotes in literal strings from groff's Unicode transform. 45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq 46.ie \n(.g .ds Aq \(aq
47.el .ds Aq ' 47.el .ds Aq '
48.\" 48.\"
49.\" If the F register is turned on, we'll generate index entries on stderr for 49.\" If the F register is >0, we'll generate index entries on stderr for
50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51.\" entries marked with X<> in POD. Of course, you'll have to process the 51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion. 52.\" output yourself in some meaningful fashion.
53.\" 53.\"
54.\" Avoid warning from groff about undefined register 'F'. 54.\" Avoid warning from groff about undefined register 'F'.
55.de IX 55.de IX
56.. 56..
57.nr rF 0 57.nr rF 0
58.if \n(.g .if rF .nr rF 1 58.if \n(.g .if rF .nr rF 1
59.if (\n(rF:(\n(.g==0)) \{ 59.if (\n(rF:(\n(.g==0)) \{\
60. if \nF \{ 60. if \nF \{\
61. de IX 61. de IX
62. tm Index:\\$1\t\\n%\t"\\$2" 62. tm Index:\\$1\t\\n%\t"\\$2"
63.. 63..
64. if !\nF==2 \{ 64. if !\nF==2 \{\
65. nr % 0 65. nr % 0
66. nr F 2 66. nr F 2
67. \} 67. \}
68. \} 68. \}
69.\} 69.\}
… …
131.\} 131.\}
132.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
133.\" ======================================================================== 133.\" ========================================================================
134.\" 134.\"
135.IX Title "LIBEV 3" 135.IX Title "LIBEV 3"
136.TH LIBEV 3 "2014-09-05" "libev-4.15" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-06-24" "libev-4.25" "libev - high performance full featured event loop"
137.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
138.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
139.if n .ad l 139.if n .ad l
140.nh 140.nh
141.SH "NAME" 141.SH "NAME"
… …
240watchers\fR, which are relatively small C structures you initialise with the 240watchers\fR, which are relatively small C structures you initialise with the
241details of the event, and then hand it over to libev by \fIstarting\fR the 241details of the event, and then hand it over to libev by \fIstarting\fR the
242watcher. 242watcher.
243.SS "\s-1FEATURES\s0" 243.SS "\s-1FEATURES\s0"
244.IX Subsection "FEATURES" 244.IX Subsection "FEATURES"
245Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the 245Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific aio and \f(CW\*(C`epoll\*(C'\fR
246BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms 246interfaces, the BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port
247for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface 247mechanisms for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR
248(for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner 248interface (for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner
249inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative 249inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative
250timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling 250timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling
251(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status 251(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status
252change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event 252change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event
253loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and 253loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and
… …
392.Sp 392.Sp
393You could override this function in high-availability programs to, say, 393You could override this function in high-availability programs to, say,
394free some memory if it cannot allocate memory, to use a special allocator, 394free some memory if it cannot allocate memory, to use a special allocator,
395or even to sleep a while and retry until some memory is available. 395or even to sleep a while and retry until some memory is available.
396.Sp 396.Sp
397Example: The following is the \f(CW\*(C`realloc\*(C'\fR function that libev itself uses
398which should work with \f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions of all kinds and
399is probably a good basis for your own implementation.
400.Sp
401.Vb 5
402\& static void *
403\& ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
404\& {
405\& if (size)
406\& return realloc (ptr, size);
407\&
408\& free (ptr);
409\& return 0;
410\& }
411.Ve
412.Sp
397Example: Replace the libev allocator with one that waits a bit and then 413Example: Replace the libev allocator with one that waits a bit and then
398retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR). 414retries.
399.Sp 415.Sp
400.Vb 6 416.Vb 8
401\& static void * 417\& static void *
402\& persistent_realloc (void *ptr, size_t size) 418\& persistent_realloc (void *ptr, size_t size)
403\& { 419\& {
420\& if (!size)
421\& {
422\& free (ptr);
423\& return 0;
424\& }
425\&
404\& for (;;) 426\& for (;;)
405\& { 427\& {
406\& void *newptr = realloc (ptr, size); 428\& void *newptr = realloc (ptr, size);
407\& 429\&
408\& if (newptr) 430\& if (newptr)
… …
536make libev check for a fork in each iteration by enabling this flag. 558make libev check for a fork in each iteration by enabling this flag.
537.Sp 559.Sp
538This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, 560This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop,
539and thus this might slow down your event loop if you do a lot of loop 561and thus this might slow down your event loop if you do a lot of loop
540iterations and little real work, but is usually not noticeable (on my 562iterations and little real work, but is usually not noticeable (on my
541GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence 563GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn
542without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has 564sequence without a system call and thus \fIvery\fR fast, but my GNU/Linux
543\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). 565system also has \f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). (Update: glibc
566versions 2.25 apparently removed the \f(CW\*(C`getpid\*(C'\fR optimisation again).
544.Sp 567.Sp
545The big advantage of this flag is that you can forget about fork (and 568The big advantage of this flag is that you can forget about fork (and
546forget about forgetting to tell libev about forking) when you use this 569forget about forgetting to tell libev about forking, although you still
547flag. 570have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
548.Sp 571.Sp
549This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR 572This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
550environment variable. 573environment variable.
551.ie n .IP """EVFLAG_NOINOTIFY""" 4 574.ie n .IP """EVFLAG_NOINOTIFY""" 4
552.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 575.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
… …
584.Sp 607.Sp
585This flag's behaviour will become the default in future versions of libev. 608This flag's behaviour will become the default in future versions of libev.
586.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 609.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
587.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 610.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
588.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 611.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
589This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 612This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
590libev tries to roll its own fd_set with no limits on the number of fds, 613libev tries to roll its own fd_set with no limits on the number of fds,
591but if that fails, expect a fairly low limit on the number of fds when 614but if that fails, expect a fairly low limit on the number of fds when
592using this backend. It doesn't scale too well (O(highest_fd)), but its 615using this backend. It doesn't scale too well (O(highest_fd)), but its
593usually the fastest backend for a low number of (low-numbered :) fds. 616usually the fastest backend for a low number of (low-numbered :) fds.
594.Sp 617.Sp
… …
603\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the 626\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the
604\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). 627\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
605.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 628.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
606.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 629.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
607.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 630.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
608And this is your standard \fIpoll\fR\|(2) backend. It's more complicated 631And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
609than select, but handles sparse fds better and has no artificial 632than select, but handles sparse fds better and has no artificial
610limit on the number of fds you can use (except it will slow down 633limit on the number of fds you can use (except it will slow down
611considerably with a lot of inactive fds). It scales similarly to select, 634considerably with a lot of inactive fds). It scales similarly to select,
612i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for 635i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
613performance tips. 636performance tips.
… …
615This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 638This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and
616\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. 639\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
617.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 640.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
618.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 641.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
619.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 642.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
620Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 643Use the linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
621kernels). 644kernels).
622.Sp 645.Sp
623For few fds, this backend is a bit little slower than poll and select, but 646For few fds, this backend is a bit little slower than poll and select, but
624it scales phenomenally better. While poll and select usually scale like 647it scales phenomenally better. While poll and select usually scale like
625O(total_fds) where total_fds is the total number of fds (or the highest 648O(total_fds) where total_fds is the total number of fds (or the highest
… …
671All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or 694All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or
672faster than epoll for maybe up to a hundred file descriptors, depending on 695faster than epoll for maybe up to a hundred file descriptors, depending on
673the usage. So sad. 696the usage. So sad.
674.Sp 697.Sp
675While nominally embeddable in other event loops, this feature is broken in 698While nominally embeddable in other event loops, this feature is broken in
676all kernel versions tested so far. 699a lot of kernel revisions, but probably(!) works in current versions.
700.Sp
701This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
702\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
703.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4
704.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4
705.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
706Use the linux-specific linux aio (\fInot\fR \f(CWaio(7)\fR but \f(CWio_submit(2)\fR) event interface available in post\-4.18 kernels.
707.Sp
708If this backend works for you (as of this writing, it was very
709experimental), it is the best event interface available on linux and might
710be well worth enabling it \- if it isn't available in your kernel this will
711be detected and this backend will be skipped.
712.Sp
713This backend can batch oneshot requests and supports a user-space ring
714buffer to receive events. It also doesn't suffer from most of the design
715problems of epoll (such as not being able to remove event sources from the
716epoll set), and generally sounds too good to be true. Because, this being
717the linux kernel, of course it suffers from a whole new set of limitations.
718.Sp
719For one, it is not easily embeddable (but probably could be done using
720an event fd at some extra overhead). It also is subject to a system wide
721limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR \- each loop
722currently requires \f(CW61\fR of this number. If no aio requests are left, this
723backend will be skipped during initialisation.
724.Sp
725Most problematic in practise, however, is that not all file descriptors
726work with it. For example, in linux 5.1, tcp sockets, pipes, event fds,
727files, \fI/dev/null\fR and a few others are supported, but ttys do not work
728properly (a known bug that the kernel developers don't care about, see
729<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
730(yet?) a generic event polling interface.
731.Sp
732Overall, it seems the linux developers just don't want it to have a
733generic event handling mechanism other than \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`poll\*(C'\fR.
734.Sp
735To work around the fd type problem, the current version of libev uses
736epoll as a fallback for file deescriptor types that do not work. Epoll
737is used in, kind of, slow mode that hopefully avoids most of its design
738problems and requires 1\-3 extra syscalls per active fd every iteration.
677.Sp 739.Sp
678This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 740This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
679\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 741\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
680.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 742.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
681.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 743.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
… …
785used if available. 847used if available.
786.Sp 848.Sp
787.Vb 1 849.Vb 1
788\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 850\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
789.Ve 851.Ve
852.Sp
853Example: Similarly, on linux, you mgiht want to take advantage of the
854linux aio backend if possible, but fall back to something else if that
855isn't available.
856.Sp
857.Vb 1
858\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
859.Ve
790.RE 860.RE
791.IP "ev_loop_destroy (loop)" 4 861.IP "ev_loop_destroy (loop)" 4
792.IX Item "ev_loop_destroy (loop)" 862.IX Item "ev_loop_destroy (loop)"
793Destroys an event loop object (frees all memory and kernel state 863Destroys an event loop object (frees all memory and kernel state
794etc.). None of the active event watchers will be stopped in the normal 864etc.). None of the active event watchers will be stopped in the normal
… …
816to reinitialise the kernel state for backends that have one. Despite 886to reinitialise the kernel state for backends that have one. Despite
817the name, you can call it anytime you are allowed to start or stop 887the name, you can call it anytime you are allowed to start or stop
818watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most 888watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
819sense after forking, in the child process. You \fImust\fR call it (or use 889sense after forking, in the child process. You \fImust\fR call it (or use
820\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 890\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
891.Sp
892In addition, if you want to reuse a loop (via this function or
893\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR.
821.Sp 894.Sp
822Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 895Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
823a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is 896a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
824because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things 897because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
825during fork. 898during fork.
… …
1361bug in your program. 1434bug in your program.
1362.Sp 1435.Sp
1363Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1436Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1364example it might indicate that a fd is readable or writable, and if your 1437example it might indicate that a fd is readable or writable, and if your
1365callbacks is well-written it can just attempt the operation and cope with 1438callbacks is well-written it can just attempt the operation and cope with
1366the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1439the error from \fBread()\fR or \fBwrite()\fR. This will not work in multi-threaded
1367programs, though, as the fd could already be closed and reused for another 1440programs, though, as the fd could already be closed and reused for another
1368thing, so beware. 1441thing, so beware.
1369.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" 1442.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1370.IX Subsection "GENERIC WATCHER FUNCTIONS" 1443.IX Subsection "GENERIC WATCHER FUNCTIONS"
1371.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1444.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
… …
1722But really, best use non-blocking mode. 1795But really, best use non-blocking mode.
1723.PP 1796.PP
1724\fIThe special problem of disappearing file descriptors\fR 1797\fIThe special problem of disappearing file descriptors\fR
1725.IX Subsection "The special problem of disappearing file descriptors" 1798.IX Subsection "The special problem of disappearing file descriptors"
1726.PP 1799.PP
1727Some backends (e.g. kqueue, epoll) need to be told about closing a file 1800Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1728descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1801a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1729such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1802means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1730descriptor, but when it goes away, the operating system will silently drop 1803file descriptor, but when it goes away, the operating system will silently
1731this interest. If another file descriptor with the same number then is 1804drop this interest. If another file descriptor with the same number then
1732registered with libev, there is no efficient way to see that this is, in 1805is registered with libev, there is no efficient way to see that this is,
1733fact, a different file descriptor. 1806in fact, a different file descriptor.
1734.PP 1807.PP
1735To avoid having to explicitly tell libev about such cases, libev follows 1808To avoid having to explicitly tell libev about such cases, libev follows
1736the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1809the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1737will assume that this is potentially a new file descriptor, otherwise 1810will assume that this is potentially a new file descriptor, otherwise
1738it is assumed that the file descriptor stays the same. That means that 1811it is assumed that the file descriptor stays the same. That means that
… …
1790reuse the same code path. 1863reuse the same code path.
1791.PP 1864.PP
1792\fIThe special problem of fork\fR 1865\fIThe special problem of fork\fR
1793.IX Subsection "The special problem of fork" 1866.IX Subsection "The special problem of fork"
1794.PP 1867.PP
1795Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1868Some backends (epoll, kqueue, probably linuxaio) do not support \f(CW\*(C`fork ()\*(C'\fR
1796useless behaviour. Libev fully supports fork, but needs to be told about 1869at all or exhibit useless behaviour. Libev fully supports fork, but needs
1797it in the child if you want to continue to use it in the child. 1870to be told about it in the child if you want to continue to use it in the
1871child.
1798.PP 1872.PP
1799To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1873To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1800()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1874()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1801\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1875\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1802.PP 1876.PP
… …
1807when writing to a pipe whose other end has been closed, your program gets 1881when writing to a pipe whose other end has been closed, your program gets
1808sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs 1882sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1809this is sensible behaviour, for daemons, this is usually undesirable. 1883this is sensible behaviour, for daemons, this is usually undesirable.
1810.PP 1884.PP
1811So when you encounter spurious, unexplained daemon exits, make sure you 1885So when you encounter spurious, unexplained daemon exits, make sure you
1812ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon 1886ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1813somewhere, as that would have given you a big clue). 1887somewhere, as that would have given you a big clue).
1814.PP 1888.PP
1815\fIThe special problem of \fIaccept()\fIing when you can't\fR 1889\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1816.IX Subsection "The special problem of accept()ing when you can't" 1890.IX Subsection "The special problem of accept()ing when you can't"
1817.PP 1891.PP
1818Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, 1892Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
1819found in post\-2004 Linux) have the peculiar behaviour of not removing a 1893found in post\-2004 Linux) have the peculiar behaviour of not removing a
1820connection from the pending queue in all error cases. 1894connection from the pending queue in all error cases.
1821.PP 1895.PP
1822For example, larger servers often run out of file descriptors (because 1896For example, larger servers often run out of file descriptors (because
1823of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not 1897of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
2247.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 2321.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
2248.PD 0 2322.PD 0
2249.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 2323.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
2250.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 2324.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
2251.PD 2325.PD
2252Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR 2326Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
2253is \f(CW0.\fR, then it will automatically be stopped once the timeout is 2327negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
2254reached. If it is positive, then the timer will automatically be 2328automatically be stopped once the timeout is reached. If it is positive,
2255configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, 2329then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
2256until stopped manually. 2330seconds later, again, and again, until stopped manually.
2257.Sp 2331.Sp
2258The timer itself will do a best-effort at avoiding drift, that is, if 2332The timer itself will do a best-effort at avoiding drift, that is, if
2259you configure a timer to trigger every 10 seconds, then it will normally 2333you configure a timer to trigger every 10 seconds, then it will normally
2260trigger at exactly 10 second intervals. If, however, your program cannot 2334trigger at exactly 10 second intervals. If, however, your program cannot
2261keep up with the timer (because it takes longer than those 10 seconds to 2335keep up with the timer (because it takes longer than those 10 seconds to
… …
2343Periodic watchers are also timers of a kind, but they are very versatile 2417Periodic watchers are also timers of a kind, but they are very versatile
2344(and unfortunately a bit complex). 2418(and unfortunately a bit complex).
2345.PP 2419.PP
2346Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or 2420Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or
2347relative time, the physical time that passes) but on wall clock time 2421relative time, the physical time that passes) but on wall clock time
2348(absolute time, the thing you can read on your calender or clock). The 2422(absolute time, the thing you can read on your calendar or clock). The
2349difference is that wall clock time can run faster or slower than real 2423difference is that wall clock time can run faster or slower than real
2350time, and time jumps are not uncommon (e.g. when you adjust your 2424time, and time jumps are not uncommon (e.g. when you adjust your
2351wrist-watch). 2425wrist-watch).
2352.PP 2426.PP
2353You can tell a periodic watcher to trigger after some specific point 2427You can tell a periodic watcher to trigger after some specific point
… …
2358\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting 2432\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
2359it, as it uses a relative timeout). 2433it, as it uses a relative timeout).
2360.PP 2434.PP
2361\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex 2435\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
2362timers, such as triggering an event on each \*(L"midnight, local time\*(R", or 2436timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
2363other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as 2437other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
2364those cannot react to time jumps. 2438watchers, as those cannot react to time jumps.
2365.PP 2439.PP
2366As with timers, the callback is guaranteed to be invoked only when the 2440As with timers, the callback is guaranteed to be invoked only when the
2367point in time where it is supposed to trigger has passed. If multiple 2441point in time where it is supposed to trigger has passed. If multiple
2368timers become ready during the same loop iteration then the ones with 2442timers become ready during the same loop iteration then the ones with
2369earlier time-out values are invoked before ones with later time-out values 2443earlier time-out values are invoked before ones with later time-out values
… …
2430In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2504In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
2431ignored. Instead, each time the periodic watcher gets scheduled, the 2505ignored. Instead, each time the periodic watcher gets scheduled, the
2432reschedule callback will be called with the watcher as first, and the 2506reschedule callback will be called with the watcher as first, and the
2433current time as second argument. 2507current time as second argument.
2434.Sp 2508.Sp
2435\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, 2509\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
2436or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2510or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2437allowed by documentation here\fR. 2511allowed by documentation here\fR.
2438.Sp 2512.Sp
2439If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2513If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
2440it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 2514it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2454It must return the next time to trigger, based on the passed time value 2528It must return the next time to trigger, based on the passed time value
2455(that is, the lowest time value larger than to the second argument). It 2529(that is, the lowest time value larger than to the second argument). It
2456will usually be called just before the callback will be triggered, but 2530will usually be called just before the callback will be triggered, but
2457might be called at other times, too. 2531might be called at other times, too.
2458.Sp 2532.Sp
2459\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or 2533\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
2460equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2534equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2461.Sp 2535.Sp
2462This can be used to create very complex timers, such as a timer that 2536This can be used to create very complex timers, such as a timer that
2463triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the 2537triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2464next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2538the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
2465you do this is, again, up to you (but it is not trivial, which is the main 2539this. Here is a (completely untested, no error checking) example on how to
2466reason I omitted it as an example). 2540do this:
2541.Sp
2542.Vb 1
2543\& #include <time.h>
2544\&
2545\& static ev_tstamp
2546\& my_rescheduler (ev_periodic *w, ev_tstamp now)
2547\& {
2548\& time_t tnow = (time_t)now;
2549\& struct tm tm;
2550\& localtime_r (&tnow, &tm);
2551\&
2552\& tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2553\& ++tm.tm_mday; // midnight next day
2554\&
2555\& return mktime (&tm);
2556\& }
2557.Ve
2558.Sp
2559Note: this code might run into trouble on days that have more then two
2560midnights (beginning and end).
2467.RE 2561.RE
2468.RS 4 2562.RS 4
2469.RE 2563.RE
2470.IP "ev_periodic_again (loop, ev_periodic *)" 4 2564.IP "ev_periodic_again (loop, ev_periodic *)" 4
2471.IX Item "ev_periodic_again (loop, ev_periodic *)" 2565.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
2589The simplest way to ensure that the signal mask is reset in the child is 2683The simplest way to ensure that the signal mask is reset in the child is
2590to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will 2684to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
2591catch fork calls done by libraries (such as the libc) as well. 2685catch fork calls done by libraries (such as the libc) as well.
2592.PP 2686.PP
2593In current versions of libev, the signal will not be blocked indefinitely 2687In current versions of libev, the signal will not be blocked indefinitely
2594unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces 2688unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
2595the window of opportunity for problems, it will not go away, as libev 2689the window of opportunity for problems, it will not go away, as libev
2596\&\fIhas\fR to modify the signal mask, at least temporarily. 2690\&\fIhas\fR to modify the signal mask, at least temporarily.
2597.PP 2691.PP
2598So I can't stress this enough: \fIIf you do not reset your signal mask when 2692So I can't stress this enough: \fIIf you do not reset your signal mask when
2599you expect it to be empty, you have a race condition in your code\fR. This 2693you expect it to be empty, you have a race condition in your code\fR. This
… …
3641is a time window between the event loop checking and resetting the async 3735is a time window between the event loop checking and resetting the async
3642notification, and the callback being invoked. 3736notification, and the callback being invoked.
3643.SH "OTHER FUNCTIONS" 3737.SH "OTHER FUNCTIONS"
3644.IX Header "OTHER FUNCTIONS" 3738.IX Header "OTHER FUNCTIONS"
3645There are some other functions of possible interest. Described. Here. Now. 3739There are some other functions of possible interest. Described. Here. Now.
3646.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 3740.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
3647.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 3741.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
3648This function combines a simple timer and an I/O watcher, calls your 3742This function combines a simple timer and an I/O watcher, calls your
3649callback on whichever event happens first and automatically stops both 3743callback on whichever event happens first and automatically stops both
3650watchers. This is useful if you want to wait for a single event on an fd 3744watchers. This is useful if you want to wait for a single event on an fd
3651or timeout without having to allocate/configure/start/stop/free one or 3745or timeout without having to allocate/configure/start/stop/free one or
3652more watchers yourself. 3746more watchers yourself.
… …
4052files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4146files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
4053.PP 4147.PP
4054.Vb 4 4148.Vb 4
4055\& // my_ev.h 4149\& // my_ev.h
4056\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4150\& #define EV_CB_DECLARE(type) struct my_coro *cb;
4057\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb); 4151\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb)
4058\& #include "../libev/ev.h" 4152\& #include "../libev/ev.h"
4059\& 4153\&
4060\& // my_ev.c 4154\& // my_ev.c
4061\& #define EV_H "my_ev.h" 4155\& #define EV_H "my_ev.h"
4062\& #include "../libev/ev.c" 4156\& #include "../libev/ev.c"
… …
4102The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the 4196The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4103libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4197libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4104will work fine. 4198will work fine.
4105.PP 4199.PP
4106Proper exception specifications might have to be added to callbacks passed 4200Proper exception specifications might have to be added to callbacks passed
4107to libev: exceptions may be thrown only from watcher callbacks, all 4201to libev: exceptions may be thrown only from watcher callbacks, all other
4108other callbacks (allocator, syserr, loop acquire/release and periodic 4202callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4109reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4203callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
4110()\*(C'\fR specification. If you have code that needs to be compiled as both C 4204specification. If you have code that needs to be compiled as both C and
4111and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4205\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
4112.PP 4206.PP
4113.Vb 6 4207.Vb 6
4114\& static void 4208\& static void
4115\& fatal_error (const char *msg) EV_THROW 4209\& fatal_error (const char *msg) EV_NOEXCEPT
4116\& { 4210\& {
4117\& perror (msg); 4211\& perror (msg);
4118\& abort (); 4212\& abort ();
4119\& } 4213\& }
4120\& 4214\&
… …
4494\& #include "ev.c" 4588\& #include "ev.c"
4495.Ve 4589.Ve
4496.PP 4590.PP
4497This will automatically include \fIev.h\fR, too, and should be done in a 4591This will automatically include \fIev.h\fR, too, and should be done in a
4498single C source file only to provide the function implementations. To use 4592single C source file only to provide the function implementations. To use
4499it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best 4593it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
4500done by writing a wrapper around \fIev.h\fR that you can include instead and 4594done by writing a wrapper around \fIev.h\fR that you can include instead and
4501where you can put other configuration options): 4595where you can put other configuration options):
4502.PP 4596.PP
4503.Vb 2 4597.Vb 2
4504\& #define EV_STANDALONE 1 4598\& #define EV_STANDALONE 1
… …
4518\& ev_vars.h 4612\& ev_vars.h
4519\& ev_wrap.h 4613\& ev_wrap.h
4520\& 4614\&
4521\& ev_win32.c required on win32 platforms only 4615\& ev_win32.c required on win32 platforms only
4522\& 4616\&
4523\& ev_select.c only when select backend is enabled (which is enabled by default) 4617\& ev_select.c only when select backend is enabled
4524\& ev_poll.c only when poll backend is enabled (disabled by default) 4618\& ev_poll.c only when poll backend is enabled
4525\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 4619\& ev_epoll.c only when the epoll backend is enabled
4620\& ev_linuxaio.c only when the linux aio backend is enabled
4526\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4621\& ev_kqueue.c only when the kqueue backend is enabled
4527\& ev_port.c only when the solaris port backend is enabled (disabled by default) 4622\& ev_port.c only when the solaris port backend is enabled
4528.Ve 4623.Ve
4529.PP 4624.PP
4530\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4625\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4531to compile this single file. 4626to compile this single file.
4532.PP 4627.PP
… …
4577values when compiling libev vs. including \fIev.h\fR, so it is permissible 4672values when compiling libev vs. including \fIev.h\fR, so it is permissible
4578to redefine them before including \fIev.h\fR without breaking compatibility 4673to redefine them before including \fIev.h\fR without breaking compatibility
4579to a compiled library. All other symbols change the \s-1ABI,\s0 which means all 4674to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4580users of libev and the libev code itself must be compiled with compatible 4675users of libev and the libev code itself must be compiled with compatible
4581settings. 4676settings.
4582.IP "\s-1EV_COMPAT3 \s0(h)" 4 4677.IP "\s-1EV_COMPAT3\s0 (h)" 4
4583.IX Item "EV_COMPAT3 (h)" 4678.IX Item "EV_COMPAT3 (h)"
4584Backwards compatibility is a major concern for libev. This is why this 4679Backwards compatibility is a major concern for libev. This is why this
4585release of libev comes with wrappers for the functions and symbols that 4680release of libev comes with wrappers for the functions and symbols that
4586have been renamed between libev version 3 and 4. 4681have been renamed between libev version 3 and 4.
4587.Sp 4682.Sp
… …
4592typedef in that case. 4687typedef in that case.
4593.Sp 4688.Sp
4594In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4689In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4595and in some even more future version the compatibility code will be 4690and in some even more future version the compatibility code will be
4596removed completely. 4691removed completely.
4597.IP "\s-1EV_STANDALONE \s0(h)" 4 4692.IP "\s-1EV_STANDALONE\s0 (h)" 4
4598.IX Item "EV_STANDALONE (h)" 4693.IX Item "EV_STANDALONE (h)"
4599Must always be \f(CW1\fR if you do not use autoconf configuration, which 4694Must always be \f(CW1\fR if you do not use autoconf configuration, which
4600keeps libev from including \fIconfig.h\fR, and it also defines dummy 4695keeps libev from including \fIconfig.h\fR, and it also defines dummy
4601implementations for some libevent functions (such as logging, which is not 4696implementations for some libevent functions (such as logging, which is not
4602supported). It will also not define any of the structs usually found in 4697supported). It will also not define any of the structs usually found in
… …
4711If defined to be \f(CW1\fR, libev will compile in support for the Linux 4806If defined to be \f(CW1\fR, libev will compile in support for the Linux
4712\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4807\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4713otherwise another method will be used as fallback. This is the preferred 4808otherwise another method will be used as fallback. This is the preferred
4714backend for GNU/Linux systems. If undefined, it will be enabled if the 4809backend for GNU/Linux systems. If undefined, it will be enabled if the
4715headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4810headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4811.IP "\s-1EV_USE_LINUXAIO\s0" 4
4812.IX Item "EV_USE_LINUXAIO"
4813If defined to be \f(CW1\fR, libev will compile in support for the Linux
4814aio backend. Due to it's currenbt limitations it has to be requested
4815explicitly. If undefined, it will be enabled on linux, otherwise
4816disabled.
4716.IP "\s-1EV_USE_KQUEUE\s0" 4 4817.IP "\s-1EV_USE_KQUEUE\s0" 4
4717.IX Item "EV_USE_KQUEUE" 4818.IX Item "EV_USE_KQUEUE"
4718If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4819If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4719\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4820\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4720otherwise another method will be used as fallback. This is the preferred 4821otherwise another method will be used as fallback. This is the preferred
… …
4760handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR 4861handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4761watchers. 4862watchers.
4762.Sp 4863.Sp
4763In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4864In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4764(from \fIsignal.h\fR), which is usually good enough on most platforms. 4865(from \fIsignal.h\fR), which is usually good enough on most platforms.
4765.IP "\s-1EV_H \s0(h)" 4 4866.IP "\s-1EV_H\s0 (h)" 4
4766.IX Item "EV_H (h)" 4867.IX Item "EV_H (h)"
4767The name of the \fIev.h\fR header file used to include it. The default if 4868The name of the \fIev.h\fR header file used to include it. The default if
4768undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4869undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4769used to virtually rename the \fIev.h\fR header file in case of conflicts. 4870used to virtually rename the \fIev.h\fR header file in case of conflicts.
4770.IP "\s-1EV_CONFIG_H \s0(h)" 4 4871.IP "\s-1EV_CONFIG_H\s0 (h)" 4
4771.IX Item "EV_CONFIG_H (h)" 4872.IX Item "EV_CONFIG_H (h)"
4772If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4873If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4773\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4874\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4774\&\f(CW\*(C`EV_H\*(C'\fR, above. 4875\&\f(CW\*(C`EV_H\*(C'\fR, above.
4775.IP "\s-1EV_EVENT_H \s0(h)" 4 4876.IP "\s-1EV_EVENT_H\s0 (h)" 4
4776.IX Item "EV_EVENT_H (h)" 4877.IX Item "EV_EVENT_H (h)"
4777Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4878Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4778of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4879of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4779.IP "\s-1EV_PROTOTYPES \s0(h)" 4 4880.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
4780.IX Item "EV_PROTOTYPES (h)" 4881.IX Item "EV_PROTOTYPES (h)"
4781If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4882If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4782prototypes, but still define all the structs and other symbols. This is 4883prototypes, but still define all the structs and other symbols. This is
4783occasionally useful if you want to provide your own wrapper functions 4884occasionally useful if you want to provide your own wrapper functions
4784around libev functions. 4885around libev functions.
… …
4993.Vb 3 5094.Vb 3
4994\& #define EV_COMMON \e 5095\& #define EV_COMMON \e
4995\& SV *self; /* contains this struct */ \e 5096\& SV *self; /* contains this struct */ \e
4996\& SV *cb_sv, *fh /* note no trailing ";" */ 5097\& SV *cb_sv, *fh /* note no trailing ";" */
4997.Ve 5098.Ve
4998.IP "\s-1EV_CB_DECLARE \s0(type)" 4 5099.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
4999.IX Item "EV_CB_DECLARE (type)" 5100.IX Item "EV_CB_DECLARE (type)"
5000.PD 0 5101.PD 0
5001.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4 5102.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
5002.IX Item "EV_CB_INVOKE (watcher, revents)" 5103.IX Item "EV_CB_INVOKE (watcher, revents)"
5003.IP "ev_set_cb (ev, cb)" 4 5104.IP "ev_set_cb (ev, cb)" 4
5004.IX Item "ev_set_cb (ev, cb)" 5105.IX Item "ev_set_cb (ev, cb)"
5005.PD 5106.PD
5006Can be used to change the callback member declaration in each watcher, 5107Can be used to change the callback member declaration in each watcher,
… …
5009their default definitions. One possible use for overriding these is to 5110their default definitions. One possible use for overriding these is to
5010avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5111avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
5011method calls instead of plain function calls in \*(C+. 5112method calls instead of plain function calls in \*(C+.
5012.SS "\s-1EXPORTED API SYMBOLS\s0" 5113.SS "\s-1EXPORTED API SYMBOLS\s0"
5013.IX Subsection "EXPORTED API SYMBOLS" 5114.IX Subsection "EXPORTED API SYMBOLS"
5014If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of 5115If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5015exported symbols, you can use the provided \fISymbol.*\fR files which list 5116exported symbols, you can use the provided \fISymbol.*\fR files which list
5016all public symbols, one per line: 5117all public symbols, one per line:
5017.PP 5118.PP
5018.Vb 2 5119.Vb 2
5019\& Symbols.ev for libev proper 5120\& Symbols.ev for libev proper
… …
5251.PP 5352.PP
5252\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5353\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5253.IX Subsection "select is buggy" 5354.IX Subsection "select is buggy"
5254.PP 5355.PP
5255All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5356All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5256one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file 5357one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5257descriptors you can pass in to 1024 \- your program suddenly crashes when 5358descriptors you can pass in to 1024 \- your program suddenly crashes when
5258you use more. 5359you use more.
5259.PP 5360.PP
5260There is an undocumented \*(L"workaround\*(R" for this \- defining 5361There is an undocumented \*(L"workaround\*(R" for this \- defining
5261\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5362\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
… …
5409Libev assumes not only that all watcher pointers have the same internal 5510Libev assumes not only that all watcher pointers have the same internal
5410structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also 5511structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5411assumes that the same (machine) code can be used to call any watcher 5512assumes that the same (machine) code can be used to call any watcher
5412callback: The watcher callbacks have different type signatures, but libev 5513callback: The watcher callbacks have different type signatures, but libev
5413calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5514calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5515.IP "null pointers and integer zero are represented by 0 bytes" 4
5516.IX Item "null pointers and integer zero are represented by 0 bytes"
5517Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
5518relies on this setting pointers and integers to null.
5414.IP "pointer accesses must be thread-atomic" 4 5519.IP "pointer accesses must be thread-atomic" 4
5415.IX Item "pointer accesses must be thread-atomic" 5520.IX Item "pointer accesses must be thread-atomic"
5416Accessing a pointer value must be atomic, it must both be readable and 5521Accessing a pointer value must be atomic, it must both be readable and
5417writable in one piece \- this is the case on all current architectures. 5522writable in one piece \- this is the case on all current architectures.
5418.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 5523.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4

Diff Legend

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