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.57 by root, Sat Dec 22 11:49:17 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 ()"
… …
484(or space) is available. 484(or space) is available.
485.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 485.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 486.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
487.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 487.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
488Kqueue deserves special mention, as at the time of this writing, it 488Kqueue 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 489was broken on all BSDs except NetBSD (usually it doesn't work reliably
490sockets and pipes, except on Darwin, where of course it's completely 490with 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" 491it'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 492unless 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) 493\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough)
495system like NetBSD. 494system like NetBSD.
496.Sp 495.Sp
496You still can embed kqueue into a normal poll or select backend and use it
497only for sockets (after having made sure that sockets work with kqueue on
498the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
499.Sp
497It scales in the same way as the epoll backend, but the interface to the 500It 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, 501kernel is more efficient (which says nothing about its actual speed, of
499of course). While stopping, setting and starting an I/O watcher does 502course). 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 503cause 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 504two event changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it
502silently in similarly hard-to-detetc cases. 505drops fds silently in similarly hard-to-detect cases.
503.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 506.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
504.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 507.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4
505.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" 508.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)"
506This is not implemented yet (and might never be). 509This is not implemented yet (and might never be).
507.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 510.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
… …
729.Sp 732.Sp
730.Vb 2 733.Vb 2
731\& ev_ref (loop); 734\& ev_ref (loop);
732\& ev_signal_stop (loop, &exitsig); 735\& ev_signal_stop (loop, &exitsig);
733.Ve 736.Ve
734.IP "ev_set_io_collect_interval (ev_tstamp interval)" 4 737.IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4
735.IX Item "ev_set_io_collect_interval (ev_tstamp interval)" 738.IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)"
736.PD 0 739.PD 0
737.IP "ev_set_timeout_collect_interval (ev_tstamp interval)" 4 740.IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4
738.IX Item "ev_set_timeout_collect_interval (ev_tstamp interval)" 741.IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)"
739.PD 742.PD
740These advanced functions influence the time that libev will spend waiting 743These 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 744for 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. 745invoke timer/periodic callbacks and I/O callbacks with minimum latency.
743.Sp 746.Sp
… …
752overhead for the actual polling but can deliver many events at once. 755overhead for the actual polling but can deliver many events at once.
753.Sp 756.Sp
754By setting a higher \fIio collect interval\fR you allow libev to spend more 757By 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, 758time 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 759at 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. 760\&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null bvalue will
761introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations.
758.Sp 762.Sp
759Likewise, by setting a higher \fItimeout collect interval\fR you allow libev 763Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
760to spend more time collecting timeouts, at the expense of increased 764to 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 765latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers
762will not be affected. 766will not be affected. Setting this to a non-null value will not introduce
767any overhead in libev.
763.Sp 768.Sp
764Many programs can usually benefit by setting the io collect interval to 769Many (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 770interval 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 771interactive 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 772usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR,
768the timing granularity of most systems. 773as this approsaches the timing granularity of most systems.
769.SH "ANATOMY OF A WATCHER" 774.SH "ANATOMY OF A WATCHER"
770.IX Header "ANATOMY OF A WATCHER" 775.IX Header "ANATOMY OF A WATCHER"
771A watcher is a structure that you create and register to record your 776A 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 777interest 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: 778become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
… …
1782.PP 1787.PP
1783It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 1788It 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 1789priority, 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, 1790after 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 1791too) 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 1792supports 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 1793did 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 1794(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 1795state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
1791others). 1796coexist peacefully with others).
1792.PP 1797.PP
1793\fIWatcher-Specific Functions and Data Members\fR 1798\fIWatcher-Specific Functions and Data Members\fR
1794.IX Subsection "Watcher-Specific Functions and Data Members" 1799.IX Subsection "Watcher-Specific Functions and Data Members"
1795.IP "ev_prepare_init (ev_prepare *, callback)" 4 1800.IP "ev_prepare_init (ev_prepare *, callback)" 4
1796.IX Item "ev_prepare_init (ev_prepare *, callback)" 1801.IX Item "ev_prepare_init (ev_prepare *, callback)"
… …
1976.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." 1981.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
1977.IX Subsection "ev_embed - when one backend isn't enough..." 1982.IX Subsection "ev_embed - when one backend isn't enough..."
1978This is a rather advanced watcher type that lets you embed one event loop 1983This 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 1984into 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 1985loop, other types of watchers might be handled in a delayed or incorrect
1981fashion and must not be used). (See portability notes, below). 1986fashion and must not be used).
1982.PP 1987.PP
1983There are primarily two reasons you would want that: work around bugs and 1988There are primarily two reasons you would want that: work around bugs and
1984prioritise I/O. 1989prioritise I/O.
1985.PP 1990.PP
1986As an example for a bug workaround, the kqueue backend might only support 1991As an example for a bug workaround, the kqueue backend might only support
… …
2046\& ev_embed_start (loop_hi, &embed); 2051\& ev_embed_start (loop_hi, &embed);
2047\& } 2052\& }
2048\& else 2053\& else
2049\& loop_lo = loop_hi; 2054\& loop_lo = loop_hi;
2050.Ve 2055.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 2056.PP
2067\fIWatcher-Specific Functions and Data Members\fR 2057\fIWatcher-Specific Functions and Data Members\fR
2068.IX Subsection "Watcher-Specific Functions and Data Members" 2058.IX Subsection "Watcher-Specific Functions and Data Members"
2069.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 2059.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)" 2060.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"

Diff Legend

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