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

Comparing libev/ev.3 (file contents):
Revision 1.86 by root, Wed Feb 16 08:07:25 2011 UTC vs.
Revision 1.90 by root, Mon Apr 2 23:14:40 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-31" "libev-4.04" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2012-04-03" "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
… …
676.Sp 685.Sp
677It scales in the same way as the epoll backend, but the interface to the 686It scales in the same way as the epoll backend, but the interface to the
678kernel is more efficient (which says nothing about its actual speed, of 687kernel is more efficient (which says nothing about its actual speed, of
679course). While stopping, setting and starting an I/O watcher does never 688course). While stopping, setting and starting an I/O watcher does never
680cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
681two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but 690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
682sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 691might have to leak fd's on fork, but it's more sane than epoll) and it
683cases 692drops fds silently in similarly hard-to-detect cases
684.Sp 693.Sp
685This backend usually performs well under most conditions. 694This backend usually performs well under most conditions.
686.Sp 695.Sp
687While nominally embeddable in other event loops, this doesn't work 696While nominally embeddable in other event loops, this doesn't work
688everywhere, so you might need to test for this. And since it is broken 697everywhere, so you might need to test for this. And since it is broken
… …
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.
… …
900given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR 909given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR
901without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. 910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR.
902.Sp 911.Sp
903Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the 912Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the
904event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). 913event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR).
905.IP "ev_run (loop, int flags)" 4 914.IP "bool ev_run (loop, int flags)" 4
906.IX Item "ev_run (loop, int flags)" 915.IX Item "bool ev_run (loop, int flags)"
907Finally, this is it, the event handler. This function usually is called 916Finally, this is it, the event handler. This function usually is called
908after you have initialised all your watchers and you want to start 917after you have initialised all your watchers and you want to start
909handling events. It will ask the operating system for any new events, call 918handling events. It will ask the operating system for any new events, call
910the watcher callbacks, an then repeat the whole process indefinitely: This 919the watcher callbacks, and then repeat the whole process indefinitely: This
911is why event loops are called \fIloops\fR. 920is why event loops are called \fIloops\fR.
912.Sp 921.Sp
913If the flags argument is specified as \f(CW0\fR, it will keep handling events 922If the flags argument is specified as \f(CW0\fR, it will keep handling events
914until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was 923until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was
915called. 924called.
925.Sp
926The return value is false if there are no more active watchers (which
927usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases
928(which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again").
916.Sp 929.Sp
917Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than 930Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than
918relying on all watchers to be stopped when deciding when a program has 931relying on all watchers to be stopped when deciding when a program has
919finished (especially in interactive programs), but having a program 932finished (especially in interactive programs), but having a program
920that automatically loops as long as it has to and no longer by virtue 933that automatically loops as long as it has to and no longer by virtue
921of relying on its watchers stopping correctly, that is truly a thing of 934of relying on its watchers stopping correctly, that is truly a thing of
922beauty. 935beauty.
923.Sp 936.Sp
924This function is also \fImostly\fR exception-safe \- you can break out of 937This function is \fImostly\fR exception-safe \- you can break out of a
925a \f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ 938\&\f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+
926exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor 939exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor
927will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. 940will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks.
928.Sp 941.Sp
929A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle 942A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle
930those events and any already outstanding ones, but will not wait and 943those events and any already outstanding ones, but will not wait and
… …
942This is useful if you are waiting for some external event in conjunction 955This is useful if you are waiting for some external event in conjunction
943with something not expressible using other libev watchers (i.e. "roll your 956with 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 957own \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. 958usually a better approach for this kind of thing.
946.Sp 959.Sp
947Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does: 960Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does (this is for your
961understanding, not a guarantee that things will work exactly like this in
962future versions):
948.Sp 963.Sp
949.Vb 10 964.Vb 10
950\& \- Increment loop depth. 965\& \- Increment loop depth.
951\& \- Reset the ev_break status. 966\& \- Reset the ev_break status.
952\& \- Before the first iteration, call any pending watchers. 967\& \- Before the first iteration, call any pending watchers.
… …
1067overhead for the actual polling but can deliver many events at once. 1082overhead for the actual polling but can deliver many events at once.
1068.Sp 1083.Sp
1069By setting a higher \fIio collect interval\fR you allow libev to spend more 1084By 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, 1085time 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 1086at 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 1087\&\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 1088introduce 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 1089sleep time ensures that libev will not poll for I/O events more often then
1075once per this interval, on average. 1090once per this interval, on average (as long as the host time resolution is
1091good enough).
1076.Sp 1092.Sp
1077Likewise, by setting a higher \fItimeout collect interval\fR you allow libev 1093Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
1078to spend more time collecting timeouts, at the expense of increased 1094to spend more time collecting timeouts, at the expense of increased
1079latency/jitter/inexactness (the watcher callback will be called 1095latency/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 1096later). \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 1148can be done relatively simply by putting mutex_lock/unlock calls around
1133each call to a libev function. 1149each call to a libev function.
1134.Sp 1150.Sp
1135However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible 1151However, \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 1152to 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 1153loop 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. 1154\&\fIrelease\fR and \fIacquire\fR callbacks on the loop.
1139.Sp 1155.Sp
1140When set, then \f(CW\*(C`release\*(C'\fR will be called just before the thread is 1156When 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 1157suspended waiting for new events, and \f(CW\*(C`acquire\*(C'\fR is called just
1142afterwards. 1158afterwards.
… …
1489active, pending and so on. In this section these states and the rules to 1505active, 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 1506transition between them will be described in more detail \- and while these
1491rules might look complicated, they usually do \*(L"the right thing\*(R". 1507rules might look complicated, they usually do \*(L"the right thing\*(R".
1492.IP "initialiased" 4 1508.IP "initialiased" 4
1493.IX Item "initialiased" 1509.IX Item "initialiased"
1494Before a watcher can be registered with the event looop it has to be 1510Before 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 1511initialised. 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. 1512\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1497.Sp 1513.Sp
1498In this state it is simply some block of memory that is suitable for 1514In 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 1515use in an event loop. It can be moved around, freed, reused etc. at
… …
1871detecting time jumps is hard, and some inaccuracies are unavoidable (the 1887detecting time jumps is hard, and some inaccuracies are unavoidable (the
1872monotonic clock option helps a lot here). 1888monotonic clock option helps a lot here).
1873.PP 1889.PP
1874The callback is guaranteed to be invoked only \fIafter\fR its timeout has 1890The 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 1891passed (not \fIat\fR, so on systems with very low-resolution clocks this
1876might introduce a small delay). If multiple timers become ready during the 1892might introduce a small delay, see \*(L"the special problem of being too
1893early\*(R", below). If multiple timers become ready during the same loop
1877same loop iteration then the ones with earlier time-out values are invoked 1894iteration 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 1895ones 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). 1896longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively).
1880.PP 1897.PP
1881\fIBe smart about timeouts\fR 1898\fIBe smart about timeouts\fR
1882.IX Subsection "Be smart about timeouts" 1899.IX Subsection "Be smart about timeouts"
1883.PP 1900.PP
1884Many real-world problems involve some kind of timeout, usually for error 1901Many real-world problems involve some kind of timeout, usually for error
… …
1966.Sp 1983.Sp
1967In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, 1984In 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 1985but remember the time of last activity, and check for a real timeout only
1969within the callback: 1986within the callback:
1970.Sp 1987.Sp
1971.Vb 1 1988.Vb 3
1989\& ev_tstamp timeout = 60.;
1972\& ev_tstamp last_activity; // time of last activity 1990\& ev_tstamp last_activity; // time of last activity
1991\& ev_timer timer;
1973\& 1992\&
1974\& static void 1993\& static void
1975\& callback (EV_P_ ev_timer *w, int revents) 1994\& callback (EV_P_ ev_timer *w, int revents)
1976\& { 1995\& {
1977\& ev_tstamp now = ev_now (EV_A); 1996\& // calculate when the timeout would happen
1978\& ev_tstamp timeout = last_activity + 60.; 1997\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout;
1979\& 1998\&
1980\& // if last_activity + 60. is older than now, we did time out 1999\& // if negative, it means we the timeout already occured
1981\& if (timeout < now) 2000\& if (after < 0.)
1982\& { 2001\& {
1983\& // timeout occurred, take action 2002\& // timeout occurred, take action
1984\& } 2003\& }
1985\& else 2004\& else
1986\& { 2005\& {
1987\& // callback was invoked, but there was some activity, re\-arm 2006\& // callback was invoked, but there was some recent
1988\& // the watcher to fire in last_activity + 60, which is 2007\& // activity. simply restart the timer to time out
1989\& // guaranteed to be in the future, so "again" is positive: 2008\& // after "after" seconds, which is the earliest time
1990\& w\->repeat = timeout \- now; 2009\& // the timeout can occur.
2010\& ev_timer_set (w, after, 0.);
1991\& ev_timer_again (EV_A_ w); 2011\& ev_timer_start (EV_A_ w);
1992\& } 2012\& }
1993\& } 2013\& }
1994.Ve 2014.Ve
1995.Sp 2015.Sp
1996To summarise the callback: first calculate the real timeout (defined 2016To 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 2017timeout will occur (by calculating the absolute time when it would occur,
1998been reached, which means something \fIdid\fR, in fact, time out. Otherwise 2018\&\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 2019(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 2020.Sp
2003Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the 2021If 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. 2022timed out, and need to do whatever is needed in this case.
2023.Sp
2024Otherwise, we now the earliest time at which the timeout would trigger,
2025and simply start the timer with this timeout value.
2026.Sp
2027In other words, each time the callback is invoked it will check whether
2028the timeout cocured. If not, it will simply reschedule itself to check
2029again at the earliest time it could time out. Rinse. Repeat.
2005.Sp 2030.Sp
2006This scheme causes more callback invocations (about one every 60 seconds 2031This scheme causes more callback invocations (about one every 60 seconds
2007minus half the average time between activity), but virtually no calls to 2032minus half the average time between activity), but virtually no calls to
2008libev to change the timeout. 2033libev to change the timeout.
2009.Sp 2034.Sp
2010To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR 2035To start the machinery, simply initialise the watcher and set
2011to the current time (meaning we just have some activity :), then call the 2036\&\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: 2037now), then call the callback, which will \*(L"do the right thing\*(R" and start
2038the timer:
2013.Sp 2039.Sp
2014.Vb 3 2040.Vb 3
2041\& last_activity = ev_now (EV_A);
2015\& ev_init (timer, callback); 2042\& ev_init (&timer, callback);
2016\& last_activity = ev_now (loop); 2043\& callback (EV_A_ &timer, 0);
2017\& callback (loop, timer, EV_TIMER);
2018.Ve 2044.Ve
2019.Sp 2045.Sp
2020And when there is some activity, simply store the current time in 2046When there is some activity, simply store the current time in
2021\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all: 2047\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all:
2022.Sp 2048.Sp
2023.Vb 1 2049.Vb 2
2050\& if (activity detected)
2024\& last_activity = ev_now (loop); 2051\& last_activity = ev_now (EV_A);
2052.Ve
2053.Sp
2054When your timeout value changes, then the timeout can be changed by simply
2055providing a new value, stopping the timer and calling the callback, which
2056will agaion do the right thing (for example, time out immediately :).
2057.Sp
2058.Vb 3
2059\& timeout = new_value;
2060\& ev_timer_stop (EV_A_ &timer);
2061\& callback (EV_A_ &timer, 0);
2025.Ve 2062.Ve
2026.Sp 2063.Sp
2027This technique is slightly more complex, but in most cases where the 2064This technique is slightly more complex, but in most cases where the
2028time-out is unlikely to be triggered, much more efficient. 2065time-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 2066.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." 2067.IX Item "4. Wee, just use a double-linked list for your timeouts."
2035If there is not one request, but many thousands (millions...), all 2068If there is not one request, but many thousands (millions...), all
2036employing some kind of timeout with the same timeout value, then one can 2069employing some kind of timeout with the same timeout value, then one can
2037do even better: 2070do even better:
… …
2061Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 2094Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
2062rather complicated, but extremely efficient, something that really pays 2095rather complicated, but extremely efficient, something that really pays
2063off after the first million or so of active timers, i.e. it's usually 2096off after the first million or so of active timers, i.e. it's usually
2064overkill :) 2097overkill :)
2065.PP 2098.PP
2099\fIThe special problem of being too early\fR
2100.IX Subsection "The special problem of being too early"
2101.PP
2102If you ask a timer to call your callback after three seconds, then
2103you expect it to be invoked after three seconds \- but of course, this
2104cannot be guaranteed to infinite precision. Less obviously, it cannot be
2105guaranteed to any precision by libev \- imagine somebody suspending the
2106process with a \s-1STOP\s0 signal for a few hours for example.
2107.PP
2108So, libev tries to invoke your callback as soon as possible \fIafter\fR the
2109delay has occurred, but cannot guarantee this.
2110.PP
2111A less obvious failure mode is calling your callback too early: many event
2112loops compare timestamps with a \*(L"elapsed delay >= requested delay\*(R", but
2113this can cause your callback to be invoked much earlier than you would
2114expect.
2115.PP
2116To see why, imagine a system with a clock that only offers full second
2117resolution (think windows if you can't come up with a broken enough \s-1OS\s0
2118yourself). If you schedule a one-second timer at the time 500.9, then the
2119event loop will schedule your timeout to elapse at a system time of 500
2120(500.9 truncated to the resolution) + 1, or 501.
2121.PP
2122If an event library looks at the timeout 0.1s later, it will see \*(L"501 >=
2123501\*(R" and invoke the callback 0.1s after it was started, even though a
2124one-second delay was requested \- this is being \*(L"too early\*(R", despite best
2125intentions.
2126.PP
2127This is the reason why libev will never invoke the callback if the elapsed
2128delay equals the requested delay, but only when the elapsed delay is
2129larger than the requested delay. In the example above, libev would only invoke
2130the callback at system time 502, or 1.1s after the timer was started.
2131.PP
2132So, while libev cannot guarantee that your callback will be invoked
2133exactly when requested, it \fIcan\fR and \fIdoes\fR guarantee that the requested
2134delay has actually elapsed, or in other words, it always errs on the \*(L"too
2135late\*(R" side of things.
2136.PP
2066\fIThe special problem of time updates\fR 2137\fIThe special problem of time updates\fR
2067.IX Subsection "The special problem of time updates" 2138.IX Subsection "The special problem of time updates"
2068.PP 2139.PP
2069Establishing the current time is a costly operation (it usually takes at 2140Establishing the current time is a costly operation (it usually takes
2070least two system calls): \s-1EV\s0 therefore updates its idea of the current 2141at 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 2142time 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 2143growing 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. 2144lots of events in one iteration.
2074.PP 2145.PP
2075The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2146The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
… …
2083.Ve 2154.Ve
2084.PP 2155.PP
2085If the event loop is suspended for a long time, you can also force an 2156If 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 2157update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2087()\*(C'\fR. 2158()\*(C'\fR.
2159.PP
2160\fIThe special problem of unsynchronised clocks\fR
2161.IX Subsection "The special problem of unsynchronised clocks"
2162.PP
2163Modern systems have a variety of clocks \- libev itself uses the normal
2164\&\*(L"wall clock\*(R" clock and, if available, the monotonic clock (to avoid time
2165jumps).
2166.PP
2167Neither of these clocks is synchronised with each other or any other clock
2168on the system, so \f(CW\*(C`ev_time ()\*(C'\fR might return a considerably different time
2169than \f(CW\*(C`gettimeofday ()\*(C'\fR or \f(CW\*(C`time ()\*(C'\fR. On a GNU/Linux system, for example,
2170a call to \f(CW\*(C`gettimeofday\*(C'\fR might return a second count that is one higher
2171than a directly following call to \f(CW\*(C`time\*(C'\fR.
2172.PP
2173The moral of this is to only compare libev-related timestamps with
2174\&\f(CW\*(C`ev_time ()\*(C'\fR and \f(CW\*(C`ev_now ()\*(C'\fR, at least if you want better precision than
2175a second or so.
2176.PP
2177One more problem arises due to this lack of synchronisation: if libev uses
2178the system monotonic clock and you compare timestamps from \f(CW\*(C`ev_time\*(C'\fR
2179or \f(CW\*(C`ev_now\*(C'\fR from when you started your timer and when your callback is
2180invoked, you will find that sometimes the callback is a bit \*(L"early\*(R".
2181.PP
2182This is because \f(CW\*(C`ev_timer\*(C'\fRs work in real time, not wall clock time, so
2183libev makes sure your callback is not invoked before the delay happened,
2184\&\fImeasured according to the real time\fR, not the system clock.
2185.PP
2186If your timeouts are based on a physical timescale (e.g. \*(L"time out this
2187connection after 100 seconds\*(R") then this shouldn't bother you as it is
2188exactly the right behaviour.
2189.PP
2190If you want to compare wall clock/system timestamps to your timers, then
2191you need to use \f(CW\*(C`ev_periodic\*(C'\fRs, as these are based on the wall clock
2192time, where your comparisons will always generate correct results.
2088.PP 2193.PP
2089\fIThe special problems of suspended animation\fR 2194\fIThe special problems of suspended animation\fR
2090.IX Subsection "The special problems of suspended animation" 2195.IX Subsection "The special problems of suspended animation"
2091.PP 2196.PP
2092When you leave the server world it is quite customary to hit machines that 2197When you leave the server world it is quite customary to hit machines that
… …
2136trigger at exactly 10 second intervals. If, however, your program cannot 2241trigger at exactly 10 second intervals. If, however, your program cannot
2137keep up with the timer (because it takes longer than those 10 seconds to 2242keep 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. 2243do stuff) the timer will not fire more than once per event loop iteration.
2139.IP "ev_timer_again (loop, ev_timer *)" 4 2244.IP "ev_timer_again (loop, ev_timer *)" 4
2140.IX Item "ev_timer_again (loop, ev_timer *)" 2245.IX Item "ev_timer_again (loop, ev_timer *)"
2141This will act as if the timer timed out and restart it again if it is 2246This will act as if the timer timed out, and restarts it again if it is
2142repeating. The exact semantics are: 2247repeating. It basically works like calling \f(CW\*(C`ev_timer_stop\*(C'\fR, updating the
2248timeout to the \f(CW\*(C`repeat\*(C'\fR value and calling \f(CW\*(C`ev_timer_start\*(C'\fR.
2143.Sp 2249.Sp
2250The exact semantics are as in the following rules, all of which will be
2251applied to the watcher:
2252.RS 4
2144If the timer is pending, its pending status is cleared. 2253.IP "If the timer is pending, the pending status is always cleared." 4
2145.Sp 2254.IX Item "If the timer is pending, the pending status is always cleared."
2255.PD 0
2146If the timer is started but non-repeating, stop it (as if it timed out). 2256.IP "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." 4
2147.Sp 2257.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 2258.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. 2259.el .IP "If the timer is repeating, make the \f(CWrepeat\fR value the new timeout and start the timer, if necessary." 4
2260.IX Item "If the timer is repeating, make the repeat value the new timeout and start the timer, if necessary."
2261.RE
2262.RS 4
2263.PD
2150.Sp 2264.Sp
2151This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a 2265This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a
2152usage example. 2266usage example.
2267.RE
2153.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 2268.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4
2154.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 2269.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)"
2155Returns the remaining time until a timer fires. If the timer is active, 2270Returns 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 2271then this time is relative to the current event loop time, otherwise it's
2157the timeout value currently configured. 2272the timeout value currently configured.
… …
2277.Sp 2392.Sp
2278Another way to think about it (for the mathematically inclined) is that 2393Another 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 2394\&\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. 2395time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps.
2281.Sp 2396.Sp
2282For numerical stability it is preferable that the \f(CW\*(C`offset\*(C'\fR value is near 2397The \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 2398interval 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. 2399microseconds) and \f(CW\*(C`offset\*(C'\fR should be higher than \f(CW0\fR and should have
2400at most a similar magnitude as the current time (say, within a factor of
2401ten). Typical values for offset are, in fact, \f(CW0\fR or something between
2402\&\f(CW0\fR and \f(CW\*(C`interval\*(C'\fR, which is also the recommended range.
2285.Sp 2403.Sp
2286Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0 2404Note 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 2405speed 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 2406will 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). 2407millisecond (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 3449\&\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 3450of \*(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, 3451signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread,
3334even without knowing which loop owns the signal. 3452even without knowing which loop owns the signal.
3335.PP 3453.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 3454\fIQueueing\fR
3340.IX Subsection "Queueing" 3455.IX Subsection "Queueing"
3341.PP 3456.PP
3342\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason 3457\&\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 3458is 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, 3552Unlike \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 3553signal 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). 3554embedding section below on what exactly this means).
3440.Sp 3555.Sp
3441Note that, as with other watchers in libev, multiple events might get 3556Note that, as with other watchers in libev, multiple events might get
3442compressed into a single callback invocation (another way to look at this 3557compressed 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, 3558this is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered: they are set on
3444reset when the event loop detects that). 3559\&\f(CW\*(C`ev_async_send\*(C'\fR, reset when the event loop detects that).
3445.Sp 3560.Sp
3446This call incurs the overhead of a system call only once per event loop 3561This 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 3562loop 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. 3563the event loop (or your program) is processing events. That means that
3564repeated calls are basically free (there is no need to avoid calls for
3565performance reasons) and that the overhead becomes smaller (typically
3566zero) under load.
3449.IP "bool = ev_async_pending (ev_async *)" 4 3567.IP "bool = ev_async_pending (ev_async *)" 4
3450.IX Item "bool = ev_async_pending (ev_async *)" 3568.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 3569Returns 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 3570watcher but the event has not yet been processed (or even noted) by the
3453event loop. 3571event loop.
… …
3501\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3619\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3502.Ve 3620.Ve
3503.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 3621.IP "ev_feed_fd_event (loop, int fd, int revents)" 4
3504.IX Item "ev_feed_fd_event (loop, int fd, int revents)" 3622.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 3623Feed an event on the given fd, as if a file descriptor backend detected
3506the given events it. 3624the given events.
3507.IP "ev_feed_signal_event (loop, int signum)" 4 3625.IP "ev_feed_signal_event (loop, int signum)" 4
3508.IX Item "ev_feed_signal_event (loop, int signum)" 3626.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, 3627Feed an event as if the given signal occurred. See also \f(CW\*(C`ev_feed_signal\*(C'\fR,
3510which is async-safe. 3628which is async-safe.
3511.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3629.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
… …
3585\& { 3703\& {
3586\& struct my_biggy big = (struct my_biggy *) 3704\& struct my_biggy big = (struct my_biggy *)
3587\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3705\& (((char *)w) \- offsetof (struct my_biggy, t2));
3588\& } 3706\& }
3589.Ve 3707.Ve
3708.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0"
3709.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3710Often you have structures like this in event-based programs:
3711.PP
3712.Vb 4
3713\& callback ()
3714\& {
3715\& free (request);
3716\& }
3717\&
3718\& request = start_new_request (..., callback);
3719.Ve
3720.PP
3721The intent is to start some \*(L"lengthy\*(R" operation. The \f(CW\*(C`request\*(C'\fR could be
3722used to cancel the operation, or do other things with it.
3723.PP
3724It's not uncommon to have code paths in \f(CW\*(C`start_new_request\*(C'\fR that
3725immediately invoke the callback, for example, to report errors. Or you add
3726some caching layer that finds that it can skip the lengthy aspects of the
3727operation and simply invoke the callback with the result.
3728.PP
3729The problem here is that this will happen \fIbefore\fR \f(CW\*(C`start_new_request\*(C'\fR
3730has returned, so \f(CW\*(C`request\*(C'\fR is not set.
3731.PP
3732Even if you pass the request by some safer means to the callback, you
3733might want to do something to the request after starting it, such as
3734canceling it, which probably isn't working so well when the callback has
3735already been invoked.
3736.PP
3737A common way around all these issues is to make sure that
3738\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If
3739\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
3740delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher
3741for example, or more sneakily, by reusing an existing (stopped) watcher
3742and pushing it into the pending queue:
3743.PP
3744.Vb 2
3745\& ev_set_cb (watcher, callback);
3746\& ev_feed_event (EV_A_ watcher, 0);
3747.Ve
3748.PP
3749This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3750invoked, 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" 3751.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" 3752.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3592Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3753Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3593\&\fImodal\fR interaction, which is most easily implemented by recursively 3754\&\fImodal\fR interaction, which is most easily implemented by recursively
3594invoking \f(CW\*(C`ev_run\*(C'\fR. 3755invoking \f(CW\*(C`ev_run\*(C'\fR.
… …
3608\& int exit_main_loop = 0; 3769\& int exit_main_loop = 0;
3609\& 3770\&
3610\& while (!exit_main_loop) 3771\& while (!exit_main_loop)
3611\& ev_run (EV_DEFAULT_ EVRUN_ONCE); 3772\& ev_run (EV_DEFAULT_ EVRUN_ONCE);
3612\& 3773\&
3613\& // in a model watcher 3774\& // in a modal watcher
3614\& int exit_nested_loop = 0; 3775\& int exit_nested_loop = 0;
3615\& 3776\&
3616\& while (!exit_nested_loop) 3777\& while (!exit_nested_loop)
3617\& ev_run (EV_A_ EVRUN_ONCE); 3778\& ev_run (EV_A_ EVRUN_ONCE);
3618.Ve 3779.Ve
… …
3817\& } 3978\& }
3818.Ve 3979.Ve
3819.PP 3980.PP
3820That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and 3981That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and
3821continues the libev coroutine, which, when appropriate, switches back to 3982continues the libev coroutine, which, when appropriate, switches back to
3822this or any other coroutine. I am sure if you sue this your own :) 3983this or any other coroutine.
3823.PP 3984.PP
3824You can do similar tricks if you have, say, threads with an event queue \- 3985You 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 3986instead 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 3987switching to a coroutine, you push the watcher onto the queue and notify
3827any waiters. 3988any waiters.
… …
3899with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy 4060with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy
3900to add as long as they only need one additional pointer for context. If 4061to add as long as they only need one additional pointer for context. If
3901you need support for other types of functors please contact the author 4062you need support for other types of functors please contact the author
3902(preferably after implementing it). 4063(preferably after implementing it).
3903.PP 4064.PP
4065For all this to work, your \*(C+ compiler either has to use the same calling
4066conventions as your C compiler (for static member functions), or you have
4067to embed libev and compile libev itself as \*(C+.
4068.PP
3904Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: 4069Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace:
3905.ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4 4070.ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4
3906.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4 4071.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4
3907.IX Item "ev::READ, ev::WRITE etc." 4072.IX Item "ev::READ, ev::WRITE etc."
3908These are just enum values with the same values as the \f(CW\*(C`EV_READ\*(C'\fR etc. 4073These are just enum values with the same values as the \f(CW\*(C`EV_READ\*(C'\fR etc.
… …
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 4080.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." 4081.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 4082For 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 4083the 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 4084which 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. 4085defined by many implementations.
3921.Sp 4086.Sp
3922All of those classes have these methods: 4087All of those classes have these methods:
3923.RS 4 4088.RS 4
3924.IP "ev::TYPE::TYPE ()" 4 4089.IP "ev::TYPE::TYPE ()" 4
3925.IX Item "ev::TYPE::TYPE ()" 4090.IX Item "ev::TYPE::TYPE ()"
… …
4056.PP 4221.PP
4057.Vb 5 4222.Vb 5
4058\& class myclass 4223\& class myclass
4059\& { 4224\& {
4060\& ev::io io ; void io_cb (ev::io &w, int revents); 4225\& ev::io io ; void io_cb (ev::io &w, int revents);
4061\& ev::io2 io2 ; void io2_cb (ev::io &w, int revents); 4226\& ev::io io2 ; void io2_cb (ev::io &w, int revents);
4062\& ev::idle idle; void idle_cb (ev::idle &w, int revents); 4227\& ev::idle idle; void idle_cb (ev::idle &w, int revents);
4063\& 4228\&
4064\& myclass (int fd) 4229\& myclass (int fd)
4065\& { 4230\& {
4066\& io .set <myclass, &myclass::io_cb > (this); 4231\& 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 4270Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4106makes rev work even on mingw. 4271makes rev work even on mingw.
4107.IP "Haskell" 4 4272.IP "Haskell" 4
4108.IX Item "Haskell" 4273.IX Item "Haskell"
4109A haskell binding to libev is available at 4274A haskell binding to libev is available at
4110<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>. 4275http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
4111.IP "D" 4 4276.IP "D" 4
4112.IX Item "D" 4277.IX Item "D"
4113Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4278Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4114be found at <http://proj.llucax.com.ar/wiki/evd>. 4279be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4115.IP "Ocaml" 4 4280.IP "Ocaml" 4
4116.IX Item "Ocaml" 4281.IX Item "Ocaml"
4117Erkki Seppala has written Ocaml bindings for libev, to be found at 4282Erkki Seppala has written Ocaml bindings for libev, to be found at
4118<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. 4283http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
4119.IP "Lua" 4 4284.IP "Lua" 4
4120.IX Item "Lua" 4285.IX Item "Lua"
4121Brian Maher has written a partial interface to libev for lua (at the 4286Brian 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 4287time 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>. 4288http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4124.SH "MACRO MAGIC" 4289.SH "MACRO MAGIC"
4125.IX Header "MACRO MAGIC" 4290.IX Header "MACRO MAGIC"
4126Libev can be compiled with a variety of options, the most fundamental 4291Libev 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) 4292of 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. 4293functions 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. 4328suitable for use with \f(CW\*(C`EV_A\*(C'\fR.
4164.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4 4329.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4
4165.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 4330.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
4166.IX Item "EV_DEFAULT, EV_DEFAULT_" 4331.IX Item "EV_DEFAULT, EV_DEFAULT_"
4167Similar to the other two macros, this gives you the value of the default 4332Similar to the other two macros, this gives you the value of the default
4168loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 4333loop, if multiple loops are supported (\*(L"ev loop default\*(R"). The default loop
4334will be initialised if it isn't already initialised.
4335.Sp
4336For non-multiplicity builds, these macros do nothing, so you always have
4337to initialise the loop somewhere.
4169.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4 4338.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4
4170.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4 4339.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4
4171.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_" 4340.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 4341Usage 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 4342default 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 4497supported). 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. 4498\&\fIevent.h\fR that are not directly supported by the libev core alone.
4330.Sp 4499.Sp
4331In standalone mode, libev will still try to automatically deduce the 4500In standalone mode, libev will still try to automatically deduce the
4332configuration, but has to be more conservative. 4501configuration, but has to be more conservative.
4502.IP "\s-1EV_USE_FLOOR\s0" 4
4503.IX Item "EV_USE_FLOOR"
4504If defined to be \f(CW1\fR, libev will use the \f(CW\*(C`floor ()\*(C'\fR function for its
4505periodic reschedule calculations, otherwise libev will fall back on a
4506portable (slower) implementation. If you enable this, you usually have to
4507link against libm or something equivalent. Enabling this when the \f(CW\*(C`floor\*(C'\fR
4508function is not available will fail, so the safe default is to not enable
4509this.
4333.IP "\s-1EV_USE_MONOTONIC\s0" 4 4510.IP "\s-1EV_USE_MONOTONIC\s0" 4
4334.IX Item "EV_USE_MONOTONIC" 4511.IX Item "EV_USE_MONOTONIC"
4335If defined to be \f(CW1\fR, libev will try to detect the availability of the 4512If 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 4513monotonic clock option at both compile time and runtime. Otherwise no
4337use of the monotonic clock option will be attempted. If you enable this, 4514use of the monotonic clock option will be attempted. If you enable this,
… …
4449.IX Item "EV_USE_INOTIFY" 4626.IX Item "EV_USE_INOTIFY"
4450If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify 4627If 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 4628interface 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 4629be detected at runtime. If undefined, it will be enabled if the headers
4453indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4630indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4631.IP "\s-1EV_NO_SMP\s0" 4
4632.IX Item "EV_NO_SMP"
4633If defined to be \f(CW1\fR, libev will assume that memory is always coherent
4634between threads, that is, threads can be used, but threads never run on
4635different cpus (or different cpu cores). This reduces dependencies
4636and makes libev faster.
4637.IP "\s-1EV_NO_THREADS\s0" 4
4638.IX Item "EV_NO_THREADS"
4639If defined to be \f(CW1\fR, libev will assume that it will never be called
4640from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR,
4641above. This reduces dependencies and makes libev faster.
4454.IP "\s-1EV_ATOMIC_T\s0" 4 4642.IP "\s-1EV_ATOMIC_T\s0" 4
4455.IX Item "EV_ATOMIC_T" 4643.IX Item "EV_ATOMIC_T"
4456Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4644Libev 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 4645access 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 4646contexts. 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" 4647provide 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. 4648both for signal handler \*(L"locking\*(R" as well as for signal and thread safety
4649in \f(CW\*(C`ev_async\*(C'\fR watchers.
4461.Sp 4650.Sp
4462In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4651In 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. 4652(from \fIsignal.h\fR), which is usually good enough on most platforms,
4653although strictly speaking using a type that also implies a memory fence
4654is required.
4464.IP "\s-1EV_H\s0 (h)" 4 4655.IP "\s-1EV_H\s0 (h)" 4
4465.IX Item "EV_H (h)" 4656.IX Item "EV_H (h)"
4466The name of the \fIev.h\fR header file used to include it. The default if 4657The 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 4658undefined 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. 4659used 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 4677If 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 4678will 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 4679additional independent event loops. Otherwise there will be no support
4489for multiple event loops and there is no first event loop pointer 4680for multiple event loops and there is no first event loop pointer
4490argument. Instead, all functions act on the single default loop. 4681argument. Instead, all functions act on the single default loop.
4682.Sp
4683Note that \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR will no longer provide a
4684default loop when multiplicity is switched off \- you always have to
4685initialise the loop manually in this case.
4491.IP "\s-1EV_MINPRI\s0" 4 4686.IP "\s-1EV_MINPRI\s0" 4
4492.IX Item "EV_MINPRI" 4687.IX Item "EV_MINPRI"
4493.PD 0 4688.PD 0
4494.IP "\s-1EV_MAXPRI\s0" 4 4689.IP "\s-1EV_MAXPRI\s0" 4
4495.IX Item "EV_MAXPRI" 4690.IX Item "EV_MAXPRI"
… …
4592With an intelligent-enough linker (gcc+binutils are intelligent enough 4787With 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 4788when 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 4789your program might be left out as well \- a binary starting a timer and an
4595I/O watcher then might come out at only 5Kb. 4790I/O watcher then might come out at only 5Kb.
4596.RE 4791.RE
4792.IP "\s-1EV_API_STATIC\s0" 4
4793.IX Item "EV_API_STATIC"
4794If this symbol is defined (by default it is not), then all identifiers
4795will have static linkage. This means that libev will not export any
4796identifiers, and you cannot link against libev anymore. This can be useful
4797when you embed libev, only want to use libev functions in a single file,
4798and do not want its identifiers to be visible.
4799.Sp
4800To use this, define \f(CW\*(C`EV_API_STATIC\*(C'\fR and include \fIev.c\fR in the file that
4801wants to use libev.
4802.Sp
4803This option only works when libev is compiled with a C compiler, as \*(C+
4804doesn't support the required declaration syntax.
4597.IP "\s-1EV_AVOID_STDIO\s0" 4 4805.IP "\s-1EV_AVOID_STDIO\s0" 4
4598.IX Item "EV_AVOID_STDIO" 4806.IX Item "EV_AVOID_STDIO"
4599If this is set to \f(CW1\fR at compiletime, then libev will avoid using stdio 4807If 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 4808functions (printf, scanf, perror etc.). This will increase the code size
4601somewhat, but if your program doesn't otherwise depend on stdio and your 4809somewhat, 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 5186requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
4979model. Libev still offers limited functionality on this platform in 5187model. 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 5188the 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 5189descriptors. This only applies when using Win32 natively, not when using
4982e.g. cygwin. Actually, it only applies to the microsofts own compilers, 5190e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4983as every compielr comes with a slightly differently broken/incompatible 5191as every compiler comes with a slightly differently broken/incompatible
4984environment. 5192environment.
4985.PP 5193.PP
4986Lifting these limitations would basically require the full 5194Lifting these limitations would basically require the full
4987re-implementation of the I/O system. If you are into this kind of thing, 5195re-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 5196then 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" 5332.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 5333The 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 5334have 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 5335good enough for at least into the year 4000 with millisecond accuracy
5128(the design goal for libev). This requirement is overfulfilled by 5336(the design goal for libev). This requirement is overfulfilled by
5129implementations using \s-1IEEE\s0 754, which is basically all existing ones. With 5337implementations using \s-1IEEE\s0 754, which is basically all existing ones.
5338.Sp
5130\&\s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least 2200. 5339With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the
5340year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5341is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5342something like that, just kidding).
5131.PP 5343.PP
5132If you know of other additional requirements drop me a note. 5344If you know of other additional requirements drop me a note.
5133.SH "ALGORITHMIC COMPLEXITIES" 5345.SH "ALGORITHMIC COMPLEXITIES"
5134.IX Header "ALGORITHMIC COMPLEXITIES" 5346.IX Header "ALGORITHMIC COMPLEXITIES"
5135In this section the complexities of (many of) the algorithms used inside 5347In this section the complexities of (many of) the algorithms used inside
… …
5189.IX Item "Processing ev_async_send: O(number_of_async_watchers)" 5401.IX Item "Processing ev_async_send: O(number_of_async_watchers)"
5190.IP "Processing signals: O(max_signal_number)" 4 5402.IP "Processing signals: O(max_signal_number)" 4
5191.IX Item "Processing signals: O(max_signal_number)" 5403.IX Item "Processing signals: O(max_signal_number)"
5192.PD 5404.PD
5193Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR 5405Sending 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 5406calls in the current loop iteration and the loop is currently
5407blocked. Checking for async and signal events involves iterating over all
5195involves iterating over all running async watchers or all signal numbers. 5408running async watchers or all signal numbers.
5196.SH "PORTING FROM LIBEV 3.X TO 4.X" 5409.SH "PORTING FROM LIBEV 3.X TO 4.X"
5197.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5410.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5198The major version 4 introduced some incompatible changes to the \s-1API\s0. 5411The major version 4 introduced some incompatible changes to the \s-1API\s0.
5199.PP 5412.PP
5200At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5413At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
… …
5297.IX Item "real time" 5510.IX Item "real time"
5298The physical time that is observed. It is apparently strictly monotonic :) 5511The physical time that is observed. It is apparently strictly monotonic :)
5299.IP "wall-clock time" 4 5512.IP "wall-clock time" 4
5300.IX Item "wall-clock time" 5513.IX Item "wall-clock time"
5301The time and date as shown on clocks. Unlike real time, it can actually 5514The time and date as shown on clocks. Unlike real time, it can actually
5302be wrong and jump forwards and backwards, e.g. when the you adjust your 5515be wrong and jump forwards and backwards, e.g. when you adjust your
5303clock. 5516clock.
5304.IP "watcher" 4 5517.IP "watcher" 4
5305.IX Item "watcher" 5518.IX Item "watcher"
5306A data structure that describes interest in certain events. Watchers need 5519A data structure that describes interest in certain events. Watchers need
5307to be started (attached to an event loop) before they can receive events. 5520to be started (attached to an event loop) before they can receive events.

Diff Legend

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