--- libev/ev.pod 2008/05/06 23:42:16 1.151 +++ libev/ev.pod 2008/05/20 20:00:34 1.156 @@ -66,7 +66,7 @@ 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. +time: L. 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 @@ -338,7 +338,7 @@ writing a server, you should C in a loop to accept as many connections as possible during one iteration. You might also want to have a look at C to increase the amount of -readyness notifications you get per iteration. +readiness notifications you get per iteration. =item C (value 2, poll backend, available everywhere except on windows) @@ -427,7 +427,7 @@ descriptors a "slow" C or C 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. @@ -1034,7 +1034,7 @@ C). 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 but a subsequent C(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 @@ -1659,7 +1659,7 @@ 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 (e.g. C). @@ -2982,8 +2982,9 @@ =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 -some inlining decisions, saves roughly 30% codesize of amd64. +speed, define this symbol to C<1>. Currently this is used to override some +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 @@ -3000,6 +3001,28 @@ watchers you might want to increase this value (I 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 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) within +the heap structure (selected by defining C 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 is set in which case it is C<0> +(disabled). + =item EV_COMMON By default, all watchers have a C member. By redefining @@ -3178,8 +3201,8 @@ =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 -beginning of the storage array. +By virtue of using a binary or 4-heap, the next timer is always found at a +fixed position in the storage array. =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) @@ -3230,7 +3253,7 @@ 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). @@ -3331,6 +3354,32 @@ 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 .