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

Comparing libev/ev.3 (file contents):
Revision 1.93 by root, Sun May 6 13:05:35 2012 UTC vs.
Revision 1.100 by root, Tue Oct 29 12:13:37 2013 UTC

1.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) 1.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
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 turned on, 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 "2012-05-06" "libev-4.11" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2013-10-29" "libev-4.15" "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.
… …
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
… …
514.IX Item "EVFLAG_NOENV" 523.IX Item "EVFLAG_NOENV"
515If this flag bit is or'ed into the flag value (or the program runs setuid 524If 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 525or 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 526\&\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 527override 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 528useful to try out specific backends to test their performance, to work
520around bugs. 529around bugs, or to make libev threadsafe (accessing environment variables
530cannot be done in a threadsafe way, but usually it works if no other
531thread modifies them).
521.ie n .IP """EVFLAG_FORKCHECK""" 4 532.ie n .IP """EVFLAG_FORKCHECK""" 4
522.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 533.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
523.IX Item "EVFLAG_FORKCHECK" 534.IX Item "EVFLAG_FORKCHECK"
524Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also 535Instead 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. 536make libev check for a fork in each iteration by enabling this flag.
… …
572\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. 583\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
573.Sp 584.Sp
574This flag's behaviour will become the default in future versions of libev. 585This flag's behaviour will become the default in future versions of libev.
575.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 586.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
576.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 587.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
577.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 588.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
578This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 589This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
579libev tries to roll its own fd_set with no limits on the number of fds, 590libev 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 591but 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 592using 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. 593usually the fastest backend for a low number of (low-numbered :) fds.
… …
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 602This 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 603\&\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). 604\&\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 605.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 606.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)" 607.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 608And this is your standard \fIpoll\fR\|(2) backend. It's more complicated
598than select, but handles sparse fds better and has no artificial 609than select, but handles sparse fds better and has no artificial
599limit on the number of fds you can use (except it will slow down 610limit 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, 611considerably 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 612i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
… …
603.Sp 614.Sp
604This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 615This 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. 616\&\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 617.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
607.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 618.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
608.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 619.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
609Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 620Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
610kernels). 621kernels).
611.Sp 622.Sp
612For few fds, this backend is a bit little slower than poll and select, but 623For 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 624it scales phenomenally better. While poll and select usually scale like
… …
666.Sp 677.Sp
667This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 678This 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. 679\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
669.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 680.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 681.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
671.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 682.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
672Kqueue deserves special mention, as at the time of this writing, it 683Kqueue deserves special mention, as at the time of this writing, it
673was broken on all BSDs except NetBSD (usually it doesn't work reliably 684was broken on all BSDs except NetBSD (usually it doesn't work reliably
674with anything but sockets and pipes, except on Darwin, where of course 685with anything but sockets and pipes, except on Darwin, where of course
675it's completely useless). Unlike epoll, however, whose brokenness 686it's completely useless). Unlike epoll, however, whose brokenness
676is by design, these kqueue bugs can (and eventually will) be fixed 687is by design, these kqueue bugs can (and eventually will) be fixed
… …
687kernel is more efficient (which says nothing about its actual speed, of 698kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 699course). 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 700cause 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 701two 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 702might have to leak fd's on fork, but it's more sane than epoll) and it
692drops fds silently in similarly hard-to-detect cases 703drops fds silently in similarly hard-to-detect cases.
693.Sp 704.Sp
694This backend usually performs well under most conditions. 705This backend usually performs well under most conditions.
695.Sp 706.Sp
696While nominally embeddable in other event loops, this doesn't work 707While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 708everywhere, 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 709almost 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 710(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 711(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. 712also broken on \s-1OS X\s0)) and, did I mention it, using it only for sockets.
702.Sp 713.Sp
703This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with 714This 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 715\&\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. 716\&\f(CW\*(C`NOTE_EOF\*(C'\fR.
706.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 717.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
… …
710implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets 721implementation). 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 722and is not embeddable, which would limit the usefulness of this backend
712immensely. 723immensely.
713.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 724.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
714.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 725.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
715.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" 726.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
716This uses the Solaris 10 event port mechanism. As with everything on Solaris, 727This 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)). 728it's really slow, but it still scales very well (O(active_fds)).
718.Sp 729.Sp
719While this backend scales well, it requires one system call per active 730While this backend scales well, it requires one system call per active
720file descriptor per loop iteration. For small and medium numbers of file 731file descriptor per loop iteration. For small and medium numbers of file
… …
805reinitialise the kernel state for backends that have one. Despite the 816reinitialise the kernel state for backends that have one. Despite the
806name, you can call it anytime, but it makes most sense after forking, in 817name, you can call it anytime, but it makes most sense after forking, in
807the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the 818the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the
808child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 819child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
809.Sp 820.Sp
810Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 821Again, 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 822a 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 823because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
813during fork. 824during fork.
814.Sp 825.Sp
815On the other hand, you only need to call this function in the child 826On the other hand, you only need to call this function in the child
… …
1352example it might indicate that a fd is readable or writable, and if your 1363example 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 1364callbacks 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 1365the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded
1355programs, though, as the fd could already be closed and reused for another 1366programs, though, as the fd could already be closed and reused for another
1356thing, so beware. 1367thing, so beware.
1357.SS "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" 1368.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1358.IX Subsection "GENERIC WATCHER FUNCTIONS" 1369.IX Subsection "GENERIC WATCHER FUNCTIONS"
1359.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1370.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
1360.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 1371.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
1361.IX Item "ev_init (ev_TYPE *watcher, callback)" 1372.IX Item "ev_init (ev_TYPE *watcher, callback)"
1362This macro initialises the generic portion of a watcher. The contents 1373This macro initialises the generic portion of a watcher. The contents
… …
1470or might not have been clamped to the valid range. 1481or might not have been clamped to the valid range.
1471.Sp 1482.Sp
1472The default priority used by watchers when no priority has been set is 1483The 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 :). 1484always \f(CW0\fR, which is supposed to not be too high and not be too low :).
1474.Sp 1485.Sp
1475See \*(L"\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0\*(R", below, for a more thorough treatment of 1486See \*(L"\s-1WATCHER PRIORITY MODELS\*(R"\s0, below, for a more thorough treatment of
1476priorities. 1487priorities.
1477.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 1488.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
1478.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" 1489.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 1490Invoke 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 1491\&\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. 1511not started in the first place.
1501.Sp 1512.Sp
1502See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related 1513See 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. 1514functions that do not need a watcher.
1504.PP 1515.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 1516See 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. 1517OWN COMPOSITE WATCHERS\*(R"\s0 idioms.
1507.SS "\s-1WATCHER\s0 \s-1STATES\s0" 1518.SS "\s-1WATCHER STATES\s0"
1508.IX Subsection "WATCHER STATES" 1519.IX Subsection "WATCHER STATES"
1509There are various watcher states mentioned throughout this manual \- 1520There are various watcher states mentioned throughout this manual \-
1510active, pending and so on. In this section these states and the rules to 1521active, 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 1522transition between them will be described in more detail \- and while these
1512rules might look complicated, they usually do \*(L"the right thing\*(R". 1523rules might look complicated, they usually do \*(L"the right thing\*(R".
1513.IP "initialiased" 4 1524.IP "initialised" 4
1514.IX Item "initialiased" 1525.IX Item "initialised"
1515Before a watcher can be registered with the event loop it has to be 1526Before a watcher can be registered with the event loop it has to be
1516initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to 1527initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to
1517\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. 1528\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1518.Sp 1529.Sp
1519In this state it is simply some block of memory that is suitable for 1530In this state it is simply some block of memory that is suitable for
… …
1555.Sp 1566.Sp
1556While stopped (and not pending) the watcher is essentially in the 1567While stopped (and not pending) the watcher is essentially in the
1557initialised state, that is, it can be reused, moved, modified in any way 1568initialised 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 1569you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR
1559it again). 1570it again).
1560.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" 1571.SS "\s-1WATCHER PRIORITY MODELS\s0"
1561.IX Subsection "WATCHER PRIORITY MODELS" 1572.IX Subsection "WATCHER PRIORITY MODELS"
1562Many event loops support \fIwatcher priorities\fR, which are usually small 1573Many event loops support \fIwatcher priorities\fR, which are usually small
1563integers that influence the ordering of event callback invocation 1574integers that influence the ordering of event callback invocation
1564between watchers in some way, all else being equal. 1575between watchers in some way, all else being equal.
1565.PP 1576.PP
… …
1763wish to read \- you would first have to request some data. 1774wish to read \- you would first have to request some data.
1764.PP 1775.PP
1765Since files are typically not-so-well supported by advanced notification 1776Since files are typically not-so-well supported by advanced notification
1766mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect 1777mechanism, 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 1778to 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 1779convenience: 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 1780usually 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 1781(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 1782\&\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 1783asynchronous I/O instead of with non-blocking I/O, it is still useful when
1773it \*(L"just works\*(R" instead of freezing. 1784it \*(L"just works\*(R" instead of freezing.
1774.PP 1785.PP
1775So avoid file descriptors pointing to files when you know it (e.g. use 1786So 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 1787libeio), 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 1788when you rarely read from a file instead of from a socket, and want to
1778reuse the same code path. 1789reuse the same code path.
1779.PP 1790.PP
1780\fIThe special problem of fork\fR 1791\fIThe special problem of fork\fR
1781.IX Subsection "The special problem of fork" 1792.IX Subsection "The special problem of fork"
… …
1791\fIThe special problem of \s-1SIGPIPE\s0\fR 1802\fIThe special problem of \s-1SIGPIPE\s0\fR
1792.IX Subsection "The special problem of SIGPIPE" 1803.IX Subsection "The special problem of SIGPIPE"
1793.PP 1804.PP
1794While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR: 1805While 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 1806when 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 1807sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1797this is sensible behaviour, for daemons, this is usually undesirable. 1808this is sensible behaviour, for daemons, this is usually undesirable.
1798.PP 1809.PP
1799So when you encounter spurious, unexplained daemon exits, make sure you 1810So 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 1811ignore \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). 1812somewhere, as that would have given you a big clue).
1802.PP 1813.PP
1803\fIThe special problem of \fIaccept()\fIing when you can't\fR 1814\fIThe special problem of \fIaccept()\fIing when you can't\fR
1804.IX Subsection "The special problem of accept()ing when you can't" 1815.IX Subsection "The special problem of accept()ing when you can't"
1805.PP 1816.PP
1806Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example, 1817Many 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 1818found in post\-2004 Linux) have the peculiar behaviour of not removing a
1808connection from the pending queue in all error cases. 1819connection from the pending queue in all error cases.
1809.PP 1820.PP
1810For example, larger servers often run out of file descriptors (because 1821For example, larger servers often run out of file descriptors (because
1811of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not 1822of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
2416In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2427In 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 2428ignored. Instead, each time the periodic watcher gets scheduled, the
2418reschedule callback will be called with the watcher as first, and the 2429reschedule callback will be called with the watcher as first, and the
2419current time as second argument. 2430current time as second argument.
2420.Sp 2431.Sp
2421\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, ever, 2432\&\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 2433or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2423allowed by documentation here\fR. 2434allowed by documentation here\fR.
2424.Sp 2435.Sp
2425If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2436If 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 2437it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2440It must return the next time to trigger, based on the passed time value 2451It must return the next time to trigger, based on the passed time value
2441(that is, the lowest time value larger than to the second argument). It 2452(that is, the lowest time value larger than to the second argument). It
2442will usually be called just before the callback will be triggered, but 2453will usually be called just before the callback will be triggered, but
2443might be called at other times, too. 2454might be called at other times, too.
2444.Sp 2455.Sp
2445\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or 2456\&\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. 2457equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2447.Sp 2458.Sp
2448This can be used to create very complex timers, such as a timer that 2459This 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 2460triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the
2450next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2461next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How
… …
2575The simplest way to ensure that the signal mask is reset in the child is 2586The simplest way to ensure that the signal mask is reset in the child is
2576to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will 2587to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
2577catch fork calls done by libraries (such as the libc) as well. 2588catch fork calls done by libraries (such as the libc) as well.
2578.PP 2589.PP
2579In current versions of libev, the signal will not be blocked indefinitely 2590In current versions of libev, the signal will not be blocked indefinitely
2580unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces 2591unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
2581the window of opportunity for problems, it will not go away, as libev 2592the window of opportunity for problems, it will not go away, as libev
2582\&\fIhas\fR to modify the signal mask, at least temporarily. 2593\&\fIhas\fR to modify the signal mask, at least temporarily.
2583.PP 2594.PP
2584So I can't stress this enough: \fIIf you do not reset your signal mask when 2595So I can't stress this enough: \fIIf you do not reset your signal mask when
2585you expect it to be empty, you have a race condition in your code\fR. This 2596you expect it to be empty, you have a race condition in your code\fR. This
… …
2615The signal the watcher watches out for. 2626The signal the watcher watches out for.
2616.PP 2627.PP
2617\fIExamples\fR 2628\fIExamples\fR
2618.IX Subsection "Examples" 2629.IX Subsection "Examples"
2619.PP 2630.PP
2620Example: Try to exit cleanly on \s-1SIGINT\s0. 2631Example: Try to exit cleanly on \s-1SIGINT.\s0
2621.PP 2632.PP
2622.Vb 5 2633.Vb 5
2623\& static void 2634\& static void
2624\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2635\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
2625\& { 2636\& {
… …
2740.ie n .SS """ev_stat"" \- did the file attributes just change?" 2751.ie n .SS """ev_stat"" \- did the file attributes just change?"
2741.el .SS "\f(CWev_stat\fP \- did the file attributes just change?" 2752.el .SS "\f(CWev_stat\fP \- did the file attributes just change?"
2742.IX Subsection "ev_stat - did the file attributes just change?" 2753.IX Subsection "ev_stat - did the file attributes just change?"
2743This watches a file system path for attribute changes. That is, it calls 2754This watches a file system path for attribute changes. That is, it calls
2744\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) 2755\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed)
2745and sees if it changed compared to the last time, invoking the callback if 2756and sees if it changed compared to the last time, invoking the callback
2746it did. 2757if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that
2758happen after the watcher has been started will be reported.
2747.PP 2759.PP
2748The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 2760The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
2749not exist\*(R" is a status change like any other. The condition \*(L"path does not 2761not exist\*(R" is a status change like any other. The condition \*(L"path does not
2750exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the 2762exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the
2751\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at 2763\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at
… …
2781compilation environment, which means that on systems with large file 2793compilation environment, which means that on systems with large file
2782support disabled by default, you get the 32 bit version of the stat 2794support disabled by default, you get the 32 bit version of the stat
2783structure. When using the library from programs that change the \s-1ABI\s0 to 2795structure. When using the library from programs that change the \s-1ABI\s0 to
2784use 64 bit file offsets the programs will fail. In that case you have to 2796use 64 bit file offsets the programs will fail. In that case you have to
2785compile libev with the same flags to get binary compatibility. This is 2797compile libev with the same flags to get binary compatibility. This is
2786obviously the case with any flags that change the \s-1ABI\s0, but the problem is 2798obviously the case with any flags that change the \s-1ABI,\s0 but the problem is
2787most noticeably displayed with ev_stat and large file support. 2799most noticeably displayed with ev_stat and large file support.
2788.PP 2800.PP
2789The solution for this is to lobby your distribution maker to make large 2801The solution for this is to lobby your distribution maker to make large
2790file interfaces available by default (as e.g. FreeBSD does) and not 2802file interfaces available by default (as e.g. FreeBSD does) and not
2791optional. Libev cannot simply switch on large file support because it has 2803optional. Libev cannot simply switch on large file support because it has
… …
3222.Ve 3234.Ve
3223.PP 3235.PP
3224Method 4: Do not use a prepare or check watcher because the module you 3236Method 4: Do not use a prepare or check watcher because the module you
3225want to embed is not flexible enough to support it. Instead, you can 3237want to embed is not flexible enough to support it. Instead, you can
3226override their poll function. The drawback with this solution is that the 3238override their poll function. The drawback with this solution is that the
3227main loop is now no longer controllable by \s-1EV\s0. The \f(CW\*(C`Glib::EV\*(C'\fR module uses 3239main loop is now no longer controllable by \s-1EV.\s0 The \f(CW\*(C`Glib::EV\*(C'\fR module uses
3228this approach, effectively embedding \s-1EV\s0 as a client into the horrible 3240this approach, effectively embedding \s-1EV\s0 as a client into the horrible
3229libglib event loop. 3241libglib event loop.
3230.PP 3242.PP
3231.Vb 4 3243.Vb 4
3232\& static gint 3244\& static gint
… …
3316\fIWatcher-Specific Functions and Data Members\fR 3328\fIWatcher-Specific Functions and Data Members\fR
3317.IX Subsection "Watcher-Specific Functions and Data Members" 3329.IX Subsection "Watcher-Specific Functions and Data Members"
3318.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3330.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
3319.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 3331.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
3320.PD 0 3332.PD 0
3321.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3333.IP "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)" 4
3322.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 3334.IX Item "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)"
3323.PD 3335.PD
3324Configures the watcher to embed the given loop, which must be 3336Configures the watcher to embed the given loop, which must be
3325embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be 3337embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be
3326invoked automatically, otherwise it is the responsibility of the callback 3338invoked automatically, otherwise it is the responsibility of the callback
3327to invoke it (it will continue to be called until the sweep has been done, 3339to invoke it (it will continue to be called until the sweep has been done,
… …
3390.ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" 3402.ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork"
3391.el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" 3403.el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
3392.IX Subsection "ev_fork - the audacity to resume the event loop after a fork" 3404.IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
3393Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 3405Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
3394whoever is a good citizen cared to tell libev about it by calling 3406whoever is a good citizen cared to tell libev about it by calling
3395\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the 3407\&\f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the event loop blocks next
3396event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, 3408and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, and only in the child
3397and only in the child after the fork. If whoever good citizen calling 3409after the fork. If whoever good citizen calling \f(CW\*(C`ev_default_fork\*(C'\fR cheats
3398\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork 3410and calls it in the wrong process, the fork handlers will be invoked, too,
3399handlers will be invoked, too, of course. 3411of course.
3400.PP 3412.PP
3401\fIThe special problem of life after fork \- how is it possible?\fR 3413\fIThe special problem of life after fork \- how is it possible?\fR
3402.IX Subsection "The special problem of life after fork - how is it possible?" 3414.IX Subsection "The special problem of life after fork - how is it possible?"
3403.PP 3415.PP
3404Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3416Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set
… …
3649\&\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 3661\&\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
3650value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR 3662value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR
3651a timeout and an io event at the same time \- you probably should give io 3663a timeout and an io event at the same time \- you probably should give io
3652events precedence. 3664events precedence.
3653.Sp 3665.Sp
3654Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0. 3666Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO.\s0
3655.Sp 3667.Sp
3656.Vb 7 3668.Vb 7
3657\& static void stdin_ready (int revents, void *arg) 3669\& static void stdin_ready (int revents, void *arg)
3658\& { 3670\& {
3659\& if (revents & EV_READ) 3671\& if (revents & EV_READ)
… …
3675.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3687.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
3676.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)" 3688.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)"
3677This section explains some common idioms that are not immediately 3689This section explains some common idioms that are not immediately
3678obvious. Note that examples are sprinkled over the whole manual, and this 3690obvious. Note that examples are sprinkled over the whole manual, and this
3679section only contains stuff that wouldn't fit anywhere else. 3691section only contains stuff that wouldn't fit anywhere else.
3680.SS "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" 3692.SS "\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\s0"
3681.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" 3693.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
3682Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read 3694Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read
3683or modify at any time: libev will completely ignore it. This can be used 3695or modify at any time: libev will completely ignore it. This can be used
3684to associate arbitrary data with your watcher. If you need more data and 3696to associate arbitrary data with your watcher. If you need more data and
3685don't want to allocate memory separately and store a pointer to it in that 3697don't want to allocate memory separately and store a pointer to it in that
… …
3711\& } 3723\& }
3712.Ve 3724.Ve
3713.PP 3725.PP
3714More interesting and less C\-conformant ways of casting your callback 3726More interesting and less C\-conformant ways of casting your callback
3715function type instead have been omitted. 3727function type instead have been omitted.
3716.SS "\s-1BUILDING\s0 \s-1YOUR\s0 \s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0" 3728.SS "\s-1BUILDING YOUR OWN COMPOSITE WATCHERS\s0"
3717.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS" 3729.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS"
3718Another common scenario is to use some data structure with multiple 3730Another common scenario is to use some data structure with multiple
3719embedded watchers, in effect creating your own watcher that combines 3731embedded watchers, in effect creating your own watcher that combines
3720multiple libev event sources into one \*(L"super-watcher\*(R": 3732multiple libev event sources into one \*(L"super-watcher\*(R":
3721.PP 3733.PP
… …
3749\& { 3761\& {
3750\& struct my_biggy big = (struct my_biggy *) 3762\& struct my_biggy big = (struct my_biggy *)
3751\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3763\& (((char *)w) \- offsetof (struct my_biggy, t2));
3752\& } 3764\& }
3753.Ve 3765.Ve
3754.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0" 3766.SS "\s-1AVOIDING FINISHING BEFORE RETURNING\s0"
3755.IX Subsection "AVOIDING FINISHING BEFORE RETURNING" 3767.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3756Often you have structures like this in event-based programs: 3768Often you have structures like this in event-based programs:
3757.PP 3769.PP
3758.Vb 4 3770.Vb 4
3759\& callback () 3771\& callback ()
… …
3781already been invoked. 3793already been invoked.
3782.PP 3794.PP
3783A common way around all these issues is to make sure that 3795A common way around all these issues is to make sure that
3784\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If 3796\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If
3785\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially 3797\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
3786delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher 3798delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for
3787for example, or more sneakily, by reusing an existing (stopped) watcher 3799example, or more sneakily, by reusing an existing (stopped) watcher and
3788and pushing it into the pending queue: 3800pushing it into the pending queue:
3789.PP 3801.PP
3790.Vb 2 3802.Vb 2
3791\& ev_set_cb (watcher, callback); 3803\& ev_set_cb (watcher, callback);
3792\& ev_feed_event (EV_A_ watcher, 0); 3804\& ev_feed_event (EV_A_ watcher, 0);
3793.Ve 3805.Ve
3794.PP 3806.PP
3795This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is 3807This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3796invoked, while not delaying callback invocation too much. 3808invoked, while not delaying callback invocation too much.
3797.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0" 3809.SS "\s-1MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS\s0"
3798.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" 3810.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3799Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3811Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3800\&\fImodal\fR interaction, which is most easily implemented by recursively 3812\&\fImodal\fR interaction, which is most easily implemented by recursively
3801invoking \f(CW\*(C`ev_run\*(C'\fR. 3813invoking \f(CW\*(C`ev_run\*(C'\fR.
3802.PP 3814.PP
3803This brings the problem of exiting \- a callback might want to finish the 3815This brings the problem of exiting \- a callback might want to finish the
3804main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but 3816main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but
3805a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one 3817a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one
3806and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some 3818and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some
3807other combination: In these cases, \f(CW\*(C`ev_break\*(C'\fR will not work alone. 3819other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work.
3808.PP 3820.PP
3809The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR 3821The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR
3810invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is 3822invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is
3811triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: 3823triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR:
3812.PP 3824.PP
… …
3834\& exit_main_loop = 1; 3846\& exit_main_loop = 1;
3835\& 3847\&
3836\& // exit both 3848\& // exit both
3837\& exit_main_loop = exit_nested_loop = 1; 3849\& exit_main_loop = exit_nested_loop = 1;
3838.Ve 3850.Ve
3839.SS "\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0" 3851.SS "\s-1THREAD LOCKING EXAMPLE\s0"
3840.IX Subsection "THREAD LOCKING EXAMPLE" 3852.IX Subsection "THREAD LOCKING EXAMPLE"
3841Here is a fictitious example of how to run an event loop in a different 3853Here is a fictitious example of how to run an event loop in a different
3842thread from where callbacks are being invoked and watchers are 3854thread from where callbacks are being invoked and watchers are
3843created/added/removed. 3855created/added/removed.
3844.PP 3856.PP
… …
3985.PP 3997.PP
3986Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise 3998Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise
3987an event loop currently blocking in the kernel will have no knowledge 3999an event loop currently blocking in the kernel will have no knowledge
3988about the newly added timer. By waking up the loop it will pick up any new 4000about the newly added timer. By waking up the loop it will pick up any new
3989watchers in the next event loop iteration. 4001watchers in the next event loop iteration.
3990.SS "\s-1THREADS\s0, \s-1COROUTINES\s0, \s-1CONTINUATIONS\s0, \s-1QUEUES\s0... \s-1INSTEAD\s0 \s-1OF\s0 \s-1CALLBACKS\s0" 4002.SS "\s-1THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS\s0"
3991.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS" 4003.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS"
3992While the overhead of a callback that e.g. schedules a thread is small, it 4004While the overhead of a callback that e.g. schedules a thread is small, it
3993is still an overhead. If you embed libev, and your main usage is with some 4005is still an overhead. If you embed libev, and your main usage is with some
3994kind of threads or coroutines, you might want to customise libev so that 4006kind of threads or coroutines, you might want to customise libev so that
3995doesn't need callbacks anymore. 4007doesn't need callbacks anymore.
… …
4031You can do similar tricks if you have, say, threads with an event queue \- 4043You can do similar tricks if you have, say, threads with an event queue \-
4032instead of storing a coroutine, you store the queue object and instead of 4044instead of storing a coroutine, you store the queue object and instead of
4033switching to a coroutine, you push the watcher onto the queue and notify 4045switching to a coroutine, you push the watcher onto the queue and notify
4034any waiters. 4046any waiters.
4035.PP 4047.PP
4036To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two 4048To embed libev, see \*(L"\s-1EMBEDDING\*(R"\s0, but in short, it's easiest to create two
4037files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4049files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
4038.PP 4050.PP
4039.Vb 4 4051.Vb 4
4040\& // my_ev.h 4052\& // my_ev.h
4041\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4053\& #define EV_CB_DECLARE(type) struct my_coro *cb;
… …
4088libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4100libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4089will work fine. 4101will work fine.
4090.PP 4102.PP
4091Proper exception specifications might have to be added to callbacks passed 4103Proper exception specifications might have to be added to callbacks passed
4092to libev: exceptions may be thrown only from watcher callbacks, all 4104to libev: exceptions may be thrown only from watcher callbacks, all
4093other callbacks (allocator, syserr, loop acquire/release and periodioc 4105other callbacks (allocator, syserr, loop acquire/release and periodic
4094reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4106reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw
4095()\*(C'\fR specification. If you have code that needs to be compiled as both C 4107()\*(C'\fR specification. If you have code that needs to be compiled as both C
4096and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4108and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
4097.PP 4109.PP
4098.Vb 6 4110.Vb 6
… …
4261.IX Item "w->set (loop)" 4273.IX Item "w->set (loop)"
4262Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only 4274Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only
4263do this when the watcher is inactive (and not pending either). 4275do this when the watcher is inactive (and not pending either).
4264.IP "w\->set ([arguments])" 4 4276.IP "w\->set ([arguments])" 4
4265.IX Item "w->set ([arguments])" 4277.IX Item "w->set ([arguments])"
4266Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this 4278Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR (except for \f(CW\*(C`ev::embed\*(C'\fR watchers>),
4267method or a suitable start method must be called at least once. Unlike the 4279with the same arguments. Either this method or a suitable start method
4268C counterpart, an active watcher gets automatically stopped and restarted 4280must be called at least once. Unlike the C counterpart, an active watcher
4269when reconfiguring it with this method. 4281gets automatically stopped and restarted when reconfiguring it with this
4282method.
4283.Sp
4284For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4285clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4270.IP "w\->start ()" 4 4286.IP "w\->start ()" 4
4271.IX Item "w->start ()" 4287.IX Item "w->start ()"
4272Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4288Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4273constructor already stores the event loop. 4289constructor already stores the event loop.
4274.IP "w\->start ([arguments])" 4 4290.IP "w\->start ([arguments])" 4
… …
4332there are additional modules that implement libev-compatible interfaces 4348there are additional modules that implement libev-compatible interfaces
4333to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays), 4349to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays),
4334\&\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 4350\&\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
4335and \f(CW\*(C`EV::Glib\*(C'\fR). 4351and \f(CW\*(C`EV::Glib\*(C'\fR).
4336.Sp 4352.Sp
4337It can be found and installed via \s-1CPAN\s0, its homepage is at 4353It can be found and installed via \s-1CPAN,\s0 its homepage is at
4338<http://software.schmorp.de/pkg/EV>. 4354<http://software.schmorp.de/pkg/EV>.
4339.IP "Python" 4 4355.IP "Python" 4
4340.IX Item "Python" 4356.IX Item "Python"
4341Python bindings can be found at <http://code.google.com/p/pyev/>. It 4357Python bindings can be found at <http://code.google.com/p/pyev/>. It
4342seems to be quite complete and well-documented. 4358seems to be quite complete and well-documented.
… …
4350Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR 4366Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4351makes rev work even on mingw. 4367makes rev work even on mingw.
4352.IP "Haskell" 4 4368.IP "Haskell" 4
4353.IX Item "Haskell" 4369.IX Item "Haskell"
4354A haskell binding to libev is available at 4370A haskell binding to libev is available at
4355http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>. 4371<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>.
4356.IP "D" 4 4372.IP "D" 4
4357.IX Item "D" 4373.IX Item "D"
4358Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4374Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4359be found at <http://www.llucax.com.ar/proj/ev.d/index.html>. 4375be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4360.IP "Ocaml" 4 4376.IP "Ocaml" 4
4361.IX Item "Ocaml" 4377.IX Item "Ocaml"
4362Erkki Seppala has written Ocaml bindings for libev, to be found at 4378Erkki Seppala has written Ocaml bindings for libev, to be found at
4363http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 4379<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
4364.IP "Lua" 4 4380.IP "Lua" 4
4365.IX Item "Lua" 4381.IX Item "Lua"
4366Brian Maher has written a partial interface to libev for lua (at the 4382Brian Maher has written a partial interface to libev for lua (at the
4367time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4383time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4368http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. 4384<http://github.com/brimworks/lua\-ev>.
4385.IP "Javascript" 4
4386.IX Item "Javascript"
4387Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4388.IP "Others" 4
4389.IX Item "Others"
4390There are others, and I stopped counting.
4369.SH "MACRO MAGIC" 4391.SH "MACRO MAGIC"
4370.IX Header "MACRO MAGIC" 4392.IX Header "MACRO MAGIC"
4371Libev can be compiled with a variety of options, the most fundamental 4393Libev can be compiled with a variety of options, the most fundamental
4372of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 4394of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
4373functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 4395functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
4456.SS "\s-1FILESETS\s0" 4478.SS "\s-1FILESETS\s0"
4457.IX Subsection "FILESETS" 4479.IX Subsection "FILESETS"
4458Depending on what features you need you need to include one or more sets of files 4480Depending on what features you need you need to include one or more sets of files
4459in your application. 4481in your application.
4460.PP 4482.PP
4461\fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR 4483\fI\s-1CORE EVENT LOOP\s0\fR
4462.IX Subsection "CORE EVENT LOOP" 4484.IX Subsection "CORE EVENT LOOP"
4463.PP 4485.PP
4464To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual 4486To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual
4465configuration (no autoconf): 4487configuration (no autoconf):
4466.PP 4488.PP
… …
4469\& #include "ev.c" 4491\& #include "ev.c"
4470.Ve 4492.Ve
4471.PP 4493.PP
4472This will automatically include \fIev.h\fR, too, and should be done in a 4494This will automatically include \fIev.h\fR, too, and should be done in a
4473single C source file only to provide the function implementations. To use 4495single C source file only to provide the function implementations. To use
4474it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best 4496it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best
4475done by writing a wrapper around \fIev.h\fR that you can include instead and 4497done by writing a wrapper around \fIev.h\fR that you can include instead and
4476where you can put other configuration options): 4498where you can put other configuration options):
4477.PP 4499.PP
4478.Vb 2 4500.Vb 2
4479\& #define EV_STANDALONE 1 4501\& #define EV_STANDALONE 1
… …
4503.Ve 4525.Ve
4504.PP 4526.PP
4505\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4527\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4506to compile this single file. 4528to compile this single file.
4507.PP 4529.PP
4508\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR 4530\fI\s-1LIBEVENT COMPATIBILITY API\s0\fR
4509.IX Subsection "LIBEVENT COMPATIBILITY API" 4531.IX Subsection "LIBEVENT COMPATIBILITY API"
4510.PP 4532.PP
4511To include the libevent compatibility \s-1API\s0, also include: 4533To include the libevent compatibility \s-1API,\s0 also include:
4512.PP 4534.PP
4513.Vb 1 4535.Vb 1
4514\& #include "event.c" 4536\& #include "event.c"
4515.Ve 4537.Ve
4516.PP 4538.PP
… …
4518.PP 4540.PP
4519.Vb 1 4541.Vb 1
4520\& #include "event.h" 4542\& #include "event.h"
4521.Ve 4543.Ve
4522.PP 4544.PP
4523in the files that want to use the libevent \s-1API\s0. This also includes \fIev.h\fR. 4545in the files that want to use the libevent \s-1API.\s0 This also includes \fIev.h\fR.
4524.PP 4546.PP
4525You need the following additional files for this: 4547You need the following additional files for this:
4526.PP 4548.PP
4527.Vb 2 4549.Vb 2
4528\& event.h 4550\& event.h
4529\& event.c 4551\& event.c
4530.Ve 4552.Ve
4531.PP 4553.PP
4532\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR 4554\fI\s-1AUTOCONF SUPPORT\s0\fR
4533.IX Subsection "AUTOCONF SUPPORT" 4555.IX Subsection "AUTOCONF SUPPORT"
4534.PP 4556.PP
4535Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in 4557Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in
4536whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your 4558whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your
4537\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then 4559\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then
… …
4540For this of course you need the m4 file: 4562For this of course you need the m4 file:
4541.PP 4563.PP
4542.Vb 1 4564.Vb 1
4543\& libev.m4 4565\& libev.m4
4544.Ve 4566.Ve
4545.SS "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0" 4567.SS "\s-1PREPROCESSOR SYMBOLS/MACROS\s0"
4546.IX Subsection "PREPROCESSOR SYMBOLS/MACROS" 4568.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
4547Libev can be configured via a variety of preprocessor symbols you have to 4569Libev can be configured via a variety of preprocessor symbols you have to
4548define before including (or compiling) any of its files. The default in 4570define before including (or compiling) any of its files. The default in
4549the absence of autoconf is documented for every option. 4571the absence of autoconf is documented for every option.
4550.PP 4572.PP
4551Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI\s0, and can have different 4573Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI,\s0 and can have different
4552values when compiling libev vs. including \fIev.h\fR, so it is permissible 4574values when compiling libev vs. including \fIev.h\fR, so it is permissible
4553to redefine them before including \fIev.h\fR without breaking compatibility 4575to redefine them before including \fIev.h\fR without breaking compatibility
4554to a compiled library. All other symbols change the \s-1ABI\s0, which means all 4576to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4555users of libev and the libev code itself must be compiled with compatible 4577users of libev and the libev code itself must be compiled with compatible
4556settings. 4578settings.
4557.IP "\s-1EV_COMPAT3\s0 (h)" 4 4579.IP "\s-1EV_COMPAT3 \s0(h)" 4
4558.IX Item "EV_COMPAT3 (h)" 4580.IX Item "EV_COMPAT3 (h)"
4559Backwards compatibility is a major concern for libev. This is why this 4581Backwards compatibility is a major concern for libev. This is why this
4560release of libev comes with wrappers for the functions and symbols that 4582release of libev comes with wrappers for the functions and symbols that
4561have been renamed between libev version 3 and 4. 4583have been renamed between libev version 3 and 4.
4562.Sp 4584.Sp
… …
4567typedef in that case. 4589typedef in that case.
4568.Sp 4590.Sp
4569In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4591In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4570and in some even more future version the compatibility code will be 4592and in some even more future version the compatibility code will be
4571removed completely. 4593removed completely.
4572.IP "\s-1EV_STANDALONE\s0 (h)" 4 4594.IP "\s-1EV_STANDALONE \s0(h)" 4
4573.IX Item "EV_STANDALONE (h)" 4595.IX Item "EV_STANDALONE (h)"
4574Must always be \f(CW1\fR if you do not use autoconf configuration, which 4596Must always be \f(CW1\fR if you do not use autoconf configuration, which
4575keeps libev from including \fIconfig.h\fR, and it also defines dummy 4597keeps libev from including \fIconfig.h\fR, and it also defines dummy
4576implementations for some libevent functions (such as logging, which is not 4598implementations for some libevent functions (such as logging, which is not
4577supported). It will also not define any of the structs usually found in 4599supported). It will also not define any of the structs usually found in
… …
4668.IX Item "EV_WIN32_CLOSE_FD(fd)" 4690.IX Item "EV_WIN32_CLOSE_FD(fd)"
4669If programs implement their own fd to handle mapping on win32, then this 4691If programs implement their own fd to handle mapping on win32, then this
4670macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister 4692macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister
4671file descriptors again. Note that the replacement function has to close 4693file descriptors again. Note that the replacement function has to close
4672the underlying \s-1OS\s0 handle. 4694the underlying \s-1OS\s0 handle.
4695.IP "\s-1EV_USE_WSASOCKET\s0" 4
4696.IX Item "EV_USE_WSASOCKET"
4697If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal
4698communication socket, which works better in some environments. Otherwise,
4699the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other
4700environments.
4673.IP "\s-1EV_USE_POLL\s0" 4 4701.IP "\s-1EV_USE_POLL\s0" 4
4674.IX Item "EV_USE_POLL" 4702.IX Item "EV_USE_POLL"
4675If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) 4703If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
4676backend. Otherwise it will be enabled on non\-win32 platforms. It 4704backend. Otherwise it will be enabled on non\-win32 platforms. It
4677takes precedence over select. 4705takes precedence over select.
… …
4714between threads, that is, threads can be used, but threads never run on 4742between threads, that is, threads can be used, but threads never run on
4715different cpus (or different cpu cores). This reduces dependencies 4743different cpus (or different cpu cores). This reduces dependencies
4716and makes libev faster. 4744and makes libev faster.
4717.IP "\s-1EV_NO_THREADS\s0" 4 4745.IP "\s-1EV_NO_THREADS\s0" 4
4718.IX Item "EV_NO_THREADS" 4746.IX Item "EV_NO_THREADS"
4719If defined to be \f(CW1\fR, libev will assume that it will never be called 4747If defined to be \f(CW1\fR, libev will assume that it will never be called from
4720from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, 4748different threads (that includes signal handlers), which is a stronger
4721above. This reduces dependencies and makes libev faster. 4749assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes
4750libev faster.
4722.IP "\s-1EV_ATOMIC_T\s0" 4 4751.IP "\s-1EV_ATOMIC_T\s0" 4
4723.IX Item "EV_ATOMIC_T" 4752.IX Item "EV_ATOMIC_T"
4724Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4753Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4725access is atomic and serialised with respect to other threads or signal 4754access is atomic with respect to other threads or signal contexts. No
4726contexts. No such type is easily found in the C language, so you can 4755such type is easily found in the C language, so you can provide your own
4727provide your own type that you know is safe for your purposes. It is used 4756type that you know is safe for your purposes. It is used both for signal
4728both for signal handler \*(L"locking\*(R" as well as for signal and thread safety 4757handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4729in \f(CW\*(C`ev_async\*(C'\fR watchers. 4758watchers.
4730.Sp 4759.Sp
4731In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4760In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4732(from \fIsignal.h\fR), which is usually good enough on most platforms, 4761(from \fIsignal.h\fR), which is usually good enough on most platforms.
4733although strictly speaking using a type that also implies a memory fence
4734is required.
4735.IP "\s-1EV_H\s0 (h)" 4 4762.IP "\s-1EV_H \s0(h)" 4
4736.IX Item "EV_H (h)" 4763.IX Item "EV_H (h)"
4737The name of the \fIev.h\fR header file used to include it. The default if 4764The name of the \fIev.h\fR header file used to include it. The default if
4738undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4765undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4739used to virtually rename the \fIev.h\fR header file in case of conflicts. 4766used to virtually rename the \fIev.h\fR header file in case of conflicts.
4740.IP "\s-1EV_CONFIG_H\s0 (h)" 4 4767.IP "\s-1EV_CONFIG_H \s0(h)" 4
4741.IX Item "EV_CONFIG_H (h)" 4768.IX Item "EV_CONFIG_H (h)"
4742If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4769If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4743\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4770\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4744\&\f(CW\*(C`EV_H\*(C'\fR, above. 4771\&\f(CW\*(C`EV_H\*(C'\fR, above.
4745.IP "\s-1EV_EVENT_H\s0 (h)" 4 4772.IP "\s-1EV_EVENT_H \s0(h)" 4
4746.IX Item "EV_EVENT_H (h)" 4773.IX Item "EV_EVENT_H (h)"
4747Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4774Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4748of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4775of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4749.IP "\s-1EV_PROTOTYPES\s0 (h)" 4 4776.IP "\s-1EV_PROTOTYPES \s0(h)" 4
4750.IX Item "EV_PROTOTYPES (h)" 4777.IX Item "EV_PROTOTYPES (h)"
4751If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4778If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4752prototypes, but still define all the structs and other symbols. This is 4779prototypes, but still define all the structs and other symbols. This is
4753occasionally useful if you want to provide your own wrapper functions 4780occasionally useful if you want to provide your own wrapper functions
4754around libev functions. 4781around libev functions.
… …
4778all the priorities, so having many of them (hundreds) uses a lot of space 4805all the priorities, so having many of them (hundreds) uses a lot of space
4779and time, so using the defaults of five priorities (\-2 .. +2) is usually 4806and time, so using the defaults of five priorities (\-2 .. +2) is usually
4780fine. 4807fine.
4781.Sp 4808.Sp
4782If your embedding application does not need any priorities, defining these 4809If your embedding application does not need any priorities, defining these
4783both to \f(CW0\fR will save some memory and \s-1CPU\s0. 4810both to \f(CW0\fR will save some memory and \s-1CPU.\s0
4784.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 4811.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
4785.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." 4812.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."
4786If undefined or defined to be \f(CW1\fR (and the platform supports it), then 4813If undefined or defined to be \f(CW1\fR (and the platform supports it), then
4787the respective watcher type is supported. If defined to be \f(CW0\fR, then it 4814the respective watcher type is supported. If defined to be \f(CW0\fR, then it
4788is not. Disabling watcher types mainly saves code size. 4815is not. Disabling watcher types mainly saves code size.
4789.IP "\s-1EV_FEATURES\s0" 4 4816.IP "\s-1EV_FEATURES\s0" 4
… …
4963.Vb 3 4990.Vb 3
4964\& #define EV_COMMON \e 4991\& #define EV_COMMON \e
4965\& SV *self; /* contains this struct */ \e 4992\& SV *self; /* contains this struct */ \e
4966\& SV *cb_sv, *fh /* note no trailing ";" */ 4993\& SV *cb_sv, *fh /* note no trailing ";" */
4967.Ve 4994.Ve
4968.IP "\s-1EV_CB_DECLARE\s0 (type)" 4 4995.IP "\s-1EV_CB_DECLARE \s0(type)" 4
4969.IX Item "EV_CB_DECLARE (type)" 4996.IX Item "EV_CB_DECLARE (type)"
4970.PD 0 4997.PD 0
4971.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4 4998.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4
4972.IX Item "EV_CB_INVOKE (watcher, revents)" 4999.IX Item "EV_CB_INVOKE (watcher, revents)"
4973.IP "ev_set_cb (ev, cb)" 4 5000.IP "ev_set_cb (ev, cb)" 4
4974.IX Item "ev_set_cb (ev, cb)" 5001.IX Item "ev_set_cb (ev, cb)"
4975.PD 5002.PD
4976Can be used to change the callback member declaration in each watcher, 5003Can be used to change the callback member declaration in each watcher,
4977and the way callbacks are invoked and set. Must expand to a struct member 5004and the way callbacks are invoked and set. Must expand to a struct member
4978definition and a statement, respectively. See the \fIev.h\fR header file for 5005definition and a statement, respectively. See the \fIev.h\fR header file for
4979their default definitions. One possible use for overriding these is to 5006their default definitions. One possible use for overriding these is to
4980avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5007avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
4981method calls instead of plain function calls in \*(C+. 5008method calls instead of plain function calls in \*(C+.
4982.SS "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0" 5009.SS "\s-1EXPORTED API SYMBOLS\s0"
4983.IX Subsection "EXPORTED API SYMBOLS" 5010.IX Subsection "EXPORTED API SYMBOLS"
4984If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of 5011If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of
4985exported symbols, you can use the provided \fISymbol.*\fR files which list 5012exported symbols, you can use the provided \fISymbol.*\fR files which list
4986all public symbols, one per line: 5013all public symbols, one per line:
4987.PP 5014.PP
4988.Vb 2 5015.Vb 2
4989\& Symbols.ev for libev proper 5016\& Symbols.ev for libev proper
… …
5041\& #include "ev_cpp.h" 5068\& #include "ev_cpp.h"
5042\& #include "ev.c" 5069\& #include "ev.c"
5043.Ve 5070.Ve
5044.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5071.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5045.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5072.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5046.SS "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0" 5073.SS "\s-1THREADS AND COROUTINES\s0"
5047.IX Subsection "THREADS AND COROUTINES" 5074.IX Subsection "THREADS AND COROUTINES"
5048\fI\s-1THREADS\s0\fR 5075\fI\s-1THREADS\s0\fR
5049.IX Subsection "THREADS" 5076.IX Subsection "THREADS"
5050.PP 5077.PP
5051All libev functions are reentrant and thread-safe unless explicitly 5078All libev functions are reentrant and thread-safe unless explicitly
… …
5097An example use would be to communicate signals or other events that only 5124An example use would be to communicate signals or other events that only
5098work in the default loop by registering the signal watcher with the 5125work in the default loop by registering the signal watcher with the
5099default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop 5126default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop
5100watcher callback into the event loop interested in the signal. 5127watcher callback into the event loop interested in the signal.
5101.PP 5128.PP
5102See also \*(L"\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0\*(R". 5129See also \*(L"\s-1THREAD LOCKING EXAMPLE\*(R"\s0.
5103.PP 5130.PP
5104\fI\s-1COROUTINES\s0\fR 5131\fI\s-1COROUTINES\s0\fR
5105.IX Subsection "COROUTINES" 5132.IX Subsection "COROUTINES"
5106.PP 5133.PP
5107Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"): 5134Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"):
… …
5112that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. 5139that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
5113.PP 5140.PP
5114Care has been taken to ensure that libev does not keep local state inside 5141Care has been taken to ensure that libev does not keep local state inside
5115\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as 5142\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as
5116they do not call any callbacks. 5143they do not call any callbacks.
5117.SS "\s-1COMPILER\s0 \s-1WARNINGS\s0" 5144.SS "\s-1COMPILER WARNINGS\s0"
5118.IX Subsection "COMPILER WARNINGS" 5145.IX Subsection "COMPILER WARNINGS"
5119Depending on your compiler and compiler settings, you might get no or a 5146Depending on your compiler and compiler settings, you might get no or a
5120lot of warnings when compiling libev code. Some people are apparently 5147lot of warnings when compiling libev code. Some people are apparently
5121scared by this. 5148scared by this.
5122.PP 5149.PP
… …
5174.PP 5201.PP
5175If you need, for some reason, empty reports from valgrind for your project 5202If you need, for some reason, empty reports from valgrind for your project
5176I suggest using suppression lists. 5203I suggest using suppression lists.
5177.SH "PORTABILITY NOTES" 5204.SH "PORTABILITY NOTES"
5178.IX Header "PORTABILITY NOTES" 5205.IX Header "PORTABILITY NOTES"
5179.SS "\s-1GNU/LINUX\s0 32 \s-1BIT\s0 \s-1LIMITATIONS\s0" 5206.SS "\s-1GNU/LINUX 32 BIT LIMITATIONS\s0"
5180.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS" 5207.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS"
5181GNU/Linux is the only common platform that supports 64 bit file/large file 5208GNU/Linux is the only common platform that supports 64 bit file/large file
5182interfaces but \fIdisables\fR them by default. 5209interfaces but \fIdisables\fR them by default.
5183.PP 5210.PP
5184That means that libev compiled in the default environment doesn't support 5211That means that libev compiled in the default environment doesn't support
5185files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers. 5212files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers.
5186.PP 5213.PP
5187Unfortunately, many programs try to work around this GNU/Linux issue 5214Unfortunately, many programs try to work around this GNU/Linux issue
5188by enabling the large file \s-1API\s0, which makes them incompatible with the 5215by enabling the large file \s-1API,\s0 which makes them incompatible with the
5189standard libev compiled for their system. 5216standard libev compiled for their system.
5190.PP 5217.PP
5191Likewise, libev cannot enable the large file \s-1API\s0 itself as this would 5218Likewise, libev cannot enable the large file \s-1API\s0 itself as this would
5192suddenly make it incompatible to the default compile time environment, 5219suddenly make it incompatible to the default compile time environment,
5193i.e. all programs not using special compile switches. 5220i.e. all programs not using special compile switches.
5194.SS "\s-1OS/X\s0 \s-1AND\s0 \s-1DARWIN\s0 \s-1BUGS\s0" 5221.SS "\s-1OS/X AND DARWIN BUGS\s0"
5195.IX Subsection "OS/X AND DARWIN BUGS" 5222.IX Subsection "OS/X AND DARWIN BUGS"
5196The whole thing is a bug if you ask me \- basically any system interface 5223The whole thing is a bug if you ask me \- basically any system interface
5197you touch is broken, whether it is locales, poll, kqueue or even the 5224you touch is broken, whether it is locales, poll, kqueue or even the
5198OpenGL drivers. 5225OpenGL drivers.
5199.PP 5226.PP
… …
5221.PP 5248.PP
5222\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5249\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5223.IX Subsection "select is buggy" 5250.IX Subsection "select is buggy"
5224.PP 5251.PP
5225All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5252All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5226one up as well: On \s-1OS/X\s0, \f(CW\*(C`select\*(C'\fR actively limits the number of file 5253one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file
5227descriptors you can pass in to 1024 \- your program suddenly crashes when 5254descriptors you can pass in to 1024 \- your program suddenly crashes when
5228you use more. 5255you use more.
5229.PP 5256.PP
5230There is an undocumented \*(L"workaround\*(R" for this \- defining 5257There is an undocumented \*(L"workaround\*(R" for this \- defining
5231\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5258\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
5232work on \s-1OS/X\s0. 5259work on \s-1OS/X.\s0
5233.SS "\s-1SOLARIS\s0 \s-1PROBLEMS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5260.SS "\s-1SOLARIS PROBLEMS AND WORKAROUNDS\s0"
5234.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS" 5261.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS"
5235\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR 5262\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR
5236.IX Subsection "errno reentrancy" 5263.IX Subsection "errno reentrancy"
5237.PP 5264.PP
5238The default compile environment on Solaris is unfortunately so 5265The default compile environment on Solaris is unfortunately so
… …
5255great. 5282great.
5256.PP 5283.PP
5257If you can't get it to work, you can try running the program by setting 5284If you can't get it to work, you can try running the program by setting
5258the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and 5285the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and
5259\&\f(CW\*(C`select\*(C'\fR backends. 5286\&\f(CW\*(C`select\*(C'\fR backends.
5260.SS "\s-1AIX\s0 \s-1POLL\s0 \s-1BUG\s0" 5287.SS "\s-1AIX POLL BUG\s0"
5261.IX Subsection "AIX POLL BUG" 5288.IX Subsection "AIX POLL BUG"
5262\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around 5289\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around
5263this by trying to avoid the poll backend altogether (i.e. it's not even 5290this by trying to avoid the poll backend altogether (i.e. it's not even
5264compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine 5291compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine
5265with large bitsets on \s-1AIX\s0, and \s-1AIX\s0 is dead anyway. 5292with large bitsets on \s-1AIX,\s0 and \s-1AIX\s0 is dead anyway.
5266.SS "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5293.SS "\s-1WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS\s0"
5267.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" 5294.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
5268\fIGeneral issues\fR 5295\fIGeneral issues\fR
5269.IX Subsection "General issues" 5296.IX Subsection "General issues"
5270.PP 5297.PP
5271Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev 5298Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
… …
5340\& #define EV_USE_SELECT 1 5367\& #define EV_USE_SELECT 1
5341\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 5368\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
5342.Ve 5369.Ve
5343.PP 5370.PP
5344Note that winsockets handling of fd sets is O(n), so you can easily get a 5371Note that winsockets handling of fd sets is O(n), so you can easily get a
5345complexity in the O(nA\*^X) range when using win32. 5372complexity in the O(nX) range when using win32.
5346.PP 5373.PP
5347\fILimited number of file descriptors\fR 5374\fILimited number of file descriptors\fR
5348.IX Subsection "Limited number of file descriptors" 5375.IX Subsection "Limited number of file descriptors"
5349.PP 5376.PP
5350Windows has numerous arbitrary (and low) limits on things. 5377Windows has numerous arbitrary (and low) limits on things.
… …
5366by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR 5393by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR
5367(another arbitrary limit), but is broken in many versions of the Microsoft 5394(another arbitrary limit), but is broken in many versions of the Microsoft
5368runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets 5395runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets
5369(depending on windows version and/or the phase of the moon). To get more, 5396(depending on windows version and/or the phase of the moon). To get more,
5370you need to wrap all I/O functions and provide your own fd management, but 5397you need to wrap all I/O functions and provide your own fd management, but
5371the cost of calling select (O(nA\*^X)) will likely make this unworkable. 5398the cost of calling select (O(nX)) will likely make this unworkable.
5372.SS "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\s0" 5399.SS "\s-1PORTABILITY REQUIREMENTS\s0"
5373.IX Subsection "PORTABILITY REQUIREMENTS" 5400.IX Subsection "PORTABILITY REQUIREMENTS"
5374In addition to a working ISO-C implementation and of course the 5401In addition to a working ISO-C implementation and of course the
5375backend-specific APIs, libev relies on a few additional extensions: 5402backend-specific APIs, libev relies on a few additional extensions:
5376.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4 5403.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4
5377.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 5404.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4
5378.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." 5405.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *."
5379Libev assumes not only that all watcher pointers have the same internal 5406Libev assumes not only that all watcher pointers have the same internal
5380structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also 5407structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5381assumes that the same (machine) code can be used to call any watcher 5408assumes that the same (machine) code can be used to call any watcher
5382callback: The watcher callbacks have different type signatures, but libev 5409callback: The watcher callbacks have different type signatures, but libev
5383calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5410calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5384.IP "pointer accesses must be thread-atomic" 4 5411.IP "pointer accesses must be thread-atomic" 4
5385.IX Item "pointer accesses must be thread-atomic" 5412.IX Item "pointer accesses must be thread-atomic"
… …
5401thread\*(R" or will block signals process-wide, both behaviours would 5428thread\*(R" or will block signals process-wide, both behaviours would
5402be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and 5429be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
5403\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. 5430\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
5404.Sp 5431.Sp
5405The most portable way to handle signals is to block signals in all threads 5432The most portable way to handle signals is to block signals in all threads
5406except the initial one, and run the default loop in the initial thread as 5433except the initial one, and run the signal handling loop in the initial
5407well. 5434thread as well.
5408.ie n .IP """long"" must be large enough for common memory allocation sizes" 4 5435.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
5409.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 5436.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
5410.IX Item "long must be large enough for common memory allocation sizes" 5437.IX Item "long must be large enough for common memory allocation sizes"
5411To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5438To improve portability and simplify its \s-1API,\s0 libev uses \f(CW\*(C`long\*(C'\fR internally
5412instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5439instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX
5413systems (Microsoft...) this might be unexpectedly low, but is still at 5440systems (Microsoft...) this might be unexpectedly low, but is still at
5414least 31 bits everywhere, which is enough for hundreds of millions of 5441least 31 bits everywhere, which is enough for hundreds of millions of
5415watchers. 5442watchers.
5416.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 5443.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
… …
5418.IX Item "double must hold a time value in seconds with enough accuracy" 5445.IX Item "double must hold a time value in seconds with enough accuracy"
5419The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to 5446The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
5420have at least 51 bits of mantissa (and 9 bits of exponent), which is 5447have at least 51 bits of mantissa (and 9 bits of exponent), which is
5421good enough for at least into the year 4000 with millisecond accuracy 5448good enough for at least into the year 4000 with millisecond accuracy
5422(the design goal for libev). This requirement is overfulfilled by 5449(the design goal for libev). This requirement is overfulfilled by
5423implementations using \s-1IEEE\s0 754, which is basically all existing ones. 5450implementations using \s-1IEEE 754,\s0 which is basically all existing ones.
5424.Sp 5451.Sp
5425With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the 5452With \s-1IEEE 754\s0 doubles, you get microsecond accuracy until at least the
5426year 2255 (and millisecond accuracy till the year 287396 \- by then, libev 5453year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5427is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or 5454is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5428something like that, just kidding). 5455something like that, just kidding).
5429.PP 5456.PP
5430If you know of other additional requirements drop me a note. 5457If you know of other additional requirements drop me a note.
… …
5492calls in the current loop iteration and the loop is currently 5519calls in the current loop iteration and the loop is currently
5493blocked. Checking for async and signal events involves iterating over all 5520blocked. Checking for async and signal events involves iterating over all
5494running async watchers or all signal numbers. 5521running async watchers or all signal numbers.
5495.SH "PORTING FROM LIBEV 3.X TO 4.X" 5522.SH "PORTING FROM LIBEV 3.X TO 4.X"
5496.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5523.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5497The major version 4 introduced some incompatible changes to the \s-1API\s0. 5524The major version 4 introduced some incompatible changes to the \s-1API.\s0
5498.PP 5525.PP
5499At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5526At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
5500for all changes, so most programs should still compile. The compatibility 5527for all changes, so most programs should still compile. The compatibility
5501layer might be removed in later versions of libev, so better update to the 5528layer might be removed in later versions of libev, so better update to the
5502new \s-1API\s0 early than late. 5529new \s-1API\s0 early than late.
5503.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5530.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5504.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5531.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5505.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5532.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5506The backward compatibility mechanism can be controlled by 5533The backward compatibility mechanism can be controlled by
5507\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R" 5534\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR SYMBOLS/MACROS\*(R"\s0 in the \*(L"\s-1EMBEDDING\*(R"\s0
5508section. 5535section.
5509.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5536.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5510.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5537.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5511.IX Item "ev_default_destroy and ev_default_fork have been removed" 5538.IX Item "ev_default_destroy and ev_default_fork have been removed"
5512These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5539These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts:
… …
5552.SH "GLOSSARY" 5579.SH "GLOSSARY"
5553.IX Header "GLOSSARY" 5580.IX Header "GLOSSARY"
5554.IP "active" 4 5581.IP "active" 4
5555.IX Item "active" 5582.IX Item "active"
5556A watcher is active as long as it has been started and not yet stopped. 5583A watcher is active as long as it has been started and not yet stopped.
5557See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5584See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5558.IP "application" 4 5585.IP "application" 4
5559.IX Item "application" 5586.IX Item "application"
5560In this document, an application is whatever is using libev. 5587In this document, an application is whatever is using libev.
5561.IP "backend" 4 5588.IP "backend" 4
5562.IX Item "backend" 5589.IX Item "backend"
… …
5589The model used to describe how an event loop handles and processes 5616The model used to describe how an event loop handles and processes
5590watchers and events. 5617watchers and events.
5591.IP "pending" 4 5618.IP "pending" 4
5592.IX Item "pending" 5619.IX Item "pending"
5593A watcher is pending as soon as the corresponding event has been 5620A watcher is pending as soon as the corresponding event has been
5594detected. See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5621detected. See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5595.IP "real time" 4 5622.IP "real time" 4
5596.IX Item "real time" 5623.IX Item "real time"
5597The physical time that is observed. It is apparently strictly monotonic :) 5624The physical time that is observed. It is apparently strictly monotonic :)
5598.IP "wall-clock time" 4 5625.IP "wall-clock time" 4
5599.IX Item "wall-clock time" 5626.IX Item "wall-clock time"

Diff Legend

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