[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.365 by root, Mon Jan 31 00:07:21 2011 UTC vs.
Revision 1.370 by root, Thu Jun 2 23:42:40 2011 UTC

 =item C<EVBACKEND_EPOLL>   (value 4, Linux)
 Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
 kernels).
-For few fds, this backend is a bit little slower than poll and select,
+For few fds, this backend is a bit little slower than poll and select, but
-but it scales phenomenally better. While poll and select usually scale
+it scales phenomenally better. While poll and select usually scale like
-like O(total_fds) where n is the total number of fds (or the highest fd),
+O(total_fds) where total_fds is the total number of fds (or the highest
-epoll scales either O(1) or O(active_fds).
+fd), epoll scales either O(1) or O(active_fds).
 The epoll mechanism deserves honorable mention as the most misdesigned
 of the more advanced event mechanisms: mere annoyances include silently
 dropping file descriptors, requiring a system call per change per file
 descriptor (and unnecessary guessing of parameters), problems with dup,
 0.1ms) and so on. The biggest issue is fork races, however - if a program
 forks then I<both> parent and child process have to recreate the epoll
 set, which can take considerable time (one syscall per file descriptor)
 and is of course hard to detect.
-Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
+Epoll is also notoriously buggy - embedding epoll fds I<should> work,
-of course I<doesn't>, and epoll just loves to report events for totally
+but of course I<doesn't>, and epoll just loves to report events for
-I<different> file descriptors (even already closed ones, so one cannot
+totally I<different> file descriptors (even already closed ones, so
-even remove them from the set) than registered in the set (especially
+one cannot even remove them from the set) than registered in the set
-on SMP systems). Libev tries to counter these spurious notifications by
+(especially on SMP systems). Libev tries to counter these spurious
-employing an additional generation counter and comparing that against the
+notifications by employing an additional generation counter and comparing
-events to filter out spurious ones, recreating the set when required. Last
+that against the events to filter out spurious ones, recreating the set
+when required. Epoll also errornously rounds down timeouts, but gives you
+no way to know when and by how much, so sometimes you have to busy-wait
+because epoll returns immediately despite a nonzero timeout. And last
 not least, it also refuses to work with some file descriptors which work
 perfectly fine with C<select> (files, many character devices...).
-Epoll is truly the train wreck analog among event poll mechanisms,
+Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
-a frankenpoll, cobbled together in a hurry, no thought to design or
+cobbled together in a hurry, no thought to design or interaction with
-interaction with others.
+others. Oh, the pain, will it ever stop...
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a system call per such
 incident (because the same I<file descriptor> could point to a different
 I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
 This is useful if you are waiting for some external event in conjunction
 with something not expressible using other libev watchers (i.e. "roll your
 own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
 usually a better approach for this kind of thing.
-Here are the gory details of what C<ev_run> does:
+Here are the gory details of what C<ev_run> does (this is for your
+understanding, not a guarantee that things will work exactly like this in
+future versions):
    - Increment loop depth.
    - Reset the ev_break status.
    - Before the first iteration, call any pending watchers.
    LOOP:
 Another way to think about it (for the mathematically inclined) is that
 C<ev_periodic> will try to run the callback in this mode at the next possible
 time where C<time = offset (mod interval)>, regardless of any time jumps.
-For numerical stability it is preferable that the C<offset> value is near
+The C<interval> I<MUST> be positive, and for numerical stability, the
-C<ev_now ()> (the current time), but there is no range requirement for
+interval value should be higher than C<1/8192> (which is around 100
-this value, and in fact is often specified as zero.
+microseconds) and C<offset> should be higher than C<0> and should have
+at most a similar magnitude as the current time (say, within a factor of
+ten). Typical values for offset are, in fact, C<0> or something between
+C<0> and C<interval>, which is also the recommended range.
 Note also that there is an upper limit to how often a timer can fire (CPU
 speed for example), so if C<interval> is very small then timing stability
 will of course deteriorate. Libev itself tries to be exact to be about one
 millisecond (if the OS supports it and the machine is fast enough).
 F<event.h> that are not directly supported by the libev core alone.
 In standalone mode, libev will still try to automatically deduce the
 configuration, but has to be more conservative.
+=item EV_USE_FLOOR
+If defined to be C<1>, libev will use the C<floor ()> function for its
+periodic reschedule calculations, otherwise libev will fall back on a
+portable (slower) implementation. If you enable this, you usually have to
+link against libm or something equivalent. Enabling this when the C<floor>
+function is not available will fail, so the safe default is to not enable
+this.
 =item EV_USE_MONOTONIC
 If defined to be C<1>, libev will try to detect the availability of the
 monotonic clock option at both compile time and runtime. Otherwise no
 use of the monotonic clock option will be attempted. If you enable this,
 The physical time that is observed. It is apparently strictly monotonic :)
 =item wall-clock time
 The time and date as shown on clocks. Unlike real time, it can actually
-be wrong and jump forwards and backwards, e.g. when the you adjust your
+be wrong and jump forwards and backwards, e.g. when you adjust your
 clock.
 =item watcher
 A data structure that describes interest in certain events. Watchers need

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.365 by root, Mon Jan 31 00:07:21 2011 UTC vs. Revision 1.370 by root, Thu Jun 2 23:42:40 2011 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.365 by root, Mon Jan 31 00:07:21 2011 UTC vs.
Revision 1.370 by root, Thu Jun 2 23:42:40 2011 UTC