*** empty log message ***

[software/libev.git] / ev.pod

diff --git a/ev.pod b/ev.pod
index 6e39af3d6d5a0624ddf003ceded01a3f881d8bd7..d1d83489e6b0ef315c676d4e0ad178047a0c7a11 100644 (file)
--- a/ev.pod
+++ b/ev.pod
@@ -117,6 +117,12 @@ Returns the current time as libev would use it. Please note that the
 C<ev_now> function is usually faster and also often returns the timestamp
 you actually want to know.
 
+=item ev_sleep (ev_tstamp interval)
+
+Sleep for the given interval: The current thread will be blocked until
+either it is interrupted or the given time interval has passed. Basically
+this is a subsecond-resolution C<sleep ()>.
+
 =item int ev_version_major ()
 
 =item int ev_version_minor ()
@@ -319,7 +325,7 @@ but it scales phenomenally better. While poll and select usually scale
 like O(total_fds) where n is the total number of fds (or the highest fd),
 epoll scales either O(1) or O(active_fds). The epoll design has a number
 of shortcomings, such as silently dropping events in some hard-to-detect
-cases and rewuiring a syscall per fd change, no fork support and bad
+cases and rewiring a syscall per fd change, no fork support and bad
 support for dup:
 
 While stopping, setting and starting an I/O watcher in the same iteration
@@ -571,6 +577,40 @@ Example: For some weird reason, unregister the above signal handler again.
   ev_ref (loop);
   ev_signal_stop (loop, &exitsig);
 
+=item ev_set_io_collect_interval (loop, ev_tstamp interval)
+
+=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
+
+These advanced functions influence the time that libev will spend waiting
+for events. Both are by default C<0>, meaning that libev will try to
+invoke timer/periodic callbacks and I/O callbacks with minimum latency.
+
+Setting these to a higher value (the C<interval> I<must> be >= C<0>)
+allows libev to delay invocation of I/O and timer/periodic callbacks to
+increase efficiency of loop iterations.
+
+The background is that sometimes your program runs just fast enough to
+handle one (or very few) event(s) per loop iteration. While this makes
+the program responsive, it also wastes a lot of CPU time to poll for new
+events, especially with backends like C<select ()> which have a high
+overhead for the actual polling but can deliver many events at once.
+
+By setting a higher I<io collect interval> you allow libev to spend more
+time collecting I/O events, so you can handle more events per iteration,
+at the cost of increasing latency. Timeouts (both C<ev_periodic> and
+C<ev_timer>) will be not affected.
+
+Likewise, by setting a higher I<timeout collect interval> you allow libev
+to spend more time collecting timeouts, at the expense of increased
+latency (the watcher callback will be called later). C<ev_io> watchers
+will not be affected.
+
+Many programs can usually benefit by setting the io collect interval to
+a value near C<0.1> or so, which is often enough for interactive servers
+(of course not for games), likewise for timeouts. It usually doesn't make
+much sense to set it to a lower value than C<0.01>, as this approsaches
+the timing granularity of most systems.
+
 =back
 
 
@@ -2299,6 +2339,11 @@ be attempted. This effectively replaces C<gettimeofday> by C<clock_get
 (CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
 note about libraries in the description of C<EV_USE_MONOTONIC>, though.
 
+=item EV_USE_NANOSLEEP
+
+If defined to be C<1>, libev will assume that C<nanosleep ()> is available
+and will use it for delays. Otherwise it will use C<select ()>.
+
 =item EV_USE_SELECT
 
 If undefined or defined to be C<1>, libev will compile in support for the