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

Comparing libev/ev.3 (file contents):
Revision 1.56 by root, Sat Dec 22 05:47:57 2007 UTC vs.
Revision 1.58 by root, Sat Dec 22 16:53:56 2007 UTC

… …
255.IP "ev_tstamp ev_time ()" 4 255.IP "ev_tstamp ev_time ()" 4
256.IX Item "ev_tstamp ev_time ()" 256.IX Item "ev_tstamp ev_time ()"
257Returns the current time as libev would use it. Please note that the 257Returns the current time as libev would use it. Please note that the
258\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp 258\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp
259you actually want to know. 259you actually want to know.
260.IP "void ev_sleep (ev_tstamp interval)" 4 260.IP "ev_sleep (ev_tstamp interval)" 4
261.IX Item "void ev_sleep (ev_tstamp interval)" 261.IX Item "ev_sleep (ev_tstamp interval)"
262Sleep for the given interval: The current thread will be blocked until 262Sleep for the given interval: The current thread will be blocked until
263either it is interrupted or the given time interval has passed. Basically 263either it is interrupted or the given time interval has passed. Basically
264this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR. 264this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR.
265.IP "int ev_version_major ()" 4 265.IP "int ev_version_major ()" 4
266.IX Item "int ev_version_major ()" 266.IX Item "int ev_version_major ()"
… …
451.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 451.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
452.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 452.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
453This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 453This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
454libev tries to roll its own fd_set with no limits on the number of fds, 454libev tries to roll its own fd_set with no limits on the number of fds,
455but if that fails, expect a fairly low limit on the number of fds when 455but if that fails, expect a fairly low limit on the number of fds when
456using this backend. It doesn't scale too well (O(highest_fd)), but its usually 456using this backend. It doesn't scale too well (O(highest_fd)), but its
457the fastest backend for a low number of fds. 457usually the fastest backend for a low number of (low\-numbered :) fds.
458.Sp
459To get good performance out of this backend you need a high amount of
460parallelity (most of the file descriptors should be busy). If you are
461writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many
462connections as possible during one iteration. You might also want to have
463a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of
464readyness notifications you get per iteration.
458.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 465.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
459.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 466.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
460.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 467.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
461And this is your standard \fIpoll\fR\|(2) backend. It's more complicated than 468And this is your standard \fIpoll\fR\|(2) backend. It's more complicated
462select, but handles sparse fds better and has no artificial limit on the 469than select, but handles sparse fds better and has no artificial
463number of fds you can use (except it will slow down considerably with a 470limit on the number of fds you can use (except it will slow down
464lot of inactive fds). It scales similarly to select, i.e. O(total_fds). 471considerably with a lot of inactive fds). It scales similarly to select,
472i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
473performance tips.
465.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 474.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
466.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 475.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
467.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 476.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
468For few fds, this backend is a bit little slower than poll and select, 477For few fds, this backend is a bit little slower than poll and select,
469but it scales phenomenally better. While poll and select usually scale 478but it scales phenomenally better. While poll and select usually scale
470like O(total_fds) where n is the total number of fds (or the highest fd), 479like O(total_fds) where n is the total number of fds (or the highest fd),
471epoll scales either O(1) or O(active_fds). The epoll design has a number 480epoll scales either O(1) or O(active_fds). The epoll design has a number
472of shortcomings, such as silently dropping events in some hard-to-detect 481of shortcomings, such as silently dropping events in some hard-to-detect
473cases and rewiring a syscall per fd change, no fork support and bad 482cases and rewiring a syscall per fd change, no fork support and bad
474support for dup: 483support for dup.
475.Sp 484.Sp
476While stopping, setting and starting an I/O watcher in the same iteration 485While stopping, setting and starting an I/O watcher in the same iteration
477will result in some caching, there is still a syscall per such incident 486will result in some caching, there is still a syscall per such incident
478(because the fd could point to a different file description now), so its 487(because the fd could point to a different file description now), so its
479best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work 488best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work
480very well if you register events for both fds. 489very well if you register events for both fds.
481.Sp 490.Sp
482Please note that epoll sometimes generates spurious notifications, so you 491Please note that epoll sometimes generates spurious notifications, so you
483need to use non-blocking I/O or other means to avoid blocking when no data 492need to use non-blocking I/O or other means to avoid blocking when no data
484(or space) is available. 493(or space) is available.
494.Sp
495Best performance from this backend is achieved by not unregistering all
496watchers for a file descriptor until it has been closed, if possible, i.e.
497keep at least one watcher active per fd at all times.
498.Sp
499While nominally embeddeble in other event loops, this feature is broken in
500all kernel versions tested so far.
485.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 501.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
486.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 502.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
487.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 503.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
488Kqueue deserves special mention, as at the time of this writing, it 504Kqueue deserves special mention, as at the time of this writing, it
489was broken on \fIall\fR BSDs (usually it doesn't work with anything but 505was broken on all BSDs except NetBSD (usually it doesn't work reliably
490sockets and pipes, except on Darwin, where of course it's completely 506with anything but sockets and pipes, except on Darwin, where of course
491useless. On NetBSD, it seems to work for all the \s-1FD\s0 types I tested, so it
492is used by default there). For this reason it's not being \*(L"autodetected\*(R" 507it's completely useless). For this reason it's not being \*(L"autodetected\*(R"
493unless you explicitly specify it explicitly in the flags (i.e. using 508unless you explicitly specify it explicitly in the flags (i.e. using
494\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) 509\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough)
495system like NetBSD. 510system like NetBSD.
496.Sp 511.Sp
512You still can embed kqueue into a normal poll or select backend and use it
513only for sockets (after having made sure that sockets work with kqueue on
514the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
515.Sp
497It scales in the same way as the epoll backend, but the interface to the 516It scales in the same way as the epoll backend, but the interface to the
498kernel is more efficient (which says nothing about its actual speed, 517kernel is more efficient (which says nothing about its actual speed, of
499of course). While stopping, setting and starting an I/O watcher does 518course). While stopping, setting and starting an I/O watcher does never
500never cause an extra syscall as with epoll, it still adds up to two event 519cause an extra syscall as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
501changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it drops fds 520two event changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it
502silently in similarly hard-to-detetc cases. 521drops fds silently in similarly hard-to-detect cases.
522.Sp
523This backend usually performs well under most conditions.
524.Sp
525While nominally embeddable in other event loops, this doesn't work
526everywhere, so you might need to test for this. And since it is broken
527almost everywhere, you should only use it when you have a lot of sockets
528(for which it usually works), by embedding it into another event loop
529(e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR) and using it only for
530sockets.
503.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 531.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
504.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 532.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4
505.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" 533.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)"
506This is not implemented yet (and might never be). 534This is not implemented yet (and might never be, unless you send me an
535implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets
536and is not embeddable, which would limit the usefulness of this backend
537immensely.
507.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 538.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
508.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 539.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
509.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" 540.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
510This uses the Solaris 10 event port mechanism. As with everything on Solaris, 541This uses the Solaris 10 event port mechanism. As with everything on Solaris,
511it's really slow, but it still scales very well (O(active_fds)). 542it's really slow, but it still scales very well (O(active_fds)).
512.Sp 543.Sp
513Please note that solaris event ports can deliver a lot of spurious 544Please note that solaris event ports can deliver a lot of spurious
514notifications, so you need to use non-blocking I/O or other means to avoid 545notifications, so you need to use non-blocking I/O or other means to avoid
515blocking when no data (or space) is available. 546blocking when no data (or space) is available.
547.Sp
548While this backend scales well, it requires one system call per active
549file descriptor per loop iteration. For small and medium numbers of file
550descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend
551might perform better.
516.ie n .IP """EVBACKEND_ALL""" 4 552.ie n .IP """EVBACKEND_ALL""" 4
517.el .IP "\f(CWEVBACKEND_ALL\fR" 4 553.el .IP "\f(CWEVBACKEND_ALL\fR" 4
518.IX Item "EVBACKEND_ALL" 554.IX Item "EVBACKEND_ALL"
519Try all backends (even potentially broken ones that wouldn't be tried 555Try all backends (even potentially broken ones that wouldn't be tried
520with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as 556with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as
521\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. 557\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR.
558.Sp
559It is definitely not recommended to use this flag.
522.RE 560.RE
523.RS 4 561.RS 4
524.Sp 562.Sp
525If one or more of these are ored into the flags value, then only these 563If one or more of these are ored into the flags value, then only these
526backends will be tried (in the reverse order as given here). If none are 564backends will be tried (in the reverse order as given here). If none are
… …
729.Sp 767.Sp
730.Vb 2 768.Vb 2
731\& ev_ref (loop); 769\& ev_ref (loop);
732\& ev_signal_stop (loop, &exitsig); 770\& ev_signal_stop (loop, &exitsig);
733.Ve 771.Ve
734.IP "ev_set_io_collect_interval (ev_tstamp interval)" 4 772.IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4
735.IX Item "ev_set_io_collect_interval (ev_tstamp interval)" 773.IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)"
736.PD 0 774.PD 0
737.IP "ev_set_timeout_collect_interval (ev_tstamp interval)" 4 775.IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4
738.IX Item "ev_set_timeout_collect_interval (ev_tstamp interval)" 776.IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)"
739.PD 777.PD
740These advanced functions influence the time that libev will spend waiting 778These advanced functions influence the time that libev will spend waiting
741for events. Both are by default \f(CW0\fR, meaning that libev will try to 779for events. Both are by default \f(CW0\fR, meaning that libev will try to
742invoke timer/periodic callbacks and I/O callbacks with minimum latency. 780invoke timer/periodic callbacks and I/O callbacks with minimum latency.
743.Sp 781.Sp
… …
752overhead for the actual polling but can deliver many events at once. 790overhead for the actual polling but can deliver many events at once.
753.Sp 791.Sp
754By setting a higher \fIio collect interval\fR you allow libev to spend more 792By setting a higher \fIio collect interval\fR you allow libev to spend more
755time collecting I/O events, so you can handle more events per iteration, 793time collecting I/O events, so you can handle more events per iteration,
756at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and 794at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and
757\&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. 795\&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null value will
796introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations.
758.Sp 797.Sp
759Likewise, by setting a higher \fItimeout collect interval\fR you allow libev 798Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
760to spend more time collecting timeouts, at the expense of increased 799to spend more time collecting timeouts, at the expense of increased
761latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers 800latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers
762will not be affected. 801will not be affected. Setting this to a non-null value will not introduce
802any overhead in libev.
763.Sp 803.Sp
764Many programs can usually benefit by setting the io collect interval to 804Many (busy) programs can usually benefit by setting the io collect
765a value near \f(CW0.1\fR or so, which is often enough for interactive servers 805interval to a value near \f(CW0.1\fR or so, which is often enough for
766(of course not for games), likewise for timeouts. It usually doesn't make 806interactive servers (of course not for games), likewise for timeouts. It
767much sense to set it to a lower value than \f(CW0.01\fR, as this approsaches 807usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR,
768the timing granularity of most systems. 808as this approsaches the timing granularity of most systems.
769.SH "ANATOMY OF A WATCHER" 809.SH "ANATOMY OF A WATCHER"
770.IX Header "ANATOMY OF A WATCHER" 810.IX Header "ANATOMY OF A WATCHER"
771A watcher is a structure that you create and register to record your 811A watcher is a structure that you create and register to record your
772interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to 812interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
773become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: 813become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
… …
1782.PP 1822.PP
1783It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 1823It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR)
1784priority, to ensure that they are being run before any other watchers 1824priority, to ensure that they are being run before any other watchers
1785after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, 1825after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
1786too) should not activate (\*(L"feed\*(R") events into libev. While libev fully 1826too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
1787supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers did 1827supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers
1788their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other event 1828did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other
1789loops those other event loops might be in an unusable state until their 1829(non\-libev) event loops those other event loops might be in an unusable
1790\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with 1830state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
1791others). 1831coexist peacefully with others).
1792.PP 1832.PP
1793\fIWatcher-Specific Functions and Data Members\fR 1833\fIWatcher-Specific Functions and Data Members\fR
1794.IX Subsection "Watcher-Specific Functions and Data Members" 1834.IX Subsection "Watcher-Specific Functions and Data Members"
1795.IP "ev_prepare_init (ev_prepare *, callback)" 4 1835.IP "ev_prepare_init (ev_prepare *, callback)" 4
1796.IX Item "ev_prepare_init (ev_prepare *, callback)" 1836.IX Item "ev_prepare_init (ev_prepare *, callback)"
… …
1976.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." 2016.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
1977.IX Subsection "ev_embed - when one backend isn't enough..." 2017.IX Subsection "ev_embed - when one backend isn't enough..."
1978This is a rather advanced watcher type that lets you embed one event loop 2018This is a rather advanced watcher type that lets you embed one event loop
1979into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded 2019into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded
1980loop, other types of watchers might be handled in a delayed or incorrect 2020loop, other types of watchers might be handled in a delayed or incorrect
1981fashion and must not be used). (See portability notes, below). 2021fashion and must not be used).
1982.PP 2022.PP
1983There are primarily two reasons you would want that: work around bugs and 2023There are primarily two reasons you would want that: work around bugs and
1984prioritise I/O. 2024prioritise I/O.
1985.PP 2025.PP
1986As an example for a bug workaround, the kqueue backend might only support 2026As an example for a bug workaround, the kqueue backend might only support
… …
2046\& ev_embed_start (loop_hi, &embed); 2086\& ev_embed_start (loop_hi, &embed);
2047\& } 2087\& }
2048\& else 2088\& else
2049\& loop_lo = loop_hi; 2089\& loop_lo = loop_hi;
2050.Ve 2090.Ve
2051.Sh "Portability notes"
2052.IX Subsection "Portability notes"
2053Kqueue is nominally embeddable, but this is broken on all BSDs that I
2054tried, in various ways. Usually the embedded event loop will simply never
2055receive events, sometimes it will only trigger a few times, sometimes in a
2056loop. Epoll is also nominally embeddable, but many Linux kernel versions
2057will always eport the epoll fd as ready, even when no events are pending.
2058.PP
2059While libev allows embedding these backends (they are contained in
2060\&\f(CW\*(C`ev_embeddable_backends ()\*(C'\fR), take extreme care that it will actually
2061work.
2062.PP
2063When in doubt, create a dynamic event loop forced to use sockets (this
2064usually works) and possibly another thread and a pipe or so to report to
2065your main event loop.
2066.PP 2091.PP
2067\fIWatcher-Specific Functions and Data Members\fR 2092\fIWatcher-Specific Functions and Data Members\fR
2068.IX Subsection "Watcher-Specific Functions and Data Members" 2093.IX Subsection "Watcher-Specific Functions and Data Members"
2069.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 2094.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
2070.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 2095.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"

Diff Legend

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