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

Comparing libev/ev.pod (file contents):
Revision 1.360 by root, Mon Jan 17 12:11:12 2011 UTC vs.
Revision 1.387 by root, Tue Dec 20 01:47:49 2011 UTC

58 ev_timer_start (loop, &timeout_watcher); 58 ev_timer_start (loop, &timeout_watcher);
59 59
60 // now wait for events to arrive 60 // now wait for events to arrive
61 ev_run (loop, 0); 61 ev_run (loop, 0);
62 62
63 // unloop was called, so exit 63 // break was called, so exit
64 return 0; 64 return 0;
65 } 65 }
66 66
67=head1 ABOUT THIS DOCUMENT 67=head1 ABOUT THIS DOCUMENT
68 68
174=item ev_tstamp ev_time () 174=item ev_tstamp ev_time ()
175 175
176Returns the current time as libev would use it. Please note that the 176Returns the current time as libev would use it. Please note that the
177C<ev_now> function is usually faster and also often returns the timestamp 177C<ev_now> function is usually faster and also often returns the timestamp
178you actually want to know. Also interesting is the combination of 178you actually want to know. Also interesting is the combination of
179C<ev_update_now> and C<ev_now>. 179C<ev_now_update> and C<ev_now>.
180 180
181=item ev_sleep (ev_tstamp interval) 181=item ev_sleep (ev_tstamp interval)
182 182
183Sleep for the given interval: The current thread will be blocked until 183Sleep for the given interval: The current thread will be blocked
184either it is interrupted or the given time interval has passed. Basically 184until either it is interrupted or the given time interval has
185passed (approximately - it might return a bit earlier even if not
186interrupted). Returns immediately if C<< interval <= 0 >>.
187
185this is a sub-second-resolution C<sleep ()>. 188Basically this is a sub-second-resolution C<sleep ()>.
189
190The range of the C<interval> is limited - libev only guarantees to work
191with sleep times of up to one day (C<< interval <= 86400 >>).
186 192
187=item int ev_version_major () 193=item int ev_version_major ()
188 194
189=item int ev_version_minor () 195=item int ev_version_minor ()
190 196
435example) that can't properly initialise their signal masks. 441example) that can't properly initialise their signal masks.
436 442
437=item C<EVFLAG_NOSIGMASK> 443=item C<EVFLAG_NOSIGMASK>
438 444
439When this flag is specified, then libev will avoid to modify the signal 445When this flag is specified, then libev will avoid to modify the signal
440mask. Specifically, this means you ahve to make sure signals are unblocked 446mask. Specifically, this means you have to make sure signals are unblocked
441when you want to receive them. 447when you want to receive them.
442 448
443This behaviour is useful when you want to do your own signal handling, or 449This behaviour is useful when you want to do your own signal handling, or
444want to handle signals only in specific threads and want to avoid libev 450want to handle signals only in specific threads and want to avoid libev
445unblocking the signals. 451unblocking the signals.
483=item C<EVBACKEND_EPOLL> (value 4, Linux) 489=item C<EVBACKEND_EPOLL> (value 4, Linux)
484 490
485Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9 491Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
486kernels). 492kernels).
487 493
488For few fds, this backend is a bit little slower than poll and select, 494For few fds, this backend is a bit little slower than poll and select, but
489but it scales phenomenally better. While poll and select usually scale 495it scales phenomenally better. While poll and select usually scale like
490like O(total_fds) where n is the total number of fds (or the highest fd), 496O(total_fds) where total_fds is the total number of fds (or the highest
491epoll scales either O(1) or O(active_fds). 497fd), epoll scales either O(1) or O(active_fds).
492 498
493The epoll mechanism deserves honorable mention as the most misdesigned 499The epoll mechanism deserves honorable mention as the most misdesigned
494of the more advanced event mechanisms: mere annoyances include silently 500of the more advanced event mechanisms: mere annoyances include silently
495dropping file descriptors, requiring a system call per change per file 501dropping file descriptors, requiring a system call per change per file
496descriptor (and unnecessary guessing of parameters), problems with dup, 502descriptor (and unnecessary guessing of parameters), problems with dup,
4990.1ms) and so on. The biggest issue is fork races, however - if a program 5050.1ms) and so on. The biggest issue is fork races, however - if a program
500forks then I<both> parent and child process have to recreate the epoll 506forks then I<both> parent and child process have to recreate the epoll
501set, which can take considerable time (one syscall per file descriptor) 507set, which can take considerable time (one syscall per file descriptor)
502and is of course hard to detect. 508and is of course hard to detect.
503 509
504Epoll is also notoriously buggy - embedding epoll fds I<should> work, but 510Epoll is also notoriously buggy - embedding epoll fds I<should> work,
505of course I<doesn't>, and epoll just loves to report events for totally 511but of course I<doesn't>, and epoll just loves to report events for
506I<different> file descriptors (even already closed ones, so one cannot 512totally I<different> file descriptors (even already closed ones, so
507even remove them from the set) than registered in the set (especially 513one cannot even remove them from the set) than registered in the set
508on SMP systems). Libev tries to counter these spurious notifications by 514(especially on SMP systems). Libev tries to counter these spurious
509employing an additional generation counter and comparing that against the 515notifications by employing an additional generation counter and comparing
510events to filter out spurious ones, recreating the set when required. Last 516that against the events to filter out spurious ones, recreating the set
517when required. Epoll also erroneously rounds down timeouts, but gives you
518no way to know when and by how much, so sometimes you have to busy-wait
519because epoll returns immediately despite a nonzero timeout. And last
511not least, it also refuses to work with some file descriptors which work 520not least, it also refuses to work with some file descriptors which work
512perfectly fine with C<select> (files, many character devices...). 521perfectly fine with C<select> (files, many character devices...).
513 522
514Epoll is truly the train wreck analog among event poll mechanisms, 523Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
515a frankenpoll, cobbled together in a hurry, no thought to design or 524cobbled together in a hurry, no thought to design or interaction with
516interaction with others. 525others. Oh, the pain, will it ever stop...
517 526
518While stopping, setting and starting an I/O watcher in the same iteration 527While stopping, setting and starting an I/O watcher in the same iteration
519will result in some caching, there is still a system call per such 528will result in some caching, there is still a system call per such
520incident (because the same I<file descriptor> could point to a different 529incident (because the same I<file descriptor> could point to a different
521I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 530I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
599among the OS-specific backends (I vastly prefer correctness over speed 608among the OS-specific backends (I vastly prefer correctness over speed
600hacks). 609hacks).
601 610
602On the negative side, the interface is I<bizarre> - so bizarre that 611On the negative side, the interface is I<bizarre> - so bizarre that
603even sun itself gets it wrong in their code examples: The event polling 612even sun itself gets it wrong in their code examples: The event polling
604function sometimes returning events to the caller even though an error 613function sometimes returns events to the caller even though an error
605occurred, but with no indication whether it has done so or not (yes, it's 614occurred, but with no indication whether it has done so or not (yes, it's
606even documented that way) - deadly for edge-triggered interfaces where 615even documented that way) - deadly for edge-triggered interfaces where you
607you absolutely have to know whether an event occurred or not because you 616absolutely have to know whether an event occurred or not because you have
608have to re-arm the watcher. 617to re-arm the watcher.
609 618
610Fortunately libev seems to be able to work around these idiocies. 619Fortunately libev seems to be able to work around these idiocies.
611 620
612This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 621This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
613C<EVBACKEND_POLL>. 622C<EVBACKEND_POLL>.
825This is useful if you are waiting for some external event in conjunction 834This is useful if you are waiting for some external event in conjunction
826with something not expressible using other libev watchers (i.e. "roll your 835with something not expressible using other libev watchers (i.e. "roll your
827own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is 836own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
828usually a better approach for this kind of thing. 837usually a better approach for this kind of thing.
829 838
830Here are the gory details of what C<ev_run> does: 839Here are the gory details of what C<ev_run> does (this is for your
840understanding, not a guarantee that things will work exactly like this in
841future versions):
831 842
832 - Increment loop depth. 843 - Increment loop depth.
833 - Reset the ev_break status. 844 - Reset the ev_break status.
834 - Before the first iteration, call any pending watchers. 845 - Before the first iteration, call any pending watchers.
835 LOOP: 846 LOOP:
868anymore. 879anymore.
869 880
870 ... queue jobs here, make sure they register event watchers as long 881 ... queue jobs here, make sure they register event watchers as long
871 ... as they still have work to do (even an idle watcher will do..) 882 ... as they still have work to do (even an idle watcher will do..)
872 ev_run (my_loop, 0); 883 ev_run (my_loop, 0);
873 ... jobs done or somebody called unloop. yeah! 884 ... jobs done or somebody called break. yeah!
874 885
875=item ev_break (loop, how) 886=item ev_break (loop, how)
876 887
877Can be used to make a call to C<ev_run> return early (but only after it 888Can be used to make a call to C<ev_run> return early (but only after it
878has processed all outstanding events). The C<how> argument must be either 889has processed all outstanding events). The C<how> argument must be either
941overhead for the actual polling but can deliver many events at once. 952overhead for the actual polling but can deliver many events at once.
942 953
943By setting a higher I<io collect interval> you allow libev to spend more 954By setting a higher I<io collect interval> you allow libev to spend more
944time collecting I/O events, so you can handle more events per iteration, 955time collecting I/O events, so you can handle more events per iteration,
945at the cost of increasing latency. Timeouts (both C<ev_periodic> and 956at the cost of increasing latency. Timeouts (both C<ev_periodic> and
946C<ev_timer>) will be not affected. Setting this to a non-null value will 957C<ev_timer>) will not be affected. Setting this to a non-null value will
947introduce an additional C<ev_sleep ()> call into most loop iterations. The 958introduce an additional C<ev_sleep ()> call into most loop iterations. The
948sleep time ensures that libev will not poll for I/O events more often then 959sleep time ensures that libev will not poll for I/O events more often then
949once per this interval, on average. 960once per this interval, on average (as long as the host time resolution is
961good enough).
950 962
951Likewise, by setting a higher I<timeout collect interval> you allow libev 963Likewise, by setting a higher I<timeout collect interval> you allow libev
952to spend more time collecting timeouts, at the expense of increased 964to spend more time collecting timeouts, at the expense of increased
953latency/jitter/inexactness (the watcher callback will be called 965latency/jitter/inexactness (the watcher callback will be called
954later). C<ev_io> watchers will not be affected. Setting this to a non-null 966later). C<ev_io> watchers will not be affected. Setting this to a non-null
1008can be done relatively simply by putting mutex_lock/unlock calls around 1020can be done relatively simply by putting mutex_lock/unlock calls around
1009each call to a libev function. 1021each call to a libev function.
1010 1022
1011However, C<ev_run> can run an indefinite time, so it is not feasible 1023However, C<ev_run> can run an indefinite time, so it is not feasible
1012to wait for it to return. One way around this is to wake up the event 1024to wait for it to return. One way around this is to wake up the event
1013loop via C<ev_break> and C<av_async_send>, another way is to set these 1025loop via C<ev_break> and C<ev_async_send>, another way is to set these
1014I<release> and I<acquire> callbacks on the loop. 1026I<release> and I<acquire> callbacks on the loop.
1015 1027
1016When set, then C<release> will be called just before the thread is 1028When set, then C<release> will be called just before the thread is
1017suspended waiting for new events, and C<acquire> is called just 1029suspended waiting for new events, and C<acquire> is called just
1018afterwards. 1030afterwards.
1374 1386
1375=over 4 1387=over 4
1376 1388
1377=item initialiased 1389=item initialiased
1378 1390
1379Before a watcher can be registered with the event looop it has to be 1391Before a watcher can be registered with the event loop it has to be
1380initialised. This can be done with a call to C<ev_TYPE_init>, or calls to 1392initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1381C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function. 1393C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1382 1394
1383In this state it is simply some block of memory that is suitable for use 1395In this state it is simply some block of memory that is suitable for
1384in an event loop. It can be moved around, freed, reused etc. at will. 1396use in an event loop. It can be moved around, freed, reused etc. at
1397will - as long as you either keep the memory contents intact, or call
1398C<ev_TYPE_init> again.
1385 1399
1386=item started/running/active 1400=item started/running/active
1387 1401
1388Once a watcher has been started with a call to C<ev_TYPE_start> it becomes 1402Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1389property of the event loop, and is actively waiting for events. While in 1403property of the event loop, and is actively waiting for events. While in
1417latter will clear any pending state the watcher might be in, regardless 1431latter will clear any pending state the watcher might be in, regardless
1418of whether it was active or not, so stopping a watcher explicitly before 1432of whether it was active or not, so stopping a watcher explicitly before
1419freeing it is often a good idea. 1433freeing it is often a good idea.
1420 1434
1421While stopped (and not pending) the watcher is essentially in the 1435While stopped (and not pending) the watcher is essentially in the
1422initialised state, that is it can be reused, moved, modified in any way 1436initialised state, that is, it can be reused, moved, modified in any way
1423you wish. 1437you wish (but when you trash the memory block, you need to C<ev_TYPE_init>
1438it again).
1424 1439
1425=back 1440=back
1426 1441
1427=head2 WATCHER PRIORITY MODELS 1442=head2 WATCHER PRIORITY MODELS
1428 1443
1756detecting time jumps is hard, and some inaccuracies are unavoidable (the 1771detecting time jumps is hard, and some inaccuracies are unavoidable (the
1757monotonic clock option helps a lot here). 1772monotonic clock option helps a lot here).
1758 1773
1759The 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
1760passed (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
1761might 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
1762same loop iteration then the ones with earlier time-out values are invoked 1778iteration then the ones with earlier time-out values are invoked before
1763before 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
1764no longer true when a callback calls C<ev_run> recursively). 1780longer true when a callback calls C<ev_run> recursively).
1765 1781
1766=head3 Be smart about timeouts 1782=head3 Be smart about timeouts
1767 1783
1768Many real-world problems involve some kind of timeout, usually for error 1784Many real-world problems involve some kind of timeout, usually for error
1769recovery. 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,
1844 1860
1845In this case, it would be more efficient to leave the C<ev_timer> alone, 1861In this case, it would be more efficient to leave the C<ev_timer> alone,
1846but remember the time of last activity, and check for a real timeout only 1862but remember the time of last activity, and check for a real timeout only
1847within the callback: 1863within the callback:
1848 1864
1865 ev_tstamp timeout = 60.;
1849 ev_tstamp last_activity; // time of last activity 1866 ev_tstamp last_activity; // time of last activity
1867 ev_timer timer;
1850 1868
1851 static void 1869 static void
1852 callback (EV_P_ ev_timer *w, int revents) 1870 callback (EV_P_ ev_timer *w, int revents)
1853 { 1871 {
1854 ev_tstamp now = ev_now (EV_A); 1872 // calculate when the timeout would happen
1855 ev_tstamp timeout = last_activity + 60.; 1873 ev_tstamp after = last_activity - ev_now (EV_A) + timeout;
1856 1874
1857 // if last_activity + 60. is older than now, we did time out 1875 // if negative, it means we the timeout already occured
1858 if (timeout < now) 1876 if (after < 0.)
1859 { 1877 {
1860 // timeout occurred, take action 1878 // timeout occurred, take action
1861 } 1879 }
1862 else 1880 else
1863 { 1881 {
1864 // callback was invoked, but there was some activity, re-arm 1882 // callback was invoked, but there was some recent
1865 // the watcher to fire in last_activity + 60, which is 1883 // activity. simply restart the timer to time out
1866 // guaranteed to be in the future, so "again" is positive: 1884 // after "after" seconds, which is the earliest time
1867 w->repeat = timeout - now; 1885 // the timeout can occur.
1886 ev_timer_set (w, after, 0.);
1868 ev_timer_again (EV_A_ w); 1887 ev_timer_start (EV_A_ w);
1869 } 1888 }
1870 } 1889 }
1871 1890
1872To summarise the callback: first calculate the real timeout (defined 1891To summarise the callback: first calculate in how many seconds the
1873as "60 seconds after the last activity"), then check if that time has 1892timeout will occur (by calculating the absolute time when it would occur,
1874been reached, which means something I<did>, in fact, time out. Otherwise 1893C<last_activity + timeout>, and subtracting the current time, C<ev_now
1875the callback was invoked too early (C<timeout> is in the future), so 1894(EV_A)> from that).
1876re-schedule the timer to fire at that future time, to see if maybe we have
1877a timeout then.
1878 1895
1879Note how C<ev_timer_again> is used, taking advantage of the 1896If this value is negative, then we are already past the timeout, i.e. we
1880C<ev_timer_again> optimisation when the timer is already running. 1897timed out, and need to do whatever is needed in this case.
1898
1899Otherwise, we now the earliest time at which the timeout would trigger,
1900and simply start the timer with this timeout value.
1901
1902In other words, each time the callback is invoked it will check whether
1903the timeout cocured. If not, it will simply reschedule itself to check
1904again at the earliest time it could time out. Rinse. Repeat.
1881 1905
1882This scheme causes more callback invocations (about one every 60 seconds 1906This scheme causes more callback invocations (about one every 60 seconds
1883minus half the average time between activity), but virtually no calls to 1907minus half the average time between activity), but virtually no calls to
1884libev to change the timeout. 1908libev to change the timeout.
1885 1909
1886To start the timer, simply initialise the watcher and set C<last_activity> 1910To start the machinery, simply initialise the watcher and set
1887to the current time (meaning we just have some activity :), then call the 1911C<last_activity> to the current time (meaning there was some activity just
1888callback, which will "do the right thing" and start the timer: 1912now), then call the callback, which will "do the right thing" and start
1913the timer:
1889 1914
1915 last_activity = ev_now (EV_A);
1890 ev_init (timer, callback); 1916 ev_init (&timer, callback);
1891 last_activity = ev_now (loop); 1917 callback (EV_A_ &timer, 0);
1892 callback (loop, timer, EV_TIMER);
1893 1918
1894And when there is some activity, simply store the current time in 1919When there is some activity, simply store the current time in
1895C<last_activity>, no libev calls at all: 1920C<last_activity>, no libev calls at all:
1896 1921
1922 if (activity detected)
1897 last_activity = ev_now (loop); 1923 last_activity = ev_now (EV_A);
1924
1925When your timeout value changes, then the timeout can be changed by simply
1926providing a new value, stopping the timer and calling the callback, which
1927will agaion do the right thing (for example, time out immediately :).
1928
1929 timeout = new_value;
1930 ev_timer_stop (EV_A_ &timer);
1931 callback (EV_A_ &timer, 0);
1898 1932
1899This technique is slightly more complex, but in most cases where the 1933This technique is slightly more complex, but in most cases where the
1900time-out is unlikely to be triggered, much more efficient. 1934time-out is unlikely to be triggered, much more efficient.
1901
1902Changing the timeout is trivial as well (if it isn't hard-coded in the
1903callback :) - just change the timeout and invoke the callback, which will
1904fix things for you.
1905 1935
1906=item 4. Wee, just use a double-linked list for your timeouts. 1936=item 4. Wee, just use a double-linked list for your timeouts.
1907 1937
1908If there is not one request, but many thousands (millions...), all 1938If there is not one request, but many thousands (millions...), all
1909employing some kind of timeout with the same timeout value, then one can 1939employing some kind of timeout with the same timeout value, then one can
1936Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 1966Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1937rather complicated, but extremely efficient, something that really pays 1967rather complicated, but extremely efficient, something that really pays
1938off after the first million or so of active timers, i.e. it's usually 1968off after the first million or so of active timers, i.e. it's usually
1939overkill :) 1969overkill :)
1940 1970
1971=head3 The special problem of being too early
1972
1973If you ask a timer to call your callback after three seconds, then
1974you expect it to be invoked after three seconds - but of course, this
1975cannot be guaranteed to infinite precision. Less obviously, it cannot be
1976guaranteed to any precision by libev - imagine somebody suspending the
1977process with a STOP signal for a few hours for example.
1978
1979So, libev tries to invoke your callback as soon as possible I<after> the
1980delay has occurred, but cannot guarantee this.
1981
1982A less obvious failure mode is calling your callback too early: many event
1983loops compare timestamps with a "elapsed delay >= requested delay", but
1984this can cause your callback to be invoked much earlier than you would
1985expect.
1986
1987To see why, imagine a system with a clock that only offers full second
1988resolution (think windows if you can't come up with a broken enough OS
1989yourself). If you schedule a one-second timer at the time 500.9, then the
1990event loop will schedule your timeout to elapse at a system time of 500
1991(500.9 truncated to the resolution) + 1, or 501.
1992
1993If an event library looks at the timeout 0.1s later, it will see "501 >=
1994501" and invoke the callback 0.1s after it was started, even though a
1995one-second delay was requested - this is being "too early", despite best
1996intentions.
1997
1998This is the reason why libev will never invoke the callback if the elapsed
1999delay equals the requested delay, but only when the elapsed delay is
2000larger than the requested delay. In the example above, libev would only invoke
2001the callback at system time 502, or 1.1s after the timer was started.
2002
2003So, while libev cannot guarantee that your callback will be invoked
2004exactly when requested, it I<can> and I<does> guarantee that the requested
2005delay has actually elapsed, or in other words, it always errs on the "too
2006late" side of things.
2007
1941=head3 The special problem of time updates 2008=head3 The special problem of time updates
1942 2009
1943Establishing the current time is a costly operation (it usually takes at 2010Establishing the current time is a costly operation (it usually takes
1944least two system calls): EV therefore updates its idea of the current 2011at least one system call): EV therefore updates its idea of the current
1945time only before and after C<ev_run> collects new events, which causes a 2012time only before and after C<ev_run> collects new events, which causes a
1946growing difference between C<ev_now ()> and C<ev_time ()> when handling 2013growing difference between C<ev_now ()> and C<ev_time ()> when handling
1947lots of events in one iteration. 2014lots of events in one iteration.
1948 2015
1949The relative timeouts are calculated relative to the C<ev_now ()> 2016The relative timeouts are calculated relative to the C<ev_now ()>
1955 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 2022 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1956 2023
1957If the event loop is suspended for a long time, you can also force an 2024If the event loop is suspended for a long time, you can also force an
1958update of the time returned by C<ev_now ()> by calling C<ev_now_update 2025update of the time returned by C<ev_now ()> by calling C<ev_now_update
1959()>. 2026()>.
2027
2028=head3 The special problem of unsynchronised clocks
2029
2030Modern systems have a variety of clocks - libev itself uses the normal
2031"wall clock" clock and, if available, the monotonic clock (to avoid time
2032jumps).
2033
2034Neither of these clocks is synchronised with each other or any other clock
2035on the system, so C<ev_time ()> might return a considerably different time
2036than C<gettimeofday ()> or C<time ()>. On a GNU/Linux system, for example,
2037a call to C<gettimeofday> might return a second count that is one higher
2038than a directly following call to C<time>.
2039
2040The moral of this is to only compare libev-related timestamps with
2041C<ev_time ()> and C<ev_now ()>, at least if you want better precision than
2042a second or so.
2043
2044One more problem arises due to this lack of synchronisation: if libev uses
2045the system monotonic clock and you compare timestamps from C<ev_time>
2046or C<ev_now> from when you started your timer and when your callback is
2047invoked, you will find that sometimes the callback is a bit "early".
2048
2049This is because C<ev_timer>s work in real time, not wall clock time, so
2050libev makes sure your callback is not invoked before the delay happened,
2051I<measured according to the real time>, not the system clock.
2052
2053If your timeouts are based on a physical timescale (e.g. "time out this
2054connection after 100 seconds") then this shouldn't bother you as it is
2055exactly the right behaviour.
2056
2057If you want to compare wall clock/system timestamps to your timers, then
2058you need to use C<ev_periodic>s, as these are based on the wall clock
2059time, where your comparisons will always generate correct results.
1960 2060
1961=head3 The special problems of suspended animation 2061=head3 The special problems of suspended animation
1962 2062
1963When you leave the server world it is quite customary to hit machines that 2063When you leave the server world it is quite customary to hit machines that
1964can suspend/hibernate - what happens to the clocks during such a suspend? 2064can suspend/hibernate - what happens to the clocks during such a suspend?
2008keep up with the timer (because it takes longer than those 10 seconds to 2108keep up with the timer (because it takes longer than those 10 seconds to
2009do stuff) the timer will not fire more than once per event loop iteration. 2109do stuff) the timer will not fire more than once per event loop iteration.
2010 2110
2011=item ev_timer_again (loop, ev_timer *) 2111=item ev_timer_again (loop, ev_timer *)
2012 2112
2013This will act as if the timer timed out and restart it again if it is 2113This will act as if the timer timed out and restarts it again if it is
2014repeating. The exact semantics are: 2114repeating. The exact semantics are:
2015 2115
2016If the timer is pending, its pending status is cleared. 2116If the timer is pending, its pending status is cleared.
2017 2117
2018If the timer is started but non-repeating, stop it (as if it timed out). 2118If the timer is started but non-repeating, stop it (as if it timed out).
2148 2248
2149Another way to think about it (for the mathematically inclined) is that 2249Another way to think about it (for the mathematically inclined) is that
2150C<ev_periodic> will try to run the callback in this mode at the next possible 2250C<ev_periodic> will try to run the callback in this mode at the next possible
2151time where C<time = offset (mod interval)>, regardless of any time jumps. 2251time where C<time = offset (mod interval)>, regardless of any time jumps.
2152 2252
2153For numerical stability it is preferable that the C<offset> value is near 2253The C<interval> I<MUST> be positive, and for numerical stability, the
2154C<ev_now ()> (the current time), but there is no range requirement for 2254interval value should be higher than C<1/8192> (which is around 100
2155this value, and in fact is often specified as zero. 2255microseconds) and C<offset> should be higher than C<0> and should have
2256at most a similar magnitude as the current time (say, within a factor of
2257ten). Typical values for offset are, in fact, C<0> or something between
2258C<0> and C<interval>, which is also the recommended range.
2156 2259
2157Note also that there is an upper limit to how often a timer can fire (CPU 2260Note also that there is an upper limit to how often a timer can fire (CPU
2158speed for example), so if C<interval> is very small then timing stability 2261speed for example), so if C<interval> is very small then timing stability
2159will of course deteriorate. Libev itself tries to be exact to be about one 2262will of course deteriorate. Libev itself tries to be exact to be about one
2160millisecond (if the OS supports it and the machine is fast enough). 2263millisecond (if the OS supports it and the machine is fast enough).
3185 atexit (program_exits); 3288 atexit (program_exits);
3186 3289
3187 3290
3188=head2 C<ev_async> - how to wake up an event loop 3291=head2 C<ev_async> - how to wake up an event loop
3189 3292
3190In general, you cannot use an C<ev_run> from multiple threads or other 3293In general, you cannot use an C<ev_loop> from multiple threads or other
3191asynchronous sources such as signal handlers (as opposed to multiple event 3294asynchronous sources such as signal handlers (as opposed to multiple event
3192loops - those are of course safe to use in different threads). 3295loops - those are of course safe to use in different threads).
3193 3296
3194Sometimes, however, you need to wake up an event loop you do not control, 3297Sometimes, however, you need to wake up an event loop you do not control,
3195for example because it belongs to another thread. This is what C<ev_async> 3298for example because it belongs to another thread. This is what C<ev_async>
3202C<ev_async_sent> calls). In fact, you could use signal watchers as a kind 3305C<ev_async_sent> calls). In fact, you could use signal watchers as a kind
3203of "global async watchers" by using a watcher on an otherwise unused 3306of "global async watchers" by using a watcher on an otherwise unused
3204signal, and C<ev_feed_signal> to signal this watcher from another thread, 3307signal, and C<ev_feed_signal> to signal this watcher from another thread,
3205even without knowing which loop owns the signal. 3308even without knowing which loop owns the signal.
3206 3309
3207Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
3208just the default loop.
3209
3210=head3 Queueing 3310=head3 Queueing
3211 3311
3212C<ev_async> does not support queueing of data in any way. The reason 3312C<ev_async> does not support queueing of data in any way. The reason
3213is that the author does not know of a simple (or any) algorithm for a 3313is that the author does not know of a simple (or any) algorithm for a
3214multiple-writer-single-reader queue that works in all cases and doesn't 3314multiple-writer-single-reader queue that works in all cases and doesn't
3305trust me. 3405trust me.
3306 3406
3307=item ev_async_send (loop, ev_async *) 3407=item ev_async_send (loop, ev_async *)
3308 3408
3309Sends/signals/activates the given C<ev_async> watcher, that is, feeds 3409Sends/signals/activates the given C<ev_async> watcher, that is, feeds
3310an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3410an C<EV_ASYNC> event on the watcher into the event loop, and instantly
3411returns.
3412
3311C<ev_feed_event>, this call is safe to do from other threads, signal or 3413Unlike C<ev_feed_event>, this call is safe to do from other threads,
3312similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 3414signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
3313section below on what exactly this means). 3415embedding section below on what exactly this means).
3314 3416
3315Note that, as with other watchers in libev, multiple events might get 3417Note that, as with other watchers in libev, multiple events might get
3316compressed into a single callback invocation (another way to look at this 3418compressed into a single callback invocation (another way to look at
3317is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>, 3419this is that C<ev_async> watchers are level-triggered: they are set on
3318reset when the event loop detects that). 3420C<ev_async_send>, reset when the event loop detects that).
3319 3421
3320This call incurs the overhead of a system call only once per event loop 3422This call incurs the overhead of at most one extra system call per event
3321iteration, so while the overhead might be noticeable, it doesn't apply to 3423loop iteration, if the event loop is blocked, and no syscall at all if
3322repeated calls to C<ev_async_send> for the same event loop. 3424the event loop (or your program) is processing events. That means that
3425repeated calls are basically free (there is no need to avoid calls for
3426performance reasons) and that the overhead becomes smaller (typically
3427zero) under load.
3323 3428
3324=item bool = ev_async_pending (ev_async *) 3429=item bool = ev_async_pending (ev_async *)
3325 3430
3326Returns a non-zero value when C<ev_async_send> has been called on the 3431Returns a non-zero value when C<ev_async_send> has been called on the
3327watcher but the event has not yet been processed (or even noted) by the 3432watcher but the event has not yet been processed (or even noted) by the
3382 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3487 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3383 3488
3384=item ev_feed_fd_event (loop, int fd, int revents) 3489=item ev_feed_fd_event (loop, int fd, int revents)
3385 3490
3386Feed an event on the given fd, as if a file descriptor backend detected 3491Feed an event on the given fd, as if a file descriptor backend detected
3387the given events it. 3492the given events.
3388 3493
3389=item ev_feed_signal_event (loop, int signum) 3494=item ev_feed_signal_event (loop, int signum)
3390 3495
3391Feed an event as if the given signal occurred. See also C<ev_feed_signal>, 3496Feed an event as if the given signal occurred. See also C<ev_feed_signal>,
3392which is async-safe. 3497which is async-safe.
3466 { 3571 {
3467 struct my_biggy big = (struct my_biggy *) 3572 struct my_biggy big = (struct my_biggy *)
3468 (((char *)w) - offsetof (struct my_biggy, t2)); 3573 (((char *)w) - offsetof (struct my_biggy, t2));
3469 } 3574 }
3470 3575
3576=head2 AVOIDING FINISHING BEFORE RETURNING
3577
3578Often you have structures like this in event-based programs:
3579
3580 callback ()
3581 {
3582 free (request);
3583 }
3584
3585 request = start_new_request (..., callback);
3586
3587The intent is to start some "lengthy" operation. The C<request> could be
3588used to cancel the operation, or do other things with it.
3589
3590It's not uncommon to have code paths in C<start_new_request> that
3591immediately invoke the callback, for example, to report errors. Or you add
3592some caching layer that finds that it can skip the lengthy aspects of the
3593operation and simply invoke the callback with the result.
3594
3595The problem here is that this will happen I<before> C<start_new_request>
3596has returned, so C<request> is not set.
3597
3598Even if you pass the request by some safer means to the callback, you
3599might want to do something to the request after starting it, such as
3600canceling it, which probably isn't working so well when the callback has
3601already been invoked.
3602
3603A common way around all these issues is to make sure that
3604C<start_new_request> I<always> returns before the callback is invoked. If
3605C<start_new_request> immediately knows the result, it can artificially
3606delay invoking the callback by e.g. using a C<prepare> or C<idle> watcher
3607for example, or more sneakily, by reusing an existing (stopped) watcher
3608and pushing it into the pending queue:
3609
3610 ev_set_cb (watcher, callback);
3611 ev_feed_event (EV_A_ watcher, 0);
3612
3613This way, C<start_new_request> can safely return before the callback is
3614invoked, while not delaying callback invocation too much.
3615
3471=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS 3616=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
3472 3617
3473Often (especially in GUI toolkits) there are places where you have 3618Often (especially in GUI toolkits) there are places where you have
3474I<modal> interaction, which is most easily implemented by recursively 3619I<modal> interaction, which is most easily implemented by recursively
3475invoking C<ev_run>. 3620invoking C<ev_run>.
3544 // now associate this with the loop 3689 // now associate this with the loop
3545 ev_set_userdata (EV_A_ u); 3690 ev_set_userdata (EV_A_ u);
3546 ev_set_invoke_pending_cb (EV_A_ l_invoke); 3691 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3547 ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 3692 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3548 3693
3549 // then create the thread running ev_loop 3694 // then create the thread running ev_run
3550 pthread_create (&u->tid, 0, l_run, EV_A); 3695 pthread_create (&u->tid, 0, l_run, EV_A);
3551 } 3696 }
3552 3697
3553The callback for the C<ev_async> watcher does nothing: the watcher is used 3698The callback for the C<ev_async> watcher does nothing: the watcher is used
3554solely to wake up the event loop so it takes notice of any new watchers 3699solely to wake up the event loop so it takes notice of any new watchers
3924watchers in the constructor. 4069watchers in the constructor.
3925 4070
3926 class myclass 4071 class myclass
3927 { 4072 {
3928 ev::io io ; void io_cb (ev::io &w, int revents); 4073 ev::io io ; void io_cb (ev::io &w, int revents);
3929 ev::io2 io2 ; void io2_cb (ev::io &w, int revents); 4074 ev::io io2 ; void io2_cb (ev::io &w, int revents);
3930 ev::idle idle; void idle_cb (ev::idle &w, int revents); 4075 ev::idle idle; void idle_cb (ev::idle &w, int revents);
3931 4076
3932 myclass (int fd) 4077 myclass (int fd)
3933 { 4078 {
3934 io .set <myclass, &myclass::io_cb > (this); 4079 io .set <myclass, &myclass::io_cb > (this);
3985L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>. 4130L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3986 4131
3987=item D 4132=item D
3988 4133
3989Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 4134Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3990be found at L<http://proj.llucax.com.ar/wiki/evd>. 4135be found at L<http://www.llucax.com.ar/proj/ev.d/index.html>.
3991 4136
3992=item Ocaml 4137=item Ocaml
3993 4138
3994Erkki Seppala has written Ocaml bindings for libev, to be found at 4139Erkki Seppala has written Ocaml bindings for libev, to be found at
3995L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 4140L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
4043suitable for use with C<EV_A>. 4188suitable for use with C<EV_A>.
4044 4189
4045=item C<EV_DEFAULT>, C<EV_DEFAULT_> 4190=item C<EV_DEFAULT>, C<EV_DEFAULT_>
4046 4191
4047Similar to the other two macros, this gives you the value of the default 4192Similar to the other two macros, this gives you the value of the default
4048loop, if multiple loops are supported ("ev loop default"). 4193loop, if multiple loops are supported ("ev loop default"). The default loop
4194will be initialised if it isn't already initialised.
4195
4196For non-multiplicity builds, these macros do nothing, so you always have
4197to initialise the loop somewhere.
4049 4198
4050=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_> 4199=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
4051 4200
4052Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the 4201Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
4053default loop has been initialised (C<UC> == unchecked). Their behaviour 4202default loop has been initialised (C<UC> == unchecked). Their behaviour
4198supported). It will also not define any of the structs usually found in 4347supported). It will also not define any of the structs usually found in
4199F<event.h> that are not directly supported by the libev core alone. 4348F<event.h> that are not directly supported by the libev core alone.
4200 4349
4201In standalone mode, libev will still try to automatically deduce the 4350In standalone mode, libev will still try to automatically deduce the
4202configuration, but has to be more conservative. 4351configuration, but has to be more conservative.
4352
4353=item EV_USE_FLOOR
4354
4355If defined to be C<1>, libev will use the C<floor ()> function for its
4356periodic reschedule calculations, otherwise libev will fall back on a
4357portable (slower) implementation. If you enable this, you usually have to
4358link against libm or something equivalent. Enabling this when the C<floor>
4359function is not available will fail, so the safe default is to not enable
4360this.
4203 4361
4204=item EV_USE_MONOTONIC 4362=item EV_USE_MONOTONIC
4205 4363
4206If defined to be C<1>, libev will try to detect the availability of the 4364If defined to be C<1>, libev will try to detect the availability of the
4207monotonic clock option at both compile time and runtime. Otherwise no 4365monotonic clock option at both compile time and runtime. Otherwise no
4340indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4498indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4341 4499
4342=item EV_ATOMIC_T 4500=item EV_ATOMIC_T
4343 4501
4344Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4502Libev requires an integer type (suitable for storing C<0> or C<1>) whose
4345access is atomic with respect to other threads or signal contexts. No such 4503access is atomic and serialised with respect to other threads or signal
4346type is easily found in the C language, so you can provide your own type 4504contexts. No such type is easily found in the C language, so you can
4347that you know is safe for your purposes. It is used both for signal handler "locking" 4505provide your own type that you know is safe for your purposes. It is used
4348as well as for signal and thread safety in C<ev_async> watchers. 4506both for signal handler "locking" as well as for signal and thread safety
4507in C<ev_async> watchers.
4349 4508
4350In the absence of this define, libev will use C<sig_atomic_t volatile> 4509In the absence of this define, libev will use C<sig_atomic_t volatile>
4351(from F<signal.h>), which is usually good enough on most platforms. 4510(from F<signal.h>), which is usually good enough on most platforms,
4511although strictly speaking using a type that also implies a memory fence
4512is required.
4352 4513
4353=item EV_H (h) 4514=item EV_H (h)
4354 4515
4355The name of the F<ev.h> header file used to include it. The default if 4516The name of the F<ev.h> header file used to include it. The default if
4356undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 4517undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
4379If undefined or defined to C<1>, then all event-loop-specific functions 4540If undefined or defined to C<1>, then all event-loop-specific functions
4380will have the C<struct ev_loop *> as first argument, and you can create 4541will have the C<struct ev_loop *> as first argument, and you can create
4381additional independent event loops. Otherwise there will be no support 4542additional independent event loops. Otherwise there will be no support
4382for multiple event loops and there is no first event loop pointer 4543for multiple event loops and there is no first event loop pointer
4383argument. Instead, all functions act on the single default loop. 4544argument. Instead, all functions act on the single default loop.
4545
4546Note that C<EV_DEFAULT> and C<EV_DEFAULT_> will no longer provide a
4547default loop when multiplicity is switched off - you always have to
4548initialise the loop manually in this case.
4384 4549
4385=item EV_MINPRI 4550=item EV_MINPRI
4386 4551
4387=item EV_MAXPRI 4552=item EV_MAXPRI
4388 4553
4875requires, and its I/O model is fundamentally incompatible with the POSIX 5040requires, and its I/O model is fundamentally incompatible with the POSIX
4876model. Libev still offers limited functionality on this platform in 5041model. Libev still offers limited functionality on this platform in
4877the form of the C<EVBACKEND_SELECT> backend, and only supports socket 5042the form of the C<EVBACKEND_SELECT> backend, and only supports socket
4878descriptors. This only applies when using Win32 natively, not when using 5043descriptors. This only applies when using Win32 natively, not when using
4879e.g. cygwin. Actually, it only applies to the microsofts own compilers, 5044e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4880as every compielr comes with a slightly differently broken/incompatible 5045as every compiler comes with a slightly differently broken/incompatible
4881environment. 5046environment.
4882 5047
4883Lifting these limitations would basically require the full 5048Lifting these limitations would basically require the full
4884re-implementation of the I/O system. If you are into this kind of thing, 5049re-implementation of the I/O system. If you are into this kind of thing,
4885then note that glib does exactly that for you in a very portable way (note 5050then note that glib does exactly that for you in a very portable way (note
5018 5183
5019The type C<double> is used to represent timestamps. It is required to 5184The type C<double> is used to represent timestamps. It is required to
5020have at least 51 bits of mantissa (and 9 bits of exponent), which is 5185have at least 51 bits of mantissa (and 9 bits of exponent), which is
5021good enough for at least into the year 4000 with millisecond accuracy 5186good enough for at least into the year 4000 with millisecond accuracy
5022(the design goal for libev). This requirement is overfulfilled by 5187(the design goal for libev). This requirement is overfulfilled by
5023implementations using IEEE 754, which is basically all existing ones. With 5188implementations using IEEE 754, which is basically all existing ones.
5189
5024IEEE 754 doubles, you get microsecond accuracy until at least 2200. 5190With IEEE 754 doubles, you get microsecond accuracy until at least the
5191year 2255 (and millisecond accuracy till the year 287396 - by then, libev
5192is either obsolete or somebody patched it to use C<long double> or
5193something like that, just kidding).
5025 5194
5026=back 5195=back
5027 5196
5028If you know of other additional requirements drop me a note. 5197If you know of other additional requirements drop me a note.
5029 5198
5091=item Processing ev_async_send: O(number_of_async_watchers) 5260=item Processing ev_async_send: O(number_of_async_watchers)
5092 5261
5093=item Processing signals: O(max_signal_number) 5262=item Processing signals: O(max_signal_number)
5094 5263
5095Sending involves a system call I<iff> there were no other C<ev_async_send> 5264Sending involves a system call I<iff> there were no other C<ev_async_send>
5096calls in the current loop iteration. Checking for async and signal events 5265calls in the current loop iteration and the loop is currently
5266blocked. Checking for async and signal events involves iterating over all
5097involves iterating over all running async watchers or all signal numbers. 5267running async watchers or all signal numbers.
5098 5268
5099=back 5269=back
5100 5270
5101 5271
5102=head1 PORTING FROM LIBEV 3.X TO 4.X 5272=head1 PORTING FROM LIBEV 3.X TO 4.X
5219The physical time that is observed. It is apparently strictly monotonic :) 5389The physical time that is observed. It is apparently strictly monotonic :)
5220 5390
5221=item wall-clock time 5391=item wall-clock time
5222 5392
5223The time and date as shown on clocks. Unlike real time, it can actually 5393The time and date as shown on clocks. Unlike real time, it can actually
5224be wrong and jump forwards and backwards, e.g. when the you adjust your 5394be wrong and jump forwards and backwards, e.g. when you adjust your
5225clock. 5395clock.
5226 5396
5227=item watcher 5397=item watcher
5228 5398
5229A data structure that describes interest in certain events. Watchers need 5399A data structure that describes interest in certain events. Watchers need
5232=back 5402=back
5233 5403
5234=head1 AUTHOR 5404=head1 AUTHOR
5235 5405
5236Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael 5406Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
5237Magnusson and Emanuele Giaquinta. 5407Magnusson and Emanuele Giaquinta, and minor corrections by many others.
5238 5408

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines