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

Comparing libev/ev.pod (file contents):
Revision 1.152 by root, Wed May 7 14:45:17 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
 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
 members. You have to define it each time you include one of the files,
 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
 =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.152 by root, Wed May 7 14:45:17 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.152 by root, Wed May 7 14:45:17 2008 UTC vs.
Revision 1.156 by root, Tue May 20 20:00:34 2008 UTC