--- libev/ev.pod 2008/05/11 11:47:27 1.154 +++ libev/ev.pod 2008/05/21 12:51:38 1.158 @@ -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 @@ -1153,8 +1153,8 @@ given time, and optionally repeating in regular intervals after that. The timers are based on real time, that is, if you register an event that -times out after an hour and you reset your system clock to last years -time, it will still time out after (roughly) and hour. "Roughly" because +times out after an hour and you reset your system clock to january last +year, it will still time out after (roughly) and hour. "Roughly" because detecting time jumps is hard, and some inaccuracies are unavoidable (the monotonic clock option helps a lot here). @@ -1166,7 +1166,7 @@ ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); -The callback is guarenteed to be invoked only when its timeout has passed, +The callback is guarenteed to be invoked only after its timeout has passed, but if multiple timers become ready during the same loop iteration then order of execution is undefined. @@ -1178,16 +1178,17 @@ =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) -Configure the timer to trigger after C seconds. If C is -C<0.>, then it will automatically be stopped. If it is positive, then the -timer will automatically be configured to trigger again C seconds -later, again, and again, until stopped manually. - -The timer itself will do a best-effort at avoiding drift, that is, if you -configure a timer to trigger every 10 seconds, then it will trigger at -exactly 10 second intervals. If, however, your program cannot keep up with -the timer (because it takes longer than those 10 seconds to do stuff) the -timer will not fire more than once per event loop iteration. +Configure the timer to trigger after C seconds. If C +is C<0.>, then it will automatically be stopped once the timeout is +reached. If it is positive, then the timer will automatically be +configured to trigger again C seconds later, again, and again, +until stopped manually. + +The timer itself will do a best-effort at avoiding drift, that is, if +you configure a timer to trigger every 10 seconds, then it will normally +trigger at exactly 10 second intervals. If, however, your program cannot +keep up with the timer (because it takes longer than those 10 seconds to +do stuff) the timer will not fire more than once per event loop iteration. =item ev_timer_again (loop, ev_timer *) @@ -1274,18 +1275,19 @@ Unlike C's, they are not based on real time (or relative time) but on wallclock time (absolute time). You can tell a periodic watcher -to trigger "at" some specific point in time. For example, if you tell a +to trigger after some specific point in time. For example, if you tell a periodic watcher to trigger in 10 seconds (by specifiying e.g. C) and then reset your system clock to the last year, then it will -take a year to trigger the event (unlike an C, which would trigger -roughly 10 seconds later). - -They can also be used to implement vastly more complex timers, such as -triggering an event on each midnight, local time or other, complicated, -rules. ++ 10.>, that is, an absolute time not a delay) and then reset your system +clock to january of the previous year, then it will take more than year +to trigger the event (unlike an C, which would still trigger +roughly 10 seconds later as it uses a relative timeout). + +Cs can also be used to implement vastly more complex timers, +such as triggering an event on each "midnight, local time", or other +complicated, rules. As with timers, the callback is guarenteed to be invoked only when the -time (C) has been passed, but if multiple periodic timers become ready +time (C) has passed, but if multiple periodic timers become ready during the same loop iteration then order of execution is undefined. =head3 Watcher-Specific Functions and Data Members @@ -1303,10 +1305,10 @@ =item * absolute timer (at = time, interval = reschedule_cb = 0) -In this configuration the watcher triggers an event at the wallclock time -C and doesn't repeat. It will not adjust when a time jump occurs, -that is, if it is to be run at January 1st 2011 then it will run when the -system time reaches or surpasses this time. +In this configuration the watcher triggers an event after the wallclock +time C has passed and doesn't repeat. It will not adjust when a time +jump occurs, that is, if it is to be run at January 1st 2011 then it will +run when the system time reaches or surpasses this time. =item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) @@ -1315,7 +1317,8 @@ and then repeat, regardless of any time jumps. This can be used to create timers that do not drift with respect to system -time: +time, for example, here is a C that triggers each hour, on +the hour: ev_periodic_set (&periodic, 0., 3600., 0); @@ -1330,7 +1333,12 @@ For numerical stability it is preferable that the C value is near C (the current time), but there is no range requirement for -this value. +this value, and in fact is often specified as zero. + +Note also that there is an upper limit to how often a timer can fire (cpu +speed for example), so if C is very small then timing stability +will of course detoriate. Libev itself tries to be exact to be about one +millisecond (if the OS supports it and the machine is fast enough). =item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) @@ -1340,12 +1348,14 @@ current time as second argument. NOTE: I. If you need to stop it, -return C (or so, fudge fudge) and stop it afterwards (e.g. by -starting an C watcher, which is legal). +ever, or make ANY event loop modifications whatsoever>. + +If you need to stop it, return C (or so, fudge fudge) and stop +it afterwards (e.g. by starting an C watcher, which is the +only event loop modification you are allowed to do). -Its prototype is C, e.g.: +The callback prototype is C, e.g.: static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) { @@ -1357,11 +1367,11 @@ will usually be called just before the callback will be triggered, but might be called at other times, too. -NOTE: I<< This callback must always return a time that is later than the -passed C value >>. Not even C itself will do, it I be larger. +NOTE: I<< This callback must always return a time that is higher than or +equal to the passed C value >>. This can be used to create very complex timers, such as a timer that -triggers on each midnight, local time. To do this, you would calculate the +triggers on "next midnight, local time". To do this, you would calculate the next midnight after C and return the timestamp value for this. How you do this is, again, up to you (but it is not trivial, which is the main reason I omitted it as an example). @@ -1659,7 +1669,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). @@ -3005,8 +3015,8 @@ 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 a -noticable after performance with many (thousands) of watchers. +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). @@ -3017,8 +3027,8 @@ 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 noticably improves -performance noticably with with many (hundreds) of watchers. +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). @@ -3253,7 +3263,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). @@ -3354,6 +3364,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 .