ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.380 by root, Mon Jul 25 03:47:28 2011 UTC vs.
Revision 1.381 by root, Sat Aug 13 17:41:14 2011 UTC

… …
1771detecting time jumps is hard, and some inaccuracies are unavoidable (the 1771detecting time jumps is hard, and some inaccuracies are unavoidable (the
1772monotonic clock option helps a lot here). 1772monotonic clock option helps a lot here).
1773 1773
1774The callback is guaranteed to be invoked only I<after> its timeout has 1774The callback is guaranteed to be invoked only I<after> its timeout has
1775passed (not I<at>, so on systems with very low-resolution clocks this 1775passed (not I<at>, so on systems with very low-resolution clocks this
1776might introduce a small delay). If multiple timers become ready during the 1776might introduce a small delay, see "the special problem of being too
1777early", below). If multiple timers become ready during the same loop
1777same loop iteration then the ones with earlier time-out values are invoked 1778iteration then the ones with earlier time-out values are invoked before
1778before ones of the same priority with later time-out values (but this is 1779ones of the same priority with later time-out values (but this is no
1779no longer true when a callback calls C<ev_run> recursively). 1780longer true when a callback calls C<ev_run> recursively).
1780 1781
1781=head3 Be smart about timeouts 1782=head3 Be smart about timeouts
1782 1783
1783Many real-world problems involve some kind of timeout, usually for error 1784Many real-world problems involve some kind of timeout, usually for error
1784recovery. A typical example is an HTTP request - if the other side hangs, 1785recovery. A typical example is an HTTP request - if the other side hangs,
… …
1951Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 1952Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1952rather complicated, but extremely efficient, something that really pays 1953rather complicated, but extremely efficient, something that really pays
1953off after the first million or so of active timers, i.e. it's usually 1954off after the first million or so of active timers, i.e. it's usually
1954overkill :) 1955overkill :)
1955 1956
1957=head3 The special problem of being too early
1958
1959If you ask a timer to call your callback after three seconds, then
1960you expect it to be invoked after three seconds - but of course, this
1961cannot be guaranteed to infinite precision. Less obviously, it cannot be
1962guaranteed to any precision by libev - imagine somebody suspending the
1963process a STOP signal for a few hours for example.
1964
1965So, libev tries to invoke your callback as soon as possible I<after> the
1966delay has occured, but cannot guarantee this.
1967
1968A less obvious failure mode is calling your callback too early: many event
1969loops compare timestamps with a "elapsed delay >= requested delay", but
1970this can cause your callback to be invoked much earlier than you would
1971expect.
1972
1973To see why, imagine a system with a clock that only offers full second
1974resolution (think windows if you can't come up with a broken enough OS
1975yourself). If you schedule a one-second timer at the time 500.9, then the
1976event loop will schedule your timeout to elapse at a system time of 500
1977(500.9 truncated to the resolution) + 1, or 501.
1978
1979If an event library looks at the timeout 0.1s later, it will see "501 >=
1980501" and invoke the callback 0.1s after it was started, even though a
1981one-second delay was requested - this is being "too early", despite best
1982intentions.
1983
1984This is the reason why libev will never invoke the callback if the elapsed
1985delay equals the requested delay, but only when the elapsed delay is
1986larger than the requested delay. In the example above, libev would only invoke
1987the callback at system time 502, or 1.1s after the timer was started.
1988
1989So, while libev cannot guarantee that your callback will be invoked
1990exactly when requested, it I<can> and I<does> guarantee that the requested
1991delay has actually elapsed, or in other words, it always errs on the "too
1992late" side of things.
1993
1956=head3 The special problem of time updates 1994=head3 The special problem of time updates
1957 1995
1958Establishing the current time is a costly operation (it usually takes at 1996Establishing the current time is a costly operation (it usually takes at
1959least two system calls): EV therefore updates its idea of the current 1997least two system calls): EV therefore updates its idea of the current
1960time only before and after C<ev_run> collects new events, which causes a 1998time only before and after C<ev_run> collects new events, which causes a
… …
1970 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 2008 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1971 2009
1972If the event loop is suspended for a long time, you can also force an 2010If the event loop is suspended for a long time, you can also force an
1973update of the time returned by C<ev_now ()> by calling C<ev_now_update 2011update of the time returned by C<ev_now ()> by calling C<ev_now_update
1974()>. 2012()>.
2013
2014=head3 The special problem of unsychronised clocks
2015
2016Modern systems have a variety of clocks - libev itself uses the normal
2017"wall clock" clock and, if available, the monotonic clock (to avoid time
2018jumps).
2019
2020Neither of these clocks is synchronised with each other or any other clock
2021on the system, so C<ev_time ()> might return a considerably different time
2022than C<gettimeofday ()> or C<time ()>. On a GNU/Linux system, for example,
2023a call to C<gettimeofday> might return a second count that is one higher
2024than a directly following call to C<time>.
2025
2026The moral of this is to only compare libev-related timestamps with
2027C<ev_time ()> and C<ev_now ()>, at least if you want better precision than
2028a seocnd or so.
2029
2030One more problem arises due to this lack of synchronisation: if libev uses
2031the system monotonic clock and you compare timestamps from C<ev_time>
2032or C<ev_now> from when you started your timer and when your callback is
2033invoked, you will find that sometimes the callback is a bit "early".
2034
2035This is because C<ev_timer>s work in real time, not wall clock time, so
2036libev makes sure your callback is not invoked before the delay happened,
2037I<measured according to the real time>, not the system clock.
2038
2039If your timeouts are based on a physical timescale (e.g. "time out this
2040connection after 100 seconds") then this shouldn't bother you as it is
2041exactly the right behaviour.
2042
2043If you want to compare wall clock/system timestamps to your timers, then
2044you need to use C<ev_periodic>s, as these are based on the wall clock
2045time, where your comparisons will always generate correct results.
1975 2046
1976=head3 The special problems of suspended animation 2047=head3 The special problems of suspended animation
1977 2048
1978When you leave the server world it is quite customary to hit machines that 2049When you leave the server world it is quite customary to hit machines that
1979can suspend/hibernate - what happens to the clocks during such a suspend? 2050can suspend/hibernate - what happens to the clocks during such a suspend?

Diff Legend

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