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.95 by root, Sat May 26 08:52:09 2012 UTC

1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
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-05-26" "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 ()"
… …
361current system. To find which embeddable backends might be supported on 367current system. To find which embeddable backends might be supported on
362the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () 368the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends ()
363& ev_supported_backends ()\*(C'\fR, likewise for recommended ones. 369& ev_supported_backends ()\*(C'\fR, likewise for recommended ones.
364.Sp 370.Sp
365See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 371See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
366.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 372.IP "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" 4
367.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" 373.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())"
368Sets the allocation function to use (the prototype is similar \- the 374Sets the allocation function to use (the prototype is similar \- the
369semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is 375semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is
370used to allocate and free memory (no surprises here). If it returns zero 376used to allocate and free memory (no surprises here). If it returns zero
371when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort 377when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort
372or take some potentially destructive action. 378or take some potentially destructive action.
… …
398\& } 404\& }
399\& 405\&
400\& ... 406\& ...
401\& ev_set_allocator (persistent_realloc); 407\& ev_set_allocator (persistent_realloc);
402.Ve 408.Ve
403.IP "ev_set_syserr_cb (void (*cb)(const char *msg))" 4 409.IP "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" 4
404.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg))" 410.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())"
405Set the callback function to call on a retryable system call error (such 411Set the callback function to call on a retryable system call error (such
406as failed select, poll, epoll_wait). The message is a printable string 412as failed select, poll, epoll_wait). The message is a printable string
407indicating the system call or subsystem causing the problem. If this 413indicating the system call or subsystem causing the problem. If this
408callback is set, then libev will expect it to remedy the situation, no 414callback is set, then libev will expect it to remedy the situation, no
409matter what, when it returns. That is, libev will generally retry the 415matter what, when it returns. That is, libev will generally retry the
… …
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
… …
673.Sp 685.Sp
674It 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
675kernel is more efficient (which says nothing about its actual speed, of 687kernel is more efficient (which says nothing about its actual speed, of
676course). While stopping, setting and starting an I/O watcher does never 688course). While stopping, setting and starting an I/O watcher does never
677cause 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
678two 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
679sane, 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
680cases 692drops fds silently in similarly hard-to-detect cases
681.Sp 693.Sp
682This backend usually performs well under most conditions. 694This backend usually performs well under most conditions.
683.Sp 695.Sp
684While nominally embeddable in other event loops, this doesn't work 696While nominally embeddable in other event loops, this doesn't work
685everywhere, 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
… …
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.
… …
897given 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
898without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. 910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR.
899.Sp 911.Sp
900Calling \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
901event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). 913event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR).
902.IP "ev_run (loop, int flags)" 4 914.IP "bool ev_run (loop, int flags)" 4
903.IX Item "ev_run (loop, int flags)" 915.IX Item "bool ev_run (loop, int flags)"
904Finally, this is it, the event handler. This function usually is called 916Finally, this is it, the event handler. This function usually is called
905after you have initialised all your watchers and you want to start 917after you have initialised all your watchers and you want to start
906handling 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
907the watcher callbacks, an then repeat the whole process indefinitely: This 919the watcher callbacks, and then repeat the whole process indefinitely: This
908is why event loops are called \fIloops\fR. 920is why event loops are called \fIloops\fR.
909.Sp 921.Sp
910If 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
911until 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
912called. 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").
913.Sp 929.Sp
914Please 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
915relying 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
916finished (especially in interactive programs), but having a program 932finished (especially in interactive programs), but having a program
917that 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
918of 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
919beauty. 935beauty.
920.Sp 936.Sp
921This 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
922a \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+
923exception 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
924will 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.
925.Sp 941.Sp
926A 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
927those events and any already outstanding ones, but will not wait and 943those events and any already outstanding ones, but will not wait and
… …
939This 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
940with something not expressible using other libev watchers (i.e. "roll your 956with 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 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
942usually a better approach for this kind of thing. 958usually a better approach for this kind of thing.
943.Sp 959.Sp
944Here 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):
945.Sp 963.Sp
946.Vb 10 964.Vb 10
947\& \- Increment loop depth. 965\& \- Increment loop depth.
948\& \- Reset the ev_break status. 966\& \- Reset the ev_break status.
949\& \- Before the first iteration, call any pending watchers. 967\& \- Before the first iteration, call any pending watchers.
… …
985.Sp 1003.Sp
986.Vb 4 1004.Vb 4
987\& ... queue jobs here, make sure they register event watchers as long 1005\& ... 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..) 1006\& ... as they still have work to do (even an idle watcher will do..)
989\& ev_run (my_loop, 0); 1007\& ev_run (my_loop, 0);
990\& ... jobs done or somebody called unloop. yeah! 1008\& ... jobs done or somebody called break. yeah!
991.Ve 1009.Ve
992.IP "ev_break (loop, how)" 4 1010.IP "ev_break (loop, how)" 4
993.IX Item "ev_break (loop, how)" 1011.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 1012Can 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 1013has 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. 1082overhead for the actual polling but can deliver many events at once.
1065.Sp 1083.Sp
1066By 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
1067time 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,
1068at 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
1069\&\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
1070introduce 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
1071sleep 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
1072once per this interval, on average. 1090once per this interval, on average (as long as the host time resolution is
1091good enough).
1073.Sp 1092.Sp
1074Likewise, by setting a higher \fItimeout collect interval\fR you allow libev 1093Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
1075to spend more time collecting timeouts, at the expense of increased 1094to spend more time collecting timeouts, at the expense of increased
1076latency/jitter/inexactness (the watcher callback will be called 1095latency/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 1096later). \f(CW\*(C`ev_io\*(C'\fR watchers will not be affected. Setting this to a non-null
… …
1121this callback instead. This is useful, for example, when you want to 1140this callback instead. This is useful, for example, when you want to
1122invoke the actual watchers inside another context (another thread etc.). 1141invoke the actual watchers inside another context (another thread etc.).
1123.Sp 1142.Sp
1124If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new 1143If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new
1125callback. 1144callback.
1126.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0), void (*acquire)(\s-1EV_P\s0))" 4 1145.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0) throw (), void (*acquire)(\s-1EV_P\s0) throw ())" 4
1127.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))" 1146.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())"
1128Sometimes you want to share the same loop between multiple threads. This 1147Sometimes you want to share the same loop between multiple threads. This
1129can be done relatively simply by putting mutex_lock/unlock calls around 1148can be done relatively simply by putting mutex_lock/unlock calls around
1130each call to a libev function. 1149each call to a libev function.
1131.Sp 1150.Sp
1132However, \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
1133to 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
1134loop 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
1135\&\fIrelease\fR and \fIacquire\fR callbacks on the loop. 1154\&\fIrelease\fR and \fIacquire\fR callbacks on the loop.
1136.Sp 1155.Sp
1137When 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
1138suspended 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
1139afterwards. 1158afterwards.
… …
1280.PD 0 1299.PD 0
1281.ie n .IP """EV_CHECK""" 4 1300.ie n .IP """EV_CHECK""" 4
1282.el .IP "\f(CWEV_CHECK\fR" 4 1301.el .IP "\f(CWEV_CHECK\fR" 4
1283.IX Item "EV_CHECK" 1302.IX Item "EV_CHECK"
1284.PD 1303.PD
1285All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts 1304All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts to
1286to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after 1305gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are queued (not invoked)
1287\&\f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it invokes any callbacks for any 1306just after \f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it queues any callbacks
1307for any received events. That means \f(CW\*(C`ev_prepare\*(C'\fR watchers are the last
1308watchers invoked before the event loop sleeps or polls for new events, and
1309\&\f(CW\*(C`ev_check\*(C'\fR watchers will be invoked before any other watchers of the same
1310or lower priority within an event loop iteration.
1311.Sp
1288received events. Callbacks of both watcher types can start and stop as 1312Callbacks of both watcher types can start and stop as many watchers as
1289many watchers as they want, and all of them will be taken into account 1313they want, and all of them will be taken into account (for example, a
1290(for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep 1314\&\f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep \f(CW\*(C`ev_run\*(C'\fR from
1291\&\f(CW\*(C`ev_run\*(C'\fR from blocking). 1315blocking).
1292.ie n .IP """EV_EMBED""" 4 1316.ie n .IP """EV_EMBED""" 4
1293.el .IP "\f(CWEV_EMBED\fR" 4 1317.el .IP "\f(CWEV_EMBED\fR" 4
1294.IX Item "EV_EMBED" 1318.IX Item "EV_EMBED"
1295The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. 1319The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention.
1296.ie n .IP """EV_FORK""" 4 1320.ie n .IP """EV_FORK""" 4
… …
1417make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR 1441make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR
1418it). 1442it).
1419.IP "callback ev_cb (ev_TYPE *watcher)" 4 1443.IP "callback ev_cb (ev_TYPE *watcher)" 4
1420.IX Item "callback ev_cb (ev_TYPE *watcher)" 1444.IX Item "callback ev_cb (ev_TYPE *watcher)"
1421Returns the callback currently set on the watcher. 1445Returns the callback currently set on the watcher.
1422.IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 1446.IP "ev_set_cb (ev_TYPE *watcher, callback)" 4
1423.IX Item "ev_cb_set (ev_TYPE *watcher, callback)" 1447.IX Item "ev_set_cb (ev_TYPE *watcher, callback)"
1424Change the callback. You can change the callback at virtually any time 1448Change the callback. You can change the callback at virtually any time
1425(modulo threads). 1449(modulo threads).
1426.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 1450.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4
1427.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" 1451.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)"
1428.PD 0 1452.PD 0
… …
1486active, pending and so on. In this section these states and the rules to 1510active, 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 1511transition between them will be described in more detail \- and while these
1488rules might look complicated, they usually do \*(L"the right thing\*(R". 1512rules might look complicated, they usually do \*(L"the right thing\*(R".
1489.IP "initialiased" 4 1513.IP "initialiased" 4
1490.IX Item "initialiased" 1514.IX Item "initialiased"
1491Before a watcher can be registered with the event looop it has to be 1515Before 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 1516initialised. 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. 1517\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1494.Sp 1518.Sp
1495In this state it is simply some block of memory that is suitable for use 1519In 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. 1520use in an event loop. It can be moved around, freed, reused etc. at
1521will \- as long as you either keep the memory contents intact, or call
1522\&\f(CW\*(C`ev_TYPE_init\*(C'\fR again.
1497.IP "started/running/active" 4 1523.IP "started/running/active" 4
1498.IX Item "started/running/active" 1524.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 1525Once 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 1526property 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, 1527this state it cannot be accessed (except in a few documented ways), moved,
… …
1526latter will clear any pending state the watcher might be in, regardless 1552latter will clear any pending state the watcher might be in, regardless
1527of whether it was active or not, so stopping a watcher explicitly before 1553of whether it was active or not, so stopping a watcher explicitly before
1528freeing it is often a good idea. 1554freeing it is often a good idea.
1529.Sp 1555.Sp
1530While stopped (and not pending) the watcher is essentially in the 1556While stopped (and not pending) the watcher is essentially in the
1531initialised state, that is it can be reused, moved, modified in any way 1557initialised state, that is, it can be reused, moved, modified in any way
1532you wish. 1558you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR
1559it again).
1533.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" 1560.SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0"
1534.IX Subsection "WATCHER PRIORITY MODELS" 1561.IX Subsection "WATCHER PRIORITY MODELS"
1535Many event loops support \fIwatcher priorities\fR, which are usually small 1562Many event loops support \fIwatcher priorities\fR, which are usually small
1536integers that influence the ordering of event callback invocation 1563integers that influence the ordering of event callback invocation
1537between watchers in some way, all else being equal. 1564between watchers in some way, all else being equal.
… …
1865detecting time jumps is hard, and some inaccuracies are unavoidable (the 1892detecting time jumps is hard, and some inaccuracies are unavoidable (the
1866monotonic clock option helps a lot here). 1893monotonic clock option helps a lot here).
1867.PP 1894.PP
1868The callback is guaranteed to be invoked only \fIafter\fR its timeout has 1895The 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 1896passed (not \fIat\fR, so on systems with very low-resolution clocks this
1870might introduce a small delay). If multiple timers become ready during the 1897might introduce a small delay, see \*(L"the special problem of being too
1898early\*(R", below). If multiple timers become ready during the same loop
1871same loop iteration then the ones with earlier time-out values are invoked 1899iteration 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 1900ones 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). 1901longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively).
1874.PP 1902.PP
1875\fIBe smart about timeouts\fR 1903\fIBe smart about timeouts\fR
1876.IX Subsection "Be smart about timeouts" 1904.IX Subsection "Be smart about timeouts"
1877.PP 1905.PP
1878Many real-world problems involve some kind of timeout, usually for error 1906Many real-world problems involve some kind of timeout, usually for error
… …
1960.Sp 1988.Sp
1961In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, 1989In 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 1990but remember the time of last activity, and check for a real timeout only
1963within the callback: 1991within the callback:
1964.Sp 1992.Sp
1965.Vb 1 1993.Vb 3
1994\& ev_tstamp timeout = 60.;
1966\& ev_tstamp last_activity; // time of last activity 1995\& ev_tstamp last_activity; // time of last activity
1996\& ev_timer timer;
1967\& 1997\&
1968\& static void 1998\& static void
1969\& callback (EV_P_ ev_timer *w, int revents) 1999\& callback (EV_P_ ev_timer *w, int revents)
1970\& { 2000\& {
1971\& ev_tstamp now = ev_now (EV_A); 2001\& // calculate when the timeout would happen
1972\& ev_tstamp timeout = last_activity + 60.; 2002\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout;
1973\& 2003\&
1974\& // if last_activity + 60. is older than now, we did time out 2004\& // if negative, it means we the timeout already occurred
1975\& if (timeout < now) 2005\& if (after < 0.)
1976\& { 2006\& {
1977\& // timeout occurred, take action 2007\& // timeout occurred, take action
1978\& } 2008\& }
1979\& else 2009\& else
1980\& { 2010\& {
1981\& // callback was invoked, but there was some activity, re\-arm 2011\& // callback was invoked, but there was some recent
1982\& // the watcher to fire in last_activity + 60, which is 2012\& // activity. simply restart the timer to time out
1983\& // guaranteed to be in the future, so "again" is positive: 2013\& // after "after" seconds, which is the earliest time
1984\& w\->repeat = timeout \- now; 2014\& // the timeout can occur.
2015\& ev_timer_set (w, after, 0.);
1985\& ev_timer_again (EV_A_ w); 2016\& ev_timer_start (EV_A_ w);
1986\& } 2017\& }
1987\& } 2018\& }
1988.Ve 2019.Ve
1989.Sp 2020.Sp
1990To summarise the callback: first calculate the real timeout (defined 2021To 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 2022timeout will occur (by calculating the absolute time when it would occur,
1992been reached, which means something \fIdid\fR, in fact, time out. Otherwise 2023\&\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 2024(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 2025.Sp
1997Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the 2026If 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. 2027timed out, and need to do whatever is needed in this case.
2028.Sp
2029Otherwise, we now the earliest time at which the timeout would trigger,
2030and simply start the timer with this timeout value.
2031.Sp
2032In other words, each time the callback is invoked it will check whether
2033the timeout occurred. If not, it will simply reschedule itself to check
2034again at the earliest time it could time out. Rinse. Repeat.
1999.Sp 2035.Sp
2000This scheme causes more callback invocations (about one every 60 seconds 2036This scheme causes more callback invocations (about one every 60 seconds
2001minus half the average time between activity), but virtually no calls to 2037minus half the average time between activity), but virtually no calls to
2002libev to change the timeout. 2038libev to change the timeout.
2003.Sp 2039.Sp
2004To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR 2040To start the machinery, simply initialise the watcher and set
2005to the current time (meaning we just have some activity :), then call the 2041\&\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: 2042now), then call the callback, which will \*(L"do the right thing\*(R" and start
2043the timer:
2007.Sp 2044.Sp
2008.Vb 3 2045.Vb 3
2046\& last_activity = ev_now (EV_A);
2009\& ev_init (timer, callback); 2047\& ev_init (&timer, callback);
2010\& last_activity = ev_now (loop); 2048\& callback (EV_A_ &timer, 0);
2011\& callback (loop, timer, EV_TIMER);
2012.Ve 2049.Ve
2013.Sp 2050.Sp
2014And when there is some activity, simply store the current time in 2051When there is some activity, simply store the current time in
2015\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all: 2052\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all:
2016.Sp 2053.Sp
2017.Vb 1 2054.Vb 2
2055\& if (activity detected)
2018\& last_activity = ev_now (loop); 2056\& last_activity = ev_now (EV_A);
2057.Ve
2058.Sp
2059When your timeout value changes, then the timeout can be changed by simply
2060providing a new value, stopping the timer and calling the callback, which
2061will again do the right thing (for example, time out immediately :).
2062.Sp
2063.Vb 3
2064\& timeout = new_value;
2065\& ev_timer_stop (EV_A_ &timer);
2066\& callback (EV_A_ &timer, 0);
2019.Ve 2067.Ve
2020.Sp 2068.Sp
2021This technique is slightly more complex, but in most cases where the 2069This technique is slightly more complex, but in most cases where the
2022time-out is unlikely to be triggered, much more efficient. 2070time-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 2071.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." 2072.IX Item "4. Wee, just use a double-linked list for your timeouts."
2029If there is not one request, but many thousands (millions...), all 2073If there is not one request, but many thousands (millions...), all
2030employing some kind of timeout with the same timeout value, then one can 2074employing some kind of timeout with the same timeout value, then one can
2031do even better: 2075do even better:
… …
2055Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 2099Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
2056rather complicated, but extremely efficient, something that really pays 2100rather complicated, but extremely efficient, something that really pays
2057off after the first million or so of active timers, i.e. it's usually 2101off after the first million or so of active timers, i.e. it's usually
2058overkill :) 2102overkill :)
2059.PP 2103.PP
2104\fIThe special problem of being too early\fR
2105.IX Subsection "The special problem of being too early"
2106.PP
2107If you ask a timer to call your callback after three seconds, then
2108you expect it to be invoked after three seconds \- but of course, this
2109cannot be guaranteed to infinite precision. Less obviously, it cannot be
2110guaranteed to any precision by libev \- imagine somebody suspending the
2111process with a \s-1STOP\s0 signal for a few hours for example.
2112.PP
2113So, libev tries to invoke your callback as soon as possible \fIafter\fR the
2114delay has occurred, but cannot guarantee this.
2115.PP
2116A less obvious failure mode is calling your callback too early: many event
2117loops compare timestamps with a \*(L"elapsed delay >= requested delay\*(R", but
2118this can cause your callback to be invoked much earlier than you would
2119expect.
2120.PP
2121To see why, imagine a system with a clock that only offers full second
2122resolution (think windows if you can't come up with a broken enough \s-1OS\s0
2123yourself). If you schedule a one-second timer at the time 500.9, then the
2124event loop will schedule your timeout to elapse at a system time of 500
2125(500.9 truncated to the resolution) + 1, or 501.
2126.PP
2127If an event library looks at the timeout 0.1s later, it will see \*(L"501 >=
2128501\*(R" and invoke the callback 0.1s after it was started, even though a
2129one-second delay was requested \- this is being \*(L"too early\*(R", despite best
2130intentions.
2131.PP
2132This is the reason why libev will never invoke the callback if the elapsed
2133delay equals the requested delay, but only when the elapsed delay is
2134larger than the requested delay. In the example above, libev would only invoke
2135the callback at system time 502, or 1.1s after the timer was started.
2136.PP
2137So, while libev cannot guarantee that your callback will be invoked
2138exactly when requested, it \fIcan\fR and \fIdoes\fR guarantee that the requested
2139delay has actually elapsed, or in other words, it always errs on the \*(L"too
2140late\*(R" side of things.
2141.PP
2060\fIThe special problem of time updates\fR 2142\fIThe special problem of time updates\fR
2061.IX Subsection "The special problem of time updates" 2143.IX Subsection "The special problem of time updates"
2062.PP 2144.PP
2063Establishing the current time is a costly operation (it usually takes at 2145Establishing the current time is a costly operation (it usually takes
2064least two system calls): \s-1EV\s0 therefore updates its idea of the current 2146at 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 2147time 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 2148growing 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. 2149lots of events in one iteration.
2068.PP 2150.PP
2069The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2151The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
… …
2077.Ve 2159.Ve
2078.PP 2160.PP
2079If the event loop is suspended for a long time, you can also force an 2161If 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 2162update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2081()\*(C'\fR. 2163()\*(C'\fR.
2164.PP
2165\fIThe special problem of unsynchronised clocks\fR
2166.IX Subsection "The special problem of unsynchronised clocks"
2167.PP
2168Modern systems have a variety of clocks \- libev itself uses the normal
2169\&\*(L"wall clock\*(R" clock and, if available, the monotonic clock (to avoid time
2170jumps).
2171.PP
2172Neither of these clocks is synchronised with each other or any other clock
2173on the system, so \f(CW\*(C`ev_time ()\*(C'\fR might return a considerably different time
2174than \f(CW\*(C`gettimeofday ()\*(C'\fR or \f(CW\*(C`time ()\*(C'\fR. On a GNU/Linux system, for example,
2175a call to \f(CW\*(C`gettimeofday\*(C'\fR might return a second count that is one higher
2176than a directly following call to \f(CW\*(C`time\*(C'\fR.
2177.PP
2178The moral of this is to only compare libev-related timestamps with
2179\&\f(CW\*(C`ev_time ()\*(C'\fR and \f(CW\*(C`ev_now ()\*(C'\fR, at least if you want better precision than
2180a second or so.
2181.PP
2182One more problem arises due to this lack of synchronisation: if libev uses
2183the system monotonic clock and you compare timestamps from \f(CW\*(C`ev_time\*(C'\fR
2184or \f(CW\*(C`ev_now\*(C'\fR from when you started your timer and when your callback is
2185invoked, you will find that sometimes the callback is a bit \*(L"early\*(R".
2186.PP
2187This is because \f(CW\*(C`ev_timer\*(C'\fRs work in real time, not wall clock time, so
2188libev makes sure your callback is not invoked before the delay happened,
2189\&\fImeasured according to the real time\fR, not the system clock.
2190.PP
2191If your timeouts are based on a physical timescale (e.g. \*(L"time out this
2192connection after 100 seconds\*(R") then this shouldn't bother you as it is
2193exactly the right behaviour.
2194.PP
2195If you want to compare wall clock/system timestamps to your timers, then
2196you need to use \f(CW\*(C`ev_periodic\*(C'\fRs, as these are based on the wall clock
2197time, where your comparisons will always generate correct results.
2082.PP 2198.PP
2083\fIThe special problems of suspended animation\fR 2199\fIThe special problems of suspended animation\fR
2084.IX Subsection "The special problems of suspended animation" 2200.IX Subsection "The special problems of suspended animation"
2085.PP 2201.PP
2086When you leave the server world it is quite customary to hit machines that 2202When you leave the server world it is quite customary to hit machines that
… …
2130trigger at exactly 10 second intervals. If, however, your program cannot 2246trigger at exactly 10 second intervals. If, however, your program cannot
2131keep up with the timer (because it takes longer than those 10 seconds to 2247keep 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. 2248do stuff) the timer will not fire more than once per event loop iteration.
2133.IP "ev_timer_again (loop, ev_timer *)" 4 2249.IP "ev_timer_again (loop, ev_timer *)" 4
2134.IX Item "ev_timer_again (loop, ev_timer *)" 2250.IX Item "ev_timer_again (loop, ev_timer *)"
2135This will act as if the timer timed out and restart it again if it is 2251This will act as if the timer timed out, and restarts it again if it is
2136repeating. The exact semantics are: 2252repeating. It basically works like calling \f(CW\*(C`ev_timer_stop\*(C'\fR, updating the
2253timeout to the \f(CW\*(C`repeat\*(C'\fR value and calling \f(CW\*(C`ev_timer_start\*(C'\fR.
2137.Sp 2254.Sp
2255The exact semantics are as in the following rules, all of which will be
2256applied to the watcher:
2257.RS 4
2138If the timer is pending, its pending status is cleared. 2258.IP "If the timer is pending, the pending status is always cleared." 4
2139.Sp 2259.IX Item "If the timer is pending, the pending status is always cleared."
2260.PD 0
2140If the timer is started but non-repeating, stop it (as if it timed out). 2261.IP "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." 4
2141.Sp 2262.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 2263.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. 2264.el .IP "If the timer is repeating, make the \f(CWrepeat\fR value the new timeout and start the timer, if necessary." 4
2265.IX Item "If the timer is repeating, make the repeat value the new timeout and start the timer, if necessary."
2266.RE
2267.RS 4
2268.PD
2144.Sp 2269.Sp
2145This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a 2270This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a
2146usage example. 2271usage example.
2272.RE
2147.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 2273.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4
2148.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 2274.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)"
2149Returns the remaining time until a timer fires. If the timer is active, 2275Returns 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 2276then this time is relative to the current event loop time, otherwise it's
2151the timeout value currently configured. 2277the timeout value currently configured.
… …
2271.Sp 2397.Sp
2272Another way to think about it (for the mathematically inclined) is that 2398Another 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 2399\&\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. 2400time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps.
2275.Sp 2401.Sp
2276For numerical stability it is preferable that the \f(CW\*(C`offset\*(C'\fR value is near 2402The \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 2403interval 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. 2404microseconds) and \f(CW\*(C`offset\*(C'\fR should be higher than \f(CW0\fR and should have
2405at most a similar magnitude as the current time (say, within a factor of
2406ten). Typical values for offset are, in fact, \f(CW0\fR or something between
2407\&\f(CW0\fR and \f(CW\*(C`interval\*(C'\fR, which is also the recommended range.
2279.Sp 2408.Sp
2280Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0 2409Note 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 2410speed 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 2411will 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). 2412millisecond (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" 2558.IX Subsection "The special problem of inheritance over fork/execve/pthread_create"
2430.PP 2559.PP
2431Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition 2560Both 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 2561(\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, 2562stopping it again), that is, libev might or might not block the signal,
2434and might or might not set or restore the installed signal handler. 2563and might or might not set or restore the installed signal handler (but
2564see \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR).
2435.PP 2565.PP
2436While this does not matter for the signal disposition (libev never 2566While 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 2567sets 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 2568\&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect
2439certain signals to be blocked. 2569certain signals to be blocked.
… …
2852Apart from keeping your process non-blocking (which is a useful 2982Apart from keeping your process non-blocking (which is a useful
2853effect on its own sometimes), idle watchers are a good place to do 2983effect on its own sometimes), idle watchers are a good place to do
2854\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the 2984\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the
2855event loop has handled all outstanding events. 2985event loop has handled all outstanding events.
2856.PP 2986.PP
2987\fIAbusing an \f(CI\*(C`ev_idle\*(C'\fI watcher for its side-effect\fR
2988.IX Subsection "Abusing an ev_idle watcher for its side-effect"
2989.PP
2990As long as there is at least one active idle watcher, libev will never
2991sleep unnecessarily. Or in other words, it will loop as fast as possible.
2992For this to work, the idle watcher doesn't need to be invoked at all \- the
2993lowest priority will do.
2994.PP
2995This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher,
2996to do something on each event loop iteration \- for example to balance load
2997between different connections.
2998.PP
2999See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer
3000example.
3001.PP
2857\fIWatcher-Specific Functions and Data Members\fR 3002\fIWatcher-Specific Functions and Data Members\fR
2858.IX Subsection "Watcher-Specific Functions and Data Members" 3003.IX Subsection "Watcher-Specific Functions and Data Members"
2859.IP "ev_idle_init (ev_idle *, callback)" 4 3004.IP "ev_idle_init (ev_idle *, callback)" 4
2860.IX Item "ev_idle_init (ev_idle *, callback)" 3005.IX Item "ev_idle_init (ev_idle *, callback)"
2861Initialises and configures the idle watcher \- it has no parameters of any 3006Initialises and configures the idle watcher \- it has no parameters of any
… …
2866.IX Subsection "Examples" 3011.IX Subsection "Examples"
2867.PP 3012.PP
2868Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the 3013Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the
2869callback, free it. Also, use no error checking, as usual. 3014callback, free it. Also, use no error checking, as usual.
2870.PP 3015.PP
2871.Vb 7 3016.Vb 5
2872\& static void 3017\& static void
2873\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) 3018\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
2874\& { 3019\& {
3020\& // stop the watcher
3021\& ev_idle_stop (loop, w);
3022\&
3023\& // now we can free it
2875\& free (w); 3024\& free (w);
3025\&
2876\& // now do something you wanted to do when the program has 3026\& // now do something you wanted to do when the program has
2877\& // no longer anything immediate to do. 3027\& // no longer anything immediate to do.
2878\& } 3028\& }
2879\& 3029\&
2880\& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 3030\& ev_idle *idle_watcher = malloc (sizeof (ev_idle));
… …
2882\& ev_idle_start (loop, idle_watcher); 3032\& ev_idle_start (loop, idle_watcher);
2883.Ve 3033.Ve
2884.ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" 3034.ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!"
2885.el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" 3035.el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!"
2886.IX Subsection "ev_prepare and ev_check - customise your event loop!" 3036.IX Subsection "ev_prepare and ev_check - customise your event loop!"
2887Prepare and check watchers are usually (but not always) used in pairs: 3037Prepare and check watchers are often (but not always) used in pairs:
2888prepare watchers get invoked before the process blocks and check watchers 3038prepare watchers get invoked before the process blocks and check watchers
2889afterwards. 3039afterwards.
2890.PP 3040.PP
2891You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3041You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter
2892the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR 3042the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR
… …
2920with priority higher than or equal to the event loop and one coroutine 3070with priority higher than or equal to the event loop and one coroutine
2921of lower priority, but only once, using idle watchers to keep the event 3071of lower priority, but only once, using idle watchers to keep the event
2922loop from blocking if lower-priority coroutines are active, thus mapping 3072loop from blocking if lower-priority coroutines are active, thus mapping
2923low-priority coroutines to idle/background tasks). 3073low-priority coroutines to idle/background tasks).
2924.PP 3074.PP
2925It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 3075When used for this purpose, it is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers
2926priority, to ensure that they are being run before any other watchers 3076highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) priority, to ensure that they are being run before
2927after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR watchers). 3077any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR
3078watchers).
2928.PP 3079.PP
2929Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not 3080Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not
2930activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they 3081activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they
2931might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As 3082might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As
2932\&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event 3083\&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event
2933loops those other event loops might be in an unusable state until their 3084loops those other event loops might be in an unusable state until their
2934\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with 3085\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with
2935others). 3086others).
3087.PP
3088\fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR
3089.IX Subsection "Abusing an ev_check watcher for its side-effect"
3090.PP
3091\&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be
3092useful because they are called once per event loop iteration. For
3093example, if you want to handle a large number of connections fairly, you
3094normally only do a bit of work for each active connection, and if there
3095is more work to do, you wait for the next event loop iteration, so other
3096connections have a chance of making progress.
3097.PP
3098Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the
3099next event loop iteration. However, that isn't as soon as possible \-
3100without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked.
3101.PP
3102This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a
3103single global idle watcher that is active as long as you have one active
3104\&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop
3105will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets
3106invoked. Neither watcher alone can do that.
2936.PP 3107.PP
2937\fIWatcher-Specific Functions and Data Members\fR 3108\fIWatcher-Specific Functions and Data Members\fR
2938.IX Subsection "Watcher-Specific Functions and Data Members" 3109.IX Subsection "Watcher-Specific Functions and Data Members"
2939.IP "ev_prepare_init (ev_prepare *, callback)" 4 3110.IP "ev_prepare_init (ev_prepare *, callback)" 4
2940.IX Item "ev_prepare_init (ev_prepare *, callback)" 3111.IX Item "ev_prepare_init (ev_prepare *, callback)"
… …
3307\& atexit (program_exits); 3478\& atexit (program_exits);
3308.Ve 3479.Ve
3309.ie n .SS """ev_async"" \- how to wake up an event loop" 3480.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" 3481.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" 3482.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 3483In 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 3484asynchronous sources such as signal handlers (as opposed to multiple event
3314loops \- those are of course safe to use in different threads). 3485loops \- those are of course safe to use in different threads).
3315.PP 3486.PP
3316Sometimes, however, you need to wake up an event loop you do not control, 3487Sometimes, 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 3488for example because it belongs to another thread. This is what \f(CW\*(C`ev_async\*(C'\fR
… …
3319it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe. 3490it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe.
3320.PP 3491.PP
3321This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, 3492This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals,
3322too, are asynchronous in nature, and signals, too, will be compressed 3493too, are asynchronous in nature, and signals, too, will be compressed
3323(i.e. the number of callback invocations may be less than the number of 3494(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 3495\&\f(CW\*(C`ev_async_send\*(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 3496of \*(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, 3497signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread,
3327even without knowing which loop owns the signal. 3498even 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 3499.PP
3332\fIQueueing\fR 3500\fIQueueing\fR
3333.IX Subsection "Queueing" 3501.IX Subsection "Queueing"
3334.PP 3502.PP
3335\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason 3503\&\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, 3590kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless,
3423trust me. 3591trust me.
3424.IP "ev_async_send (loop, ev_async *)" 4 3592.IP "ev_async_send (loop, ev_async *)" 4
3425.IX Item "ev_async_send (loop, ev_async *)" 3593.IX Item "ev_async_send (loop, ev_async *)"
3426Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds 3594Sends/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 3595an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop, and instantly
3596returns.
3597.Sp
3428\&\f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, signal or 3598Unlike \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 3599signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the
3430section below on what exactly this means). 3600embedding section below on what exactly this means).
3431.Sp 3601.Sp
3432Note that, as with other watchers in libev, multiple events might get 3602Note that, as with other watchers in libev, multiple events might get
3433compressed into a single callback invocation (another way to look at this 3603compressed 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, 3604this is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered: they are set on
3435reset when the event loop detects that). 3605\&\f(CW\*(C`ev_async_send\*(C'\fR, reset when the event loop detects that).
3436.Sp 3606.Sp
3437This call incurs the overhead of a system call only once per event loop 3607This 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 3608loop 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. 3609the event loop (or your program) is processing events. That means that
3610repeated calls are basically free (there is no need to avoid calls for
3611performance reasons) and that the overhead becomes smaller (typically
3612zero) under load.
3440.IP "bool = ev_async_pending (ev_async *)" 4 3613.IP "bool = ev_async_pending (ev_async *)" 4
3441.IX Item "bool = ev_async_pending (ev_async *)" 3614.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 3615Returns 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 3616watcher but the event has not yet been processed (or even noted) by the
3444event loop. 3617event loop.
… …
3492\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3665\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3493.Ve 3666.Ve
3494.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 3667.IP "ev_feed_fd_event (loop, int fd, int revents)" 4
3495.IX Item "ev_feed_fd_event (loop, int fd, int revents)" 3668.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 3669Feed an event on the given fd, as if a file descriptor backend detected
3497the given events it. 3670the given events.
3498.IP "ev_feed_signal_event (loop, int signum)" 4 3671.IP "ev_feed_signal_event (loop, int signum)" 4
3499.IX Item "ev_feed_signal_event (loop, int signum)" 3672.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, 3673Feed an event as if the given signal occurred. See also \f(CW\*(C`ev_feed_signal\*(C'\fR,
3501which is async-safe. 3674which is async-safe.
3502.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3675.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
… …
3576\& { 3749\& {
3577\& struct my_biggy big = (struct my_biggy *) 3750\& struct my_biggy big = (struct my_biggy *)
3578\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3751\& (((char *)w) \- offsetof (struct my_biggy, t2));
3579\& } 3752\& }
3580.Ve 3753.Ve
3754.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0"
3755.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3756Often you have structures like this in event-based programs:
3757.PP
3758.Vb 4
3759\& callback ()
3760\& {
3761\& free (request);
3762\& }
3763\&
3764\& request = start_new_request (..., callback);
3765.Ve
3766.PP
3767The intent is to start some \*(L"lengthy\*(R" operation. The \f(CW\*(C`request\*(C'\fR could be
3768used to cancel the operation, or do other things with it.
3769.PP
3770It's not uncommon to have code paths in \f(CW\*(C`start_new_request\*(C'\fR that
3771immediately invoke the callback, for example, to report errors. Or you add
3772some caching layer that finds that it can skip the lengthy aspects of the
3773operation and simply invoke the callback with the result.
3774.PP
3775The problem here is that this will happen \fIbefore\fR \f(CW\*(C`start_new_request\*(C'\fR
3776has returned, so \f(CW\*(C`request\*(C'\fR is not set.
3777.PP
3778Even if you pass the request by some safer means to the callback, you
3779might want to do something to the request after starting it, such as
3780canceling it, which probably isn't working so well when the callback has
3781already been invoked.
3782.PP
3783A common way around all these issues is to make sure that
3784\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If
3785\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
3786delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher
3787for example, or more sneakily, by reusing an existing (stopped) watcher
3788and pushing it into the pending queue:
3789.PP
3790.Vb 2
3791\& ev_set_cb (watcher, callback);
3792\& ev_feed_event (EV_A_ watcher, 0);
3793.Ve
3794.PP
3795This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3796invoked, 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" 3797.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" 3798.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3583Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3799Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3584\&\fImodal\fR interaction, which is most easily implemented by recursively 3800\&\fImodal\fR interaction, which is most easily implemented by recursively
3585invoking \f(CW\*(C`ev_run\*(C'\fR. 3801invoking \f(CW\*(C`ev_run\*(C'\fR.
… …
3599\& int exit_main_loop = 0; 3815\& int exit_main_loop = 0;
3600\& 3816\&
3601\& while (!exit_main_loop) 3817\& while (!exit_main_loop)
3602\& ev_run (EV_DEFAULT_ EVRUN_ONCE); 3818\& ev_run (EV_DEFAULT_ EVRUN_ONCE);
3603\& 3819\&
3604\& // in a model watcher 3820\& // in a modal watcher
3605\& int exit_nested_loop = 0; 3821\& int exit_nested_loop = 0;
3606\& 3822\&
3607\& while (!exit_nested_loop) 3823\& while (!exit_nested_loop)
3608\& ev_run (EV_A_ EVRUN_ONCE); 3824\& ev_run (EV_A_ EVRUN_ONCE);
3609.Ve 3825.Ve
… …
3658\& // now associate this with the loop 3874\& // now associate this with the loop
3659\& ev_set_userdata (EV_A_ u); 3875\& ev_set_userdata (EV_A_ u);
3660\& ev_set_invoke_pending_cb (EV_A_ l_invoke); 3876\& ev_set_invoke_pending_cb (EV_A_ l_invoke);
3661\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 3877\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3662\& 3878\&
3663\& // then create the thread running ev_loop 3879\& // then create the thread running ev_run
3664\& pthread_create (&u\->tid, 0, l_run, EV_A); 3880\& pthread_create (&u\->tid, 0, l_run, EV_A);
3665\& } 3881\& }
3666.Ve 3882.Ve
3667.PP 3883.PP
3668The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used 3884The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used
… …
3801.PP 4017.PP
3802.Vb 6 4018.Vb 6
3803\& void 4019\& void
3804\& wait_for_event (ev_watcher *w) 4020\& wait_for_event (ev_watcher *w)
3805\& { 4021\& {
3806\& ev_cb_set (w) = current_coro; 4022\& ev_set_cb (w, current_coro);
3807\& switch_to (libev_coro); 4023\& switch_to (libev_coro);
3808\& } 4024\& }
3809.Ve 4025.Ve
3810.PP 4026.PP
3811That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and 4027That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and
3812continues the libev coroutine, which, when appropriate, switches back to 4028continues the libev coroutine, which, when appropriate, switches back to
3813this or any other coroutine. I am sure if you sue this your own :) 4029this or any other coroutine.
3814.PP 4030.PP
3815You can do similar tricks if you have, say, threads with an event queue \- 4031You 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 4032instead 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 4033switching to a coroutine, you push the watcher onto the queue and notify
3818any waiters. 4034any waiters.
3819.PP 4035.PP
3820To embed libev, see \s-1EMBEDDING\s0, but in short, it's easiest to create two 4036To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two
3821files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4037files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
3822.PP 4038.PP
3823.Vb 4 4039.Vb 4
3824\& // my_ev.h 4040\& // my_ev.h
3825\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4041\& #define EV_CB_DECLARE(type) struct my_coro *cb;
… …
3864.IP "\(bu" 4 4080.IP "\(bu" 4
3865The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need 4081The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
3866to use the libev header file and library. 4082to use the libev header file and library.
3867.SH "\*(C+ SUPPORT" 4083.SH "\*(C+ SUPPORT"
3868.IX Header " SUPPORT" 4084.IX Header " SUPPORT"
4085.SS "C \s-1API\s0"
4086.IX Subsection "C API"
4087The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4088libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4089will work fine.
4090.PP
4091Proper exception specifications might have to be added to callbacks passed
4092to libev: exceptions may be thrown only from watcher callbacks, all
4093other callbacks (allocator, syserr, loop acquire/release and periodic
4094reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw
4095()\*(C'\fR specification. If you have code that needs to be compiled as both C
4096and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
4097.PP
4098.Vb 6
4099\& static void
4100\& fatal_error (const char *msg) EV_THROW
4101\& {
4102\& perror (msg);
4103\& abort ();
4104\& }
4105\&
4106\& ...
4107\& ev_set_syserr_cb (fatal_error);
4108.Ve
4109.PP
4110The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR,
4111\&\f(CW\*(C`ev_invoke\*(C'\fR, \f(CW\*(C`ev_invoke_pending\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR (the latter
4112because it runs cleanup watchers).
4113.PP
4114Throwing exceptions in watcher callbacks is only supported if libev itself
4115is compiled with a \*(C+ compiler or your C and \*(C+ environments allow
4116throwing exceptions through C libraries (most do).
4117.SS "\*(C+ \s-1API\s0"
4118.IX Subsection " API"
3869Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow 4119Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
3870you to use some convenience methods to start/stop watchers and also change 4120you to use some convenience methods to start/stop watchers and also change
3871the callback model to a model using method callbacks on objects. 4121the callback model to a model using method callbacks on objects.
3872.PP 4122.PP
3873To use it, 4123To use it,
… …
3889Currently, functions, static and non-static member functions and classes 4139Currently, functions, static and non-static member functions and classes
3890with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy 4140with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy
3891to add as long as they only need one additional pointer for context. If 4141to add as long as they only need one additional pointer for context. If
3892you need support for other types of functors please contact the author 4142you need support for other types of functors please contact the author
3893(preferably after implementing it). 4143(preferably after implementing it).
4144.PP
4145For all this to work, your \*(C+ compiler either has to use the same calling
4146conventions as your C compiler (for static member functions), or you have
4147to embed libev and compile libev itself as \*(C+.
3894.PP 4148.PP
3895Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: 4149Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace:
3896.ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4 4150.ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4
3897.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4 4151.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4
3898.IX Item "ev::READ, ev::WRITE etc." 4152.IX Item "ev::READ, ev::WRITE etc."
… …
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 4160.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." 4161.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 4162For 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 4163the 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 4164which 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. 4165defined by many implementations.
3912.Sp 4166.Sp
3913All of those classes have these methods: 4167All of those classes have these methods:
3914.RS 4 4168.RS 4
3915.IP "ev::TYPE::TYPE ()" 4 4169.IP "ev::TYPE::TYPE ()" 4
3916.IX Item "ev::TYPE::TYPE ()" 4170.IX Item "ev::TYPE::TYPE ()"
… …
4047.PP 4301.PP
4048.Vb 5 4302.Vb 5
4049\& class myclass 4303\& class myclass
4050\& { 4304\& {
4051\& ev::io io ; void io_cb (ev::io &w, int revents); 4305\& ev::io io ; void io_cb (ev::io &w, int revents);
4052\& ev::io2 io2 ; void io2_cb (ev::io &w, int revents); 4306\& ev::io io2 ; void io2_cb (ev::io &w, int revents);
4053\& ev::idle idle; void idle_cb (ev::idle &w, int revents); 4307\& ev::idle idle; void idle_cb (ev::idle &w, int revents);
4054\& 4308\&
4055\& myclass (int fd) 4309\& myclass (int fd)
4056\& { 4310\& {
4057\& io .set <myclass, &myclass::io_cb > (this); 4311\& 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 4350Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4097makes rev work even on mingw. 4351makes rev work even on mingw.
4098.IP "Haskell" 4 4352.IP "Haskell" 4
4099.IX Item "Haskell" 4353.IX Item "Haskell"
4100A haskell binding to libev is available at 4354A haskell binding to libev is available at
4101<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>. 4355http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
4102.IP "D" 4 4356.IP "D" 4
4103.IX Item "D" 4357.IX Item "D"
4104Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4358Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4105be found at <http://proj.llucax.com.ar/wiki/evd>. 4359be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4106.IP "Ocaml" 4 4360.IP "Ocaml" 4
4107.IX Item "Ocaml" 4361.IX Item "Ocaml"
4108Erkki Seppala has written Ocaml bindings for libev, to be found at 4362Erkki Seppala has written Ocaml bindings for libev, to be found at
4109<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. 4363http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
4110.IP "Lua" 4 4364.IP "Lua" 4
4111.IX Item "Lua" 4365.IX Item "Lua"
4112Brian Maher has written a partial interface to libev for lua (at the 4366Brian 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 4367time 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>. 4368http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4369.IP "Javascript" 4
4370.IX Item "Javascript"
4371Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4372.IP "Others" 4
4373.IX Item "Others"
4374There are others, and I stopped counting.
4115.SH "MACRO MAGIC" 4375.SH "MACRO MAGIC"
4116.IX Header "MACRO MAGIC" 4376.IX Header "MACRO MAGIC"
4117Libev can be compiled with a variety of options, the most fundamental 4377Libev 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) 4378of 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. 4379functions 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. 4414suitable for use with \f(CW\*(C`EV_A\*(C'\fR.
4155.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4 4415.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4
4156.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 4416.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
4157.IX Item "EV_DEFAULT, EV_DEFAULT_" 4417.IX Item "EV_DEFAULT, EV_DEFAULT_"
4158Similar to the other two macros, this gives you the value of the default 4418Similar to the other two macros, this gives you the value of the default
4159loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 4419loop, if multiple loops are supported (\*(L"ev loop default\*(R"). The default loop
4420will be initialised if it isn't already initialised.
4421.Sp
4422For non-multiplicity builds, these macros do nothing, so you always have
4423to initialise the loop somewhere.
4160.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4 4424.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4
4161.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4 4425.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4
4162.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_" 4426.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 4427Usage 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 4428default 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 4583supported). 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. 4584\&\fIevent.h\fR that are not directly supported by the libev core alone.
4321.Sp 4585.Sp
4322In standalone mode, libev will still try to automatically deduce the 4586In standalone mode, libev will still try to automatically deduce the
4323configuration, but has to be more conservative. 4587configuration, but has to be more conservative.
4588.IP "\s-1EV_USE_FLOOR\s0" 4
4589.IX Item "EV_USE_FLOOR"
4590If defined to be \f(CW1\fR, libev will use the \f(CW\*(C`floor ()\*(C'\fR function for its
4591periodic reschedule calculations, otherwise libev will fall back on a
4592portable (slower) implementation. If you enable this, you usually have to
4593link against libm or something equivalent. Enabling this when the \f(CW\*(C`floor\*(C'\fR
4594function is not available will fail, so the safe default is to not enable
4595this.
4324.IP "\s-1EV_USE_MONOTONIC\s0" 4 4596.IP "\s-1EV_USE_MONOTONIC\s0" 4
4325.IX Item "EV_USE_MONOTONIC" 4597.IX Item "EV_USE_MONOTONIC"
4326If defined to be \f(CW1\fR, libev will try to detect the availability of the 4598If 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 4599monotonic clock option at both compile time and runtime. Otherwise no
4328use of the monotonic clock option will be attempted. If you enable this, 4600use of the monotonic clock option will be attempted. If you enable this,
… …
4402.IX Item "EV_WIN32_CLOSE_FD(fd)" 4674.IX Item "EV_WIN32_CLOSE_FD(fd)"
4403If programs implement their own fd to handle mapping on win32, then this 4675If programs implement their own fd to handle mapping on win32, then this
4404macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister 4676macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister
4405file descriptors again. Note that the replacement function has to close 4677file descriptors again. Note that the replacement function has to close
4406the underlying \s-1OS\s0 handle. 4678the underlying \s-1OS\s0 handle.
4679.IP "\s-1EV_USE_WSASOCKET\s0" 4
4680.IX Item "EV_USE_WSASOCKET"
4681If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal
4682communication socket, which works better in some environments. Otherwise,
4683the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other
4684environments.
4407.IP "\s-1EV_USE_POLL\s0" 4 4685.IP "\s-1EV_USE_POLL\s0" 4
4408.IX Item "EV_USE_POLL" 4686.IX Item "EV_USE_POLL"
4409If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) 4687If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
4410backend. Otherwise it will be enabled on non\-win32 platforms. It 4688backend. Otherwise it will be enabled on non\-win32 platforms. It
4411takes precedence over select. 4689takes precedence over select.
… …
4440.IX Item "EV_USE_INOTIFY" 4718.IX Item "EV_USE_INOTIFY"
4441If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify 4719If 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 4720interface 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 4721be detected at runtime. If undefined, it will be enabled if the headers
4444indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4722indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4723.IP "\s-1EV_NO_SMP\s0" 4
4724.IX Item "EV_NO_SMP"
4725If defined to be \f(CW1\fR, libev will assume that memory is always coherent
4726between threads, that is, threads can be used, but threads never run on
4727different cpus (or different cpu cores). This reduces dependencies
4728and makes libev faster.
4729.IP "\s-1EV_NO_THREADS\s0" 4
4730.IX Item "EV_NO_THREADS"
4731If defined to be \f(CW1\fR, libev will assume that it will never be called
4732from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR,
4733above. This reduces dependencies and makes libev faster.
4445.IP "\s-1EV_ATOMIC_T\s0" 4 4734.IP "\s-1EV_ATOMIC_T\s0" 4
4446.IX Item "EV_ATOMIC_T" 4735.IX Item "EV_ATOMIC_T"
4447Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4736Libev 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 4737access 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 4738contexts. 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" 4739provide 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. 4740both for signal handler \*(L"locking\*(R" as well as for signal and thread safety
4741in \f(CW\*(C`ev_async\*(C'\fR watchers.
4452.Sp 4742.Sp
4453In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4743In 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. 4744(from \fIsignal.h\fR), which is usually good enough on most platforms,
4745although strictly speaking using a type that also implies a memory fence
4746is required.
4455.IP "\s-1EV_H\s0 (h)" 4 4747.IP "\s-1EV_H\s0 (h)" 4
4456.IX Item "EV_H (h)" 4748.IX Item "EV_H (h)"
4457The name of the \fIev.h\fR header file used to include it. The default if 4749The 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 4750undefined 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. 4751used 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 4769If 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 4770will 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 4771additional independent event loops. Otherwise there will be no support
4480for multiple event loops and there is no first event loop pointer 4772for multiple event loops and there is no first event loop pointer
4481argument. Instead, all functions act on the single default loop. 4773argument. Instead, all functions act on the single default loop.
4774.Sp
4775Note that \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR will no longer provide a
4776default loop when multiplicity is switched off \- you always have to
4777initialise the loop manually in this case.
4482.IP "\s-1EV_MINPRI\s0" 4 4778.IP "\s-1EV_MINPRI\s0" 4
4483.IX Item "EV_MINPRI" 4779.IX Item "EV_MINPRI"
4484.PD 0 4780.PD 0
4485.IP "\s-1EV_MAXPRI\s0" 4 4781.IP "\s-1EV_MAXPRI\s0" 4
4486.IX Item "EV_MAXPRI" 4782.IX Item "EV_MAXPRI"
… …
4522\& #define EV_CHILD_ENABLE 1 4818\& #define EV_CHILD_ENABLE 1
4523\& #define EV_ASYNC_ENABLE 1 4819\& #define EV_ASYNC_ENABLE 1
4524.Ve 4820.Ve
4525.Sp 4821.Sp
4526The actual value is a bitset, it can be a combination of the following 4822The actual value is a bitset, it can be a combination of the following
4527values: 4823values (by default, all of these are enabled):
4528.RS 4 4824.RS 4
4529.ie n .IP "1 \- faster/larger code" 4 4825.ie n .IP "1 \- faster/larger code" 4
4530.el .IP "\f(CW1\fR \- faster/larger code" 4 4826.el .IP "\f(CW1\fR \- faster/larger code" 4
4531.IX Item "1 - faster/larger code" 4827.IX Item "1 - faster/larger code"
4532Use larger code to speed up some operations. 4828Use larger code to speed up some operations.
… …
4535code size by roughly 30% on amd64). 4831code size by roughly 30% on amd64).
4536.Sp 4832.Sp
4537When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with 4833When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with
4538gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of 4834gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of
4539assertions. 4835assertions.
4836.Sp
4837The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4838(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4540.ie n .IP "2 \- faster/larger data structures" 4 4839.ie n .IP "2 \- faster/larger data structures" 4
4541.el .IP "\f(CW2\fR \- faster/larger data structures" 4 4840.el .IP "\f(CW2\fR \- faster/larger data structures" 4
4542.IX Item "2 - faster/larger data structures" 4841.IX Item "2 - faster/larger data structures"
4543Replaces the small 2\-heap for timer management by a faster 4\-heap, larger 4842Replaces the small 2\-heap for timer management by a faster 4\-heap, larger
4544hash table sizes and so on. This will usually further increase code size 4843hash table sizes and so on. This will usually further increase code size
4545and can additionally have an effect on the size of data structures at 4844and can additionally have an effect on the size of data structures at
4546runtime. 4845runtime.
4846.Sp
4847The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4848(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4547.ie n .IP "4 \- full \s-1API\s0 configuration" 4 4849.ie n .IP "4 \- full \s-1API\s0 configuration" 4
4548.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 4850.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4
4549.IX Item "4 - full API configuration" 4851.IX Item "4 - full API configuration"
4550This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and 4852This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and
4551enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). 4853enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1).
… …
4583With an intelligent-enough linker (gcc+binutils are intelligent enough 4885With 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 4886when 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 4887your program might be left out as well \- a binary starting a timer and an
4586I/O watcher then might come out at only 5Kb. 4888I/O watcher then might come out at only 5Kb.
4587.RE 4889.RE
4890.IP "\s-1EV_API_STATIC\s0" 4
4891.IX Item "EV_API_STATIC"
4892If this symbol is defined (by default it is not), then all identifiers
4893will have static linkage. This means that libev will not export any
4894identifiers, and you cannot link against libev anymore. This can be useful
4895when you embed libev, only want to use libev functions in a single file,
4896and do not want its identifiers to be visible.
4897.Sp
4898To use this, define \f(CW\*(C`EV_API_STATIC\*(C'\fR and include \fIev.c\fR in the file that
4899wants to use libev.
4900.Sp
4901This option only works when libev is compiled with a C compiler, as \*(C+
4902doesn't support the required declaration syntax.
4588.IP "\s-1EV_AVOID_STDIO\s0" 4 4903.IP "\s-1EV_AVOID_STDIO\s0" 4
4589.IX Item "EV_AVOID_STDIO" 4904.IX Item "EV_AVOID_STDIO"
4590If this is set to \f(CW1\fR at compiletime, then libev will avoid using stdio 4905If 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 4906functions (printf, scanf, perror etc.). This will increase the code size
4592somewhat, but if your program doesn't otherwise depend on stdio and your 4907somewhat, 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 5284requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
4970model. Libev still offers limited functionality on this platform in 5285model. 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 5286the 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 5287descriptors. This only applies when using Win32 natively, not when using
4973e.g. cygwin. Actually, it only applies to the microsofts own compilers, 5288e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4974as every compielr comes with a slightly differently broken/incompatible 5289as every compiler comes with a slightly differently broken/incompatible
4975environment. 5290environment.
4976.PP 5291.PP
4977Lifting these limitations would basically require the full 5292Lifting these limitations would basically require the full
4978re-implementation of the I/O system. If you are into this kind of thing, 5293re-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 5294then 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" 5430.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 5431The 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 5432have 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 5433good enough for at least into the year 4000 with millisecond accuracy
5119(the design goal for libev). This requirement is overfulfilled by 5434(the design goal for libev). This requirement is overfulfilled by
5120implementations using \s-1IEEE\s0 754, which is basically all existing ones. With 5435implementations using \s-1IEEE\s0 754, which is basically all existing ones.
5436.Sp
5121\&\s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least 2200. 5437With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the
5438year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5439is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5440something like that, just kidding).
5122.PP 5441.PP
5123If you know of other additional requirements drop me a note. 5442If you know of other additional requirements drop me a note.
5124.SH "ALGORITHMIC COMPLEXITIES" 5443.SH "ALGORITHMIC COMPLEXITIES"
5125.IX Header "ALGORITHMIC COMPLEXITIES" 5444.IX Header "ALGORITHMIC COMPLEXITIES"
5126In this section the complexities of (many of) the algorithms used inside 5445In this section the complexities of (many of) the algorithms used inside
… …
5180.IX Item "Processing ev_async_send: O(number_of_async_watchers)" 5499.IX Item "Processing ev_async_send: O(number_of_async_watchers)"
5181.IP "Processing signals: O(max_signal_number)" 4 5500.IP "Processing signals: O(max_signal_number)" 4
5182.IX Item "Processing signals: O(max_signal_number)" 5501.IX Item "Processing signals: O(max_signal_number)"
5183.PD 5502.PD
5184Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR 5503Sending 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 5504calls in the current loop iteration and the loop is currently
5505blocked. Checking for async and signal events involves iterating over all
5186involves iterating over all running async watchers or all signal numbers. 5506running async watchers or all signal numbers.
5187.SH "PORTING FROM LIBEV 3.X TO 4.X" 5507.SH "PORTING FROM LIBEV 3.X TO 4.X"
5188.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5508.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5189The major version 4 introduced some incompatible changes to the \s-1API\s0. 5509The major version 4 introduced some incompatible changes to the \s-1API\s0.
5190.PP 5510.PP
5191At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5511At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
… …
5194new \s-1API\s0 early than late. 5514new \s-1API\s0 early than late.
5195.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5515.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5196.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5516.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5197.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5517.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5198The backward compatibility mechanism can be controlled by 5518The backward compatibility mechanism can be controlled by
5199\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1MACROS\s0\*(R" in \s-1PREPROCESSOR\s0 \s-1SYMBOLS\s0 in the \s-1EMBEDDING\s0 5519\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R"
5200section. 5520section.
5201.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5521.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5202.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5522.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5203.IX Item "ev_default_destroy and ev_default_fork have been removed" 5523.IX Item "ev_default_destroy and ev_default_fork have been removed"
5204These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5524These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts:
… …
5288.IX Item "real time" 5608.IX Item "real time"
5289The physical time that is observed. It is apparently strictly monotonic :) 5609The physical time that is observed. It is apparently strictly monotonic :)
5290.IP "wall-clock time" 4 5610.IP "wall-clock time" 4
5291.IX Item "wall-clock time" 5611.IX Item "wall-clock time"
5292The time and date as shown on clocks. Unlike real time, it can actually 5612The 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 5613be wrong and jump forwards and backwards, e.g. when you adjust your
5294clock. 5614clock.
5295.IP "watcher" 4 5615.IP "watcher" 4
5296.IX Item "watcher" 5616.IX Item "watcher"
5297A data structure that describes interest in certain events. Watchers need 5617A data structure that describes interest in certain events. Watchers need
5298to be started (attached to an event loop) before they can receive events. 5618to be started (attached to an event loop) before they can receive events.
5299.SH "AUTHOR" 5619.SH "AUTHOR"
5300.IX Header "AUTHOR" 5620.IX Header "AUTHOR"
5301Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael 5621Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
5302Magnusson and Emanuele Giaquinta. 5622Magnusson and Emanuele Giaquinta, and minor corrections by many others.

Diff Legend

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