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

Comparing libev/ev.3 (file contents):
Revision 1.97 by root, Mon Feb 18 03:20:28 2013 UTC vs.
Revision 1.104 by root, Sun Dec 20 01:35:55 2015 UTC

1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) 1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30)
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 "2013-02-18" "libev-4.11" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2015-12-20" "libev-4.20" "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.
… …
530GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence 541GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence
531without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has 542without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has
532\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). 543\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster).
533.Sp 544.Sp
534The big advantage of this flag is that you can forget about fork (and 545The big advantage of this flag is that you can forget about fork (and
535forget about forgetting to tell libev about forking) when you use this 546forget about forgetting to tell libev about forking, although you still
536flag. 547have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
537.Sp 548.Sp
538This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR 549This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
539environment variable. 550environment variable.
540.ie n .IP """EVFLAG_NOINOTIFY""" 4 551.ie n .IP """EVFLAG_NOINOTIFY""" 4
541.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 552.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
… …
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
… …
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
… …
799except in the rare occasion where you really need to free its resources. 810except in the rare occasion where you really need to free its resources.
800If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR 811If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR
801and \f(CW\*(C`ev_loop_destroy\*(C'\fR. 812and \f(CW\*(C`ev_loop_destroy\*(C'\fR.
802.IP "ev_loop_fork (loop)" 4 813.IP "ev_loop_fork (loop)" 4
803.IX Item "ev_loop_fork (loop)" 814.IX Item "ev_loop_fork (loop)"
804This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to 815This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations
805reinitialise the kernel state for backends that have one. Despite the 816to reinitialise the kernel state for backends that have one. Despite
806name, you can call it anytime, but it makes most sense after forking, in 817the name, you can call it anytime you are allowed to start or stop
807the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the 818watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
808child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 819sense after forking, in the child process. You \fImust\fR call it (or use
820\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
809.Sp 821.Sp
822In addition, if you want to reuse a loop (via this function or
823\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR.
824.Sp
810Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 825Again, 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 826a 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 827because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
813during fork. 828during fork.
814.Sp 829.Sp
815On the other hand, you only need to call this function in the child 830On 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 1367example 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 1368callbacks 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 1369the 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 1370programs, though, as the fd could already be closed and reused for another
1356thing, so beware. 1371thing, so beware.
1357.SS "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" 1372.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1358.IX Subsection "GENERIC WATCHER FUNCTIONS" 1373.IX Subsection "GENERIC WATCHER FUNCTIONS"
1359.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1374.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
1360.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 1375.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
1361.IX Item "ev_init (ev_TYPE *watcher, callback)" 1376.IX Item "ev_init (ev_TYPE *watcher, callback)"
1362This macro initialises the generic portion of a watcher. The contents 1377This macro initialises the generic portion of a watcher. The contents
… …
1470or might not have been clamped to the valid range. 1485or might not have been clamped to the valid range.
1471.Sp 1486.Sp
1472The default priority used by watchers when no priority has been set is 1487The 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 :). 1488always \f(CW0\fR, which is supposed to not be too high and not be too low :).
1474.Sp 1489.Sp
1475See \*(L"\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0\*(R", below, for a more thorough treatment of 1490See \*(L"\s-1WATCHER PRIORITY MODELS\*(R"\s0, below, for a more thorough treatment of
1476priorities. 1491priorities.
1477.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 1492.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
1478.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" 1493.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 1494Invoke 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 1495\&\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. 1515not started in the first place.
1501.Sp 1516.Sp
1502See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related 1517See 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. 1518functions that do not need a watcher.
1504.PP 1519.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 1520See 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. 1521OWN COMPOSITE WATCHERS\*(R"\s0 idioms.
1507.SS "\s-1WATCHER\s0 \s-1STATES\s0" 1522.SS "\s-1WATCHER STATES\s0"
1508.IX Subsection "WATCHER STATES" 1523.IX Subsection "WATCHER STATES"
1509There are various watcher states mentioned throughout this manual \- 1524There are various watcher states mentioned throughout this manual \-
1510active, pending and so on. In this section these states and the rules to 1525active, 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 1526transition between them will be described in more detail \- and while these
1512rules might look complicated, they usually do \*(L"the right thing\*(R". 1527rules might look complicated, they usually do \*(L"the right thing\*(R".
… …
1555.Sp 1570.Sp
1556While stopped (and not pending) the watcher is essentially in the 1571While stopped (and not pending) the watcher is essentially in the
1557initialised state, that is, it can be reused, moved, modified in any way 1572initialised 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 1573you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR
1559it again). 1574it again).
1560.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" 1575.SS "\s-1WATCHER PRIORITY MODELS\s0"
1561.IX Subsection "WATCHER PRIORITY MODELS" 1576.IX Subsection "WATCHER PRIORITY MODELS"
1562Many event loops support \fIwatcher priorities\fR, which are usually small 1577Many event loops support \fIwatcher priorities\fR, which are usually small
1563integers that influence the ordering of event callback invocation 1578integers that influence the ordering of event callback invocation
1564between watchers in some way, all else being equal. 1579between watchers in some way, all else being equal.
1565.PP 1580.PP
… …
1763wish to read \- you would first have to request some data. 1778wish to read \- you would first have to request some data.
1764.PP 1779.PP
1765Since files are typically not-so-well supported by advanced notification 1780Since files are typically not-so-well supported by advanced notification
1766mechanism, libev tries hard to emulate \s-1POSIX\s0 behaviour with respect 1781mechanism, 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 1782to 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 1783convenience: 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 1784usually 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 1785(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 1786\&\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 1787asynchronous I/O instead of with non-blocking I/O, it is still useful when
1773it \*(L"just works\*(R" instead of freezing. 1788it \*(L"just works\*(R" instead of freezing.
1774.PP 1789.PP
1775So avoid file descriptors pointing to files when you know it (e.g. use 1790So 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 1791libeio), 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 1792when you rarely read from a file instead of from a socket, and want to
1778reuse the same code path. 1793reuse the same code path.
1779.PP 1794.PP
1780\fIThe special problem of fork\fR 1795\fIThe special problem of fork\fR
1781.IX Subsection "The special problem of fork" 1796.IX Subsection "The special problem of fork"
… …
1791\fIThe special problem of \s-1SIGPIPE\s0\fR 1806\fIThe special problem of \s-1SIGPIPE\s0\fR
1792.IX Subsection "The special problem of SIGPIPE" 1807.IX Subsection "The special problem of SIGPIPE"
1793.PP 1808.PP
1794While not really specific to libev, it is easy to forget about \f(CW\*(C`SIGPIPE\*(C'\fR: 1809While 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 1810when 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 1811sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1797this is sensible behaviour, for daemons, this is usually undesirable. 1812this is sensible behaviour, for daemons, this is usually undesirable.
1798.PP 1813.PP
1799So when you encounter spurious, unexplained daemon exits, make sure you 1814So 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 1815ignore \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). 1816somewhere, as that would have given you a big clue).
1802.PP 1817.PP
1803\fIThe special problem of \fIaccept()\fIing when you can't\fR 1818\fIThe special problem of \fIaccept()\fIing when you can't\fR
1804.IX Subsection "The special problem of accept()ing when you can't" 1819.IX Subsection "The special problem of accept()ing when you can't"
1805.PP 1820.PP
1806Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example, 1821Many 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 1822found in post\-2004 Linux) have the peculiar behaviour of not removing a
1808connection from the pending queue in all error cases. 1823connection from the pending queue in all error cases.
1809.PP 1824.PP
1810For example, larger servers often run out of file descriptors (because 1825For 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 1826of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
2150.PP 2165.PP
2151The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2166The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
2152time. This is usually the right thing as this timestamp refers to the time 2167time. This is usually the right thing as this timestamp refers to the time
2153of the event triggering whatever timeout you are modifying/starting. If 2168of the event triggering whatever timeout you are modifying/starting. If
2154you suspect event processing to be delayed and you \fIneed\fR to base the 2169you suspect event processing to be delayed and you \fIneed\fR to base the
2155timeout on the current time, use something like this to adjust for this: 2170timeout on the current time, use something like the following to adjust
2171for it:
2156.PP 2172.PP
2157.Vb 1 2173.Vb 1
2158\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.); 2174\& ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.);
2159.Ve 2175.Ve
2160.PP 2176.PP
2161If the event loop is suspended for a long time, you can also force an 2177If the event loop is suspended for a long time, you can also force an
2162update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update 2178update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2163()\*(C'\fR. 2179()\*(C'\fR, although that will push the event time of all outstanding events
2180further into the future.
2164.PP 2181.PP
2165\fIThe special problem of unsynchronised clocks\fR 2182\fIThe special problem of unsynchronised clocks\fR
2166.IX Subsection "The special problem of unsynchronised clocks" 2183.IX Subsection "The special problem of unsynchronised clocks"
2167.PP 2184.PP
2168Modern systems have a variety of clocks \- libev itself uses the normal 2185Modern systems have a variety of clocks \- libev itself uses the normal
… …
2416In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2433In 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 2434ignored. Instead, each time the periodic watcher gets scheduled, the
2418reschedule callback will be called with the watcher as first, and the 2435reschedule callback will be called with the watcher as first, and the
2419current time as second argument. 2436current time as second argument.
2420.Sp 2437.Sp
2421\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, ever, 2438\&\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 2439or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2423allowed by documentation here\fR. 2440allowed by documentation here\fR.
2424.Sp 2441.Sp
2425If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2442If 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 2443it 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 2457It 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 2458(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 2459will usually be called just before the callback will be triggered, but
2443might be called at other times, too. 2460might be called at other times, too.
2444.Sp 2461.Sp
2445\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or 2462\&\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. 2463equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2447.Sp 2464.Sp
2448This can be used to create very complex timers, such as a timer that 2465This 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 2466triggers 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 2467next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How
… …
2542only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your 2559only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your
2543default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for 2560default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for
2544\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At 2561\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At
2545the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. 2562the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop.
2546.PP 2563.PP
2547When the first watcher gets started will libev actually register something 2564Only after the first watcher for a signal is started will libev actually
2548with the kernel (thus it coexists with your own signal handlers as long as 2565register something with the kernel. It thus coexists with your own signal
2549you don't register any with libev for the same signal). 2566handlers as long as you don't register any with libev for the same signal.
2550.PP 2567.PP
2551If possible and supported, libev will install its handlers with 2568If possible and supported, libev will install its handlers with
2552\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should 2569\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should
2553not be unduly interrupted. If you have a problem with system calls getting 2570not be unduly interrupted. If you have a problem with system calls getting
2554interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher 2571interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher
… …
2575The simplest way to ensure that the signal mask is reset in the child is 2592The 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 2593to 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. 2594catch fork calls done by libraries (such as the libc) as well.
2578.PP 2595.PP
2579In current versions of libev, the signal will not be blocked indefinitely 2596In 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 2597unless 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 2598the window of opportunity for problems, it will not go away, as libev
2582\&\fIhas\fR to modify the signal mask, at least temporarily. 2599\&\fIhas\fR to modify the signal mask, at least temporarily.
2583.PP 2600.PP
2584So I can't stress this enough: \fIIf you do not reset your signal mask when 2601So 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 2602you expect it to be empty, you have a race condition in your code\fR. This
… …
2615The signal the watcher watches out for. 2632The signal the watcher watches out for.
2616.PP 2633.PP
2617\fIExamples\fR 2634\fIExamples\fR
2618.IX Subsection "Examples" 2635.IX Subsection "Examples"
2619.PP 2636.PP
2620Example: Try to exit cleanly on \s-1SIGINT\s0. 2637Example: Try to exit cleanly on \s-1SIGINT.\s0
2621.PP 2638.PP
2622.Vb 5 2639.Vb 5
2623\& static void 2640\& static void
2624\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2641\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
2625\& { 2642\& {
… …
2782compilation environment, which means that on systems with large file 2799compilation environment, which means that on systems with large file
2783support disabled by default, you get the 32 bit version of the stat 2800support disabled by default, you get the 32 bit version of the stat
2784structure. When using the library from programs that change the \s-1ABI\s0 to 2801structure. When using the library from programs that change the \s-1ABI\s0 to
2785use 64 bit file offsets the programs will fail. In that case you have to 2802use 64 bit file offsets the programs will fail. In that case you have to
2786compile libev with the same flags to get binary compatibility. This is 2803compile libev with the same flags to get binary compatibility. This is
2787obviously the case with any flags that change the \s-1ABI\s0, but the problem is 2804obviously the case with any flags that change the \s-1ABI,\s0 but the problem is
2788most noticeably displayed with ev_stat and large file support. 2805most noticeably displayed with ev_stat and large file support.
2789.PP 2806.PP
2790The solution for this is to lobby your distribution maker to make large 2807The solution for this is to lobby your distribution maker to make large
2791file interfaces available by default (as e.g. FreeBSD does) and not 2808file interfaces available by default (as e.g. FreeBSD does) and not
2792optional. Libev cannot simply switch on large file support because it has 2809optional. Libev cannot simply switch on large file support because it has
… …
3037.IX Subsection "ev_prepare and ev_check - customise your event loop!" 3054.IX Subsection "ev_prepare and ev_check - customise your event loop!"
3038Prepare and check watchers are often (but not always) used in pairs: 3055Prepare and check watchers are often (but not always) used in pairs:
3039prepare watchers get invoked before the process blocks and check watchers 3056prepare watchers get invoked before the process blocks and check watchers
3040afterwards. 3057afterwards.
3041.PP 3058.PP
3042You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3059You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR (or similar functions that enter the
3043the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR 3060current event loop) or \f(CW\*(C`ev_loop_fork\*(C'\fR from either \f(CW\*(C`ev_prepare\*(C'\fR or
3044watchers. Other loops than the current one are fine, however. The 3061\&\f(CW\*(C`ev_check\*(C'\fR watchers. Other loops than the current one are fine,
3045rationale behind this is that you do not need to check for recursion in 3062however. The rationale behind this is that you do not need to check
3046those watchers, i.e. the sequence will always be \f(CW\*(C`ev_prepare\*(C'\fR, blocking, 3063for recursion in those watchers, i.e. the sequence will always be
3047\&\f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each kind they will always be 3064\&\f(CW\*(C`ev_prepare\*(C'\fR, blocking, \f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each
3048called in pairs bracketing the blocking call. 3065kind they will always be called in pairs bracketing the blocking call.
3049.PP 3066.PP
3050Their main purpose is to integrate other event mechanisms into libev and 3067Their main purpose is to integrate other event mechanisms into libev and
3051their use is somewhat advanced. They could be used, for example, to track 3068their use is somewhat advanced. They could be used, for example, to track
3052variable changes, implement your own watchers, integrate net-snmp or a 3069variable changes, implement your own watchers, integrate net-snmp or a
3053coroutine library and lots more. They are also occasionally useful if 3070coroutine library and lots more. They are also occasionally useful if
… …
3223.Ve 3240.Ve
3224.PP 3241.PP
3225Method 4: Do not use a prepare or check watcher because the module you 3242Method 4: Do not use a prepare or check watcher because the module you
3226want to embed is not flexible enough to support it. Instead, you can 3243want to embed is not flexible enough to support it. Instead, you can
3227override their poll function. The drawback with this solution is that the 3244override their poll function. The drawback with this solution is that the
3228main loop is now no longer controllable by \s-1EV\s0. The \f(CW\*(C`Glib::EV\*(C'\fR module uses 3245main loop is now no longer controllable by \s-1EV.\s0 The \f(CW\*(C`Glib::EV\*(C'\fR module uses
3229this approach, effectively embedding \s-1EV\s0 as a client into the horrible 3246this approach, effectively embedding \s-1EV\s0 as a client into the horrible
3230libglib event loop. 3247libglib event loop.
3231.PP 3248.PP
3232.Vb 4 3249.Vb 4
3233\& static gint 3250\& static gint
… …
3347.PP 3364.PP
3348.Vb 3 3365.Vb 3
3349\& struct ev_loop *loop_hi = ev_default_init (0); 3366\& struct ev_loop *loop_hi = ev_default_init (0);
3350\& struct ev_loop *loop_lo = 0; 3367\& struct ev_loop *loop_lo = 0;
3351\& ev_embed embed; 3368\& ev_embed embed;
3352\& 3369\&
3353\& // see if there is a chance of getting one that works 3370\& // see if there is a chance of getting one that works
3354\& // (remember that a flags value of 0 means autodetection) 3371\& // (remember that a flags value of 0 means autodetection)
3355\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3372\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
3356\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3373\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
3357\& : 0; 3374\& : 0;
… …
3373.PP 3390.PP
3374.Vb 3 3391.Vb 3
3375\& struct ev_loop *loop = ev_default_init (0); 3392\& struct ev_loop *loop = ev_default_init (0);
3376\& struct ev_loop *loop_socket = 0; 3393\& struct ev_loop *loop_socket = 0;
3377\& ev_embed embed; 3394\& ev_embed embed;
3378\& 3395\&
3379\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3396\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
3380\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3397\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
3381\& { 3398\& {
3382\& ev_embed_init (&embed, 0, loop_socket); 3399\& ev_embed_init (&embed, 0, loop_socket);
3383\& ev_embed_start (loop, &embed); 3400\& ev_embed_start (loop, &embed);
… …
3400of course. 3417of course.
3401.PP 3418.PP
3402\fIThe special problem of life after fork \- how is it possible?\fR 3419\fIThe special problem of life after fork \- how is it possible?\fR
3403.IX Subsection "The special problem of life after fork - how is it possible?" 3420.IX Subsection "The special problem of life after fork - how is it possible?"
3404.PP 3421.PP
3405Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3422Most uses of \f(CW\*(C`fork ()\*(C'\fR consist of forking, then some simple calls to set
3406up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This 3423up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This
3407sequence should be handled by libev without any problems. 3424sequence should be handled by libev without any problems.
3408.PP 3425.PP
3409This changes when the application actually wants to do event handling 3426This changes when the application actually wants to do event handling
3410in the child, or both parent in child, in effect \*(L"continuing\*(R" after the 3427in the child, or both parent in child, in effect \*(L"continuing\*(R" after the
… …
3650\&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMER\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR 3667\&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMER\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR
3651value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR 3668value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR
3652a timeout and an io event at the same time \- you probably should give io 3669a timeout and an io event at the same time \- you probably should give io
3653events precedence. 3670events precedence.
3654.Sp 3671.Sp
3655Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0. 3672Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO.\s0
3656.Sp 3673.Sp
3657.Vb 7 3674.Vb 7
3658\& static void stdin_ready (int revents, void *arg) 3675\& static void stdin_ready (int revents, void *arg)
3659\& { 3676\& {
3660\& if (revents & EV_READ) 3677\& if (revents & EV_READ)
… …
3676.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3693.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
3677.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)" 3694.IX Header "COMMON OR USEFUL IDIOMS (OR BOTH)"
3678This section explains some common idioms that are not immediately 3695This section explains some common idioms that are not immediately
3679obvious. Note that examples are sprinkled over the whole manual, and this 3696obvious. Note that examples are sprinkled over the whole manual, and this
3680section only contains stuff that wouldn't fit anywhere else. 3697section only contains stuff that wouldn't fit anywhere else.
3681.SS "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" 3698.SS "\s-1ASSOCIATING CUSTOM DATA WITH A WATCHER\s0"
3682.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" 3699.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
3683Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read 3700Each watcher has, by default, a \f(CW\*(C`void *data\*(C'\fR member that you can read
3684or modify at any time: libev will completely ignore it. This can be used 3701or modify at any time: libev will completely ignore it. This can be used
3685to associate arbitrary data with your watcher. If you need more data and 3702to associate arbitrary data with your watcher. If you need more data and
3686don't want to allocate memory separately and store a pointer to it in that 3703don't want to allocate memory separately and store a pointer to it in that
… …
3712\& } 3729\& }
3713.Ve 3730.Ve
3714.PP 3731.PP
3715More interesting and less C\-conformant ways of casting your callback 3732More interesting and less C\-conformant ways of casting your callback
3716function type instead have been omitted. 3733function type instead have been omitted.
3717.SS "\s-1BUILDING\s0 \s-1YOUR\s0 \s-1OWN\s0 \s-1COMPOSITE\s0 \s-1WATCHERS\s0" 3734.SS "\s-1BUILDING YOUR OWN COMPOSITE WATCHERS\s0"
3718.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS" 3735.IX Subsection "BUILDING YOUR OWN COMPOSITE WATCHERS"
3719Another common scenario is to use some data structure with multiple 3736Another common scenario is to use some data structure with multiple
3720embedded watchers, in effect creating your own watcher that combines 3737embedded watchers, in effect creating your own watcher that combines
3721multiple libev event sources into one \*(L"super-watcher\*(R": 3738multiple libev event sources into one \*(L"super-watcher\*(R":
3722.PP 3739.PP
… …
3750\& { 3767\& {
3751\& struct my_biggy big = (struct my_biggy *) 3768\& struct my_biggy big = (struct my_biggy *)
3752\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3769\& (((char *)w) \- offsetof (struct my_biggy, t2));
3753\& } 3770\& }
3754.Ve 3771.Ve
3755.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0" 3772.SS "\s-1AVOIDING FINISHING BEFORE RETURNING\s0"
3756.IX Subsection "AVOIDING FINISHING BEFORE RETURNING" 3773.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3757Often you have structures like this in event-based programs: 3774Often you have structures like this in event-based programs:
3758.PP 3775.PP
3759.Vb 4 3776.Vb 4
3760\& callback () 3777\& callback ()
… …
3793\& ev_feed_event (EV_A_ watcher, 0); 3810\& ev_feed_event (EV_A_ watcher, 0);
3794.Ve 3811.Ve
3795.PP 3812.PP
3796This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is 3813This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3797invoked, while not delaying callback invocation too much. 3814invoked, while not delaying callback invocation too much.
3798.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0" 3815.SS "\s-1MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS\s0"
3799.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" 3816.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3800Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3817Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3801\&\fImodal\fR interaction, which is most easily implemented by recursively 3818\&\fImodal\fR interaction, which is most easily implemented by recursively
3802invoking \f(CW\*(C`ev_run\*(C'\fR. 3819invoking \f(CW\*(C`ev_run\*(C'\fR.
3803.PP 3820.PP
… …
3835\& exit_main_loop = 1; 3852\& exit_main_loop = 1;
3836\& 3853\&
3837\& // exit both 3854\& // exit both
3838\& exit_main_loop = exit_nested_loop = 1; 3855\& exit_main_loop = exit_nested_loop = 1;
3839.Ve 3856.Ve
3840.SS "\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0" 3857.SS "\s-1THREAD LOCKING EXAMPLE\s0"
3841.IX Subsection "THREAD LOCKING EXAMPLE" 3858.IX Subsection "THREAD LOCKING EXAMPLE"
3842Here is a fictitious example of how to run an event loop in a different 3859Here is a fictitious example of how to run an event loop in a different
3843thread from where callbacks are being invoked and watchers are 3860thread from where callbacks are being invoked and watchers are
3844created/added/removed. 3861created/added/removed.
3845.PP 3862.PP
… …
3986.PP 4003.PP
3987Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise 4004Note that sending the \f(CW\*(C`ev_async\*(C'\fR watcher is required because otherwise
3988an event loop currently blocking in the kernel will have no knowledge 4005an event loop currently blocking in the kernel will have no knowledge
3989about the newly added timer. By waking up the loop it will pick up any new 4006about the newly added timer. By waking up the loop it will pick up any new
3990watchers in the next event loop iteration. 4007watchers in the next event loop iteration.
3991.SS "\s-1THREADS\s0, \s-1COROUTINES\s0, \s-1CONTINUATIONS\s0, \s-1QUEUES\s0... \s-1INSTEAD\s0 \s-1OF\s0 \s-1CALLBACKS\s0" 4008.SS "\s-1THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS\s0"
3992.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS" 4009.IX Subsection "THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS"
3993While the overhead of a callback that e.g. schedules a thread is small, it 4010While the overhead of a callback that e.g. schedules a thread is small, it
3994is still an overhead. If you embed libev, and your main usage is with some 4011is still an overhead. If you embed libev, and your main usage is with some
3995kind of threads or coroutines, you might want to customise libev so that 4012kind of threads or coroutines, you might want to customise libev so that
3996doesn't need callbacks anymore. 4013doesn't need callbacks anymore.
… …
4032You can do similar tricks if you have, say, threads with an event queue \- 4049You can do similar tricks if you have, say, threads with an event queue \-
4033instead of storing a coroutine, you store the queue object and instead of 4050instead of storing a coroutine, you store the queue object and instead of
4034switching to a coroutine, you push the watcher onto the queue and notify 4051switching to a coroutine, you push the watcher onto the queue and notify
4035any waiters. 4052any waiters.
4036.PP 4053.PP
4037To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two 4054To embed libev, see \*(L"\s-1EMBEDDING\*(R"\s0, but in short, it's easiest to create two
4038files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4055files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
4039.PP 4056.PP
4040.Vb 4 4057.Vb 4
4041\& // my_ev.h 4058\& // my_ev.h
4042\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4059\& #define EV_CB_DECLARE(type) struct my_coro *cb;
4043\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb); 4060\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb)
4044\& #include "../libev/ev.h" 4061\& #include "../libev/ev.h"
4045\& 4062\&
4046\& // my_ev.c 4063\& // my_ev.c
4047\& #define EV_H "my_ev.h" 4064\& #define EV_H "my_ev.h"
4048\& #include "../libev/ev.c" 4065\& #include "../libev/ev.c"
… …
4234\& void operator() (ev::io &w, int revents) 4251\& void operator() (ev::io &w, int revents)
4235\& { 4252\& {
4236\& ... 4253\& ...
4237\& } 4254\& }
4238\& } 4255\& }
4239\& 4256\&
4240\& myfunctor f; 4257\& myfunctor f;
4241\& 4258\&
4242\& ev::io w; 4259\& ev::io w;
4243\& w.set (&f); 4260\& w.set (&f);
4244.Ve 4261.Ve
… …
4337there are additional modules that implement libev-compatible interfaces 4354there are additional modules that implement libev-compatible interfaces
4338to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays), 4355to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR, but \f(CW\*(C`AnyEvent::DNS\*(C'\fR is preferred nowadays),
4339\&\f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the \f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR 4356\&\f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the \f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR
4340and \f(CW\*(C`EV::Glib\*(C'\fR). 4357and \f(CW\*(C`EV::Glib\*(C'\fR).
4341.Sp 4358.Sp
4342It can be found and installed via \s-1CPAN\s0, its homepage is at 4359It can be found and installed via \s-1CPAN,\s0 its homepage is at
4343<http://software.schmorp.de/pkg/EV>. 4360<http://software.schmorp.de/pkg/EV>.
4344.IP "Python" 4 4361.IP "Python" 4
4345.IX Item "Python" 4362.IX Item "Python"
4346Python bindings can be found at <http://code.google.com/p/pyev/>. It 4363Python bindings can be found at <http://code.google.com/p/pyev/>. It
4347seems to be quite complete and well-documented. 4364seems to be quite complete and well-documented.
… …
4355Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR 4372Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4356makes rev work even on mingw. 4373makes rev work even on mingw.
4357.IP "Haskell" 4 4374.IP "Haskell" 4
4358.IX Item "Haskell" 4375.IX Item "Haskell"
4359A haskell binding to libev is available at 4376A haskell binding to libev is available at
4360http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>. 4377<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>.
4361.IP "D" 4 4378.IP "D" 4
4362.IX Item "D" 4379.IX Item "D"
4363Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4380Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4364be found at <http://www.llucax.com.ar/proj/ev.d/index.html>. 4381be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4365.IP "Ocaml" 4 4382.IP "Ocaml" 4
4366.IX Item "Ocaml" 4383.IX Item "Ocaml"
4367Erkki Seppala has written Ocaml bindings for libev, to be found at 4384Erkki Seppala has written Ocaml bindings for libev, to be found at
4368http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 4385<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
4369.IP "Lua" 4 4386.IP "Lua" 4
4370.IX Item "Lua" 4387.IX Item "Lua"
4371Brian Maher has written a partial interface to libev for lua (at the 4388Brian Maher has written a partial interface to libev for lua (at the
4372time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4389time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4373http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. 4390<http://github.com/brimworks/lua\-ev>.
4374.IP "Javascript" 4 4391.IP "Javascript" 4
4375.IX Item "Javascript" 4392.IX Item "Javascript"
4376Node.js (<http://nodejs.org>) uses libev as the underlying event library. 4393Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4377.IP "Others" 4 4394.IP "Others" 4
4378.IX Item "Others" 4395.IX Item "Others"
… …
4467.SS "\s-1FILESETS\s0" 4484.SS "\s-1FILESETS\s0"
4468.IX Subsection "FILESETS" 4485.IX Subsection "FILESETS"
4469Depending on what features you need you need to include one or more sets of files 4486Depending on what features you need you need to include one or more sets of files
4470in your application. 4487in your application.
4471.PP 4488.PP
4472\fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR 4489\fI\s-1CORE EVENT LOOP\s0\fR
4473.IX Subsection "CORE EVENT LOOP" 4490.IX Subsection "CORE EVENT LOOP"
4474.PP 4491.PP
4475To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual 4492To include only the libev core (all the \f(CW\*(C`ev_*\*(C'\fR functions), with manual
4476configuration (no autoconf): 4493configuration (no autoconf):
4477.PP 4494.PP
… …
4480\& #include "ev.c" 4497\& #include "ev.c"
4481.Ve 4498.Ve
4482.PP 4499.PP
4483This will automatically include \fIev.h\fR, too, and should be done in a 4500This will automatically include \fIev.h\fR, too, and should be done in a
4484single C source file only to provide the function implementations. To use 4501single C source file only to provide the function implementations. To use
4485it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best 4502it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best
4486done by writing a wrapper around \fIev.h\fR that you can include instead and 4503done by writing a wrapper around \fIev.h\fR that you can include instead and
4487where you can put other configuration options): 4504where you can put other configuration options):
4488.PP 4505.PP
4489.Vb 2 4506.Vb 2
4490\& #define EV_STANDALONE 1 4507\& #define EV_STANDALONE 1
… …
4514.Ve 4531.Ve
4515.PP 4532.PP
4516\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4533\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4517to compile this single file. 4534to compile this single file.
4518.PP 4535.PP
4519\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR 4536\fI\s-1LIBEVENT COMPATIBILITY API\s0\fR
4520.IX Subsection "LIBEVENT COMPATIBILITY API" 4537.IX Subsection "LIBEVENT COMPATIBILITY API"
4521.PP 4538.PP
4522To include the libevent compatibility \s-1API\s0, also include: 4539To include the libevent compatibility \s-1API,\s0 also include:
4523.PP 4540.PP
4524.Vb 1 4541.Vb 1
4525\& #include "event.c" 4542\& #include "event.c"
4526.Ve 4543.Ve
4527.PP 4544.PP
… …
4529.PP 4546.PP
4530.Vb 1 4547.Vb 1
4531\& #include "event.h" 4548\& #include "event.h"
4532.Ve 4549.Ve
4533.PP 4550.PP
4534in the files that want to use the libevent \s-1API\s0. This also includes \fIev.h\fR. 4551in the files that want to use the libevent \s-1API.\s0 This also includes \fIev.h\fR.
4535.PP 4552.PP
4536You need the following additional files for this: 4553You need the following additional files for this:
4537.PP 4554.PP
4538.Vb 2 4555.Vb 2
4539\& event.h 4556\& event.h
4540\& event.c 4557\& event.c
4541.Ve 4558.Ve
4542.PP 4559.PP
4543\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR 4560\fI\s-1AUTOCONF SUPPORT\s0\fR
4544.IX Subsection "AUTOCONF SUPPORT" 4561.IX Subsection "AUTOCONF SUPPORT"
4545.PP 4562.PP
4546Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in 4563Instead of using \f(CW\*(C`EV_STANDALONE=1\*(C'\fR and providing your configuration in
4547whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your 4564whatever way you want, you can also \f(CW\*(C`m4_include([libev.m4])\*(C'\fR in your
4548\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then 4565\&\fIconfigure.ac\fR and leave \f(CW\*(C`EV_STANDALONE\*(C'\fR undefined. \fIev.c\fR will then
… …
4551For this of course you need the m4 file: 4568For this of course you need the m4 file:
4552.PP 4569.PP
4553.Vb 1 4570.Vb 1
4554\& libev.m4 4571\& libev.m4
4555.Ve 4572.Ve
4556.SS "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0" 4573.SS "\s-1PREPROCESSOR SYMBOLS/MACROS\s0"
4557.IX Subsection "PREPROCESSOR SYMBOLS/MACROS" 4574.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
4558Libev can be configured via a variety of preprocessor symbols you have to 4575Libev can be configured via a variety of preprocessor symbols you have to
4559define before including (or compiling) any of its files. The default in 4576define before including (or compiling) any of its files. The default in
4560the absence of autoconf is documented for every option. 4577the absence of autoconf is documented for every option.
4561.PP 4578.PP
4562Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI\s0, and can have different 4579Symbols marked with \*(L"(h)\*(R" do not change the \s-1ABI,\s0 and can have different
4563values when compiling libev vs. including \fIev.h\fR, so it is permissible 4580values when compiling libev vs. including \fIev.h\fR, so it is permissible
4564to redefine them before including \fIev.h\fR without breaking compatibility 4581to redefine them before including \fIev.h\fR without breaking compatibility
4565to a compiled library. All other symbols change the \s-1ABI\s0, which means all 4582to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4566users of libev and the libev code itself must be compiled with compatible 4583users of libev and the libev code itself must be compiled with compatible
4567settings. 4584settings.
4568.IP "\s-1EV_COMPAT3\s0 (h)" 4 4585.IP "\s-1EV_COMPAT3 \s0(h)" 4
4569.IX Item "EV_COMPAT3 (h)" 4586.IX Item "EV_COMPAT3 (h)"
4570Backwards compatibility is a major concern for libev. This is why this 4587Backwards compatibility is a major concern for libev. This is why this
4571release of libev comes with wrappers for the functions and symbols that 4588release of libev comes with wrappers for the functions and symbols that
4572have been renamed between libev version 3 and 4. 4589have been renamed between libev version 3 and 4.
4573.Sp 4590.Sp
… …
4578typedef in that case. 4595typedef in that case.
4579.Sp 4596.Sp
4580In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4597In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4581and in some even more future version the compatibility code will be 4598and in some even more future version the compatibility code will be
4582removed completely. 4599removed completely.
4583.IP "\s-1EV_STANDALONE\s0 (h)" 4 4600.IP "\s-1EV_STANDALONE \s0(h)" 4
4584.IX Item "EV_STANDALONE (h)" 4601.IX Item "EV_STANDALONE (h)"
4585Must always be \f(CW1\fR if you do not use autoconf configuration, which 4602Must always be \f(CW1\fR if you do not use autoconf configuration, which
4586keeps libev from including \fIconfig.h\fR, and it also defines dummy 4603keeps libev from including \fIconfig.h\fR, and it also defines dummy
4587implementations for some libevent functions (such as logging, which is not 4604implementations for some libevent functions (such as logging, which is not
4588supported). It will also not define any of the structs usually found in 4605supported). It will also not define any of the structs usually found in
… …
4731between threads, that is, threads can be used, but threads never run on 4748between threads, that is, threads can be used, but threads never run on
4732different cpus (or different cpu cores). This reduces dependencies 4749different cpus (or different cpu cores). This reduces dependencies
4733and makes libev faster. 4750and makes libev faster.
4734.IP "\s-1EV_NO_THREADS\s0" 4 4751.IP "\s-1EV_NO_THREADS\s0" 4
4735.IX Item "EV_NO_THREADS" 4752.IX Item "EV_NO_THREADS"
4736If defined to be \f(CW1\fR, libev will assume that it will never be called 4753If defined to be \f(CW1\fR, libev will assume that it will never be called from
4737from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, 4754different threads (that includes signal handlers), which is a stronger
4738above. This reduces dependencies and makes libev faster. 4755assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes
4756libev faster.
4739.IP "\s-1EV_ATOMIC_T\s0" 4 4757.IP "\s-1EV_ATOMIC_T\s0" 4
4740.IX Item "EV_ATOMIC_T" 4758.IX Item "EV_ATOMIC_T"
4741Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4759Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4742access is atomic with respect to other threads or signal contexts. No 4760access is atomic with respect to other threads or signal contexts. No
4743such type is easily found in the C language, so you can provide your own 4761such type is easily found in the C language, so you can provide your own
… …
4745handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR 4763handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4746watchers. 4764watchers.
4747.Sp 4765.Sp
4748In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4766In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4749(from \fIsignal.h\fR), which is usually good enough on most platforms. 4767(from \fIsignal.h\fR), which is usually good enough on most platforms.
4750.IP "\s-1EV_H\s0 (h)" 4 4768.IP "\s-1EV_H \s0(h)" 4
4751.IX Item "EV_H (h)" 4769.IX Item "EV_H (h)"
4752The name of the \fIev.h\fR header file used to include it. The default if 4770The name of the \fIev.h\fR header file used to include it. The default if
4753undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4771undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4754used to virtually rename the \fIev.h\fR header file in case of conflicts. 4772used to virtually rename the \fIev.h\fR header file in case of conflicts.
4755.IP "\s-1EV_CONFIG_H\s0 (h)" 4 4773.IP "\s-1EV_CONFIG_H \s0(h)" 4
4756.IX Item "EV_CONFIG_H (h)" 4774.IX Item "EV_CONFIG_H (h)"
4757If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4775If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4758\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4776\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4759\&\f(CW\*(C`EV_H\*(C'\fR, above. 4777\&\f(CW\*(C`EV_H\*(C'\fR, above.
4760.IP "\s-1EV_EVENT_H\s0 (h)" 4 4778.IP "\s-1EV_EVENT_H \s0(h)" 4
4761.IX Item "EV_EVENT_H (h)" 4779.IX Item "EV_EVENT_H (h)"
4762Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4780Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4763of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4781of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4764.IP "\s-1EV_PROTOTYPES\s0 (h)" 4 4782.IP "\s-1EV_PROTOTYPES \s0(h)" 4
4765.IX Item "EV_PROTOTYPES (h)" 4783.IX Item "EV_PROTOTYPES (h)"
4766If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4784If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4767prototypes, but still define all the structs and other symbols. This is 4785prototypes, but still define all the structs and other symbols. This is
4768occasionally useful if you want to provide your own wrapper functions 4786occasionally useful if you want to provide your own wrapper functions
4769around libev functions. 4787around libev functions.
… …
4793all the priorities, so having many of them (hundreds) uses a lot of space 4811all the priorities, so having many of them (hundreds) uses a lot of space
4794and time, so using the defaults of five priorities (\-2 .. +2) is usually 4812and time, so using the defaults of five priorities (\-2 .. +2) is usually
4795fine. 4813fine.
4796.Sp 4814.Sp
4797If your embedding application does not need any priorities, defining these 4815If your embedding application does not need any priorities, defining these
4798both to \f(CW0\fR will save some memory and \s-1CPU\s0. 4816both to \f(CW0\fR will save some memory and \s-1CPU.\s0
4799.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 4817.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
4800.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." 4818.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."
4801If undefined or defined to be \f(CW1\fR (and the platform supports it), then 4819If undefined or defined to be \f(CW1\fR (and the platform supports it), then
4802the respective watcher type is supported. If defined to be \f(CW0\fR, then it 4820the respective watcher type is supported. If defined to be \f(CW0\fR, then it
4803is not. Disabling watcher types mainly saves code size. 4821is not. Disabling watcher types mainly saves code size.
4804.IP "\s-1EV_FEATURES\s0" 4 4822.IP "\s-1EV_FEATURES\s0" 4
… …
4978.Vb 3 4996.Vb 3
4979\& #define EV_COMMON \e 4997\& #define EV_COMMON \e
4980\& SV *self; /* contains this struct */ \e 4998\& SV *self; /* contains this struct */ \e
4981\& SV *cb_sv, *fh /* note no trailing ";" */ 4999\& SV *cb_sv, *fh /* note no trailing ";" */
4982.Ve 5000.Ve
4983.IP "\s-1EV_CB_DECLARE\s0 (type)" 4 5001.IP "\s-1EV_CB_DECLARE \s0(type)" 4
4984.IX Item "EV_CB_DECLARE (type)" 5002.IX Item "EV_CB_DECLARE (type)"
4985.PD 0 5003.PD 0
4986.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4 5004.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4
4987.IX Item "EV_CB_INVOKE (watcher, revents)" 5005.IX Item "EV_CB_INVOKE (watcher, revents)"
4988.IP "ev_set_cb (ev, cb)" 4 5006.IP "ev_set_cb (ev, cb)" 4
4989.IX Item "ev_set_cb (ev, cb)" 5007.IX Item "ev_set_cb (ev, cb)"
4990.PD 5008.PD
4991Can be used to change the callback member declaration in each watcher, 5009Can be used to change the callback member declaration in each watcher,
4992and the way callbacks are invoked and set. Must expand to a struct member 5010and the way callbacks are invoked and set. Must expand to a struct member
4993definition and a statement, respectively. See the \fIev.h\fR header file for 5011definition and a statement, respectively. See the \fIev.h\fR header file for
4994their default definitions. One possible use for overriding these is to 5012their default definitions. One possible use for overriding these is to
4995avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5013avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
4996method calls instead of plain function calls in \*(C+. 5014method calls instead of plain function calls in \*(C+.
4997.SS "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0" 5015.SS "\s-1EXPORTED API SYMBOLS\s0"
4998.IX Subsection "EXPORTED API SYMBOLS" 5016.IX Subsection "EXPORTED API SYMBOLS"
4999If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of 5017If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of
5000exported symbols, you can use the provided \fISymbol.*\fR files which list 5018exported symbols, you can use the provided \fISymbol.*\fR files which list
5001all public symbols, one per line: 5019all public symbols, one per line:
5002.PP 5020.PP
5003.Vb 2 5021.Vb 2
5004\& Symbols.ev for libev proper 5022\& Symbols.ev for libev proper
… …
5056\& #include "ev_cpp.h" 5074\& #include "ev_cpp.h"
5057\& #include "ev.c" 5075\& #include "ev.c"
5058.Ve 5076.Ve
5059.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5077.SH "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5060.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT" 5078.IX Header "INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT"
5061.SS "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0" 5079.SS "\s-1THREADS AND COROUTINES\s0"
5062.IX Subsection "THREADS AND COROUTINES" 5080.IX Subsection "THREADS AND COROUTINES"
5063\fI\s-1THREADS\s0\fR 5081\fI\s-1THREADS\s0\fR
5064.IX Subsection "THREADS" 5082.IX Subsection "THREADS"
5065.PP 5083.PP
5066All libev functions are reentrant and thread-safe unless explicitly 5084All libev functions are reentrant and thread-safe unless explicitly
… …
5112An example use would be to communicate signals or other events that only 5130An example use would be to communicate signals or other events that only
5113work in the default loop by registering the signal watcher with the 5131work in the default loop by registering the signal watcher with the
5114default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop 5132default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop
5115watcher callback into the event loop interested in the signal. 5133watcher callback into the event loop interested in the signal.
5116.PP 5134.PP
5117See also \*(L"\s-1THREAD\s0 \s-1LOCKING\s0 \s-1EXAMPLE\s0\*(R". 5135See also \*(L"\s-1THREAD LOCKING EXAMPLE\*(R"\s0.
5118.PP 5136.PP
5119\fI\s-1COROUTINES\s0\fR 5137\fI\s-1COROUTINES\s0\fR
5120.IX Subsection "COROUTINES" 5138.IX Subsection "COROUTINES"
5121.PP 5139.PP
5122Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"): 5140Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"):
… …
5127that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. 5145that you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
5128.PP 5146.PP
5129Care has been taken to ensure that libev does not keep local state inside 5147Care has been taken to ensure that libev does not keep local state inside
5130\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as 5148\&\f(CW\*(C`ev_run\*(C'\fR, and other calls do not usually allow for coroutine switches as
5131they do not call any callbacks. 5149they do not call any callbacks.
5132.SS "\s-1COMPILER\s0 \s-1WARNINGS\s0" 5150.SS "\s-1COMPILER WARNINGS\s0"
5133.IX Subsection "COMPILER WARNINGS" 5151.IX Subsection "COMPILER WARNINGS"
5134Depending on your compiler and compiler settings, you might get no or a 5152Depending on your compiler and compiler settings, you might get no or a
5135lot of warnings when compiling libev code. Some people are apparently 5153lot of warnings when compiling libev code. Some people are apparently
5136scared by this. 5154scared by this.
5137.PP 5155.PP
… …
5189.PP 5207.PP
5190If you need, for some reason, empty reports from valgrind for your project 5208If you need, for some reason, empty reports from valgrind for your project
5191I suggest using suppression lists. 5209I suggest using suppression lists.
5192.SH "PORTABILITY NOTES" 5210.SH "PORTABILITY NOTES"
5193.IX Header "PORTABILITY NOTES" 5211.IX Header "PORTABILITY NOTES"
5194.SS "\s-1GNU/LINUX\s0 32 \s-1BIT\s0 \s-1LIMITATIONS\s0" 5212.SS "\s-1GNU/LINUX 32 BIT LIMITATIONS\s0"
5195.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS" 5213.IX Subsection "GNU/LINUX 32 BIT LIMITATIONS"
5196GNU/Linux is the only common platform that supports 64 bit file/large file 5214GNU/Linux is the only common platform that supports 64 bit file/large file
5197interfaces but \fIdisables\fR them by default. 5215interfaces but \fIdisables\fR them by default.
5198.PP 5216.PP
5199That means that libev compiled in the default environment doesn't support 5217That means that libev compiled in the default environment doesn't support
5200files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers. 5218files larger than 2GiB or so, which mainly affects \f(CW\*(C`ev_stat\*(C'\fR watchers.
5201.PP 5219.PP
5202Unfortunately, many programs try to work around this GNU/Linux issue 5220Unfortunately, many programs try to work around this GNU/Linux issue
5203by enabling the large file \s-1API\s0, which makes them incompatible with the 5221by enabling the large file \s-1API,\s0 which makes them incompatible with the
5204standard libev compiled for their system. 5222standard libev compiled for their system.
5205.PP 5223.PP
5206Likewise, libev cannot enable the large file \s-1API\s0 itself as this would 5224Likewise, libev cannot enable the large file \s-1API\s0 itself as this would
5207suddenly make it incompatible to the default compile time environment, 5225suddenly make it incompatible to the default compile time environment,
5208i.e. all programs not using special compile switches. 5226i.e. all programs not using special compile switches.
5209.SS "\s-1OS/X\s0 \s-1AND\s0 \s-1DARWIN\s0 \s-1BUGS\s0" 5227.SS "\s-1OS/X AND DARWIN BUGS\s0"
5210.IX Subsection "OS/X AND DARWIN BUGS" 5228.IX Subsection "OS/X AND DARWIN BUGS"
5211The whole thing is a bug if you ask me \- basically any system interface 5229The whole thing is a bug if you ask me \- basically any system interface
5212you touch is broken, whether it is locales, poll, kqueue or even the 5230you touch is broken, whether it is locales, poll, kqueue or even the
5213OpenGL drivers. 5231OpenGL drivers.
5214.PP 5232.PP
… …
5236.PP 5254.PP
5237\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5255\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5238.IX Subsection "select is buggy" 5256.IX Subsection "select is buggy"
5239.PP 5257.PP
5240All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5258All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5241one up as well: On \s-1OS/X\s0, \f(CW\*(C`select\*(C'\fR actively limits the number of file 5259one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file
5242descriptors you can pass in to 1024 \- your program suddenly crashes when 5260descriptors you can pass in to 1024 \- your program suddenly crashes when
5243you use more. 5261you use more.
5244.PP 5262.PP
5245There is an undocumented \*(L"workaround\*(R" for this \- defining 5263There is an undocumented \*(L"workaround\*(R" for this \- defining
5246\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5264\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR
5247work on \s-1OS/X\s0. 5265work on \s-1OS/X.\s0
5248.SS "\s-1SOLARIS\s0 \s-1PROBLEMS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5266.SS "\s-1SOLARIS PROBLEMS AND WORKAROUNDS\s0"
5249.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS" 5267.IX Subsection "SOLARIS PROBLEMS AND WORKAROUNDS"
5250\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR 5268\fI\f(CI\*(C`errno\*(C'\fI reentrancy\fR
5251.IX Subsection "errno reentrancy" 5269.IX Subsection "errno reentrancy"
5252.PP 5270.PP
5253The default compile environment on Solaris is unfortunately so 5271The default compile environment on Solaris is unfortunately so
… …
5270great. 5288great.
5271.PP 5289.PP
5272If you can't get it to work, you can try running the program by setting 5290If you can't get it to work, you can try running the program by setting
5273the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and 5291the environment variable \f(CW\*(C`LIBEV_FLAGS=3\*(C'\fR to only allow \f(CW\*(C`poll\*(C'\fR and
5274\&\f(CW\*(C`select\*(C'\fR backends. 5292\&\f(CW\*(C`select\*(C'\fR backends.
5275.SS "\s-1AIX\s0 \s-1POLL\s0 \s-1BUG\s0" 5293.SS "\s-1AIX POLL BUG\s0"
5276.IX Subsection "AIX POLL BUG" 5294.IX Subsection "AIX POLL BUG"
5277\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around 5295\&\s-1AIX\s0 unfortunately has a broken \f(CW\*(C`poll.h\*(C'\fR header. Libev works around
5278this by trying to avoid the poll backend altogether (i.e. it's not even 5296this by trying to avoid the poll backend altogether (i.e. it's not even
5279compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine 5297compiled in), which normally isn't a big problem as \f(CW\*(C`select\*(C'\fR works fine
5280with large bitsets on \s-1AIX\s0, and \s-1AIX\s0 is dead anyway. 5298with large bitsets on \s-1AIX,\s0 and \s-1AIX\s0 is dead anyway.
5281.SS "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" 5299.SS "\s-1WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS\s0"
5282.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" 5300.IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS"
5283\fIGeneral issues\fR 5301\fIGeneral issues\fR
5284.IX Subsection "General issues" 5302.IX Subsection "General issues"
5285.PP 5303.PP
5286Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev 5304Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
… …
5355\& #define EV_USE_SELECT 1 5373\& #define EV_USE_SELECT 1
5356\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 5374\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
5357.Ve 5375.Ve
5358.PP 5376.PP
5359Note that winsockets handling of fd sets is O(n), so you can easily get a 5377Note that winsockets handling of fd sets is O(n), so you can easily get a
5360complexity in the O(nA\*^X) range when using win32. 5378complexity in the O(nX) range when using win32.
5361.PP 5379.PP
5362\fILimited number of file descriptors\fR 5380\fILimited number of file descriptors\fR
5363.IX Subsection "Limited number of file descriptors" 5381.IX Subsection "Limited number of file descriptors"
5364.PP 5382.PP
5365Windows has numerous arbitrary (and low) limits on things. 5383Windows has numerous arbitrary (and low) limits on things.
… …
5381by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR 5399by calling \f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR
5382(another arbitrary limit), but is broken in many versions of the Microsoft 5400(another arbitrary limit), but is broken in many versions of the Microsoft
5383runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets 5401runtime libraries. This might get you to about \f(CW512\fR or \f(CW2048\fR sockets
5384(depending on windows version and/or the phase of the moon). To get more, 5402(depending on windows version and/or the phase of the moon). To get more,
5385you need to wrap all I/O functions and provide your own fd management, but 5403you need to wrap all I/O functions and provide your own fd management, but
5386the cost of calling select (O(nA\*^X)) will likely make this unworkable. 5404the cost of calling select (O(nX)) will likely make this unworkable.
5387.SS "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\s0" 5405.SS "\s-1PORTABILITY REQUIREMENTS\s0"
5388.IX Subsection "PORTABILITY REQUIREMENTS" 5406.IX Subsection "PORTABILITY REQUIREMENTS"
5389In addition to a working ISO-C implementation and of course the 5407In addition to a working ISO-C implementation and of course the
5390backend-specific APIs, libev relies on a few additional extensions: 5408backend-specific APIs, libev relies on a few additional extensions:
5391.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4 5409.ie n .IP """void (*)(ev_watcher_type *, int revents)"" must have compatible calling conventions regardless of ""ev_watcher_type *""." 4
5392.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 5410.el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4
5393.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." 5411.IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *."
5394Libev assumes not only that all watcher pointers have the same internal 5412Libev assumes not only that all watcher pointers have the same internal
5395structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also 5413structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5396assumes that the same (machine) code can be used to call any watcher 5414assumes that the same (machine) code can be used to call any watcher
5397callback: The watcher callbacks have different type signatures, but libev 5415callback: The watcher callbacks have different type signatures, but libev
5398calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5416calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5399.IP "pointer accesses must be thread-atomic" 4 5417.IP "pointer accesses must be thread-atomic" 4
5400.IX Item "pointer accesses must be thread-atomic" 5418.IX Item "pointer accesses must be thread-atomic"
… …
5421except the initial one, and run the signal handling loop in the initial 5439except the initial one, and run the signal handling loop in the initial
5422thread as well. 5440thread as well.
5423.ie n .IP """long"" must be large enough for common memory allocation sizes" 4 5441.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
5424.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 5442.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
5425.IX Item "long must be large enough for common memory allocation sizes" 5443.IX Item "long must be large enough for common memory allocation sizes"
5426To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5444To improve portability and simplify its \s-1API,\s0 libev uses \f(CW\*(C`long\*(C'\fR internally
5427instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5445instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX
5428systems (Microsoft...) this might be unexpectedly low, but is still at 5446systems (Microsoft...) this might be unexpectedly low, but is still at
5429least 31 bits everywhere, which is enough for hundreds of millions of 5447least 31 bits everywhere, which is enough for hundreds of millions of
5430watchers. 5448watchers.
5431.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 5449.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
… …
5433.IX Item "double must hold a time value in seconds with enough accuracy" 5451.IX Item "double must hold a time value in seconds with enough accuracy"
5434The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to 5452The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
5435have at least 51 bits of mantissa (and 9 bits of exponent), which is 5453have at least 51 bits of mantissa (and 9 bits of exponent), which is
5436good enough for at least into the year 4000 with millisecond accuracy 5454good enough for at least into the year 4000 with millisecond accuracy
5437(the design goal for libev). This requirement is overfulfilled by 5455(the design goal for libev). This requirement is overfulfilled by
5438implementations using \s-1IEEE\s0 754, which is basically all existing ones. 5456implementations using \s-1IEEE 754,\s0 which is basically all existing ones.
5439.Sp 5457.Sp
5440With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the 5458With \s-1IEEE 754\s0 doubles, you get microsecond accuracy until at least the
5441year 2255 (and millisecond accuracy till the year 287396 \- by then, libev 5459year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5442is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or 5460is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5443something like that, just kidding). 5461something like that, just kidding).
5444.PP 5462.PP
5445If you know of other additional requirements drop me a note. 5463If you know of other additional requirements drop me a note.
… …
5507calls in the current loop iteration and the loop is currently 5525calls in the current loop iteration and the loop is currently
5508blocked. Checking for async and signal events involves iterating over all 5526blocked. Checking for async and signal events involves iterating over all
5509running async watchers or all signal numbers. 5527running async watchers or all signal numbers.
5510.SH "PORTING FROM LIBEV 3.X TO 4.X" 5528.SH "PORTING FROM LIBEV 3.X TO 4.X"
5511.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5529.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5512The major version 4 introduced some incompatible changes to the \s-1API\s0. 5530The major version 4 introduced some incompatible changes to the \s-1API.\s0
5513.PP 5531.PP
5514At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5532At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
5515for all changes, so most programs should still compile. The compatibility 5533for all changes, so most programs should still compile. The compatibility
5516layer might be removed in later versions of libev, so better update to the 5534layer might be removed in later versions of libev, so better update to the
5517new \s-1API\s0 early than late. 5535new \s-1API\s0 early than late.
5518.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5536.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5519.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5537.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5520.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5538.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5521The backward compatibility mechanism can be controlled by 5539The backward compatibility mechanism can be controlled by
5522\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R" 5540\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR SYMBOLS/MACROS\*(R"\s0 in the \*(L"\s-1EMBEDDING\*(R"\s0
5523section. 5541section.
5524.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5542.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5525.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5543.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5526.IX Item "ev_default_destroy and ev_default_fork have been removed" 5544.IX Item "ev_default_destroy and ev_default_fork have been removed"
5527These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5545These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts:
… …
5567.SH "GLOSSARY" 5585.SH "GLOSSARY"
5568.IX Header "GLOSSARY" 5586.IX Header "GLOSSARY"
5569.IP "active" 4 5587.IP "active" 4
5570.IX Item "active" 5588.IX Item "active"
5571A watcher is active as long as it has been started and not yet stopped. 5589A watcher is active as long as it has been started and not yet stopped.
5572See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5590See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5573.IP "application" 4 5591.IP "application" 4
5574.IX Item "application" 5592.IX Item "application"
5575In this document, an application is whatever is using libev. 5593In this document, an application is whatever is using libev.
5576.IP "backend" 4 5594.IP "backend" 4
5577.IX Item "backend" 5595.IX Item "backend"
… …
5604The model used to describe how an event loop handles and processes 5622The model used to describe how an event loop handles and processes
5605watchers and events. 5623watchers and events.
5606.IP "pending" 4 5624.IP "pending" 4
5607.IX Item "pending" 5625.IX Item "pending"
5608A watcher is pending as soon as the corresponding event has been 5626A watcher is pending as soon as the corresponding event has been
5609detected. See \*(L"\s-1WATCHER\s0 \s-1STATES\s0\*(R" for details. 5627detected. See \*(L"\s-1WATCHER STATES\*(R"\s0 for details.
5610.IP "real time" 4 5628.IP "real time" 4
5611.IX Item "real time" 5629.IX Item "real time"
5612The physical time that is observed. It is apparently strictly monotonic :) 5630The physical time that is observed. It is apparently strictly monotonic :)
5613.IP "wall-clock time" 4 5631.IP "wall-clock time" 4
5614.IX Item "wall-clock time" 5632.IX Item "wall-clock time"

Diff Legend

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