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

Comparing libev/ev.pod (file contents):
Revision 1.94 by root, Fri Dec 21 04:38:45 2007 UTC vs.
Revision 1.97 by root, Sat Dec 22 05:48:02 2007 UTC

… …
115 115
116Returns the current time as libev would use it. Please note that the 116Returns the current time as libev would use it. Please note that the
117C<ev_now> function is usually faster and also often returns the timestamp 117C<ev_now> function is usually faster and also often returns the timestamp
118you actually want to know. 118you actually want to know.
119 119
120=item ev_sleep (ev_tstamp interval)
121
122Sleep for the given interval: The current thread will be blocked until
123either it is interrupted or the given time interval has passed. Basically
124this is a subsecond-resolution C<sleep ()>.
125
120=item int ev_version_major () 126=item int ev_version_major ()
121 127
122=item int ev_version_minor () 128=item int ev_version_minor ()
123 129
124You can find out the major and minor ABI version numbers of the library 130You can find out the major and minor ABI version numbers of the library
… …
317For few fds, this backend is a bit little slower than poll and select, 323For few fds, this backend is a bit little slower than poll and select,
318but it scales phenomenally better. While poll and select usually scale 324but it scales phenomenally better. While poll and select usually scale
319like O(total_fds) where n is the total number of fds (or the highest fd), 325like O(total_fds) where n is the total number of fds (or the highest fd),
320epoll scales either O(1) or O(active_fds). The epoll design has a number 326epoll scales either O(1) or O(active_fds). The epoll design has a number
321of shortcomings, such as silently dropping events in some hard-to-detect 327of shortcomings, such as silently dropping events in some hard-to-detect
322cases and rewuiring a syscall per fd change, no fork support and bad 328cases and rewiring a syscall per fd change, no fork support and bad
323support for dup: 329support for dup:
324 330
325While stopping, setting and starting an I/O watcher in the same iteration 331While stopping, setting and starting an I/O watcher in the same iteration
326will result in some caching, there is still a syscall per such incident 332will result in some caching, there is still a syscall per such incident
327(because the fd could point to a different file description now), so its 333(because the fd could point to a different file description now), so its
… …
569Example: For some weird reason, unregister the above signal handler again. 575Example: For some weird reason, unregister the above signal handler again.
570 576
571 ev_ref (loop); 577 ev_ref (loop);
572 ev_signal_stop (loop, &exitsig); 578 ev_signal_stop (loop, &exitsig);
573 579
580=item ev_set_io_collect_interval (loop, ev_tstamp interval)
581
582=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
583
584These advanced functions influence the time that libev will spend waiting
585for events. Both are by default C<0>, meaning that libev will try to
586invoke timer/periodic callbacks and I/O callbacks with minimum latency.
587
588Setting these to a higher value (the C<interval> I<must> be >= C<0>)
589allows libev to delay invocation of I/O and timer/periodic callbacks to
590increase efficiency of loop iterations.
591
592The background is that sometimes your program runs just fast enough to
593handle one (or very few) event(s) per loop iteration. While this makes
594the program responsive, it also wastes a lot of CPU time to poll for new
595events, especially with backends like C<select ()> which have a high
596overhead for the actual polling but can deliver many events at once.
597
598By setting a higher I<io collect interval> you allow libev to spend more
599time collecting I/O events, so you can handle more events per iteration,
600at the cost of increasing latency. Timeouts (both C<ev_periodic> and
601C<ev_timer>) will be not affected.
602
603Likewise, by setting a higher I<timeout collect interval> you allow libev
604to spend more time collecting timeouts, at the expense of increased
605latency (the watcher callback will be called later). C<ev_io> watchers
606will not be affected.
607
608Many programs can usually benefit by setting the io collect interval to
609a value near C<0.1> or so, which is often enough for interactive servers
610(of course not for games), likewise for timeouts. It usually doesn't make
611much sense to set it to a lower value than C<0.01>, as this approsaches
612the timing granularity of most systems.
613
574=back 614=back
575 615
576 616
577=head1 ANATOMY OF A WATCHER 617=head1 ANATOMY OF A WATCHER
578 618
… …
949 989
950This is how one would do it normally anyway, the important point is that 990This is how one would do it normally anyway, the important point is that
951the libev application should not optimise around libev but should leave 991the libev application should not optimise around libev but should leave
952optimisations to libev. 992optimisations to libev.
953 993
954=head3 Ths special problem of dup'ed file descriptors 994=head3 The special problem of dup'ed file descriptors
955 995
956Some backends (e.g. epoll), cannot register events for file descriptors, 996Some backends (e.g. epoll), cannot register events for file descriptors,
957but only events for the underlying file descriptions. That menas when you 997but only events for the underlying file descriptions. That menas when you
958have C<dup ()>'ed file descriptors and register events for them, only one 998have C<dup ()>'ed file descriptors and register events for them, only one
959file descriptor might actually receive events. 999file descriptor might actually receive events.
… …
2297runtime if successful). Otherwise no use of the realtime clock option will 2337runtime if successful). Otherwise no use of the realtime clock option will
2298be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2338be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2299(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 2339(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2300note about libraries in the description of C<EV_USE_MONOTONIC>, though. 2340note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2301 2341
2342=item EV_USE_NANOSLEEP
2343
2344If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2345and will use it for delays. Otherwise it will use C<select ()>.
2346
2302=item EV_USE_SELECT 2347=item EV_USE_SELECT
2303 2348
2304If undefined or defined to be C<1>, libev will compile in support for the 2349If undefined or defined to be C<1>, libev will compile in support for the
2305C<select>(2) backend. No attempt at autodetection will be done: if no 2350C<select>(2) backend. No attempt at autodetection will be done: if no
2306other method takes over, select will be it. Otherwise the select backend 2351other method takes over, select will be it. Otherwise the select backend

Diff Legend

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