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

Comparing libev/ev.3 (file contents):
Revision 1.85 by root, Tue Jan 11 13:45:28 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-01-11" "libev-4.03" "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"
… …
189\& ev_timer_start (loop, &timeout_watcher); 189\& ev_timer_start (loop, &timeout_watcher);
190\& 190\&
191\& // now wait for events to arrive 191\& // now wait for events to arrive
192\& ev_run (loop, 0); 192\& ev_run (loop, 0);
193\& 193\&
194\& // unloop was called, so exit 194\& // break was called, so exit
195\& return 0; 195\& return 0;
196\& } 196\& }
197.Ve 197.Ve
198.SH "ABOUT THIS DOCUMENT" 198.SH "ABOUT THIS DOCUMENT"
199.IX Header "ABOUT THIS DOCUMENT" 199.IX Header "ABOUT THIS DOCUMENT"
… …
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.
570.Sp
571It's also required by \s-1POSIX\s0 in a threaded program, as libev calls
572\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
564.Sp 573.Sp
565This flag's behaviour will become the default in future versions of libev. 574This flag's behaviour will become the default in future versions of libev.
566.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 575.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
567.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 576.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
568.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 577.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
… …
598.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 607.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
599.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 608.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
600Use 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
601kernels). 610kernels).
602.Sp 611.Sp
603For 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
604but it scales phenomenally better. While poll and select usually scale 613it scales phenomenally better. While poll and select usually scale like
605like 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
606epoll scales either O(1) or O(active_fds). 615fd), epoll scales either O(1) or O(active_fds).
607.Sp 616.Sp
608The epoll mechanism deserves honorable mention as the most misdesigned 617The epoll mechanism deserves honorable mention as the most misdesigned
609of the more advanced event mechanisms: mere annoyances include silently 618of the more advanced event mechanisms: mere annoyances include silently
610dropping file descriptors, requiring a system call per change per file 619dropping file descriptors, requiring a system call per change per file
611descriptor (and unnecessary guessing of parameters), problems with dup, 620descriptor (and unnecessary guessing of parameters), problems with dup,
… …
6140.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
615forks 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
616set, which can take considerable time (one syscall per file descriptor) 625set, which can take considerable time (one syscall per file descriptor)
617and is of course hard to detect. 626and is of course hard to detect.
618.Sp 627.Sp
619Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but 628Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work,
620of 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
621\&\fIdifferent\fR file descriptors (even already closed ones, so one cannot 630totally \fIdifferent\fR file descriptors (even already closed ones, so
622even remove them from the set) than registered in the set (especially 631one cannot even remove them from the set) than registered in the set
623on \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
624employing an additional generation counter and comparing that against the 633notifications by employing an additional generation counter and comparing
625events 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
626not 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
627perfectly 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...).
628.Sp 640.Sp
629Epoll is truly the train wreck analog among event poll mechanisms, 641Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
630a frankenpoll, cobbled together in a hurry, no thought to design or 642cobbled together in a hurry, no thought to design or interaction with
631interaction with others. 643others. Oh, the pain, will it ever stop...
632.Sp 644.Sp
633While 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
634will 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
635incident (because the same \fIfile descriptor\fR could point to a different 647incident (because the same \fIfile descriptor\fR could point to a different
636\&\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
… …
714among the OS-specific backends (I vastly prefer correctness over speed 726among the OS-specific backends (I vastly prefer correctness over speed
715hacks). 727hacks).
716.Sp 728.Sp
717On the negative side, the interface is \fIbizarre\fR \- so bizarre that 729On the negative side, the interface is \fIbizarre\fR \- so bizarre that
718even 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
719function sometimes returning events to the caller even though an error 731function sometimes returns events to the caller even though an error
720occurred, 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
721even documented that way) \- deadly for edge-triggered interfaces where 733even documented that way) \- deadly for edge-triggered interfaces where you
722you 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
723have to re-arm the watcher. 735to re-arm the watcher.
724.Sp 736.Sp
725Fortunately libev seems to be able to work around these idiocies. 737Fortunately libev seems to be able to work around these idiocies.
726.Sp 738.Sp
727This 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
728\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 740\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
… …
939This 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
940with something not expressible using other libev watchers (i.e. "roll your 952with something not expressible using other libev watchers (i.e. "roll your
941own \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
942usually a better approach for this kind of thing. 954usually a better approach for this kind of thing.
943.Sp 955.Sp
944Here 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):
945.Sp 959.Sp
946.Vb 10 960.Vb 10
947\& \- Increment loop depth. 961\& \- Increment loop depth.
948\& \- Reset the ev_break status. 962\& \- Reset the ev_break status.
949\& \- Before the first iteration, call any pending watchers. 963\& \- Before the first iteration, call any pending watchers.
… …
985.Sp 999.Sp
986.Vb 4 1000.Vb 4
987\& ... queue jobs here, make sure they register event watchers as long 1001\& ... queue jobs here, make sure they register event watchers as long
988\& ... as they still have work to do (even an idle watcher will do..) 1002\& ... as they still have work to do (even an idle watcher will do..)
989\& ev_run (my_loop, 0); 1003\& ev_run (my_loop, 0);
990\& ... jobs done or somebody called unloop. yeah! 1004\& ... jobs done or somebody called break. yeah!
991.Ve 1005.Ve
992.IP "ev_break (loop, how)" 4 1006.IP "ev_break (loop, how)" 4
993.IX Item "ev_break (loop, how)" 1007.IX Item "ev_break (loop, how)"
994Can be used to make a call to \f(CW\*(C`ev_run\*(C'\fR return early (but only after it 1008Can be used to make a call to \f(CW\*(C`ev_run\*(C'\fR return early (but only after it
995has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either 1009has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either
… …
1064overhead for the actual polling but can deliver many events at once. 1078overhead for the actual polling but can deliver many events at once.
1065.Sp 1079.Sp
1066By 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
1067time 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,
1068at 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
1069\&\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
1070introduce 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
1071sleep 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
1072once per this interval, on average. 1086once per this interval, on average (as long as the host time resolution is
1087good enough).
1073.Sp 1088.Sp
1074Likewise, by setting a higher \fItimeout collect interval\fR you allow libev 1089Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
1075to spend more time collecting timeouts, at the expense of increased 1090to spend more time collecting timeouts, at the expense of increased
1076latency/jitter/inexactness (the watcher callback will be called 1091latency/jitter/inexactness (the watcher callback will be called
1077later). \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
… …
1129can be done relatively simply by putting mutex_lock/unlock calls around 1144can be done relatively simply by putting mutex_lock/unlock calls around
1130each call to a libev function. 1145each call to a libev function.
1131.Sp 1146.Sp
1132However, \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
1133to 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
1134loop 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
1135\&\fIrelease\fR and \fIacquire\fR callbacks on the loop. 1150\&\fIrelease\fR and \fIacquire\fR callbacks on the loop.
1136.Sp 1151.Sp
1137When 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
1138suspended 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
1139afterwards. 1154afterwards.
… …
1486active, 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
1487transition between them will be described in more detail \- and while these 1502transition between them will be described in more detail \- and while these
1488rules might look complicated, they usually do \*(L"the right thing\*(R". 1503rules might look complicated, they usually do \*(L"the right thing\*(R".
1489.IP "initialiased" 4 1504.IP "initialiased" 4
1490.IX Item "initialiased" 1505.IX Item "initialiased"
1491Before 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
1492initialised. 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
1493\&\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.
1494.Sp 1509.Sp
1495In this state it is simply some block of memory that is suitable for use 1510In this state it is simply some block of memory that is suitable for
1496in an event loop. It can be moved around, freed, reused etc. at will. 1511use in an event loop. It can be moved around, freed, reused etc. at
1512will \- as long as you either keep the memory contents intact, or call
1513\&\f(CW\*(C`ev_TYPE_init\*(C'\fR again.
1497.IP "started/running/active" 4 1514.IP "started/running/active" 4
1498.IX Item "started/running/active" 1515.IX Item "started/running/active"
1499Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes 1516Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes
1500property of the event loop, and is actively waiting for events. While in 1517property of the event loop, and is actively waiting for events. While in
1501this state it cannot be accessed (except in a few documented ways), moved, 1518this state it cannot be accessed (except in a few documented ways), moved,
… …
1526latter will clear any pending state the watcher might be in, regardless 1543latter will clear any pending state the watcher might be in, regardless
1527of whether it was active or not, so stopping a watcher explicitly before 1544of whether it was active or not, so stopping a watcher explicitly before
1528freeing it is often a good idea. 1545freeing it is often a good idea.
1529.Sp 1546.Sp
1530While stopped (and not pending) the watcher is essentially in the 1547While stopped (and not pending) the watcher is essentially in the
1531initialised state, that is it can be reused, moved, modified in any way 1548initialised state, that is, it can be reused, moved, modified in any way
1532you wish. 1549you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR
1550it again).
1533.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" 1551.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0"
1534.IX Subsection "WATCHER PRIORITY MODELS" 1552.IX Subsection "WATCHER PRIORITY MODELS"
1535Many event loops support \fIwatcher priorities\fR, which are usually small 1553Many event loops support \fIwatcher priorities\fR, which are usually small
1536integers that influence the ordering of event callback invocation 1554integers that influence the ordering of event callback invocation
1537between watchers in some way, all else being equal. 1555between watchers in some way, all else being equal.
… …
1865detecting time jumps is hard, and some inaccuracies are unavoidable (the 1883detecting time jumps is hard, and some inaccuracies are unavoidable (the
1866monotonic clock option helps a lot here). 1884monotonic clock option helps a lot here).
1867.PP 1885.PP
1868The 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
1869passed (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
1870might 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
1871same loop iteration then the ones with earlier time-out values are invoked 1890iteration then the ones with earlier time-out values are invoked before
1872before 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
1873no 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).
1874.PP 1893.PP
1875\fIBe smart about timeouts\fR 1894\fIBe smart about timeouts\fR
1876.IX Subsection "Be smart about timeouts" 1895.IX Subsection "Be smart about timeouts"
1877.PP 1896.PP
1878Many real-world problems involve some kind of timeout, usually for error 1897Many real-world problems involve some kind of timeout, usually for error
… …
1960.Sp 1979.Sp
1961In 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,
1962but 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
1963within the callback: 1982within the callback:
1964.Sp 1983.Sp
1965.Vb 1 1984.Vb 3
1985\& ev_tstamp timeout = 60.;
1966\& ev_tstamp last_activity; // time of last activity 1986\& ev_tstamp last_activity; // time of last activity
1987\& ev_timer timer;
1967\& 1988\&
1968\& static void 1989\& static void
1969\& callback (EV_P_ ev_timer *w, int revents) 1990\& callback (EV_P_ ev_timer *w, int revents)
1970\& { 1991\& {
1971\& ev_tstamp now = ev_now (EV_A); 1992\& // calculate when the timeout would happen
1972\& ev_tstamp timeout = last_activity + 60.; 1993\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout;
1973\& 1994\&
1974\& // if last_activity + 60. is older than now, we did time out 1995\& // if negative, it means we the timeout already occured
1975\& if (timeout < now) 1996\& if (after < 0.)
1976\& { 1997\& {
1977\& // timeout occurred, take action 1998\& // timeout occurred, take action
1978\& } 1999\& }
1979\& else 2000\& else
1980\& { 2001\& {
1981\& // callback was invoked, but there was some activity, re\-arm 2002\& // callback was invoked, but there was some recent
1982\& // the watcher to fire in last_activity + 60, which is 2003\& // activity. simply restart the timer to time out
1983\& // guaranteed to be in the future, so "again" is positive: 2004\& // after "after" seconds, which is the earliest time
1984\& w\->repeat = timeout \- now; 2005\& // the timeout can occur.
2006\& ev_timer_set (w, after, 0.);
1985\& ev_timer_again (EV_A_ w); 2007\& ev_timer_start (EV_A_ w);
1986\& } 2008\& }
1987\& } 2009\& }
1988.Ve 2010.Ve
1989.Sp 2011.Sp
1990To summarise the callback: first calculate the real timeout (defined 2012To summarise the callback: first calculate in how many seconds the
1991as \*(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,
1992been 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
1993the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so 2015(EV_A)\*(C'\fR from that).
1994re-schedule the timer to fire at that future time, to see if maybe we have
1995a timeout then.
1996.Sp 2016.Sp
1997Note 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
1998\&\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.
1999.Sp 2026.Sp
2000This scheme causes more callback invocations (about one every 60 seconds 2027This scheme causes more callback invocations (about one every 60 seconds
2001minus half the average time between activity), but virtually no calls to 2028minus half the average time between activity), but virtually no calls to
2002libev to change the timeout. 2029libev to change the timeout.
2003.Sp 2030.Sp
2004To 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
2005to 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
2006callback, 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:
2007.Sp 2035.Sp
2008.Vb 3 2036.Vb 3
2037\& last_activity = ev_now (EV_A);
2009\& ev_init (timer, callback); 2038\& ev_init (&timer, callback);
2010\& last_activity = ev_now (loop); 2039\& callback (EV_A_ &timer, 0);
2011\& callback (loop, timer, EV_TIMER);
2012.Ve 2040.Ve
2013.Sp 2041.Sp
2014And when there is some activity, simply store the current time in 2042When there is some activity, simply store the current time in
2015\&\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:
2016.Sp 2044.Sp
2017.Vb 1 2045.Vb 2
2046\& if (activity detected)
2018\& 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);
2019.Ve 2058.Ve
2020.Sp 2059.Sp
2021This technique is slightly more complex, but in most cases where the 2060This technique is slightly more complex, but in most cases where the
2022time-out is unlikely to be triggered, much more efficient. 2061time-out is unlikely to be triggered, much more efficient.
2023.Sp
2024Changing the timeout is trivial as well (if it isn't hard-coded in the
2025callback :) \- just change the timeout and invoke the callback, which will
2026fix things for you.
2027.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
2028.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."
2029If there is not one request, but many thousands (millions...), all 2064If there is not one request, but many thousands (millions...), all
2030employing 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
2031do even better: 2066do even better:
… …
2055Method #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
2056rather complicated, but extremely efficient, something that really pays 2091rather complicated, but extremely efficient, something that really pays
2057off 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
2058overkill :) 2093overkill :)
2059.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
2060\fIThe special problem of time updates\fR 2133\fIThe special problem of time updates\fR
2061.IX Subsection "The special problem of time updates" 2134.IX Subsection "The special problem of time updates"
2062.PP 2135.PP
2063Establishing the current time is a costly operation (it usually takes at 2136Establishing the current time is a costly operation (it usually takes
2064least 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
2065time 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
2066growing 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
2067lots of events in one iteration. 2140lots of events in one iteration.
2068.PP 2141.PP
2069The 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
… …
2077.Ve 2150.Ve
2078.PP 2151.PP
2079If 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
2080update 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
2081()\*(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.
2082.PP 2189.PP
2083\fIThe special problems of suspended animation\fR 2190\fIThe special problems of suspended animation\fR
2084.IX Subsection "The special problems of suspended animation" 2191.IX Subsection "The special problems of suspended animation"
2085.PP 2192.PP
2086When 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
… …
2130trigger at exactly 10 second intervals. If, however, your program cannot 2237trigger at exactly 10 second intervals. If, however, your program cannot
2131keep 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
2132do 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.
2133.IP "ev_timer_again (loop, ev_timer *)" 4 2240.IP "ev_timer_again (loop, ev_timer *)" 4
2134.IX Item "ev_timer_again (loop, ev_timer *)" 2241.IX Item "ev_timer_again (loop, ev_timer *)"
2135This 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
2136repeating. 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.
2137.Sp 2245.Sp
2246The exact semantics are as in the following rules, all of which will be
2247applied to the watcher:
2248.RS 4
2138If the timer is pending, its pending status is cleared. 2249.IP "If the timer is pending, the pending status is always cleared." 4
2139.Sp 2250.IX Item "If the timer is pending, the pending status is always cleared."
2251.PD 0
2140If 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
2141.Sp 2253.IX Item "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)."
2142If 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
2143\&\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
2144.Sp 2260.Sp
2145This 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
2146usage example. 2262usage example.
2263.RE
2147.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 2264.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4
2148.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 2265.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)"
2149Returns 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,
2150then 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
2151the timeout value currently configured. 2268the timeout value currently configured.
… …
2271.Sp 2388.Sp
2272Another way to think about it (for the mathematically inclined) is that 2389Another way to think about it (for the mathematically inclined) is that
2273\&\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
2274time 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.
2275.Sp 2392.Sp
2276For 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
2277\&\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
2278this 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.
2279.Sp 2399.Sp
2280Note 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
2281speed 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
2282will 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
2283millisecond (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).
… …
2429.IX Subsection "The special problem of inheritance over fork/execve/pthread_create" 2549.IX Subsection "The special problem of inheritance over fork/execve/pthread_create"
2430.PP 2550.PP
2431Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition 2551Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition
2432(\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after 2552(\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after
2433stopping it again), that is, libev might or might not block the signal, 2553stopping it again), that is, libev might or might not block the signal,
2434and might or might not set or restore the installed signal handler. 2554and might or might not set or restore the installed signal handler (but
2555see \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR).
2435.PP 2556.PP
2436While this does not matter for the signal disposition (libev never 2557While this does not matter for the signal disposition (libev never
2437sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on 2558sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on
2438\&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect 2559\&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect
2439certain signals to be blocked. 2560certain signals to be blocked.
… …
3307\& atexit (program_exits); 3428\& atexit (program_exits);
3308.Ve 3429.Ve
3309.ie n .SS """ev_async"" \- how to wake up an event loop" 3430.ie n .SS """ev_async"" \- how to wake up an event loop"
3310.el .SS "\f(CWev_async\fP \- how to wake up an event loop" 3431.el .SS "\f(CWev_async\fP \- how to wake up an event loop"
3311.IX Subsection "ev_async - how to wake up an event loop" 3432.IX Subsection "ev_async - how to wake up an event loop"
3312In general, you cannot use an \f(CW\*(C`ev_run\*(C'\fR from multiple threads or other 3433In general, you cannot use an \f(CW\*(C`ev_loop\*(C'\fR from multiple threads or other
3313asynchronous sources such as signal handlers (as opposed to multiple event 3434asynchronous sources such as signal handlers (as opposed to multiple event
3314loops \- those are of course safe to use in different threads). 3435loops \- those are of course safe to use in different threads).
3315.PP 3436.PP
3316Sometimes, however, you need to wake up an event loop you do not control, 3437Sometimes, however, you need to wake up an event loop you do not control,
3317for example because it belongs to another thread. This is what \f(CW\*(C`ev_async\*(C'\fR 3438for example because it belongs to another thread. This is what \f(CW\*(C`ev_async\*(C'\fR
… …
3323(i.e. the number of callback invocations may be less than the number of 3444(i.e. the number of callback invocations may be less than the number of
3324\&\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
3325of \*(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
3326signal, 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,
3327even without knowing which loop owns the signal. 3448even without knowing which loop owns the signal.
3328.PP
3329Unlike \f(CW\*(C`ev_signal\*(C'\fR watchers, \f(CW\*(C`ev_async\*(C'\fR works with any event loop, not
3330just the default loop.
3331.PP 3449.PP
3332\fIQueueing\fR 3450\fIQueueing\fR
3333.IX Subsection "Queueing" 3451.IX Subsection "Queueing"
3334.PP 3452.PP
3335\&\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
… …
3422kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless, 3540kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless,
3423trust me. 3541trust me.
3424.IP "ev_async_send (loop, ev_async *)" 4 3542.IP "ev_async_send (loop, ev_async *)" 4
3425.IX Item "ev_async_send (loop, ev_async *)" 3543.IX Item "ev_async_send (loop, ev_async *)"
3426Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds 3544Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds
3427an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike 3545an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop, and instantly
3546returns.
3547.Sp
3428\&\f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, signal or 3548Unlike \f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads,
3429similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the embedding 3549signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the
3430section below on what exactly this means). 3550embedding section below on what exactly this means).
3431.Sp 3551.Sp
3432Note that, as with other watchers in libev, multiple events might get 3552Note that, as with other watchers in libev, multiple events might get
3433compressed into a single callback invocation (another way to look at this 3553compressed into a single callback invocation (another way to look at
3434is 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
3435reset when the event loop detects that). 3555\&\f(CW\*(C`ev_async_send\*(C'\fR, reset when the event loop detects that).
3436.Sp 3556.Sp
3437This 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
3438iteration, 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
3439repeated 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.
3440.IP "bool = ev_async_pending (ev_async *)" 4 3563.IP "bool = ev_async_pending (ev_async *)" 4
3441.IX Item "bool = ev_async_pending (ev_async *)" 3564.IX Item "bool = ev_async_pending (ev_async *)"
3442Returns 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
3443watcher 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
3444event loop. 3567event loop.
… …
3492\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3615\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3493.Ve 3616.Ve
3494.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 3617.IP "ev_feed_fd_event (loop, int fd, int revents)" 4
3495.IX Item "ev_feed_fd_event (loop, int fd, int revents)" 3618.IX Item "ev_feed_fd_event (loop, int fd, int revents)"
3496Feed 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
3497the given events it. 3620the given events.
3498.IP "ev_feed_signal_event (loop, int signum)" 4 3621.IP "ev_feed_signal_event (loop, int signum)" 4
3499.IX Item "ev_feed_signal_event (loop, int signum)" 3622.IX Item "ev_feed_signal_event (loop, int signum)"
3500Feed 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,
3501which is async-safe. 3624which is async-safe.
3502.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3625.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
… …
3576\& { 3699\& {
3577\& struct my_biggy big = (struct my_biggy *) 3700\& struct my_biggy big = (struct my_biggy *)
3578\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3701\& (((char *)w) \- offsetof (struct my_biggy, t2));
3579\& } 3702\& }
3580.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.
3581.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"
3582.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" 3748.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3583Often (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
3584\&\fImodal\fR interaction, which is most easily implemented by recursively 3750\&\fImodal\fR interaction, which is most easily implemented by recursively
3585invoking \f(CW\*(C`ev_run\*(C'\fR. 3751invoking \f(CW\*(C`ev_run\*(C'\fR.
… …
3599\& int exit_main_loop = 0; 3765\& int exit_main_loop = 0;
3600\& 3766\&
3601\& while (!exit_main_loop) 3767\& while (!exit_main_loop)
3602\& ev_run (EV_DEFAULT_ EVRUN_ONCE); 3768\& ev_run (EV_DEFAULT_ EVRUN_ONCE);
3603\& 3769\&
3604\& // in a model watcher 3770\& // in a modal watcher
3605\& int exit_nested_loop = 0; 3771\& int exit_nested_loop = 0;
3606\& 3772\&
3607\& while (!exit_nested_loop) 3773\& while (!exit_nested_loop)
3608\& ev_run (EV_A_ EVRUN_ONCE); 3774\& ev_run (EV_A_ EVRUN_ONCE);
3609.Ve 3775.Ve
… …
3658\& // now associate this with the loop 3824\& // now associate this with the loop
3659\& ev_set_userdata (EV_A_ u); 3825\& ev_set_userdata (EV_A_ u);
3660\& ev_set_invoke_pending_cb (EV_A_ l_invoke); 3826\& ev_set_invoke_pending_cb (EV_A_ l_invoke);
3661\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 3827\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3662\& 3828\&
3663\& // then create the thread running ev_loop 3829\& // then create the thread running ev_run
3664\& pthread_create (&u\->tid, 0, l_run, EV_A); 3830\& pthread_create (&u\->tid, 0, l_run, EV_A);
3665\& } 3831\& }
3666.Ve 3832.Ve
3667.PP 3833.PP
3668The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used 3834The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used
… …
3808\& } 3974\& }
3809.Ve 3975.Ve
3810.PP 3976.PP
3811That 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
3812continues the libev coroutine, which, when appropriate, switches back to 3978continues the libev coroutine, which, when appropriate, switches back to
3813this or any other coroutine. I am sure if you sue this your own :) 3979this or any other coroutine.
3814.PP 3980.PP
3815You 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 \-
3816instead 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
3817switching 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
3818any waiters. 3984any waiters.
… …
3906.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
3907.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."
3908For 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
3909the 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
3910which 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
3911defines by many implementations. 4077defined by many implementations.
3912.Sp 4078.Sp
3913All of those classes have these methods: 4079All of those classes have these methods:
3914.RS 4 4080.RS 4
3915.IP "ev::TYPE::TYPE ()" 4 4081.IP "ev::TYPE::TYPE ()" 4
3916.IX Item "ev::TYPE::TYPE ()" 4082.IX Item "ev::TYPE::TYPE ()"
… …
4047.PP 4213.PP
4048.Vb 5 4214.Vb 5
4049\& class myclass 4215\& class myclass
4050\& { 4216\& {
4051\& ev::io io ; void io_cb (ev::io &w, int revents); 4217\& ev::io io ; void io_cb (ev::io &w, int revents);
4052\& ev::io2 io2 ; void io2_cb (ev::io &w, int revents); 4218\& ev::io io2 ; void io2_cb (ev::io &w, int revents);
4053\& ev::idle idle; void idle_cb (ev::idle &w, int revents); 4219\& ev::idle idle; void idle_cb (ev::idle &w, int revents);
4054\& 4220\&
4055\& myclass (int fd) 4221\& myclass (int fd)
4056\& { 4222\& {
4057\& io .set <myclass, &myclass::io_cb > (this); 4223\& io .set <myclass, &myclass::io_cb > (this);
… …
4096Roger 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
4097makes rev work even on mingw. 4263makes rev work even on mingw.
4098.IP "Haskell" 4 4264.IP "Haskell" 4
4099.IX Item "Haskell" 4265.IX Item "Haskell"
4100A haskell binding to libev is available at 4266A haskell binding to libev is available at
4101<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>.
4102.IP "D" 4 4268.IP "D" 4
4103.IX Item "D" 4269.IX Item "D"
4104Leandro 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
4105be found at <http://proj.llucax.com.ar/wiki/evd>. 4271be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4106.IP "Ocaml" 4 4272.IP "Ocaml" 4
4107.IX Item "Ocaml" 4273.IX Item "Ocaml"
4108Erkki Seppala has written Ocaml bindings for libev, to be found at 4274Erkki Seppala has written Ocaml bindings for libev, to be found at
4109<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/>.
4110.IP "Lua" 4 4276.IP "Lua" 4
4111.IX Item "Lua" 4277.IX Item "Lua"
4112Brian 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
4113time 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
4114<http://github.com/brimworks/lua\-ev>. 4280http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4115.SH "MACRO MAGIC" 4281.SH "MACRO MAGIC"
4116.IX Header "MACRO MAGIC" 4282.IX Header "MACRO MAGIC"
4117Libev can be compiled with a variety of options, the most fundamental 4283Libev can be compiled with a variety of options, the most fundamental
4118of 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)
4119functions 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.
… …
4154suitable for use with \f(CW\*(C`EV_A\*(C'\fR. 4320suitable for use with \f(CW\*(C`EV_A\*(C'\fR.
4155.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4 4321.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4
4156.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 4322.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
4157.IX Item "EV_DEFAULT, EV_DEFAULT_" 4323.IX Item "EV_DEFAULT, EV_DEFAULT_"
4158Similar 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
4159loop, 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.
4160.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4 4330.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4
4161.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
4162.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_" 4332.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_"
4163Usage 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
4164default 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
… …
4319supported). 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
4320\&\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.
4321.Sp 4491.Sp
4322In standalone mode, libev will still try to automatically deduce the 4492In standalone mode, libev will still try to automatically deduce the
4323configuration, 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.
4324.IP "\s-1EV_USE_MONOTONIC\s0" 4 4502.IP "\s-1EV_USE_MONOTONIC\s0" 4
4325.IX Item "EV_USE_MONOTONIC" 4503.IX Item "EV_USE_MONOTONIC"
4326If 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
4327monotonic clock option at both compile time and runtime. Otherwise no 4505monotonic clock option at both compile time and runtime. Otherwise no
4328use 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,
… …
4440.IX Item "EV_USE_INOTIFY" 4618.IX Item "EV_USE_INOTIFY"
4441If 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
4442interface 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
4443be 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
4444indicate 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.
4445.IP "\s-1EV_ATOMIC_T\s0" 4 4634.IP "\s-1EV_ATOMIC_T\s0" 4
4446.IX Item "EV_ATOMIC_T" 4635.IX Item "EV_ATOMIC_T"
4447Libev 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
4448access is atomic with respect to other threads or signal contexts. No such 4637access is atomic and serialised with respect to other threads or signal
4449type 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
4450that 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
4451as 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.
4452.Sp 4642.Sp
4453In 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
4454(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.
4455.IP "\s-1EV_H\s0 (h)" 4 4647.IP "\s-1EV_H\s0 (h)" 4
4456.IX Item "EV_H (h)" 4648.IX Item "EV_H (h)"
4457The 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
4458undefined 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
4459used 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.
… …
4477If 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
4478will 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
4479additional independent event loops. Otherwise there will be no support 4671additional independent event loops. Otherwise there will be no support
4480for multiple event loops and there is no first event loop pointer 4672for multiple event loops and there is no first event loop pointer
4481argument. 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.
4482.IP "\s-1EV_MINPRI\s0" 4 4678.IP "\s-1EV_MINPRI\s0" 4
4483.IX Item "EV_MINPRI" 4679.IX Item "EV_MINPRI"
4484.PD 0 4680.PD 0
4485.IP "\s-1EV_MAXPRI\s0" 4 4681.IP "\s-1EV_MAXPRI\s0" 4
4486.IX Item "EV_MAXPRI" 4682.IX Item "EV_MAXPRI"
… …
4583With an intelligent-enough linker (gcc+binutils are intelligent enough 4779With an intelligent-enough linker (gcc+binutils are intelligent enough
4584when 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
4585your 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
4586I/O watcher then might come out at only 5Kb. 4782I/O watcher then might come out at only 5Kb.
4587.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.
4588.IP "\s-1EV_AVOID_STDIO\s0" 4 4797.IP "\s-1EV_AVOID_STDIO\s0" 4
4589.IX Item "EV_AVOID_STDIO" 4798.IX Item "EV_AVOID_STDIO"
4590If 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
4591functions (printf, scanf, perror etc.). This will increase the code size 4800functions (printf, scanf, perror etc.). This will increase the code size
4592somewhat, 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
… …
4969requires, 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
4970model. Libev still offers limited functionality on this platform in 5179model. Libev still offers limited functionality on this platform in
4971the 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
4972descriptors. This only applies when using Win32 natively, not when using 5181descriptors. This only applies when using Win32 natively, not when using
4973e.g. cygwin. Actually, it only applies to the microsofts own compilers, 5182e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4974as every compielr comes with a slightly differently broken/incompatible 5183as every compiler comes with a slightly differently broken/incompatible
4975environment. 5184environment.
4976.PP 5185.PP
4977Lifting these limitations would basically require the full 5186Lifting these limitations would basically require the full
4978re-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,
4979then 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
… …
5115.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"
5116The 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
5117have 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
5118good enough for at least into the year 4000 with millisecond accuracy 5327good enough for at least into the year 4000 with millisecond accuracy
5119(the design goal for libev). This requirement is overfulfilled by 5328(the design goal for libev). This requirement is overfulfilled by
5120implementations 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
5121\&\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).
5122.PP 5335.PP
5123If you know of other additional requirements drop me a note. 5336If you know of other additional requirements drop me a note.
5124.SH "ALGORITHMIC COMPLEXITIES" 5337.SH "ALGORITHMIC COMPLEXITIES"
5125.IX Header "ALGORITHMIC COMPLEXITIES" 5338.IX Header "ALGORITHMIC COMPLEXITIES"
5126In this section the complexities of (many of) the algorithms used inside 5339In this section the complexities of (many of) the algorithms used inside
… …
5180.IX Item "Processing ev_async_send: O(number_of_async_watchers)" 5393.IX Item "Processing ev_async_send: O(number_of_async_watchers)"
5181.IP "Processing signals: O(max_signal_number)" 4 5394.IP "Processing signals: O(max_signal_number)" 4
5182.IX Item "Processing signals: O(max_signal_number)" 5395.IX Item "Processing signals: O(max_signal_number)"
5183.PD 5396.PD
5184Sending 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
5185calls 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
5186involves iterating over all running async watchers or all signal numbers. 5400running async watchers or all signal numbers.
5187.SH "PORTING FROM LIBEV 3.X TO 4.X" 5401.SH "PORTING FROM LIBEV 3.X TO 4.X"
5188.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5402.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5189The 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.
5190.PP 5404.PP
5191At 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
… …
5288.IX Item "real time" 5502.IX Item "real time"
5289The physical time that is observed. It is apparently strictly monotonic :) 5503The physical time that is observed. It is apparently strictly monotonic :)
5290.IP "wall-clock time" 4 5504.IP "wall-clock time" 4
5291.IX Item "wall-clock time" 5505.IX Item "wall-clock time"
5292The time and date as shown on clocks. Unlike real time, it can actually 5506The time and date as shown on clocks. Unlike real time, it can actually
5293be wrong and jump forwards and backwards, e.g. when the you adjust your 5507be wrong and jump forwards and backwards, e.g. when you adjust your
5294clock. 5508clock.
5295.IP "watcher" 4 5509.IP "watcher" 4
5296.IX Item "watcher" 5510.IX Item "watcher"
5297A data structure that describes interest in certain events. Watchers need 5511A data structure that describes interest in certain events. Watchers need
5298to be started (attached to an event loop) before they can receive events. 5512to be started (attached to an event loop) before they can receive events.
5299.SH "AUTHOR" 5513.SH "AUTHOR"
5300.IX Header "AUTHOR" 5514.IX Header "AUTHOR"
5301Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael 5515Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
5302Magnusson and Emanuele Giaquinta. 5516Magnusson and Emanuele Giaquinta, and minor corrections by many others.

Diff Legend

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