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

Comparing libev/ev.pod (file contents):
Revision 1.150 by root, Tue May 6 23:34:16 2008 UTC vs.
Revision 1.156 by root, Tue May 20 20:00:34 2008 UTC

 =head1 DESCRIPTION
 The newest version of this document is also available as an html-formatted
 web page you might find easier to navigate when reading it for the first
-time: L<http://cvs.schmorp.de/libev/ev.html>.
+time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
 Libev is an event loop: you register interest in certain events (such as a
 file descriptor being readable or a timeout occurring), and it will manage
 these event sources and provide your program with events.
 To get good performance out of this backend you need a high amount of
 parallelity (most of the file descriptors should be busy). If you are
 writing a server, you should C<accept ()> in a loop to accept as many
 connections as possible during one iteration. You might also want to have
 a look at C<ev_set_io_collect_interval ()> to increase the amount of
-readyness notifications you get per iteration.
+readiness notifications you get per iteration.
 =item C<EVBACKEND_POLL>    (value 2, poll backend, available everywhere except on windows)
 And this is your standard poll(2) backend. It's more complicated
 than select, but handles sparse fds better and has no artificial
 While this backend scales well, it requires one system call per active
 file descriptor per loop iteration. For small and medium numbers of file
 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
 might perform better.
-On the positive side, ignoring the spurious readyness notifications, this
+On the positive side, ignoring the spurious readiness notifications, this
 backend actually performed to specification in all tests and is fully
 embeddable, which is a rare feat among the OS-specific backends.
 =item C<EVBACKEND_ALL>
 If you must do this, then force the use of a known-to-be-good backend
 (at the time of this writing, this includes only C<EVBACKEND_SELECT> and
 C<EVBACKEND_POLL>).
 Another thing you have to watch out for is that it is quite easy to
-receive "spurious" readyness notifications, that is your callback might
+receive "spurious" readiness notifications, that is your callback might
 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
 because there is no data. Not only are some backends known to create a
 lot of those (for example solaris ports), it is very easy to get into
 this situation even with a relatively standard program structure. Thus
 it is best to always use non-blocking I/O: An extra C<read>(2) returning
 calls your callback, which does something. When there is another update
 within the same second, C<ev_stat> will be unable to detect it as the stat
 data does not change.
 The solution to this is to delay acting on a change for slightly more
-than second (or till slightly after the next full second boundary), using
+than a second (or till slightly after the next full second boundary), using
 a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
 ev_timer_again (loop, w)>).
 The C<.02> offset is added to work around small timing inconsistencies
 of some operating systems (where the second counter of the current time
 defined to be C<0>, then they are not.
 =item EV_MINIMAL
 If you need to shave off some kilobytes of code at the expense of some
-speed, define this symbol to C<1>. Currently only used for gcc to override
+speed, define this symbol to C<1>. Currently this is used to override some
-some inlining decisions, saves roughly 30% codesize of amd64.
+inlining decisions, saves roughly 30% codesize of amd64. It also selects a
+much smaller 2-heap for timer management over the default 4-heap.
 =item EV_PID_HASHSIZE
 C<ev_child> watchers use a small hash table to distribute workload by
 pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
 C<ev_stat> watchers use a small hash table to distribute workload by
 inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
 usually more than enough. If you need to manage thousands of C<ev_stat>
 watchers you might want to increase this value (I<must> be a power of
 two).
+=item EV_USE_4HEAP
+Heaps are not very cache-efficient. To improve the cache-efficiency of the
+timer and periodics heap, libev uses a 4-heap when this symbol is defined
+to C<1>. The 4-heap uses more complicated (longer) code but has
+noticably faster performance with many (thousands) of watchers.
+The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
+(disabled).
+=item EV_HEAP_CACHE_AT
+Heaps are not very cache-efficient. To improve the cache-efficiency of the
+timer and periodics heap, libev can cache the timestamp (I<at>) within
+the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
+which uses 8-12 bytes more per watcher and a few hundred bytes more code,
+but avoids random read accesses on heap changes. This improves performance
+noticably with with many (hundreds) of watchers.
+The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
+(disabled).
 =item EV_COMMON
 By default, all watchers have a C<void *data> member. By redefining
 this macro to a something else you can include more and other types of
 correct watcher to remove. The lists are usually short (you don't usually
 have many watchers waiting for the same fd or signal).
 =item Finding the next timer in each loop iteration: O(1)
-By virtue of using a binary heap, the next timer is always found at the
+By virtue of using a binary or 4-heap, the next timer is always found at a
-beginning of the storage array.
+fixed position in the storage array.
 =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
 A change means an I/O watcher gets started or stopped, which requires
 libev to recalculate its status (and possibly tell the kernel, depending
 Due to the many, low, and arbitrary limits on the win32 platform and
 the abysmal performance of winsockets, using a large number of sockets
 is not recommended (and not reasonable). If your program needs to use
 more than a hundred or so sockets, then likely it needs to use a totally
-different implementation for windows, as libev offers the POSIX readyness
+different implementation for windows, as libev offers the POSIX readiness
 notification model, which cannot be implemented efficiently on windows
 (microsoft monopoly games).
 =over 4
 is still at least 31 bits everywhere, which is enough for hundreds of
 millions of watchers.
 =item C<double> must hold a time value in seconds with enough accuracy
-The type C<double> is used to represent timestamps. It is required to have
+The type C<double> is used to represent timestamps. It is required to
-at least 51 bits of mantissa, which is good enough for at least into the
+have at least 51 bits of mantissa (and 9 bits of exponent), which is good
-year 4000. This requirement is fulfilled by implementations implementing
+enough for at least into the year 4000. This requirement is fulfilled by
-IEEE 754 (basically all existing ones).
+implementations implementing IEEE 754 (basically all existing ones).
 =back
 If you know of other additional requirements drop me a note.
+=head1 VALGRIND
+Valgrind has a special section here because it is a popular tool that is
+highly useful, but valgrind reports are very hard to interpret.
+If you think you found a bug (memory leak, uninitialised data access etc.)
+in libev, then check twice: If valgrind reports something like:
+   ==2274==    definitely lost: 0 bytes in 0 blocks.
+   ==2274==      possibly lost: 0 bytes in 0 blocks.
+   ==2274==    still reachable: 256 bytes in 1 blocks.
+then there is no memory leak. Similarly, under some circumstances,
+valgrind might report kernel bugs as if it were a bug in libev, or it
+might be confused (it is a very good tool, but only a tool).
+If you are unsure about something, feel free to contact the mailing list
+with the full valgrind report and an explanation on why you think this is
+a bug in libev. However, don't be annoyed when you get a brisk "this is
+no bug" answer and take the chance of learning how to interpret valgrind
+properly.
+If you need, for some reason, empty reports from valgrind for your project
+I suggest using suppression lists.
 =head1 AUTHOR
 Marc Lehmann <libev@schmorp.de>.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.150 by root, Tue May 6 23:34:16 2008 UTC vs. Revision 1.156 by root, Tue May 20 20:00:34 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.150 by root, Tue May 6 23:34:16 2008 UTC vs.
Revision 1.156 by root, Tue May 20 20:00:34 2008 UTC