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

Comparing libev/ev.3 (file contents):
Revision 1.87 by root, Wed Feb 16 08:09:06 2011 UTC vs.
Revision 1.88 by root, Sat Feb 4 18:55:50 2012 UTC

1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) 1.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
122.\} 122.\}
123.rm #[ #] #H #V #F C 123.rm #[ #] #H #V #F C
124.\" ======================================================================== 124.\" ========================================================================
125.\" 125.\"
126.IX Title "LIBEV 3" 126.IX Title "LIBEV 3"
127.TH LIBEV 3 "2011-02-16" "libev-4.04" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2012-02-04" "libev-4.11" "libev - high performance full featured event loop"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 129.\" way too many mistakes in technical documents.
130.if n .ad l 130.if n .ad l
131.nh 131.nh
132.SH "NAME" 132.SH "NAME"
244loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and 244loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and
245\&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even 245\&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even
246limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR). 246limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR).
247.PP 247.PP
248It also is quite fast (see this 248It also is quite fast (see this
249<benchmark> comparing it to libevent 249benchmark <http://libev.schmorp.de/bench.html> comparing it to libevent
250for example). 250for example).
251.SS "\s-1CONVENTIONS\s0" 251.SS "\s-1CONVENTIONS\s0"
252.IX Subsection "CONVENTIONS" 252.IX Subsection "CONVENTIONS"
253Libev is very configurable. In this manual the default (and most common) 253Libev is very configurable. In this manual the default (and most common)
254configuration will be described, which supports multiple event loops. For 254configuration will be described, which supports multiple event loops. For
294.IP "ev_tstamp ev_time ()" 4 294.IP "ev_tstamp ev_time ()" 4
295.IX Item "ev_tstamp ev_time ()" 295.IX Item "ev_tstamp ev_time ()"
296Returns the current time as libev would use it. Please note that the 296Returns the current time as libev would use it. Please note that the
297\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp 297\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp
298you actually want to know. Also interesting is the combination of 298you actually want to know. Also interesting is the combination of
299\&\f(CW\*(C`ev_update_now\*(C'\fR and \f(CW\*(C`ev_now\*(C'\fR. 299\&\f(CW\*(C`ev_now_update\*(C'\fR and \f(CW\*(C`ev_now\*(C'\fR.
300.IP "ev_sleep (ev_tstamp interval)" 4 300.IP "ev_sleep (ev_tstamp interval)" 4
301.IX Item "ev_sleep (ev_tstamp interval)" 301.IX Item "ev_sleep (ev_tstamp interval)"
302Sleep for the given interval: The current thread will be blocked until 302Sleep for the given interval: The current thread will be blocked
303either it is interrupted or the given time interval has passed. Basically 303until either it is interrupted or the given time interval has
304passed (approximately \- it might return a bit earlier even if not
305interrupted). Returns immediately if \f(CW\*(C`interval <= 0\*(C'\fR.
306.Sp
304this is a sub-second-resolution \f(CW\*(C`sleep ()\*(C'\fR. 307Basically this is a sub-second-resolution \f(CW\*(C`sleep ()\*(C'\fR.
308.Sp
309The range of the \f(CW\*(C`interval\*(C'\fR is limited \- libev only guarantees to work
310with sleep times of up to one day (\f(CW\*(C`interval <= 86400\*(C'\fR).
305.IP "int ev_version_major ()" 4 311.IP "int ev_version_major ()" 4
306.IX Item "int ev_version_major ()" 312.IX Item "int ev_version_major ()"
307.PD 0 313.PD 0
308.IP "int ev_version_minor ()" 4 314.IP "int ev_version_minor ()" 4
309.IX Item "int ev_version_minor ()" 315.IX Item "int ev_version_minor ()"
553example) that can't properly initialise their signal masks. 559example) that can't properly initialise their signal masks.
554.ie n .IP """EVFLAG_NOSIGMASK""" 4 560.ie n .IP """EVFLAG_NOSIGMASK""" 4
555.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4 561.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4
556.IX Item "EVFLAG_NOSIGMASK" 562.IX Item "EVFLAG_NOSIGMASK"
557When this flag is specified, then libev will avoid to modify the signal 563When this flag is specified, then libev will avoid to modify the signal
558mask. Specifically, this means you ahve to make sure signals are unblocked 564mask. Specifically, this means you have to make sure signals are unblocked
559when you want to receive them. 565when you want to receive them.
560.Sp 566.Sp
561This behaviour is useful when you want to do your own signal handling, or 567This behaviour is useful when you want to do your own signal handling, or
562want to handle signals only in specific threads and want to avoid libev 568want to handle signals only in specific threads and want to avoid libev
563unblocking the signals. 569unblocking the signals.
601.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 607.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
602.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 608.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
603Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 609Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
604kernels). 610kernels).
605.Sp 611.Sp
606For few fds, this backend is a bit little slower than poll and select, 612For few fds, this backend is a bit little slower than poll and select, but
607but it scales phenomenally better. While poll and select usually scale 613it scales phenomenally better. While poll and select usually scale like
608like O(total_fds) where n is the total number of fds (or the highest fd), 614O(total_fds) where total_fds is the total number of fds (or the highest
609epoll scales either O(1) or O(active_fds). 615fd), epoll scales either O(1) or O(active_fds).
610.Sp 616.Sp
611The epoll mechanism deserves honorable mention as the most misdesigned 617The epoll mechanism deserves honorable mention as the most misdesigned
612of the more advanced event mechanisms: mere annoyances include silently 618of the more advanced event mechanisms: mere annoyances include silently
613dropping file descriptors, requiring a system call per change per file 619dropping file descriptors, requiring a system call per change per file
614descriptor (and unnecessary guessing of parameters), problems with dup, 620descriptor (and unnecessary guessing of parameters), problems with dup,
6170.1ms) and so on. The biggest issue is fork races, however \- if a program 6230.1ms) and so on. The biggest issue is fork races, however \- if a program
618forks then \fIboth\fR parent and child process have to recreate the epoll 624forks then \fIboth\fR parent and child process have to recreate the epoll
619set, which can take considerable time (one syscall per file descriptor) 625set, which can take considerable time (one syscall per file descriptor)
620and is of course hard to detect. 626and is of course hard to detect.
621.Sp 627.Sp
622Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but 628Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work,
623of course \fIdoesn't\fR, and epoll just loves to report events for totally 629but of course \fIdoesn't\fR, and epoll just loves to report events for
624\&\fIdifferent\fR file descriptors (even already closed ones, so one cannot 630totally \fIdifferent\fR file descriptors (even already closed ones, so
625even remove them from the set) than registered in the set (especially 631one cannot even remove them from the set) than registered in the set
626on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by 632(especially on \s-1SMP\s0 systems). Libev tries to counter these spurious
627employing an additional generation counter and comparing that against the 633notifications by employing an additional generation counter and comparing
628events to filter out spurious ones, recreating the set when required. Last 634that against the events to filter out spurious ones, recreating the set
635when required. Epoll also erroneously rounds down timeouts, but gives you
636no way to know when and by how much, so sometimes you have to busy-wait
637because epoll returns immediately despite a nonzero timeout. And last
629not least, it also refuses to work with some file descriptors which work 638not least, it also refuses to work with some file descriptors which work
630perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...). 639perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...).
631.Sp 640.Sp
632Epoll is truly the train wreck analog among event poll mechanisms, 641Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
633a frankenpoll, cobbled together in a hurry, no thought to design or 642cobbled together in a hurry, no thought to design or interaction with
634interaction with others. 643others. Oh, the pain, will it ever stop...
635.Sp 644.Sp
636While stopping, setting and starting an I/O watcher in the same iteration 645While stopping, setting and starting an I/O watcher in the same iteration
637will result in some caching, there is still a system call per such 646will result in some caching, there is still a system call per such
638incident (because the same \fIfile descriptor\fR could point to a different 647incident (because the same \fIfile descriptor\fR could point to a different
639\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed 648\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed
717among the OS-specific backends (I vastly prefer correctness over speed 726among the OS-specific backends (I vastly prefer correctness over speed
718hacks). 727hacks).
719.Sp 728.Sp
720On the negative side, the interface is \fIbizarre\fR \- so bizarre that 729On the negative side, the interface is \fIbizarre\fR \- so bizarre that
721even sun itself gets it wrong in their code examples: The event polling 730even sun itself gets it wrong in their code examples: The event polling
722function sometimes returning events to the caller even though an error 731function sometimes returns events to the caller even though an error
723occurred, but with no indication whether it has done so or not (yes, it's 732occurred, but with no indication whether it has done so or not (yes, it's
724even documented that way) \- deadly for edge-triggered interfaces where 733even documented that way) \- deadly for edge-triggered interfaces where you
725you absolutely have to know whether an event occurred or not because you 734absolutely have to know whether an event occurred or not because you have
726have to re-arm the watcher. 735to re-arm the watcher.
727.Sp 736.Sp
728Fortunately libev seems to be able to work around these idiocies. 737Fortunately libev seems to be able to work around these idiocies.
729.Sp 738.Sp
730This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 739This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
731\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 740\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
942This is useful if you are waiting for some external event in conjunction 951This is useful if you are waiting for some external event in conjunction
943with something not expressible using other libev watchers (i.e. "roll your 952with something not expressible using other libev watchers (i.e. "roll your
944own \f(CW\*(C`ev_run\*(C'\fR"). However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is 953own \f(CW\*(C`ev_run\*(C'\fR"). However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is
945usually a better approach for this kind of thing. 954usually a better approach for this kind of thing.
946.Sp 955.Sp
947Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does: 956Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does (this is for your
957understanding, not a guarantee that things will work exactly like this in
958future versions):
948.Sp 959.Sp
949.Vb 10 960.Vb 10
950\& \- Increment loop depth. 961\& \- Increment loop depth.
951\& \- Reset the ev_break status. 962\& \- Reset the ev_break status.
952\& \- Before the first iteration, call any pending watchers. 963\& \- Before the first iteration, call any pending watchers.
1067overhead for the actual polling but can deliver many events at once. 1078overhead for the actual polling but can deliver many events at once.
1068.Sp 1079.Sp
1069By setting a higher \fIio collect interval\fR you allow libev to spend more 1080By setting a higher \fIio collect interval\fR you allow libev to spend more
1070time collecting I/O events, so you can handle more events per iteration, 1081time collecting I/O events, so you can handle more events per iteration,
1071at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and 1082at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and
1072\&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null value will 1083\&\f(CW\*(C`ev_timer\*(C'\fR) will not be affected. Setting this to a non-null value will
1073introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. The 1084introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. The
1074sleep time ensures that libev will not poll for I/O events more often then 1085sleep time ensures that libev will not poll for I/O events more often then
1075once per this interval, on average. 1086once per this interval, on average (as long as the host time resolution is
1087good enough).
1076.Sp 1088.Sp
1077Likewise, by setting a higher \fItimeout collect interval\fR you allow libev 1089Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
1078to spend more time collecting timeouts, at the expense of increased 1090to spend more time collecting timeouts, at the expense of increased
1079latency/jitter/inexactness (the watcher callback will be called 1091latency/jitter/inexactness (the watcher callback will be called
1080later). \f(CW\*(C`ev_io\*(C'\fR watchers will not be affected. Setting this to a non-null 1092later). \f(CW\*(C`ev_io\*(C'\fR watchers will not be affected. Setting this to a non-null
1132can be done relatively simply by putting mutex_lock/unlock calls around 1144can be done relatively simply by putting mutex_lock/unlock calls around
1133each call to a libev function. 1145each call to a libev function.
1134.Sp 1146.Sp
1135However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible 1147However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible
1136to wait for it to return. One way around this is to wake up the event 1148to wait for it to return. One way around this is to wake up the event
1137loop via \f(CW\*(C`ev_break\*(C'\fR and \f(CW\*(C`av_async_send\*(C'\fR, another way is to set these 1149loop via \f(CW\*(C`ev_break\*(C'\fR and \f(CW\*(C`ev_async_send\*(C'\fR, another way is to set these
1138\&\fIrelease\fR and \fIacquire\fR callbacks on the loop. 1150\&\fIrelease\fR and \fIacquire\fR callbacks on the loop.
1139.Sp 1151.Sp
1140When set, then \f(CW\*(C`release\*(C'\fR will be called just before the thread is 1152When set, then \f(CW\*(C`release\*(C'\fR will be called just before the thread is
1141suspended waiting for new events, and \f(CW\*(C`acquire\*(C'\fR is called just 1153suspended waiting for new events, and \f(CW\*(C`acquire\*(C'\fR is called just
1142afterwards. 1154afterwards.
1489active, pending and so on. In this section these states and the rules to 1501active, pending and so on. In this section these states and the rules to
1490transition between them will be described in more detail \- and while these 1502transition between them will be described in more detail \- and while these
1491rules might look complicated, they usually do \*(L"the right thing\*(R". 1503rules might look complicated, they usually do \*(L"the right thing\*(R".
1492.IP "initialiased" 4 1504.IP "initialiased" 4
1493.IX Item "initialiased" 1505.IX Item "initialiased"
1494Before a watcher can be registered with the event looop it has to be 1506Before a watcher can be registered with the event loop it has to be
1495initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to 1507initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to
1496\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. 1508\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1497.Sp 1509.Sp
1498In this state it is simply some block of memory that is suitable for 1510In this state it is simply some block of memory that is suitable for
1499use in an event loop. It can be moved around, freed, reused etc. at 1511use in an event loop. It can be moved around, freed, reused etc. at
1871detecting time jumps is hard, and some inaccuracies are unavoidable (the 1883detecting time jumps is hard, and some inaccuracies are unavoidable (the
1872monotonic clock option helps a lot here). 1884monotonic clock option helps a lot here).
1873.PP 1885.PP
1874The callback is guaranteed to be invoked only \fIafter\fR its timeout has 1886The callback is guaranteed to be invoked only \fIafter\fR its timeout has
1875passed (not \fIat\fR, so on systems with very low-resolution clocks this 1887passed (not \fIat\fR, so on systems with very low-resolution clocks this
1876might introduce a small delay). If multiple timers become ready during the 1888might introduce a small delay, see \*(L"the special problem of being too
1889early\*(R", below). If multiple timers become ready during the same loop
1877same loop iteration then the ones with earlier time-out values are invoked 1890iteration then the ones with earlier time-out values are invoked before
1878before ones of the same priority with later time-out values (but this is 1891ones of the same priority with later time-out values (but this is no
1879no longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively). 1892longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively).
1880.PP 1893.PP
1881\fIBe smart about timeouts\fR 1894\fIBe smart about timeouts\fR
1882.IX Subsection "Be smart about timeouts" 1895.IX Subsection "Be smart about timeouts"
1883.PP 1896.PP
1884Many real-world problems involve some kind of timeout, usually for error 1897Many real-world problems involve some kind of timeout, usually for error
1966.Sp 1979.Sp
1967In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, 1980In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone,
1968but remember the time of last activity, and check for a real timeout only 1981but remember the time of last activity, and check for a real timeout only
1969within the callback: 1982within the callback:
1970.Sp 1983.Sp
1971.Vb 1 1984.Vb 3
1985\& ev_tstamp timeout = 60.;
1972\& ev_tstamp last_activity; // time of last activity 1986\& ev_tstamp last_activity; // time of last activity
1987\& ev_timer timer;
1973\& 1988\&
1974\& static void 1989\& static void
1975\& callback (EV_P_ ev_timer *w, int revents) 1990\& callback (EV_P_ ev_timer *w, int revents)
1976\& { 1991\& {
1977\& ev_tstamp now = ev_now (EV_A); 1992\& // calculate when the timeout would happen
1978\& ev_tstamp timeout = last_activity + 60.; 1993\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout;
1979\& 1994\&
1980\& // if last_activity + 60. is older than now, we did time out 1995\& // if negative, it means we the timeout already occured
1981\& if (timeout < now) 1996\& if (after < 0.)
1982\& { 1997\& {
1983\& // timeout occurred, take action 1998\& // timeout occurred, take action
1984\& } 1999\& }
1985\& else 2000\& else
1986\& { 2001\& {
1987\& // callback was invoked, but there was some activity, re\-arm 2002\& // callback was invoked, but there was some recent
1988\& // the watcher to fire in last_activity + 60, which is 2003\& // activity. simply restart the timer to time out
1989\& // guaranteed to be in the future, so "again" is positive: 2004\& // after "after" seconds, which is the earliest time
1990\& w\->repeat = timeout \- now; 2005\& // the timeout can occur.
2006\& ev_timer_set (w, after, 0.);
1991\& ev_timer_again (EV_A_ w); 2007\& ev_timer_start (EV_A_ w);
1992\& } 2008\& }
1993\& } 2009\& }
1994.Ve 2010.Ve
1995.Sp 2011.Sp
1996To summarise the callback: first calculate the real timeout (defined 2012To summarise the callback: first calculate in how many seconds the
1997as \*(L"60 seconds after the last activity\*(R"), then check if that time has 2013timeout will occur (by calculating the absolute time when it would occur,
1998been reached, which means something \fIdid\fR, in fact, time out. Otherwise 2014\&\f(CW\*(C`last_activity + timeout\*(C'\fR, and subtracting the current time, \f(CW\*(C`ev_now
1999the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so 2015(EV_A)\*(C'\fR from that).
2000re-schedule the timer to fire at that future time, to see if maybe we have
2001a timeout then.
2002.Sp 2016.Sp
2003Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the 2017If this value is negative, then we are already past the timeout, i.e. we
2004\&\f(CW\*(C`ev_timer_again\*(C'\fR optimisation when the timer is already running. 2018timed out, and need to do whatever is needed in this case.
2019.Sp
2020Otherwise, we now the earliest time at which the timeout would trigger,
2021and simply start the timer with this timeout value.
2022.Sp
2023In other words, each time the callback is invoked it will check whether
2024the timeout cocured. If not, it will simply reschedule itself to check
2025again at the earliest time it could time out. Rinse. Repeat.
2005.Sp 2026.Sp
2006This scheme causes more callback invocations (about one every 60 seconds 2027This scheme causes more callback invocations (about one every 60 seconds
2007minus half the average time between activity), but virtually no calls to 2028minus half the average time between activity), but virtually no calls to
2008libev to change the timeout. 2029libev to change the timeout.
2009.Sp 2030.Sp
2010To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR 2031To start the machinery, simply initialise the watcher and set
2011to the current time (meaning we just have some activity :), then call the 2032\&\f(CW\*(C`last_activity\*(C'\fR to the current time (meaning there was some activity just
2012callback, which will \*(L"do the right thing\*(R" and start the timer: 2033now), then call the callback, which will \*(L"do the right thing\*(R" and start
2034the timer:
2013.Sp 2035.Sp
2014.Vb 3 2036.Vb 3
2037\& last_activity = ev_now (EV_A);
2015\& ev_init (timer, callback); 2038\& ev_init (&timer, callback);
2016\& last_activity = ev_now (loop); 2039\& callback (EV_A_ &timer, 0);
2017\& callback (loop, timer, EV_TIMER);
2018.Ve 2040.Ve
2019.Sp 2041.Sp
2020And when there is some activity, simply store the current time in 2042When there is some activity, simply store the current time in
2021\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all: 2043\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all:
2022.Sp 2044.Sp
2023.Vb 1 2045.Vb 2
2046\& if (activity detected)
2024\& last_activity = ev_now (loop); 2047\& last_activity = ev_now (EV_A);
2048.Ve
2049.Sp
2050When your timeout value changes, then the timeout can be changed by simply
2051providing a new value, stopping the timer and calling the callback, which
2052will agaion do the right thing (for example, time out immediately :).
2053.Sp
2054.Vb 3
2055\& timeout = new_value;
2056\& ev_timer_stop (EV_A_ &timer);
2057\& callback (EV_A_ &timer, 0);
2025.Ve 2058.Ve
2026.Sp 2059.Sp
2027This technique is slightly more complex, but in most cases where the 2060This technique is slightly more complex, but in most cases where the
2028time-out is unlikely to be triggered, much more efficient. 2061time-out is unlikely to be triggered, much more efficient.
2029.Sp
2030Changing the timeout is trivial as well (if it isn't hard-coded in the
2031callback :) \- just change the timeout and invoke the callback, which will
2032fix things for you.
2033.IP "4. Wee, just use a double-linked list for your timeouts." 4 2062.IP "4. Wee, just use a double-linked list for your timeouts." 4
2034.IX Item "4. Wee, just use a double-linked list for your timeouts." 2063.IX Item "4. Wee, just use a double-linked list for your timeouts."
2035If there is not one request, but many thousands (millions...), all 2064If there is not one request, but many thousands (millions...), all
2036employing some kind of timeout with the same timeout value, then one can 2065employing some kind of timeout with the same timeout value, then one can
2037do even better: 2066do even better:
2061Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 2090Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
2062rather complicated, but extremely efficient, something that really pays 2091rather complicated, but extremely efficient, something that really pays
2063off after the first million or so of active timers, i.e. it's usually 2092off after the first million or so of active timers, i.e. it's usually
2064overkill :) 2093overkill :)
2065.PP 2094.PP
2095\fIThe special problem of being too early\fR
2096.IX Subsection "The special problem of being too early"
2097.PP
2098If you ask a timer to call your callback after three seconds, then
2099you expect it to be invoked after three seconds \- but of course, this
2100cannot be guaranteed to infinite precision. Less obviously, it cannot be
2101guaranteed to any precision by libev \- imagine somebody suspending the
2102process with a \s-1STOP\s0 signal for a few hours for example.
2103.PP
2104So, libev tries to invoke your callback as soon as possible \fIafter\fR the
2105delay has occurred, but cannot guarantee this.
2106.PP
2107A less obvious failure mode is calling your callback too early: many event
2108loops compare timestamps with a \*(L"elapsed delay >= requested delay\*(R", but
2109this can cause your callback to be invoked much earlier than you would
2110expect.
2111.PP
2112To see why, imagine a system with a clock that only offers full second
2113resolution (think windows if you can't come up with a broken enough \s-1OS\s0
2114yourself). If you schedule a one-second timer at the time 500.9, then the
2115event loop will schedule your timeout to elapse at a system time of 500
2116(500.9 truncated to the resolution) + 1, or 501.
2117.PP
2118If an event library looks at the timeout 0.1s later, it will see \*(L"501 >=
2119501\*(R" and invoke the callback 0.1s after it was started, even though a
2120one-second delay was requested \- this is being \*(L"too early\*(R", despite best
2121intentions.
2122.PP
2123This is the reason why libev will never invoke the callback if the elapsed
2124delay equals the requested delay, but only when the elapsed delay is
2125larger than the requested delay. In the example above, libev would only invoke
2126the callback at system time 502, or 1.1s after the timer was started.
2127.PP
2128So, while libev cannot guarantee that your callback will be invoked
2129exactly when requested, it \fIcan\fR and \fIdoes\fR guarantee that the requested
2130delay has actually elapsed, or in other words, it always errs on the \*(L"too
2131late\*(R" side of things.
2132.PP
2066\fIThe special problem of time updates\fR 2133\fIThe special problem of time updates\fR
2067.IX Subsection "The special problem of time updates" 2134.IX Subsection "The special problem of time updates"
2068.PP 2135.PP
2069Establishing the current time is a costly operation (it usually takes at 2136Establishing the current time is a costly operation (it usually takes
2070least two system calls): \s-1EV\s0 therefore updates its idea of the current 2137at least one system call): \s-1EV\s0 therefore updates its idea of the current
2071time only before and after \f(CW\*(C`ev_run\*(C'\fR collects new events, which causes a 2138time only before and after \f(CW\*(C`ev_run\*(C'\fR collects new events, which causes a
2072growing difference between \f(CW\*(C`ev_now ()\*(C'\fR and \f(CW\*(C`ev_time ()\*(C'\fR when handling 2139growing difference between \f(CW\*(C`ev_now ()\*(C'\fR and \f(CW\*(C`ev_time ()\*(C'\fR when handling
2073lots of events in one iteration. 2140lots of events in one iteration.
2074.PP 2141.PP
2075The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2142The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
2083.Ve 2150.Ve
2084.PP 2151.PP
2085If the event loop is suspended for a long time, you can also force an 2152If the event loop is suspended for a long time, you can also force an
2086update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update 2153update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2087()\*(C'\fR. 2154()\*(C'\fR.
2155.PP
2156\fIThe special problem of unsynchronised clocks\fR
2157.IX Subsection "The special problem of unsynchronised clocks"
2158.PP
2159Modern systems have a variety of clocks \- libev itself uses the normal
2160\&\*(L"wall clock\*(R" clock and, if available, the monotonic clock (to avoid time
2161jumps).
2162.PP
2163Neither of these clocks is synchronised with each other or any other clock
2164on the system, so \f(CW\*(C`ev_time ()\*(C'\fR might return a considerably different time
2165than \f(CW\*(C`gettimeofday ()\*(C'\fR or \f(CW\*(C`time ()\*(C'\fR. On a GNU/Linux system, for example,
2166a call to \f(CW\*(C`gettimeofday\*(C'\fR might return a second count that is one higher
2167than a directly following call to \f(CW\*(C`time\*(C'\fR.
2168.PP
2169The moral of this is to only compare libev-related timestamps with
2170\&\f(CW\*(C`ev_time ()\*(C'\fR and \f(CW\*(C`ev_now ()\*(C'\fR, at least if you want better precision than
2171a second or so.
2172.PP
2173One more problem arises due to this lack of synchronisation: if libev uses
2174the system monotonic clock and you compare timestamps from \f(CW\*(C`ev_time\*(C'\fR
2175or \f(CW\*(C`ev_now\*(C'\fR from when you started your timer and when your callback is
2176invoked, you will find that sometimes the callback is a bit \*(L"early\*(R".
2177.PP
2178This is because \f(CW\*(C`ev_timer\*(C'\fRs work in real time, not wall clock time, so
2179libev makes sure your callback is not invoked before the delay happened,
2180\&\fImeasured according to the real time\fR, not the system clock.
2181.PP
2182If your timeouts are based on a physical timescale (e.g. \*(L"time out this
2183connection after 100 seconds\*(R") then this shouldn't bother you as it is
2184exactly the right behaviour.
2185.PP
2186If you want to compare wall clock/system timestamps to your timers, then
2187you need to use \f(CW\*(C`ev_periodic\*(C'\fRs, as these are based on the wall clock
2188time, where your comparisons will always generate correct results.
2088.PP 2189.PP
2089\fIThe special problems of suspended animation\fR 2190\fIThe special problems of suspended animation\fR
2090.IX Subsection "The special problems of suspended animation" 2191.IX Subsection "The special problems of suspended animation"
2091.PP 2192.PP
2092When you leave the server world it is quite customary to hit machines that 2193When you leave the server world it is quite customary to hit machines that
2136trigger at exactly 10 second intervals. If, however, your program cannot 2237trigger at exactly 10 second intervals. If, however, your program cannot
2137keep up with the timer (because it takes longer than those 10 seconds to 2238keep up with the timer (because it takes longer than those 10 seconds to
2138do stuff) the timer will not fire more than once per event loop iteration. 2239do stuff) the timer will not fire more than once per event loop iteration.
2139.IP "ev_timer_again (loop, ev_timer *)" 4 2240.IP "ev_timer_again (loop, ev_timer *)" 4
2140.IX Item "ev_timer_again (loop, ev_timer *)" 2241.IX Item "ev_timer_again (loop, ev_timer *)"
2141This will act as if the timer timed out and restart it again if it is 2242This will act as if the timer timed out, and restarts it again if it is
2142repeating. The exact semantics are: 2243repeating. It basically works like calling \f(CW\*(C`ev_timer_stop\*(C'\fR, updating the
2244timeout to the \f(CW\*(C`repeat\*(C'\fR value and calling \f(CW\*(C`ev_timer_start\*(C'\fR.
2143.Sp 2245.Sp
2246The exact semantics are as in the following rules, all of which will be
2247applied to the watcher:
2248.RS 4
2144If the timer is pending, its pending status is cleared. 2249.IP "If the timer is pending, the pending status is always cleared." 4
2145.Sp 2250.IX Item "If the timer is pending, the pending status is always cleared."
2251.PD 0
2146If the timer is started but non-repeating, stop it (as if it timed out). 2252.IP "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." 4
2147.Sp 2253.IX Item "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)."
2148If the timer is repeating, either start it if necessary (with the 2254.ie n .IP "If the timer is repeating, make the ""repeat"" value the new timeout and start the timer, if necessary." 4
2149\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. 2255.el .IP "If the timer is repeating, make the \f(CWrepeat\fR value the new timeout and start the timer, if necessary." 4
2256.IX Item "If the timer is repeating, make the repeat value the new timeout and start the timer, if necessary."
2257.RE
2258.RS 4
2259.PD
2150.Sp 2260.Sp
2151This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a 2261This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a
2152usage example. 2262usage example.
2263.RE
2153.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 2264.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4
2154.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 2265.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)"
2155Returns the remaining time until a timer fires. If the timer is active, 2266Returns the remaining time until a timer fires. If the timer is active,
2156then this time is relative to the current event loop time, otherwise it's 2267then this time is relative to the current event loop time, otherwise it's
2157the timeout value currently configured. 2268the timeout value currently configured.
2277.Sp 2388.Sp
2278Another way to think about it (for the mathematically inclined) is that 2389Another way to think about it (for the mathematically inclined) is that
2279\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible 2390\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible
2280time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps. 2391time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps.
2281.Sp 2392.Sp
2282For numerical stability it is preferable that the \f(CW\*(C`offset\*(C'\fR value is near 2393The \f(CW\*(C`interval\*(C'\fR \fI\s-1MUST\s0\fR be positive, and for numerical stability, the
2283\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for 2394interval value should be higher than \f(CW\*(C`1/8192\*(C'\fR (which is around 100
2284this value, and in fact is often specified as zero. 2395microseconds) and \f(CW\*(C`offset\*(C'\fR should be higher than \f(CW0\fR and should have
2396at most a similar magnitude as the current time (say, within a factor of
2397ten). Typical values for offset are, in fact, \f(CW0\fR or something between
2398\&\f(CW0\fR and \f(CW\*(C`interval\*(C'\fR, which is also the recommended range.
2285.Sp 2399.Sp
2286Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0 2400Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0
2287speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability 2401speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability
2288will of course deteriorate. Libev itself tries to be exact to be about one 2402will of course deteriorate. Libev itself tries to be exact to be about one
2289millisecond (if the \s-1OS\s0 supports it and the machine is fast enough). 2403millisecond (if the \s-1OS\s0 supports it and the machine is fast enough).
3331\&\f(CW\*(C`ev_async_sent\*(C'\fR calls). In fact, you could use signal watchers as a kind 3445\&\f(CW\*(C`ev_async_sent\*(C'\fR calls). In fact, you could use signal watchers as a kind
3332of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused 3446of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused
3333signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread, 3447signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread,
3334even without knowing which loop owns the signal. 3448even without knowing which loop owns the signal.
3335.PP 3449.PP
3336Unlike \f(CW\*(C`ev_signal\*(C'\fR watchers, \f(CW\*(C`ev_async\*(C'\fR works with any event loop, not
3337just the default loop.
3338.PP
3339\fIQueueing\fR 3450\fIQueueing\fR
3340.IX Subsection "Queueing" 3451.IX Subsection "Queueing"
3341.PP 3452.PP
3342\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason 3453\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason
3343is that the author does not know of a simple (or any) algorithm for a 3454is that the author does not know of a simple (or any) algorithm for a
3437Unlike \f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, 3548Unlike \f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads,
3438signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the 3549signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the
3439embedding section below on what exactly this means). 3550embedding section below on what exactly this means).
3440.Sp 3551.Sp
3441Note that, as with other watchers in libev, multiple events might get 3552Note that, as with other watchers in libev, multiple events might get
3442compressed into a single callback invocation (another way to look at this 3553compressed into a single callback invocation (another way to look at
3443is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered, set on \f(CW\*(C`ev_async_send\*(C'\fR, 3554this is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered: they are set on
3444reset when the event loop detects that). 3555\&\f(CW\*(C`ev_async_send\*(C'\fR, reset when the event loop detects that).
3445.Sp 3556.Sp
3446This call incurs the overhead of a system call only once per event loop 3557This call incurs the overhead of at most one extra system call per event
3447iteration, so while the overhead might be noticeable, it doesn't apply to 3558loop iteration, if the event loop is blocked, and no syscall at all if
3448repeated calls to \f(CW\*(C`ev_async_send\*(C'\fR for the same event loop. 3559the event loop (or your program) is processing events. That means that
3560repeated calls are basically free (there is no need to avoid calls for
3561performance reasons) and that the overhead becomes smaller (typically
3562zero) under load.
3449.IP "bool = ev_async_pending (ev_async *)" 4 3563.IP "bool = ev_async_pending (ev_async *)" 4
3450.IX Item "bool = ev_async_pending (ev_async *)" 3564.IX Item "bool = ev_async_pending (ev_async *)"
3451Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the 3565Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the
3452watcher but the event has not yet been processed (or even noted) by the 3566watcher but the event has not yet been processed (or even noted) by the
3453event loop. 3567event loop.
3501\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3615\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3502.Ve 3616.Ve
3503.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 3617.IP "ev_feed_fd_event (loop, int fd, int revents)" 4
3504.IX Item "ev_feed_fd_event (loop, int fd, int revents)" 3618.IX Item "ev_feed_fd_event (loop, int fd, int revents)"
3505Feed an event on the given fd, as if a file descriptor backend detected 3619Feed an event on the given fd, as if a file descriptor backend detected
3506the given events it. 3620the given events.
3507.IP "ev_feed_signal_event (loop, int signum)" 4 3621.IP "ev_feed_signal_event (loop, int signum)" 4
3508.IX Item "ev_feed_signal_event (loop, int signum)" 3622.IX Item "ev_feed_signal_event (loop, int signum)"
3509Feed an event as if the given signal occurred. See also \f(CW\*(C`ev_feed_signal\*(C'\fR, 3623Feed an event as if the given signal occurred. See also \f(CW\*(C`ev_feed_signal\*(C'\fR,
3510which is async-safe. 3624which is async-safe.
3511.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3625.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
3585\& { 3699\& {
3586\& struct my_biggy big = (struct my_biggy *) 3700\& struct my_biggy big = (struct my_biggy *)
3587\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3701\& (((char *)w) \- offsetof (struct my_biggy, t2));
3588\& } 3702\& }
3589.Ve 3703.Ve
3704.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0"
3705.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3706Often you have structures like this in event-based programs:
3707.PP
3708.Vb 4
3709\& callback ()
3710\& {
3711\& free (request);
3712\& }
3713\&
3714\& request = start_new_request (..., callback);
3715.Ve
3716.PP
3717The intent is to start some \*(L"lengthy\*(R" operation. The \f(CW\*(C`request\*(C'\fR could be
3718used to cancel the operation, or do other things with it.
3719.PP
3720It's not uncommon to have code paths in \f(CW\*(C`start_new_request\*(C'\fR that
3721immediately invoke the callback, for example, to report errors. Or you add
3722some caching layer that finds that it can skip the lengthy aspects of the
3723operation and simply invoke the callback with the result.
3724.PP
3725The problem here is that this will happen \fIbefore\fR \f(CW\*(C`start_new_request\*(C'\fR
3726has returned, so \f(CW\*(C`request\*(C'\fR is not set.
3727.PP
3728Even if you pass the request by some safer means to the callback, you
3729might want to do something to the request after starting it, such as
3730canceling it, which probably isn't working so well when the callback has
3731already been invoked.
3732.PP
3733A common way around all these issues is to make sure that
3734\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If
3735\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
3736delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher
3737for example, or more sneakily, by reusing an existing (stopped) watcher
3738and pushing it into the pending queue:
3739.PP
3740.Vb 2
3741\& ev_set_cb (watcher, callback);
3742\& ev_feed_event (EV_A_ watcher, 0);
3743.Ve
3744.PP
3745This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3746invoked, while not delaying callback invocation too much.
3590.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0" 3747.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0"
3591.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" 3748.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3592Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3749Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3593\&\fImodal\fR interaction, which is most easily implemented by recursively 3750\&\fImodal\fR interaction, which is most easily implemented by recursively
3594invoking \f(CW\*(C`ev_run\*(C'\fR. 3751invoking \f(CW\*(C`ev_run\*(C'\fR.
3608\& int exit_main_loop = 0; 3765\& int exit_main_loop = 0;
3609\& 3766\&
3610\& while (!exit_main_loop) 3767\& while (!exit_main_loop)
3611\& ev_run (EV_DEFAULT_ EVRUN_ONCE); 3768\& ev_run (EV_DEFAULT_ EVRUN_ONCE);
3612\& 3769\&
3613\& // in a model watcher 3770\& // in a modal watcher
3614\& int exit_nested_loop = 0; 3771\& int exit_nested_loop = 0;
3615\& 3772\&
3616\& while (!exit_nested_loop) 3773\& while (!exit_nested_loop)
3617\& ev_run (EV_A_ EVRUN_ONCE); 3774\& ev_run (EV_A_ EVRUN_ONCE);
3618.Ve 3775.Ve
3817\& } 3974\& }
3818.Ve 3975.Ve
3819.PP 3976.PP
3820That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and 3977That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and
3821continues the libev coroutine, which, when appropriate, switches back to 3978continues the libev coroutine, which, when appropriate, switches back to
3822this or any other coroutine. I am sure if you sue this your own :) 3979this or any other coroutine.
3823.PP 3980.PP
3824You can do similar tricks if you have, say, threads with an event queue \- 3981You can do similar tricks if you have, say, threads with an event queue \-
3825instead of storing a coroutine, you store the queue object and instead of 3982instead of storing a coroutine, you store the queue object and instead of
3826switching to a coroutine, you push the watcher onto the queue and notify 3983switching to a coroutine, you push the watcher onto the queue and notify
3827any waiters. 3984any waiters.
3915.el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4 4072.el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4
3916.IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc." 4073.IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc."
3917For each \f(CW\*(C`ev_TYPE\*(C'\fR watcher in \fIev.h\fR there is a corresponding class of 4074For each \f(CW\*(C`ev_TYPE\*(C'\fR watcher in \fIev.h\fR there is a corresponding class of
3918the same name in the \f(CW\*(C`ev\*(C'\fR namespace, with the exception of \f(CW\*(C`ev_signal\*(C'\fR 4075the same name in the \f(CW\*(C`ev\*(C'\fR namespace, with the exception of \f(CW\*(C`ev_signal\*(C'\fR
3919which is called \f(CW\*(C`ev::sig\*(C'\fR to avoid clashes with the \f(CW\*(C`signal\*(C'\fR macro 4076which is called \f(CW\*(C`ev::sig\*(C'\fR to avoid clashes with the \f(CW\*(C`signal\*(C'\fR macro
3920defines by many implementations. 4077defined by many implementations.
3921.Sp 4078.Sp
3922All of those classes have these methods: 4079All of those classes have these methods:
3923.RS 4 4080.RS 4
3924.IP "ev::TYPE::TYPE ()" 4 4081.IP "ev::TYPE::TYPE ()" 4
3925.IX Item "ev::TYPE::TYPE ()" 4082.IX Item "ev::TYPE::TYPE ()"
4056.PP 4213.PP
4057.Vb 5 4214.Vb 5
4058\& class myclass 4215\& class myclass
4059\& { 4216\& {
4060\& ev::io io ; void io_cb (ev::io &w, int revents); 4217\& ev::io io ; void io_cb (ev::io &w, int revents);
4061\& ev::io2 io2 ; void io2_cb (ev::io &w, int revents); 4218\& ev::io io2 ; void io2_cb (ev::io &w, int revents);
4062\& ev::idle idle; void idle_cb (ev::idle &w, int revents); 4219\& ev::idle idle; void idle_cb (ev::idle &w, int revents);
4063\& 4220\&
4064\& myclass (int fd) 4221\& myclass (int fd)
4065\& { 4222\& {
4066\& io .set <myclass, &myclass::io_cb > (this); 4223\& io .set <myclass, &myclass::io_cb > (this);
4105Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR 4262Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4106makes rev work even on mingw. 4263makes rev work even on mingw.
4107.IP "Haskell" 4 4264.IP "Haskell" 4
4108.IX Item "Haskell" 4265.IX Item "Haskell"
4109A haskell binding to libev is available at 4266A haskell binding to libev is available at
4110<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>. 4267http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
4111.IP "D" 4 4268.IP "D" 4
4112.IX Item "D" 4269.IX Item "D"
4113Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4270Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4114be found at <http://proj.llucax.com.ar/wiki/evd>. 4271be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4115.IP "Ocaml" 4 4272.IP "Ocaml" 4
4116.IX Item "Ocaml" 4273.IX Item "Ocaml"
4117Erkki Seppala has written Ocaml bindings for libev, to be found at 4274Erkki Seppala has written Ocaml bindings for libev, to be found at
4118<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. 4275http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
4119.IP "Lua" 4 4276.IP "Lua" 4
4120.IX Item "Lua" 4277.IX Item "Lua"
4121Brian Maher has written a partial interface to libev for lua (at the 4278Brian Maher has written a partial interface to libev for lua (at the
4122time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4279time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4123<http://github.com/brimworks/lua\-ev>. 4280http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4124.SH "MACRO MAGIC" 4281.SH "MACRO MAGIC"
4125.IX Header "MACRO MAGIC" 4282.IX Header "MACRO MAGIC"
4126Libev can be compiled with a variety of options, the most fundamental 4283Libev can be compiled with a variety of options, the most fundamental
4127of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 4284of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
4128functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 4285functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
4163suitable for use with \f(CW\*(C`EV_A\*(C'\fR. 4320suitable for use with \f(CW\*(C`EV_A\*(C'\fR.
4164.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4 4321.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4
4165.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 4322.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
4166.IX Item "EV_DEFAULT, EV_DEFAULT_" 4323.IX Item "EV_DEFAULT, EV_DEFAULT_"
4167Similar to the other two macros, this gives you the value of the default 4324Similar to the other two macros, this gives you the value of the default
4168loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 4325loop, if multiple loops are supported (\*(L"ev loop default\*(R"). The default loop
4326will be initialised if it isn't already initialised.
4327.Sp
4328For non-multiplicity builds, these macros do nothing, so you always have
4329to initialise the loop somewhere.
4169.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4 4330.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4
4170.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4 4331.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4
4171.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_" 4332.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_"
4172Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the 4333Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the
4173default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour 4334default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour
4328supported). It will also not define any of the structs usually found in 4489supported). It will also not define any of the structs usually found in
4329\&\fIevent.h\fR that are not directly supported by the libev core alone. 4490\&\fIevent.h\fR that are not directly supported by the libev core alone.
4330.Sp 4491.Sp
4331In standalone mode, libev will still try to automatically deduce the 4492In standalone mode, libev will still try to automatically deduce the
4332configuration, but has to be more conservative. 4493configuration, but has to be more conservative.
4494.IP "\s-1EV_USE_FLOOR\s0" 4
4495.IX Item "EV_USE_FLOOR"
4496If defined to be \f(CW1\fR, libev will use the \f(CW\*(C`floor ()\*(C'\fR function for its
4497periodic reschedule calculations, otherwise libev will fall back on a
4498portable (slower) implementation. If you enable this, you usually have to
4499link against libm or something equivalent. Enabling this when the \f(CW\*(C`floor\*(C'\fR
4500function is not available will fail, so the safe default is to not enable
4501this.
4333.IP "\s-1EV_USE_MONOTONIC\s0" 4 4502.IP "\s-1EV_USE_MONOTONIC\s0" 4
4334.IX Item "EV_USE_MONOTONIC" 4503.IX Item "EV_USE_MONOTONIC"
4335If defined to be \f(CW1\fR, libev will try to detect the availability of the 4504If defined to be \f(CW1\fR, libev will try to detect the availability of the
4336monotonic clock option at both compile time and runtime. Otherwise no 4505monotonic clock option at both compile time and runtime. Otherwise no
4337use of the monotonic clock option will be attempted. If you enable this, 4506use of the monotonic clock option will be attempted. If you enable this,
4449.IX Item "EV_USE_INOTIFY" 4618.IX Item "EV_USE_INOTIFY"
4450If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify 4619If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify
4451interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will 4620interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
4452be detected at runtime. If undefined, it will be enabled if the headers 4621be detected at runtime. If undefined, it will be enabled if the headers
4453indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4622indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4623.IP "\s-1EV_NO_SMP\s0" 4
4624.IX Item "EV_NO_SMP"
4625If defined to be \f(CW1\fR, libev will assume that memory is always coherent
4626between threads, that is, threads can be used, but threads never run on
4627different cpus (or different cpu cores). This reduces dependencies
4628and makes libev faster.
4629.IP "\s-1EV_NO_THREADS\s0" 4
4630.IX Item "EV_NO_THREADS"
4631If defined to be \f(CW1\fR, libev will assume that it will never be called
4632from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR,
4633above. This reduces dependencies and makes libev faster.
4454.IP "\s-1EV_ATOMIC_T\s0" 4 4634.IP "\s-1EV_ATOMIC_T\s0" 4
4455.IX Item "EV_ATOMIC_T" 4635.IX Item "EV_ATOMIC_T"
4456Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4636Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4457access is atomic with respect to other threads or signal contexts. No such 4637access is atomic and serialised with respect to other threads or signal
4458type is easily found in the C language, so you can provide your own type 4638contexts. No such type is easily found in the C language, so you can
4459that you know is safe for your purposes. It is used both for signal handler \*(L"locking\*(R" 4639provide your own type that you know is safe for your purposes. It is used
4460as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR watchers. 4640both for signal handler \*(L"locking\*(R" as well as for signal and thread safety
4641in \f(CW\*(C`ev_async\*(C'\fR watchers.
4461.Sp 4642.Sp
4462In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4643In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4463(from \fIsignal.h\fR), which is usually good enough on most platforms. 4644(from \fIsignal.h\fR), which is usually good enough on most platforms,
4645although strictly speaking using a type that also implies a memory fence
4646is required.
4464.IP "\s-1EV_H\s0 (h)" 4 4647.IP "\s-1EV_H\s0 (h)" 4
4465.IX Item "EV_H (h)" 4648.IX Item "EV_H (h)"
4466The name of the \fIev.h\fR header file used to include it. The default if 4649The name of the \fIev.h\fR header file used to include it. The default if
4467undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4650undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4468used to virtually rename the \fIev.h\fR header file in case of conflicts. 4651used to virtually rename the \fIev.h\fR header file in case of conflicts.
4486If undefined or defined to \f(CW1\fR, then all event-loop-specific functions 4669If undefined or defined to \f(CW1\fR, then all event-loop-specific functions
4487will have the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument, and you can create 4670will have the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument, and you can create
4488additional independent event loops. Otherwise there will be no support 4671additional independent event loops. Otherwise there will be no support
4489for multiple event loops and there is no first event loop pointer 4672for multiple event loops and there is no first event loop pointer
4490argument. Instead, all functions act on the single default loop. 4673argument. Instead, all functions act on the single default loop.
4674.Sp
4675Note that \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR will no longer provide a
4676default loop when multiplicity is switched off \- you always have to
4677initialise the loop manually in this case.
4491.IP "\s-1EV_MINPRI\s0" 4 4678.IP "\s-1EV_MINPRI\s0" 4
4492.IX Item "EV_MINPRI" 4679.IX Item "EV_MINPRI"
4493.PD 0 4680.PD 0
4494.IP "\s-1EV_MAXPRI\s0" 4 4681.IP "\s-1EV_MAXPRI\s0" 4
4495.IX Item "EV_MAXPRI" 4682.IX Item "EV_MAXPRI"
4592With an intelligent-enough linker (gcc+binutils are intelligent enough 4779With an intelligent-enough linker (gcc+binutils are intelligent enough
4593when you use \f(CW\*(C`\-Wl,\-\-gc\-sections \-ffunction\-sections\*(C'\fR) functions unused by 4780when you use \f(CW\*(C`\-Wl,\-\-gc\-sections \-ffunction\-sections\*(C'\fR) functions unused by
4594your program might be left out as well \- a binary starting a timer and an 4781your program might be left out as well \- a binary starting a timer and an
4595I/O watcher then might come out at only 5Kb. 4782I/O watcher then might come out at only 5Kb.
4596.RE 4783.RE
4784.IP "\s-1EV_API_STATIC\s0" 4
4785.IX Item "EV_API_STATIC"
4786If this symbol is defined (by default it is not), then all identifiers
4787will have static linkage. This means that libev will not export any
4788identifiers, and you cannot link against libev anymore. This can be useful
4789when you embed libev, only want to use libev functions in a single file,
4790and do not want its identifiers to be visible.
4791.Sp
4792To use this, define \f(CW\*(C`EV_API_STATIC\*(C'\fR and include \fIev.c\fR in the file that
4793wants to use libev.
4794.Sp
4795This option only works when libev is compiled with a C compiler, as \*(C+
4796doesn't support the required declaration syntax.
4597.IP "\s-1EV_AVOID_STDIO\s0" 4 4797.IP "\s-1EV_AVOID_STDIO\s0" 4
4598.IX Item "EV_AVOID_STDIO" 4798.IX Item "EV_AVOID_STDIO"
4599If this is set to \f(CW1\fR at compiletime, then libev will avoid using stdio 4799If this is set to \f(CW1\fR at compiletime, then libev will avoid using stdio
4600functions (printf, scanf, perror etc.). This will increase the code size 4800functions (printf, scanf, perror etc.). This will increase the code size
4601somewhat, but if your program doesn't otherwise depend on stdio and your 4801somewhat, but if your program doesn't otherwise depend on stdio and your
4978requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 5178requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
4979model. Libev still offers limited functionality on this platform in 5179model. Libev still offers limited functionality on this platform in
4980the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket 5180the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
4981descriptors. This only applies when using Win32 natively, not when using 5181descriptors. This only applies when using Win32 natively, not when using
4982e.g. cygwin. Actually, it only applies to the microsofts own compilers, 5182e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4983as every compielr comes with a slightly differently broken/incompatible 5183as every compiler comes with a slightly differently broken/incompatible
4984environment. 5184environment.
4985.PP 5185.PP
4986Lifting these limitations would basically require the full 5186Lifting these limitations would basically require the full
4987re-implementation of the I/O system. If you are into this kind of thing, 5187re-implementation of the I/O system. If you are into this kind of thing,
4988then note that glib does exactly that for you in a very portable way (note 5188then note that glib does exactly that for you in a very portable way (note
5124.IX Item "double must hold a time value in seconds with enough accuracy" 5324.IX Item "double must hold a time value in seconds with enough accuracy"
5125The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to 5325The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
5126have at least 51 bits of mantissa (and 9 bits of exponent), which is 5326have at least 51 bits of mantissa (and 9 bits of exponent), which is
5127good enough for at least into the year 4000 with millisecond accuracy 5327good enough for at least into the year 4000 with millisecond accuracy
5128(the design goal for libev). This requirement is overfulfilled by 5328(the design goal for libev). This requirement is overfulfilled by
5129implementations using \s-1IEEE\s0 754, which is basically all existing ones. With 5329implementations using \s-1IEEE\s0 754, which is basically all existing ones.
5330.Sp
5130\&\s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least 2200. 5331With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the
5332year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5333is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5334something like that, just kidding).
5131.PP 5335.PP
5132If you know of other additional requirements drop me a note. 5336If you know of other additional requirements drop me a note.
5133.SH "ALGORITHMIC COMPLEXITIES" 5337.SH "ALGORITHMIC COMPLEXITIES"
5134.IX Header "ALGORITHMIC COMPLEXITIES" 5338.IX Header "ALGORITHMIC COMPLEXITIES"
5135In this section the complexities of (many of) the algorithms used inside 5339In this section the complexities of (many of) the algorithms used inside
5189.IX Item "Processing ev_async_send: O(number_of_async_watchers)" 5393.IX Item "Processing ev_async_send: O(number_of_async_watchers)"
5190.IP "Processing signals: O(max_signal_number)" 4 5394.IP "Processing signals: O(max_signal_number)" 4
5191.IX Item "Processing signals: O(max_signal_number)" 5395.IX Item "Processing signals: O(max_signal_number)"
5192.PD 5396.PD
5193Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR 5397Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR
5194calls in the current loop iteration. Checking for async and signal events 5398calls in the current loop iteration and the loop is currently
5399blocked. Checking for async and signal events involves iterating over all
5195involves iterating over all running async watchers or all signal numbers. 5400running async watchers or all signal numbers.
5196.SH "PORTING FROM LIBEV 3.X TO 4.X" 5401.SH "PORTING FROM LIBEV 3.X TO 4.X"
5197.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5402.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5198The major version 4 introduced some incompatible changes to the \s-1API\s0. 5403The major version 4 introduced some incompatible changes to the \s-1API\s0.
5199.PP 5404.PP
5200At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5405At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines