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

Comparing libev/ev.3 (file contents):
Revision 1.55 by root, Fri Dec 21 05:10:38 2007 UTC vs.
Revision 1.56 by root, Sat Dec 22 05:47:57 2007 UTC

… …
127.\} 127.\}
128.rm #[ #] #H #V #F C 128.rm #[ #] #H #V #F C
129.\" ======================================================================== 129.\" ========================================================================
130.\" 130.\"
131.IX Title "EV 1" 131.IX Title "EV 1"
132.TH EV 1 "2007-12-21" "perl v5.8.8" "User Contributed Perl Documentation" 132.TH EV 1 "2007-12-22" "perl v5.8.8" "User Contributed Perl Documentation"
133.SH "NAME" 133.SH "NAME"
134libev \- a high performance full\-featured event loop written in C 134libev \- a high performance full\-featured event loop written in C
135.SH "SYNOPSIS" 135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS" 136.IX Header "SYNOPSIS"
137.Vb 1 137.Vb 1
… …
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
261.IX Item "void ev_sleep (ev_tstamp interval)"
262Sleep for the given interval: The current thread will be blocked until
263either it is interrupted or the given time interval has passed. Basically
264this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR.
260.IP "int ev_version_major ()" 4 265.IP "int ev_version_major ()" 4
261.IX Item "int ev_version_major ()" 266.IX Item "int ev_version_major ()"
262.PD 0 267.PD 0
263.IP "int ev_version_minor ()" 4 268.IP "int ev_version_minor ()" 4
264.IX Item "int ev_version_minor ()" 269.IX Item "int ev_version_minor ()"
… …
463For few fds, this backend is a bit little slower than poll and select, 468For few fds, this backend is a bit little slower than poll and select,
464but it scales phenomenally better. While poll and select usually scale 469but it scales phenomenally better. While poll and select usually scale
465like O(total_fds) where n is the total number of fds (or the highest fd), 470like O(total_fds) where n is the total number of fds (or the highest fd),
466epoll scales either O(1) or O(active_fds). The epoll design has a number 471epoll scales either O(1) or O(active_fds). The epoll design has a number
467of shortcomings, such as silently dropping events in some hard-to-detect 472of shortcomings, such as silently dropping events in some hard-to-detect
468cases and rewuiring a syscall per fd change, no fork support and bad 473cases and rewiring a syscall per fd change, no fork support and bad
469support for dup: 474support for dup:
470.Sp 475.Sp
471While stopping, setting and starting an I/O watcher in the same iteration 476While stopping, setting and starting an I/O watcher in the same iteration
472will result in some caching, there is still a syscall per such incident 477will result in some caching, there is still a syscall per such incident
473(because the fd could point to a different file description now), so its 478(because the fd could point to a different file description now), so its
… …
724.Sp 729.Sp
725.Vb 2 730.Vb 2
726\& ev_ref (loop); 731\& ev_ref (loop);
727\& ev_signal_stop (loop, &exitsig); 732\& ev_signal_stop (loop, &exitsig);
728.Ve 733.Ve
734.IP "ev_set_io_collect_interval (ev_tstamp interval)" 4
735.IX Item "ev_set_io_collect_interval (ev_tstamp interval)"
736.PD 0
737.IP "ev_set_timeout_collect_interval (ev_tstamp interval)" 4
738.IX Item "ev_set_timeout_collect_interval (ev_tstamp interval)"
739.PD
740These 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
742invoke timer/periodic callbacks and I/O callbacks with minimum latency.
743.Sp
744Setting these to a higher value (the \f(CW\*(C`interval\*(C'\fR \fImust\fR be >= \f(CW0\fR)
745allows libev to delay invocation of I/O and timer/periodic callbacks to
746increase efficiency of loop iterations.
747.Sp
748The background is that sometimes your program runs just fast enough to
749handle one (or very few) event(s) per loop iteration. While this makes
750the program responsive, it also wastes a lot of \s-1CPU\s0 time to poll for new
751events, especially with backends like \f(CW\*(C`select ()\*(C'\fR which have a high
752overhead for the actual polling but can deliver many events at once.
753.Sp
754By 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,
756at 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.
758.Sp
759Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
760to 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
762will not be affected.
763.Sp
764Many programs can usually benefit by setting the io collect interval to
765a value near \f(CW0.1\fR or so, which is often enough for interactive servers
766(of course not for games), likewise for timeouts. It usually doesn't make
767much sense to set it to a lower value than \f(CW0.01\fR, as this approsaches
768the timing granularity of most systems.
729.SH "ANATOMY OF A WATCHER" 769.SH "ANATOMY OF A WATCHER"
730.IX Header "ANATOMY OF A WATCHER" 770.IX Header "ANATOMY OF A WATCHER"
731A watcher is a structure that you create and register to record your 771A watcher is a structure that you create and register to record your
732interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to 772interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
733become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: 773become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
… …
2501realtime clock option at compiletime (and assume its availability at 2541realtime clock option at compiletime (and assume its availability at
2502runtime if successful). Otherwise no use of the realtime clock option will 2542runtime if successful). Otherwise no use of the realtime clock option will
2503be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get 2543be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get
2504(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the 2544(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the
2505note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. 2545note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
2546.IP "\s-1EV_USE_NANOSLEEP\s0" 4
2547.IX Item "EV_USE_NANOSLEEP"
2548If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
2549and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
2506.IP "\s-1EV_USE_SELECT\s0" 4 2550.IP "\s-1EV_USE_SELECT\s0" 4
2507.IX Item "EV_USE_SELECT" 2551.IX Item "EV_USE_SELECT"
2508If undefined or defined to be \f(CW1\fR, libev will compile in support for the 2552If undefined or defined to be \f(CW1\fR, libev will compile in support for the
2509\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no 2553\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no
2510other method takes over, select will be it. Otherwise the select backend 2554other method takes over, select will be it. Otherwise the select backend

Diff Legend

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