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

Comparing libev/ev.3 (file contents):
Revision 1.86 by root, Wed Feb 16 08:07:25 2011 UTC vs.
Revision 1.99 by root, Mon Jun 10 00:14:23 2013 UTC

1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
… …
122.\} 122.\}
123.rm #[ #] #H #V #F C 123.rm #[ #] #H #V #F C
124.\" ======================================================================== 124.\" ========================================================================
125.\" 125.\"
126.IX Title "LIBEV 3" 126.IX Title "LIBEV 3"
127.TH LIBEV 3 "2011-01-31" "libev-4.04" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2013-06-07" "libev-4.15" "libev - high performance full featured event loop"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 129.\" way too many mistakes in technical documents.
130.if n .ad l 130.if n .ad l
131.nh 131.nh
132.SH "NAME" 132.SH "NAME"
… …
244loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and 244loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and
245\&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even 245\&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even
246limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR). 246limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR).
247.PP 247.PP
248It also is quite fast (see this 248It also is quite fast (see this
249<benchmark> comparing it to libevent 249benchmark <http://libev.schmorp.de/bench.html> comparing it to libevent
250for example). 250for example).
251.SS "\s-1CONVENTIONS\s0" 251.SS "\s-1CONVENTIONS\s0"
252.IX Subsection "CONVENTIONS" 252.IX Subsection "CONVENTIONS"
253Libev is very configurable. In this manual the default (and most common) 253Libev is very configurable. In this manual the default (and most common)
254configuration will be described, which supports multiple event loops. For 254configuration will be described, which supports multiple event loops. For
… …
294.IP "ev_tstamp ev_time ()" 4 294.IP "ev_tstamp ev_time ()" 4
295.IX Item "ev_tstamp ev_time ()" 295.IX Item "ev_tstamp ev_time ()"
296Returns the current time as libev would use it. Please note that the 296Returns the current time as libev would use it. Please note that the
297\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp 297\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp
298you actually want to know. Also interesting is the combination of 298you actually want to know. Also interesting is the combination of
299\&\f(CW\*(C`ev_update_now\*(C'\fR and \f(CW\*(C`ev_now\*(C'\fR. 299\&\f(CW\*(C`ev_now_update\*(C'\fR and \f(CW\*(C`ev_now\*(C'\fR.
300.IP "ev_sleep (ev_tstamp interval)" 4 300.IP "ev_sleep (ev_tstamp interval)" 4
301.IX Item "ev_sleep (ev_tstamp interval)" 301.IX Item "ev_sleep (ev_tstamp interval)"
302Sleep for the given interval: The current thread will be blocked until 302Sleep for the given interval: The current thread will be blocked
303either it is interrupted or the given time interval has passed. Basically 303until either it is interrupted or the given time interval has
304passed (approximately \- it might return a bit earlier even if not
305interrupted). Returns immediately if \f(CW\*(C`interval <= 0\*(C'\fR.
306.Sp
304this is a sub-second-resolution \f(CW\*(C`sleep ()\*(C'\fR. 307Basically this is a sub-second-resolution \f(CW\*(C`sleep ()\*(C'\fR.
308.Sp
309The range of the \f(CW\*(C`interval\*(C'\fR is limited \- libev only guarantees to work
310with sleep times of up to one day (\f(CW\*(C`interval <= 86400\*(C'\fR).
305.IP "int ev_version_major ()" 4 311.IP "int ev_version_major ()" 4
306.IX Item "int ev_version_major ()" 312.IX Item "int ev_version_major ()"
307.PD 0 313.PD 0
308.IP "int ev_version_minor ()" 4 314.IP "int ev_version_minor ()" 4
309.IX Item "int ev_version_minor ()" 315.IX Item "int ev_version_minor ()"
… …
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
… …
508.IX Item "EVFLAG_NOENV" 514.IX Item "EVFLAG_NOENV"
509If this flag bit is or'ed into the flag value (or the program runs setuid 515If this flag bit is or'ed into the flag value (or the program runs setuid
510or setgid) then libev will \fInot\fR look at the environment variable 516or setgid) then libev will \fInot\fR look at the environment variable
511\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will 517\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will
512override the flags completely if it is found in the environment. This is 518override the flags completely if it is found in the environment. This is
513useful to try out specific backends to test their performance, or to work 519useful to try out specific backends to test their performance, to work
514around bugs. 520around bugs, or to make libev threadsafe (accessing environment variables
521cannot be done in a threadsafe way, but usually it works if no other
522thread modifies them).
515.ie n .IP """EVFLAG_FORKCHECK""" 4 523.ie n .IP """EVFLAG_FORKCHECK""" 4
516.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 524.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
517.IX Item "EVFLAG_FORKCHECK" 525.IX Item "EVFLAG_FORKCHECK"
518Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also 526Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also
519make libev check for a fork in each iteration by enabling this flag. 527make libev check for a fork in each iteration by enabling this flag.
… …
553example) that can't properly initialise their signal masks. 561example) that can't properly initialise their signal masks.
554.ie n .IP """EVFLAG_NOSIGMASK""" 4 562.ie n .IP """EVFLAG_NOSIGMASK""" 4
555.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4 563.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4
556.IX Item "EVFLAG_NOSIGMASK" 564.IX Item "EVFLAG_NOSIGMASK"
557When this flag is specified, then libev will avoid to modify the signal 565When this flag is specified, then libev will avoid to modify the signal
558mask. Specifically, this means you ahve to make sure signals are unblocked 566mask. Specifically, this means you have to make sure signals are unblocked
559when you want to receive them. 567when you want to receive them.
560.Sp 568.Sp
561This behaviour is useful when you want to do your own signal handling, or 569This 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 570want to handle signals only in specific threads and want to avoid libev
563unblocking the signals. 571unblocking the signals.
… …
601.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 609.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
602.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 610.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
603Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 611Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
604kernels). 612kernels).
605.Sp 613.Sp
606For few fds, this backend is a bit little slower than poll and select, 614For few fds, this backend is a bit little slower than poll and select, but
607but it scales phenomenally better. While poll and select usually scale 615it scales phenomenally better. While poll and select usually scale like
608like O(total_fds) where n is the total number of fds (or the highest fd), 616O(total_fds) where total_fds is the total number of fds (or the highest
609epoll scales either O(1) or O(active_fds). 617fd), epoll scales either O(1) or O(active_fds).
610.Sp 618.Sp
611The epoll mechanism deserves honorable mention as the most misdesigned 619The epoll mechanism deserves honorable mention as the most misdesigned
612of the more advanced event mechanisms: mere annoyances include silently 620of the more advanced event mechanisms: mere annoyances include silently
613dropping file descriptors, requiring a system call per change per file 621dropping file descriptors, requiring a system call per change per file
614descriptor (and unnecessary guessing of parameters), problems with dup, 622descriptor (and unnecessary guessing of parameters), problems with dup,
… …
6170.1ms) and so on. The biggest issue is fork races, however \- if a program 6250.1ms) and so on. The biggest issue is fork races, however \- if a program
618forks then \fIboth\fR parent and child process have to recreate the epoll 626forks then \fIboth\fR parent and child process have to recreate the epoll
619set, which can take considerable time (one syscall per file descriptor) 627set, which can take considerable time (one syscall per file descriptor)
620and is of course hard to detect. 628and is of course hard to detect.
621.Sp 629.Sp
622Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but 630Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work,
623of course \fIdoesn't\fR, and epoll just loves to report events for totally 631but of course \fIdoesn't\fR, and epoll just loves to report events for
624\&\fIdifferent\fR file descriptors (even already closed ones, so one cannot 632totally \fIdifferent\fR file descriptors (even already closed ones, so
625even remove them from the set) than registered in the set (especially 633one cannot even remove them from the set) than registered in the set
626on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by 634(especially on \s-1SMP\s0 systems). Libev tries to counter these spurious
627employing an additional generation counter and comparing that against the 635notifications by employing an additional generation counter and comparing
628events to filter out spurious ones, recreating the set when required. Last 636that against the events to filter out spurious ones, recreating the set
637when required. Epoll also erroneously rounds down timeouts, but gives you
638no way to know when and by how much, so sometimes you have to busy-wait
639because epoll returns immediately despite a nonzero timeout. And last
629not least, it also refuses to work with some file descriptors which work 640not least, it also refuses to work with some file descriptors which work
630perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...). 641perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...).
631.Sp 642.Sp
632Epoll is truly the train wreck analog among event poll mechanisms, 643Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
633a frankenpoll, cobbled together in a hurry, no thought to design or 644cobbled together in a hurry, no thought to design or interaction with
634interaction with others. 645others. Oh, the pain, will it ever stop...
635.Sp 646.Sp
636While stopping, setting and starting an I/O watcher in the same iteration 647While stopping, setting and starting an I/O watcher in the same iteration
637will result in some caching, there is still a system call per such 648will result in some caching, there is still a system call per such
638incident (because the same \fIfile descriptor\fR could point to a different 649incident (because the same \fIfile descriptor\fR could point to a different
639\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed 650\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed
… …
676.Sp 687.Sp
677It scales in the same way as the epoll backend, but the interface to the 688It scales in the same way as the epoll backend, but the interface to the
678kernel is more efficient (which says nothing about its actual speed, of 689kernel is more efficient (which says nothing about its actual speed, of
679course). While stopping, setting and starting an I/O watcher does never 690course). While stopping, setting and starting an I/O watcher does never
680cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 691cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
681two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but 692two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
682sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 693might have to leak fd's on fork, but it's more sane than epoll) and it
683cases 694drops fds silently in similarly hard-to-detect cases.
684.Sp 695.Sp
685This backend usually performs well under most conditions. 696This backend usually performs well under most conditions.
686.Sp 697.Sp
687While nominally embeddable in other event loops, this doesn't work 698While nominally embeddable in other event loops, this doesn't work
688everywhere, so you might need to test for this. And since it is broken 699everywhere, so you might need to test for this. And since it is broken
… …
717among the OS-specific backends (I vastly prefer correctness over speed 728among the OS-specific backends (I vastly prefer correctness over speed
718hacks). 729hacks).
719.Sp 730.Sp
720On the negative side, the interface is \fIbizarre\fR \- so bizarre that 731On the negative side, the interface is \fIbizarre\fR \- so bizarre that
721even sun itself gets it wrong in their code examples: The event polling 732even sun itself gets it wrong in their code examples: The event polling
722function sometimes returning events to the caller even though an error 733function sometimes returns events to the caller even though an error
723occurred, but with no indication whether it has done so or not (yes, it's 734occurred, but with no indication whether it has done so or not (yes, it's
724even documented that way) \- deadly for edge-triggered interfaces where 735even documented that way) \- deadly for edge-triggered interfaces where you
725you absolutely have to know whether an event occurred or not because you 736absolutely have to know whether an event occurred or not because you have
726have to re-arm the watcher. 737to re-arm the watcher.
727.Sp 738.Sp
728Fortunately libev seems to be able to work around these idiocies. 739Fortunately libev seems to be able to work around these idiocies.
729.Sp 740.Sp
730This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 741This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
731\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 742\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
… …
900given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR 911given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR
901without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. 912without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR.
902.Sp 913.Sp
903Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the 914Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the
904event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). 915event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR).
905.IP "ev_run (loop, int flags)" 4 916.IP "bool ev_run (loop, int flags)" 4
906.IX Item "ev_run (loop, int flags)" 917.IX Item "bool ev_run (loop, int flags)"
907Finally, this is it, the event handler. This function usually is called 918Finally, this is it, the event handler. This function usually is called
908after you have initialised all your watchers and you want to start 919after you have initialised all your watchers and you want to start
909handling events. It will ask the operating system for any new events, call 920handling events. It will ask the operating system for any new events, call
910the watcher callbacks, an then repeat the whole process indefinitely: This 921the watcher callbacks, and then repeat the whole process indefinitely: This
911is why event loops are called \fIloops\fR. 922is why event loops are called \fIloops\fR.
912.Sp 923.Sp
913If the flags argument is specified as \f(CW0\fR, it will keep handling events 924If the flags argument is specified as \f(CW0\fR, it will keep handling events
914until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was 925until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was
915called. 926called.
927.Sp
928The return value is false if there are no more active watchers (which
929usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases
930(which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again").
916.Sp 931.Sp
917Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than 932Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than
918relying on all watchers to be stopped when deciding when a program has 933relying on all watchers to be stopped when deciding when a program has
919finished (especially in interactive programs), but having a program 934finished (especially in interactive programs), but having a program
920that automatically loops as long as it has to and no longer by virtue 935that automatically loops as long as it has to and no longer by virtue
921of relying on its watchers stopping correctly, that is truly a thing of 936of relying on its watchers stopping correctly, that is truly a thing of
922beauty. 937beauty.
923.Sp 938.Sp
924This function is also \fImostly\fR exception-safe \- you can break out of 939This function is \fImostly\fR exception-safe \- you can break out of a
925a \f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ 940\&\f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+
926exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor 941exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor
927will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. 942will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks.
928.Sp 943.Sp
929A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle 944A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle
930those events and any already outstanding ones, but will not wait and 945those events and any already outstanding ones, but will not wait and
… …
942This is useful if you are waiting for some external event in conjunction 957This is useful if you are waiting for some external event in conjunction
943with something not expressible using other libev watchers (i.e. "roll your 958with something not expressible using other libev watchers (i.e. "roll your
944own \f(CW\*(C`ev_run\*(C'\fR"). However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is 959own \f(CW\*(C`ev_run\*(C'\fR"). However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is
945usually a better approach for this kind of thing. 960usually a better approach for this kind of thing.
946.Sp 961.Sp
947Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does: 962Here are the gory details of what \f(CW\*(C`ev_run\*(C'\fR does (this is for your
963understanding, not a guarantee that things will work exactly like this in
964future versions):
948.Sp 965.Sp
949.Vb 10 966.Vb 10
950\& \- Increment loop depth. 967\& \- Increment loop depth.
951\& \- Reset the ev_break status. 968\& \- Reset the ev_break status.
952\& \- Before the first iteration, call any pending watchers. 969\& \- Before the first iteration, call any pending watchers.
… …
1067overhead for the actual polling but can deliver many events at once. 1084overhead for the actual polling but can deliver many events at once.
1068.Sp 1085.Sp
1069By setting a higher \fIio collect interval\fR you allow libev to spend more 1086By setting a higher \fIio collect interval\fR you allow libev to spend more
1070time collecting I/O events, so you can handle more events per iteration, 1087time collecting I/O events, so you can handle more events per iteration,
1071at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and 1088at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and
1072\&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null value will 1089\&\f(CW\*(C`ev_timer\*(C'\fR) will not be affected. Setting this to a non-null value will
1073introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. The 1090introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations. The
1074sleep time ensures that libev will not poll for I/O events more often then 1091sleep time ensures that libev will not poll for I/O events more often then
1075once per this interval, on average. 1092once per this interval, on average (as long as the host time resolution is
1093good enough).
1076.Sp 1094.Sp
1077Likewise, by setting a higher \fItimeout collect interval\fR you allow libev 1095Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
1078to spend more time collecting timeouts, at the expense of increased 1096to spend more time collecting timeouts, at the expense of increased
1079latency/jitter/inexactness (the watcher callback will be called 1097latency/jitter/inexactness (the watcher callback will be called
1080later). \f(CW\*(C`ev_io\*(C'\fR watchers will not be affected. Setting this to a non-null 1098later). \f(CW\*(C`ev_io\*(C'\fR watchers will not be affected. Setting this to a non-null
… …
1124this callback instead. This is useful, for example, when you want to 1142this callback instead. This is useful, for example, when you want to
1125invoke the actual watchers inside another context (another thread etc.). 1143invoke the actual watchers inside another context (another thread etc.).
1126.Sp 1144.Sp
1127If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new 1145If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new
1128callback. 1146callback.
1129.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0), void (*acquire)(\s-1EV_P\s0))" 4 1147.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0) throw (), void (*acquire)(\s-1EV_P\s0) throw ())" 4
1130.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))" 1148.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())"
1131Sometimes you want to share the same loop between multiple threads. This 1149Sometimes you want to share the same loop between multiple threads. This
1132can be done relatively simply by putting mutex_lock/unlock calls around 1150can be done relatively simply by putting mutex_lock/unlock calls around
1133each call to a libev function. 1151each call to a libev function.
1134.Sp 1152.Sp
1135However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible 1153However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible
1136to wait for it to return. One way around this is to wake up the event 1154to wait for it to return. One way around this is to wake up the event
1137loop via \f(CW\*(C`ev_break\*(C'\fR and \f(CW\*(C`av_async_send\*(C'\fR, another way is to set these 1155loop via \f(CW\*(C`ev_break\*(C'\fR and \f(CW\*(C`ev_async_send\*(C'\fR, another way is to set these
1138\&\fIrelease\fR and \fIacquire\fR callbacks on the loop. 1156\&\fIrelease\fR and \fIacquire\fR callbacks on the loop.
1139.Sp 1157.Sp
1140When set, then \f(CW\*(C`release\*(C'\fR will be called just before the thread is 1158When set, then \f(CW\*(C`release\*(C'\fR will be called just before the thread is
1141suspended waiting for new events, and \f(CW\*(C`acquire\*(C'\fR is called just 1159suspended waiting for new events, and \f(CW\*(C`acquire\*(C'\fR is called just
1142afterwards. 1160afterwards.
… …
1283.PD 0 1301.PD 0
1284.ie n .IP """EV_CHECK""" 4 1302.ie n .IP """EV_CHECK""" 4
1285.el .IP "\f(CWEV_CHECK\fR" 4 1303.el .IP "\f(CWEV_CHECK\fR" 4
1286.IX Item "EV_CHECK" 1304.IX Item "EV_CHECK"
1287.PD 1305.PD
1288All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts 1306All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts to
1289to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after 1307gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are queued (not invoked)
1290\&\f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it invokes any callbacks for any 1308just after \f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it queues any callbacks
1309for any received events. That means \f(CW\*(C`ev_prepare\*(C'\fR watchers are the last
1310watchers invoked before the event loop sleeps or polls for new events, and
1311\&\f(CW\*(C`ev_check\*(C'\fR watchers will be invoked before any other watchers of the same
1312or lower priority within an event loop iteration.
1313.Sp
1291received events. Callbacks of both watcher types can start and stop as 1314Callbacks of both watcher types can start and stop as many watchers as
1292many watchers as they want, and all of them will be taken into account 1315they want, and all of them will be taken into account (for example, a
1293(for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep 1316\&\f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep \f(CW\*(C`ev_run\*(C'\fR from
1294\&\f(CW\*(C`ev_run\*(C'\fR from blocking). 1317blocking).
1295.ie n .IP """EV_EMBED""" 4 1318.ie n .IP """EV_EMBED""" 4
1296.el .IP "\f(CWEV_EMBED\fR" 4 1319.el .IP "\f(CWEV_EMBED\fR" 4
1297.IX Item "EV_EMBED" 1320.IX Item "EV_EMBED"
1298The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. 1321The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention.
1299.ie n .IP """EV_FORK""" 4 1322.ie n .IP """EV_FORK""" 4
… …
1420make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR 1443make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR
1421it). 1444it).
1422.IP "callback ev_cb (ev_TYPE *watcher)" 4 1445.IP "callback ev_cb (ev_TYPE *watcher)" 4
1423.IX Item "callback ev_cb (ev_TYPE *watcher)" 1446.IX Item "callback ev_cb (ev_TYPE *watcher)"
1424Returns the callback currently set on the watcher. 1447Returns the callback currently set on the watcher.
1425.IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 1448.IP "ev_set_cb (ev_TYPE *watcher, callback)" 4
1426.IX Item "ev_cb_set (ev_TYPE *watcher, callback)" 1449.IX Item "ev_set_cb (ev_TYPE *watcher, callback)"
1427Change the callback. You can change the callback at virtually any time 1450Change the callback. You can change the callback at virtually any time
1428(modulo threads). 1451(modulo threads).
1429.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 1452.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4
1430.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" 1453.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)"
1431.PD 0 1454.PD 0
… …
1487.IX Subsection "WATCHER STATES" 1510.IX Subsection "WATCHER STATES"
1488There are various watcher states mentioned throughout this manual \- 1511There are various watcher states mentioned throughout this manual \-
1489active, pending and so on. In this section these states and the rules to 1512active, pending and so on. In this section these states and the rules to
1490transition between them will be described in more detail \- and while these 1513transition between them will be described in more detail \- and while these
1491rules might look complicated, they usually do \*(L"the right thing\*(R". 1514rules might look complicated, they usually do \*(L"the right thing\*(R".
1492.IP "initialiased" 4 1515.IP "initialised" 4
1493.IX Item "initialiased" 1516.IX Item "initialised"
1494Before a watcher can be registered with the event looop it has to be 1517Before a watcher can be registered with the event loop it has to be
1495initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to 1518initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to
1496\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. 1519\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1497.Sp 1520.Sp
1498In this state it is simply some block of memory that is suitable for 1521In this state it is simply some block of memory that is suitable for
1499use in an event loop. It can be moved around, freed, reused etc. at 1522use in an event loop. It can be moved around, freed, reused etc. at
… …
1871detecting time jumps is hard, and some inaccuracies are unavoidable (the 1894detecting time jumps is hard, and some inaccuracies are unavoidable (the
1872monotonic clock option helps a lot here). 1895monotonic clock option helps a lot here).
1873.PP 1896.PP
1874The callback is guaranteed to be invoked only \fIafter\fR its timeout has 1897The callback is guaranteed to be invoked only \fIafter\fR its timeout has
1875passed (not \fIat\fR, so on systems with very low-resolution clocks this 1898passed (not \fIat\fR, so on systems with very low-resolution clocks this
1876might introduce a small delay). If multiple timers become ready during the 1899might introduce a small delay, see \*(L"the special problem of being too
1900early\*(R", below). If multiple timers become ready during the same loop
1877same loop iteration then the ones with earlier time-out values are invoked 1901iteration then the ones with earlier time-out values are invoked before
1878before ones of the same priority with later time-out values (but this is 1902ones of the same priority with later time-out values (but this is no
1879no longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively). 1903longer true when a callback calls \f(CW\*(C`ev_run\*(C'\fR recursively).
1880.PP 1904.PP
1881\fIBe smart about timeouts\fR 1905\fIBe smart about timeouts\fR
1882.IX Subsection "Be smart about timeouts" 1906.IX Subsection "Be smart about timeouts"
1883.PP 1907.PP
1884Many real-world problems involve some kind of timeout, usually for error 1908Many real-world problems involve some kind of timeout, usually for error
… …
1966.Sp 1990.Sp
1967In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone, 1991In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone,
1968but remember the time of last activity, and check for a real timeout only 1992but remember the time of last activity, and check for a real timeout only
1969within the callback: 1993within the callback:
1970.Sp 1994.Sp
1971.Vb 1 1995.Vb 3
1996\& ev_tstamp timeout = 60.;
1972\& ev_tstamp last_activity; // time of last activity 1997\& ev_tstamp last_activity; // time of last activity
1998\& ev_timer timer;
1973\& 1999\&
1974\& static void 2000\& static void
1975\& callback (EV_P_ ev_timer *w, int revents) 2001\& callback (EV_P_ ev_timer *w, int revents)
1976\& { 2002\& {
1977\& ev_tstamp now = ev_now (EV_A); 2003\& // calculate when the timeout would happen
1978\& ev_tstamp timeout = last_activity + 60.; 2004\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout;
1979\& 2005\&
1980\& // if last_activity + 60. is older than now, we did time out 2006\& // if negative, it means we the timeout already occurred
1981\& if (timeout < now) 2007\& if (after < 0.)
1982\& { 2008\& {
1983\& // timeout occurred, take action 2009\& // timeout occurred, take action
1984\& } 2010\& }
1985\& else 2011\& else
1986\& { 2012\& {
1987\& // callback was invoked, but there was some activity, re\-arm 2013\& // callback was invoked, but there was some recent
1988\& // the watcher to fire in last_activity + 60, which is 2014\& // activity. simply restart the timer to time out
1989\& // guaranteed to be in the future, so "again" is positive: 2015\& // after "after" seconds, which is the earliest time
1990\& w\->repeat = timeout \- now; 2016\& // the timeout can occur.
2017\& ev_timer_set (w, after, 0.);
1991\& ev_timer_again (EV_A_ w); 2018\& ev_timer_start (EV_A_ w);
1992\& } 2019\& }
1993\& } 2020\& }
1994.Ve 2021.Ve
1995.Sp 2022.Sp
1996To summarise the callback: first calculate the real timeout (defined 2023To summarise the callback: first calculate in how many seconds the
1997as \*(L"60 seconds after the last activity\*(R"), then check if that time has 2024timeout will occur (by calculating the absolute time when it would occur,
1998been reached, which means something \fIdid\fR, in fact, time out. Otherwise 2025\&\f(CW\*(C`last_activity + timeout\*(C'\fR, and subtracting the current time, \f(CW\*(C`ev_now
1999the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so 2026(EV_A)\*(C'\fR from that).
2000re-schedule the timer to fire at that future time, to see if maybe we have
2001a timeout then.
2002.Sp 2027.Sp
2003Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the 2028If this value is negative, then we are already past the timeout, i.e. we
2004\&\f(CW\*(C`ev_timer_again\*(C'\fR optimisation when the timer is already running. 2029timed out, and need to do whatever is needed in this case.
2030.Sp
2031Otherwise, we now the earliest time at which the timeout would trigger,
2032and simply start the timer with this timeout value.
2033.Sp
2034In other words, each time the callback is invoked it will check whether
2035the timeout occurred. If not, it will simply reschedule itself to check
2036again at the earliest time it could time out. Rinse. Repeat.
2005.Sp 2037.Sp
2006This scheme causes more callback invocations (about one every 60 seconds 2038This scheme causes more callback invocations (about one every 60 seconds
2007minus half the average time between activity), but virtually no calls to 2039minus half the average time between activity), but virtually no calls to
2008libev to change the timeout. 2040libev to change the timeout.
2009.Sp 2041.Sp
2010To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR 2042To start the machinery, simply initialise the watcher and set
2011to the current time (meaning we just have some activity :), then call the 2043\&\f(CW\*(C`last_activity\*(C'\fR to the current time (meaning there was some activity just
2012callback, which will \*(L"do the right thing\*(R" and start the timer: 2044now), then call the callback, which will \*(L"do the right thing\*(R" and start
2045the timer:
2013.Sp 2046.Sp
2014.Vb 3 2047.Vb 3
2048\& last_activity = ev_now (EV_A);
2015\& ev_init (timer, callback); 2049\& ev_init (&timer, callback);
2016\& last_activity = ev_now (loop); 2050\& callback (EV_A_ &timer, 0);
2017\& callback (loop, timer, EV_TIMER);
2018.Ve 2051.Ve
2019.Sp 2052.Sp
2020And when there is some activity, simply store the current time in 2053When there is some activity, simply store the current time in
2021\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all: 2054\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all:
2022.Sp 2055.Sp
2023.Vb 1 2056.Vb 2
2057\& if (activity detected)
2024\& last_activity = ev_now (loop); 2058\& last_activity = ev_now (EV_A);
2059.Ve
2060.Sp
2061When your timeout value changes, then the timeout can be changed by simply
2062providing a new value, stopping the timer and calling the callback, which
2063will again do the right thing (for example, time out immediately :).
2064.Sp
2065.Vb 3
2066\& timeout = new_value;
2067\& ev_timer_stop (EV_A_ &timer);
2068\& callback (EV_A_ &timer, 0);
2025.Ve 2069.Ve
2026.Sp 2070.Sp
2027This technique is slightly more complex, but in most cases where the 2071This technique is slightly more complex, but in most cases where the
2028time-out is unlikely to be triggered, much more efficient. 2072time-out is unlikely to be triggered, much more efficient.
2029.Sp
2030Changing the timeout is trivial as well (if it isn't hard-coded in the
2031callback :) \- just change the timeout and invoke the callback, which will
2032fix things for you.
2033.IP "4. Wee, just use a double-linked list for your timeouts." 4 2073.IP "4. Wee, just use a double-linked list for your timeouts." 4
2034.IX Item "4. Wee, just use a double-linked list for your timeouts." 2074.IX Item "4. Wee, just use a double-linked list for your timeouts."
2035If there is not one request, but many thousands (millions...), all 2075If there is not one request, but many thousands (millions...), all
2036employing some kind of timeout with the same timeout value, then one can 2076employing some kind of timeout with the same timeout value, then one can
2037do even better: 2077do even better:
… …
2061Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 2101Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
2062rather complicated, but extremely efficient, something that really pays 2102rather complicated, but extremely efficient, something that really pays
2063off after the first million or so of active timers, i.e. it's usually 2103off after the first million or so of active timers, i.e. it's usually
2064overkill :) 2104overkill :)
2065.PP 2105.PP
2106\fIThe special problem of being too early\fR
2107.IX Subsection "The special problem of being too early"
2108.PP
2109If you ask a timer to call your callback after three seconds, then
2110you expect it to be invoked after three seconds \- but of course, this
2111cannot be guaranteed to infinite precision. Less obviously, it cannot be
2112guaranteed to any precision by libev \- imagine somebody suspending the
2113process with a \s-1STOP\s0 signal for a few hours for example.
2114.PP
2115So, libev tries to invoke your callback as soon as possible \fIafter\fR the
2116delay has occurred, but cannot guarantee this.
2117.PP
2118A less obvious failure mode is calling your callback too early: many event
2119loops compare timestamps with a \*(L"elapsed delay >= requested delay\*(R", but
2120this can cause your callback to be invoked much earlier than you would
2121expect.
2122.PP
2123To see why, imagine a system with a clock that only offers full second
2124resolution (think windows if you can't come up with a broken enough \s-1OS\s0
2125yourself). If you schedule a one-second timer at the time 500.9, then the
2126event loop will schedule your timeout to elapse at a system time of 500
2127(500.9 truncated to the resolution) + 1, or 501.
2128.PP
2129If an event library looks at the timeout 0.1s later, it will see \*(L"501 >=
2130501\*(R" and invoke the callback 0.1s after it was started, even though a
2131one-second delay was requested \- this is being \*(L"too early\*(R", despite best
2132intentions.
2133.PP
2134This is the reason why libev will never invoke the callback if the elapsed
2135delay equals the requested delay, but only when the elapsed delay is
2136larger than the requested delay. In the example above, libev would only invoke
2137the callback at system time 502, or 1.1s after the timer was started.
2138.PP
2139So, while libev cannot guarantee that your callback will be invoked
2140exactly when requested, it \fIcan\fR and \fIdoes\fR guarantee that the requested
2141delay has actually elapsed, or in other words, it always errs on the \*(L"too
2142late\*(R" side of things.
2143.PP
2066\fIThe special problem of time updates\fR 2144\fIThe special problem of time updates\fR
2067.IX Subsection "The special problem of time updates" 2145.IX Subsection "The special problem of time updates"
2068.PP 2146.PP
2069Establishing the current time is a costly operation (it usually takes at 2147Establishing the current time is a costly operation (it usually takes
2070least two system calls): \s-1EV\s0 therefore updates its idea of the current 2148at least one system call): \s-1EV\s0 therefore updates its idea of the current
2071time only before and after \f(CW\*(C`ev_run\*(C'\fR collects new events, which causes a 2149time only before and after \f(CW\*(C`ev_run\*(C'\fR collects new events, which causes a
2072growing difference between \f(CW\*(C`ev_now ()\*(C'\fR and \f(CW\*(C`ev_time ()\*(C'\fR when handling 2150growing difference between \f(CW\*(C`ev_now ()\*(C'\fR and \f(CW\*(C`ev_time ()\*(C'\fR when handling
2073lots of events in one iteration. 2151lots of events in one iteration.
2074.PP 2152.PP
2075The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2153The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
… …
2083.Ve 2161.Ve
2084.PP 2162.PP
2085If the event loop is suspended for a long time, you can also force an 2163If the event loop is suspended for a long time, you can also force an
2086update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update 2164update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2087()\*(C'\fR. 2165()\*(C'\fR.
2166.PP
2167\fIThe special problem of unsynchronised clocks\fR
2168.IX Subsection "The special problem of unsynchronised clocks"
2169.PP
2170Modern systems have a variety of clocks \- libev itself uses the normal
2171\&\*(L"wall clock\*(R" clock and, if available, the monotonic clock (to avoid time
2172jumps).
2173.PP
2174Neither of these clocks is synchronised with each other or any other clock
2175on the system, so \f(CW\*(C`ev_time ()\*(C'\fR might return a considerably different time
2176than \f(CW\*(C`gettimeofday ()\*(C'\fR or \f(CW\*(C`time ()\*(C'\fR. On a GNU/Linux system, for example,
2177a call to \f(CW\*(C`gettimeofday\*(C'\fR might return a second count that is one higher
2178than a directly following call to \f(CW\*(C`time\*(C'\fR.
2179.PP
2180The moral of this is to only compare libev-related timestamps with
2181\&\f(CW\*(C`ev_time ()\*(C'\fR and \f(CW\*(C`ev_now ()\*(C'\fR, at least if you want better precision than
2182a second or so.
2183.PP
2184One more problem arises due to this lack of synchronisation: if libev uses
2185the system monotonic clock and you compare timestamps from \f(CW\*(C`ev_time\*(C'\fR
2186or \f(CW\*(C`ev_now\*(C'\fR from when you started your timer and when your callback is
2187invoked, you will find that sometimes the callback is a bit \*(L"early\*(R".
2188.PP
2189This is because \f(CW\*(C`ev_timer\*(C'\fRs work in real time, not wall clock time, so
2190libev makes sure your callback is not invoked before the delay happened,
2191\&\fImeasured according to the real time\fR, not the system clock.
2192.PP
2193If your timeouts are based on a physical timescale (e.g. \*(L"time out this
2194connection after 100 seconds\*(R") then this shouldn't bother you as it is
2195exactly the right behaviour.
2196.PP
2197If you want to compare wall clock/system timestamps to your timers, then
2198you need to use \f(CW\*(C`ev_periodic\*(C'\fRs, as these are based on the wall clock
2199time, where your comparisons will always generate correct results.
2088.PP 2200.PP
2089\fIThe special problems of suspended animation\fR 2201\fIThe special problems of suspended animation\fR
2090.IX Subsection "The special problems of suspended animation" 2202.IX Subsection "The special problems of suspended animation"
2091.PP 2203.PP
2092When you leave the server world it is quite customary to hit machines that 2204When you leave the server world it is quite customary to hit machines that
… …
2136trigger at exactly 10 second intervals. If, however, your program cannot 2248trigger at exactly 10 second intervals. If, however, your program cannot
2137keep up with the timer (because it takes longer than those 10 seconds to 2249keep up with the timer (because it takes longer than those 10 seconds to
2138do stuff) the timer will not fire more than once per event loop iteration. 2250do stuff) the timer will not fire more than once per event loop iteration.
2139.IP "ev_timer_again (loop, ev_timer *)" 4 2251.IP "ev_timer_again (loop, ev_timer *)" 4
2140.IX Item "ev_timer_again (loop, ev_timer *)" 2252.IX Item "ev_timer_again (loop, ev_timer *)"
2141This will act as if the timer timed out and restart it again if it is 2253This will act as if the timer timed out, and restarts it again if it is
2142repeating. The exact semantics are: 2254repeating. It basically works like calling \f(CW\*(C`ev_timer_stop\*(C'\fR, updating the
2255timeout to the \f(CW\*(C`repeat\*(C'\fR value and calling \f(CW\*(C`ev_timer_start\*(C'\fR.
2143.Sp 2256.Sp
2257The exact semantics are as in the following rules, all of which will be
2258applied to the watcher:
2259.RS 4
2144If the timer is pending, its pending status is cleared. 2260.IP "If the timer is pending, the pending status is always cleared." 4
2145.Sp 2261.IX Item "If the timer is pending, the pending status is always cleared."
2262.PD 0
2146If the timer is started but non-repeating, stop it (as if it timed out). 2263.IP "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)." 4
2147.Sp 2264.IX Item "If the timer is started but non-repeating, stop it (as if it timed out, without invoking it)."
2148If the timer is repeating, either start it if necessary (with the 2265.ie n .IP "If the timer is repeating, make the ""repeat"" value the new timeout and start the timer, if necessary." 4
2149\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. 2266.el .IP "If the timer is repeating, make the \f(CWrepeat\fR value the new timeout and start the timer, if necessary." 4
2267.IX Item "If the timer is repeating, make the repeat value the new timeout and start the timer, if necessary."
2268.RE
2269.RS 4
2270.PD
2150.Sp 2271.Sp
2151This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a 2272This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a
2152usage example. 2273usage example.
2274.RE
2153.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 2275.IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4
2154.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 2276.IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)"
2155Returns the remaining time until a timer fires. If the timer is active, 2277Returns the remaining time until a timer fires. If the timer is active,
2156then this time is relative to the current event loop time, otherwise it's 2278then this time is relative to the current event loop time, otherwise it's
2157the timeout value currently configured. 2279the timeout value currently configured.
… …
2277.Sp 2399.Sp
2278Another way to think about it (for the mathematically inclined) is that 2400Another way to think about it (for the mathematically inclined) is that
2279\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible 2401\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible
2280time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps. 2402time where \f(CW\*(C`time = offset (mod interval)\*(C'\fR, regardless of any time jumps.
2281.Sp 2403.Sp
2282For numerical stability it is preferable that the \f(CW\*(C`offset\*(C'\fR value is near 2404The \f(CW\*(C`interval\*(C'\fR \fI\s-1MUST\s0\fR be positive, and for numerical stability, the
2283\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for 2405interval value should be higher than \f(CW\*(C`1/8192\*(C'\fR (which is around 100
2284this value, and in fact is often specified as zero. 2406microseconds) and \f(CW\*(C`offset\*(C'\fR should be higher than \f(CW0\fR and should have
2407at most a similar magnitude as the current time (say, within a factor of
2408ten). Typical values for offset are, in fact, \f(CW0\fR or something between
2409\&\f(CW0\fR and \f(CW\*(C`interval\*(C'\fR, which is also the recommended range.
2285.Sp 2410.Sp
2286Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0 2411Note also that there is an upper limit to how often a timer can fire (\s-1CPU\s0
2287speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability 2412speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability
2288will of course deteriorate. Libev itself tries to be exact to be about one 2413will of course deteriorate. Libev itself tries to be exact to be about one
2289millisecond (if the \s-1OS\s0 supports it and the machine is fast enough). 2414millisecond (if the \s-1OS\s0 supports it and the machine is fast enough).
… …
2617.ie n .SS """ev_stat"" \- did the file attributes just change?" 2742.ie n .SS """ev_stat"" \- did the file attributes just change?"
2618.el .SS "\f(CWev_stat\fP \- did the file attributes just change?" 2743.el .SS "\f(CWev_stat\fP \- did the file attributes just change?"
2619.IX Subsection "ev_stat - did the file attributes just change?" 2744.IX Subsection "ev_stat - did the file attributes just change?"
2620This watches a file system path for attribute changes. That is, it calls 2745This watches a file system path for attribute changes. That is, it calls
2621\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) 2746\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed)
2622and sees if it changed compared to the last time, invoking the callback if 2747and sees if it changed compared to the last time, invoking the callback
2623it did. 2748if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that
2749happen after the watcher has been started will be reported.
2624.PP 2750.PP
2625The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 2751The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
2626not exist\*(R" is a status change like any other. The condition \*(L"path does not 2752not exist\*(R" is a status change like any other. The condition \*(L"path does not
2627exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the 2753exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the
2628\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at 2754\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at
… …
2859Apart from keeping your process non-blocking (which is a useful 2985Apart from keeping your process non-blocking (which is a useful
2860effect on its own sometimes), idle watchers are a good place to do 2986effect on its own sometimes), idle watchers are a good place to do
2861\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the 2987\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the
2862event loop has handled all outstanding events. 2988event loop has handled all outstanding events.
2863.PP 2989.PP
2990\fIAbusing an \f(CI\*(C`ev_idle\*(C'\fI watcher for its side-effect\fR
2991.IX Subsection "Abusing an ev_idle watcher for its side-effect"
2992.PP
2993As long as there is at least one active idle watcher, libev will never
2994sleep unnecessarily. Or in other words, it will loop as fast as possible.
2995For this to work, the idle watcher doesn't need to be invoked at all \- the
2996lowest priority will do.
2997.PP
2998This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher,
2999to do something on each event loop iteration \- for example to balance load
3000between different connections.
3001.PP
3002See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer
3003example.
3004.PP
2864\fIWatcher-Specific Functions and Data Members\fR 3005\fIWatcher-Specific Functions and Data Members\fR
2865.IX Subsection "Watcher-Specific Functions and Data Members" 3006.IX Subsection "Watcher-Specific Functions and Data Members"
2866.IP "ev_idle_init (ev_idle *, callback)" 4 3007.IP "ev_idle_init (ev_idle *, callback)" 4
2867.IX Item "ev_idle_init (ev_idle *, callback)" 3008.IX Item "ev_idle_init (ev_idle *, callback)"
2868Initialises and configures the idle watcher \- it has no parameters of any 3009Initialises and configures the idle watcher \- it has no parameters of any
… …
2873.IX Subsection "Examples" 3014.IX Subsection "Examples"
2874.PP 3015.PP
2875Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the 3016Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the
2876callback, free it. Also, use no error checking, as usual. 3017callback, free it. Also, use no error checking, as usual.
2877.PP 3018.PP
2878.Vb 7 3019.Vb 5
2879\& static void 3020\& static void
2880\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) 3021\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
2881\& { 3022\& {
3023\& // stop the watcher
3024\& ev_idle_stop (loop, w);
3025\&
3026\& // now we can free it
2882\& free (w); 3027\& free (w);
3028\&
2883\& // now do something you wanted to do when the program has 3029\& // now do something you wanted to do when the program has
2884\& // no longer anything immediate to do. 3030\& // no longer anything immediate to do.
2885\& } 3031\& }
2886\& 3032\&
2887\& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 3033\& ev_idle *idle_watcher = malloc (sizeof (ev_idle));
… …
2889\& ev_idle_start (loop, idle_watcher); 3035\& ev_idle_start (loop, idle_watcher);
2890.Ve 3036.Ve
2891.ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" 3037.ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!"
2892.el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" 3038.el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!"
2893.IX Subsection "ev_prepare and ev_check - customise your event loop!" 3039.IX Subsection "ev_prepare and ev_check - customise your event loop!"
2894Prepare and check watchers are usually (but not always) used in pairs: 3040Prepare and check watchers are often (but not always) used in pairs:
2895prepare watchers get invoked before the process blocks and check watchers 3041prepare watchers get invoked before the process blocks and check watchers
2896afterwards. 3042afterwards.
2897.PP 3043.PP
2898You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3044You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter
2899the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR 3045the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR
… …
2927with priority higher than or equal to the event loop and one coroutine 3073with priority higher than or equal to the event loop and one coroutine
2928of lower priority, but only once, using idle watchers to keep the event 3074of lower priority, but only once, using idle watchers to keep the event
2929loop from blocking if lower-priority coroutines are active, thus mapping 3075loop from blocking if lower-priority coroutines are active, thus mapping
2930low-priority coroutines to idle/background tasks). 3076low-priority coroutines to idle/background tasks).
2931.PP 3077.PP
2932It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 3078When used for this purpose, it is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers
2933priority, to ensure that they are being run before any other watchers 3079highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) priority, to ensure that they are being run before
2934after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR watchers). 3080any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR
3081watchers).
2935.PP 3082.PP
2936Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not 3083Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not
2937activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they 3084activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they
2938might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As 3085might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As
2939\&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event 3086\&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event
2940loops those other event loops might be in an unusable state until their 3087loops those other event loops might be in an unusable state until their
2941\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with 3088\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with
2942others). 3089others).
3090.PP
3091\fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR
3092.IX Subsection "Abusing an ev_check watcher for its side-effect"
3093.PP
3094\&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be
3095useful because they are called once per event loop iteration. For
3096example, if you want to handle a large number of connections fairly, you
3097normally only do a bit of work for each active connection, and if there
3098is more work to do, you wait for the next event loop iteration, so other
3099connections have a chance of making progress.
3100.PP
3101Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the
3102next event loop iteration. However, that isn't as soon as possible \-
3103without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked.
3104.PP
3105This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a
3106single global idle watcher that is active as long as you have one active
3107\&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop
3108will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets
3109invoked. Neither watcher alone can do that.
2943.PP 3110.PP
2944\fIWatcher-Specific Functions and Data Members\fR 3111\fIWatcher-Specific Functions and Data Members\fR
2945.IX Subsection "Watcher-Specific Functions and Data Members" 3112.IX Subsection "Watcher-Specific Functions and Data Members"
2946.IP "ev_prepare_init (ev_prepare *, callback)" 4 3113.IP "ev_prepare_init (ev_prepare *, callback)" 4
2947.IX Item "ev_prepare_init (ev_prepare *, callback)" 3114.IX Item "ev_prepare_init (ev_prepare *, callback)"
… …
3152\fIWatcher-Specific Functions and Data Members\fR 3319\fIWatcher-Specific Functions and Data Members\fR
3153.IX Subsection "Watcher-Specific Functions and Data Members" 3320.IX Subsection "Watcher-Specific Functions and Data Members"
3154.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3321.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
3155.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 3322.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
3156.PD 0 3323.PD 0
3157.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3324.IP "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)" 4
3158.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 3325.IX Item "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)"
3159.PD 3326.PD
3160Configures the watcher to embed the given loop, which must be 3327Configures the watcher to embed the given loop, which must be
3161embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be 3328embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be
3162invoked automatically, otherwise it is the responsibility of the callback 3329invoked automatically, otherwise it is the responsibility of the callback
3163to invoke it (it will continue to be called until the sweep has been done, 3330to invoke it (it will continue to be called until the sweep has been done,
… …
3226.ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" 3393.ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork"
3227.el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" 3394.el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
3228.IX Subsection "ev_fork - the audacity to resume the event loop after a fork" 3395.IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
3229Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 3396Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
3230whoever is a good citizen cared to tell libev about it by calling 3397whoever is a good citizen cared to tell libev about it by calling
3231\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the 3398\&\f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the event loop blocks next
3232event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, 3399and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, and only in the child
3233and only in the child after the fork. If whoever good citizen calling 3400after the fork. If whoever good citizen calling \f(CW\*(C`ev_default_fork\*(C'\fR cheats
3234\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork 3401and calls it in the wrong process, the fork handlers will be invoked, too,
3235handlers will be invoked, too, of course. 3402of course.
3236.PP 3403.PP
3237\fIThe special problem of life after fork \- how is it possible?\fR 3404\fIThe special problem of life after fork \- how is it possible?\fR
3238.IX Subsection "The special problem of life after fork - how is it possible?" 3405.IX Subsection "The special problem of life after fork - how is it possible?"
3239.PP 3406.PP
3240Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3407Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set
… …
3326it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe. 3493it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe.
3327.PP 3494.PP
3328This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, 3495This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals,
3329too, are asynchronous in nature, and signals, too, will be compressed 3496too, are asynchronous in nature, and signals, too, will be compressed
3330(i.e. the number of callback invocations may be less than the number of 3497(i.e. the number of callback invocations may be less than the number of
3331\&\f(CW\*(C`ev_async_sent\*(C'\fR calls). In fact, you could use signal watchers as a kind 3498\&\f(CW\*(C`ev_async_send\*(C'\fR calls). In fact, you could use signal watchers as a kind
3332of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused 3499of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused
3333signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread, 3500signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread,
3334even without knowing which loop owns the signal. 3501even without knowing which loop owns the signal.
3335.PP
3336Unlike \f(CW\*(C`ev_signal\*(C'\fR watchers, \f(CW\*(C`ev_async\*(C'\fR works with any event loop, not
3337just the default loop.
3338.PP 3502.PP
3339\fIQueueing\fR 3503\fIQueueing\fR
3340.IX Subsection "Queueing" 3504.IX Subsection "Queueing"
3341.PP 3505.PP
3342\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason 3506\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason
… …
3437Unlike \f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, 3601Unlike \f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads,
3438signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the 3602signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the
3439embedding section below on what exactly this means). 3603embedding section below on what exactly this means).
3440.Sp 3604.Sp
3441Note that, as with other watchers in libev, multiple events might get 3605Note that, as with other watchers in libev, multiple events might get
3442compressed into a single callback invocation (another way to look at this 3606compressed into a single callback invocation (another way to look at
3443is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered, set on \f(CW\*(C`ev_async_send\*(C'\fR, 3607this is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered: they are set on
3444reset when the event loop detects that). 3608\&\f(CW\*(C`ev_async_send\*(C'\fR, reset when the event loop detects that).
3445.Sp 3609.Sp
3446This call incurs the overhead of a system call only once per event loop 3610This call incurs the overhead of at most one extra system call per event
3447iteration, so while the overhead might be noticeable, it doesn't apply to 3611loop iteration, if the event loop is blocked, and no syscall at all if
3448repeated calls to \f(CW\*(C`ev_async_send\*(C'\fR for the same event loop. 3612the event loop (or your program) is processing events. That means that
3613repeated calls are basically free (there is no need to avoid calls for
3614performance reasons) and that the overhead becomes smaller (typically
3615zero) under load.
3449.IP "bool = ev_async_pending (ev_async *)" 4 3616.IP "bool = ev_async_pending (ev_async *)" 4
3450.IX Item "bool = ev_async_pending (ev_async *)" 3617.IX Item "bool = ev_async_pending (ev_async *)"
3451Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the 3618Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the
3452watcher but the event has not yet been processed (or even noted) by the 3619watcher but the event has not yet been processed (or even noted) by the
3453event loop. 3620event loop.
… …
3501\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3668\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3502.Ve 3669.Ve
3503.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 3670.IP "ev_feed_fd_event (loop, int fd, int revents)" 4
3504.IX Item "ev_feed_fd_event (loop, int fd, int revents)" 3671.IX Item "ev_feed_fd_event (loop, int fd, int revents)"
3505Feed an event on the given fd, as if a file descriptor backend detected 3672Feed an event on the given fd, as if a file descriptor backend detected
3506the given events it. 3673the given events.
3507.IP "ev_feed_signal_event (loop, int signum)" 4 3674.IP "ev_feed_signal_event (loop, int signum)" 4
3508.IX Item "ev_feed_signal_event (loop, int signum)" 3675.IX Item "ev_feed_signal_event (loop, int signum)"
3509Feed an event as if the given signal occurred. See also \f(CW\*(C`ev_feed_signal\*(C'\fR, 3676Feed an event as if the given signal occurred. See also \f(CW\*(C`ev_feed_signal\*(C'\fR,
3510which is async-safe. 3677which is async-safe.
3511.SH "COMMON OR USEFUL IDIOMS (OR BOTH)" 3678.SH "COMMON OR USEFUL IDIOMS (OR BOTH)"
… …
3585\& { 3752\& {
3586\& struct my_biggy big = (struct my_biggy *) 3753\& struct my_biggy big = (struct my_biggy *)
3587\& (((char *)w) \- offsetof (struct my_biggy, t2)); 3754\& (((char *)w) \- offsetof (struct my_biggy, t2));
3588\& } 3755\& }
3589.Ve 3756.Ve
3757.SS "\s-1AVOIDING\s0 \s-1FINISHING\s0 \s-1BEFORE\s0 \s-1RETURNING\s0"
3758.IX Subsection "AVOIDING FINISHING BEFORE RETURNING"
3759Often you have structures like this in event-based programs:
3760.PP
3761.Vb 4
3762\& callback ()
3763\& {
3764\& free (request);
3765\& }
3766\&
3767\& request = start_new_request (..., callback);
3768.Ve
3769.PP
3770The intent is to start some \*(L"lengthy\*(R" operation. The \f(CW\*(C`request\*(C'\fR could be
3771used to cancel the operation, or do other things with it.
3772.PP
3773It's not uncommon to have code paths in \f(CW\*(C`start_new_request\*(C'\fR that
3774immediately invoke the callback, for example, to report errors. Or you add
3775some caching layer that finds that it can skip the lengthy aspects of the
3776operation and simply invoke the callback with the result.
3777.PP
3778The problem here is that this will happen \fIbefore\fR \f(CW\*(C`start_new_request\*(C'\fR
3779has returned, so \f(CW\*(C`request\*(C'\fR is not set.
3780.PP
3781Even if you pass the request by some safer means to the callback, you
3782might want to do something to the request after starting it, such as
3783canceling it, which probably isn't working so well when the callback has
3784already been invoked.
3785.PP
3786A common way around all these issues is to make sure that
3787\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If
3788\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
3789delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for
3790example, or more sneakily, by reusing an existing (stopped) watcher and
3791pushing it into the pending queue:
3792.PP
3793.Vb 2
3794\& ev_set_cb (watcher, callback);
3795\& ev_feed_event (EV_A_ watcher, 0);
3796.Ve
3797.PP
3798This way, \f(CW\*(C`start_new_request\*(C'\fR can safely return before the callback is
3799invoked, while not delaying callback invocation too much.
3590.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0" 3800.SS "\s-1MODEL/NESTED\s0 \s-1EVENT\s0 \s-1LOOP\s0 \s-1INVOCATIONS\s0 \s-1AND\s0 \s-1EXIT\s0 \s-1CONDITIONS\s0"
3591.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS" 3801.IX Subsection "MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS"
3592Often (especially in \s-1GUI\s0 toolkits) there are places where you have 3802Often (especially in \s-1GUI\s0 toolkits) there are places where you have
3593\&\fImodal\fR interaction, which is most easily implemented by recursively 3803\&\fImodal\fR interaction, which is most easily implemented by recursively
3594invoking \f(CW\*(C`ev_run\*(C'\fR. 3804invoking \f(CW\*(C`ev_run\*(C'\fR.
3595.PP 3805.PP
3596This brings the problem of exiting \- a callback might want to finish the 3806This brings the problem of exiting \- a callback might want to finish the
3597main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but 3807main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but
3598a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one 3808a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one
3599and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some 3809and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some
3600other combination: In these cases, \f(CW\*(C`ev_break\*(C'\fR will not work alone. 3810other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work.
3601.PP 3811.PP
3602The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR 3812The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR
3603invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is 3813invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is
3604triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: 3814triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR:
3605.PP 3815.PP
… …
3608\& int exit_main_loop = 0; 3818\& int exit_main_loop = 0;
3609\& 3819\&
3610\& while (!exit_main_loop) 3820\& while (!exit_main_loop)
3611\& ev_run (EV_DEFAULT_ EVRUN_ONCE); 3821\& ev_run (EV_DEFAULT_ EVRUN_ONCE);
3612\& 3822\&
3613\& // in a model watcher 3823\& // in a modal watcher
3614\& int exit_nested_loop = 0; 3824\& int exit_nested_loop = 0;
3615\& 3825\&
3616\& while (!exit_nested_loop) 3826\& while (!exit_nested_loop)
3617\& ev_run (EV_A_ EVRUN_ONCE); 3827\& ev_run (EV_A_ EVRUN_ONCE);
3618.Ve 3828.Ve
… …
3810.PP 4020.PP
3811.Vb 6 4021.Vb 6
3812\& void 4022\& void
3813\& wait_for_event (ev_watcher *w) 4023\& wait_for_event (ev_watcher *w)
3814\& { 4024\& {
3815\& ev_cb_set (w) = current_coro; 4025\& ev_set_cb (w, current_coro);
3816\& switch_to (libev_coro); 4026\& switch_to (libev_coro);
3817\& } 4027\& }
3818.Ve 4028.Ve
3819.PP 4029.PP
3820That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and 4030That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and
3821continues the libev coroutine, which, when appropriate, switches back to 4031continues the libev coroutine, which, when appropriate, switches back to
3822this or any other coroutine. I am sure if you sue this your own :) 4032this or any other coroutine.
3823.PP 4033.PP
3824You can do similar tricks if you have, say, threads with an event queue \- 4034You can do similar tricks if you have, say, threads with an event queue \-
3825instead of storing a coroutine, you store the queue object and instead of 4035instead of storing a coroutine, you store the queue object and instead of
3826switching to a coroutine, you push the watcher onto the queue and notify 4036switching to a coroutine, you push the watcher onto the queue and notify
3827any waiters. 4037any waiters.
3828.PP 4038.PP
3829To embed libev, see \s-1EMBEDDING\s0, but in short, it's easiest to create two 4039To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two
3830files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4040files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
3831.PP 4041.PP
3832.Vb 4 4042.Vb 4
3833\& // my_ev.h 4043\& // my_ev.h
3834\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4044\& #define EV_CB_DECLARE(type) struct my_coro *cb;
… …
3873.IP "\(bu" 4 4083.IP "\(bu" 4
3874The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need 4084The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
3875to use the libev header file and library. 4085to use the libev header file and library.
3876.SH "\*(C+ SUPPORT" 4086.SH "\*(C+ SUPPORT"
3877.IX Header " SUPPORT" 4087.IX Header " SUPPORT"
4088.SS "C \s-1API\s0"
4089.IX Subsection "C API"
4090The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4091libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4092will work fine.
4093.PP
4094Proper exception specifications might have to be added to callbacks passed
4095to libev: exceptions may be thrown only from watcher callbacks, all
4096other callbacks (allocator, syserr, loop acquire/release and periodic
4097reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw
4098()\*(C'\fR specification. If you have code that needs to be compiled as both C
4099and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
4100.PP
4101.Vb 6
4102\& static void
4103\& fatal_error (const char *msg) EV_THROW
4104\& {
4105\& perror (msg);
4106\& abort ();
4107\& }
4108\&
4109\& ...
4110\& ev_set_syserr_cb (fatal_error);
4111.Ve
4112.PP
4113The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR,
4114\&\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
4115because it runs cleanup watchers).
4116.PP
4117Throwing exceptions in watcher callbacks is only supported if libev itself
4118is compiled with a \*(C+ compiler or your C and \*(C+ environments allow
4119throwing exceptions through C libraries (most do).
4120.SS "\*(C+ \s-1API\s0"
4121.IX Subsection " API"
3878Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow 4122Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
3879you to use some convenience methods to start/stop watchers and also change 4123you to use some convenience methods to start/stop watchers and also change
3880the callback model to a model using method callbacks on objects. 4124the callback model to a model using method callbacks on objects.
3881.PP 4125.PP
3882To use it, 4126To use it,
… …
3898Currently, functions, static and non-static member functions and classes 4142Currently, functions, static and non-static member functions and classes
3899with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy 4143with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy
3900to add as long as they only need one additional pointer for context. If 4144to add as long as they only need one additional pointer for context. If
3901you need support for other types of functors please contact the author 4145you need support for other types of functors please contact the author
3902(preferably after implementing it). 4146(preferably after implementing it).
4147.PP
4148For all this to work, your \*(C+ compiler either has to use the same calling
4149conventions as your C compiler (for static member functions), or you have
4150to embed libev and compile libev itself as \*(C+.
3903.PP 4151.PP
3904Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: 4152Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace:
3905.ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4 4153.ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4
3906.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4 4154.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4
3907.IX Item "ev::READ, ev::WRITE etc." 4155.IX Item "ev::READ, ev::WRITE etc."
… …
3915.el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4 4163.el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4
3916.IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc." 4164.IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc."
3917For each \f(CW\*(C`ev_TYPE\*(C'\fR watcher in \fIev.h\fR there is a corresponding class of 4165For each \f(CW\*(C`ev_TYPE\*(C'\fR watcher in \fIev.h\fR there is a corresponding class of
3918the same name in the \f(CW\*(C`ev\*(C'\fR namespace, with the exception of \f(CW\*(C`ev_signal\*(C'\fR 4166the same name in the \f(CW\*(C`ev\*(C'\fR namespace, with the exception of \f(CW\*(C`ev_signal\*(C'\fR
3919which is called \f(CW\*(C`ev::sig\*(C'\fR to avoid clashes with the \f(CW\*(C`signal\*(C'\fR macro 4167which is called \f(CW\*(C`ev::sig\*(C'\fR to avoid clashes with the \f(CW\*(C`signal\*(C'\fR macro
3920defines by many implementations. 4168defined by many implementations.
3921.Sp 4169.Sp
3922All of those classes have these methods: 4170All of those classes have these methods:
3923.RS 4 4171.RS 4
3924.IP "ev::TYPE::TYPE ()" 4 4172.IP "ev::TYPE::TYPE ()" 4
3925.IX Item "ev::TYPE::TYPE ()" 4173.IX Item "ev::TYPE::TYPE ()"
… …
4016.IX Item "w->set (loop)" 4264.IX Item "w->set (loop)"
4017Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only 4265Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only
4018do this when the watcher is inactive (and not pending either). 4266do this when the watcher is inactive (and not pending either).
4019.IP "w\->set ([arguments])" 4 4267.IP "w\->set ([arguments])" 4
4020.IX Item "w->set ([arguments])" 4268.IX Item "w->set ([arguments])"
4021Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this 4269Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR (except for \f(CW\*(C`ev::embed\*(C'\fR watchers>),
4022method or a suitable start method must be called at least once. Unlike the 4270with the same arguments. Either this method or a suitable start method
4023C counterpart, an active watcher gets automatically stopped and restarted 4271must be called at least once. Unlike the C counterpart, an active watcher
4024when reconfiguring it with this method. 4272gets automatically stopped and restarted when reconfiguring it with this
4273method.
4274.Sp
4275For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4276clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4025.IP "w\->start ()" 4 4277.IP "w\->start ()" 4
4026.IX Item "w->start ()" 4278.IX Item "w->start ()"
4027Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4279Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4028constructor already stores the event loop. 4280constructor already stores the event loop.
4029.IP "w\->start ([arguments])" 4 4281.IP "w\->start ([arguments])" 4
… …
4056.PP 4308.PP
4057.Vb 5 4309.Vb 5
4058\& class myclass 4310\& class myclass
4059\& { 4311\& {
4060\& ev::io io ; void io_cb (ev::io &w, int revents); 4312\& ev::io io ; void io_cb (ev::io &w, int revents);
4061\& ev::io2 io2 ; void io2_cb (ev::io &w, int revents); 4313\& ev::io io2 ; void io2_cb (ev::io &w, int revents);
4062\& ev::idle idle; void idle_cb (ev::idle &w, int revents); 4314\& ev::idle idle; void idle_cb (ev::idle &w, int revents);
4063\& 4315\&
4064\& myclass (int fd) 4316\& myclass (int fd)
4065\& { 4317\& {
4066\& io .set <myclass, &myclass::io_cb > (this); 4318\& io .set <myclass, &myclass::io_cb > (this);
… …
4105Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR 4357Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR
4106makes rev work even on mingw. 4358makes rev work even on mingw.
4107.IP "Haskell" 4 4359.IP "Haskell" 4
4108.IX Item "Haskell" 4360.IX Item "Haskell"
4109A haskell binding to libev is available at 4361A haskell binding to libev is available at
4110<http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev>. 4362http://hackage.haskell.org/cgi\-bin/hackage\-scripts/package/hlibev <http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
4111.IP "D" 4 4363.IP "D" 4
4112.IX Item "D" 4364.IX Item "D"
4113Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 4365Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
4114be found at <http://proj.llucax.com.ar/wiki/evd>. 4366be found at <http://www.llucax.com.ar/proj/ev.d/index.html>.
4115.IP "Ocaml" 4 4367.IP "Ocaml" 4
4116.IX Item "Ocaml" 4368.IX Item "Ocaml"
4117Erkki Seppala has written Ocaml bindings for libev, to be found at 4369Erkki Seppala has written Ocaml bindings for libev, to be found at
4118<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. 4370http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/ <http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
4119.IP "Lua" 4 4371.IP "Lua" 4
4120.IX Item "Lua" 4372.IX Item "Lua"
4121Brian Maher has written a partial interface to libev for lua (at the 4373Brian Maher has written a partial interface to libev for lua (at the
4122time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4374time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4123<http://github.com/brimworks/lua\-ev>. 4375http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4376.IP "Javascript" 4
4377.IX Item "Javascript"
4378Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4379.IP "Others" 4
4380.IX Item "Others"
4381There are others, and I stopped counting.
4124.SH "MACRO MAGIC" 4382.SH "MACRO MAGIC"
4125.IX Header "MACRO MAGIC" 4383.IX Header "MACRO MAGIC"
4126Libev can be compiled with a variety of options, the most fundamental 4384Libev can be compiled with a variety of options, the most fundamental
4127of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 4385of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
4128functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 4386functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
4163suitable for use with \f(CW\*(C`EV_A\*(C'\fR. 4421suitable for use with \f(CW\*(C`EV_A\*(C'\fR.
4164.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4 4422.ie n .IP """EV_DEFAULT"", ""EV_DEFAULT_""" 4
4165.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 4423.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
4166.IX Item "EV_DEFAULT, EV_DEFAULT_" 4424.IX Item "EV_DEFAULT, EV_DEFAULT_"
4167Similar to the other two macros, this gives you the value of the default 4425Similar to the other two macros, this gives you the value of the default
4168loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 4426loop, if multiple loops are supported (\*(L"ev loop default\*(R"). The default loop
4427will be initialised if it isn't already initialised.
4428.Sp
4429For non-multiplicity builds, these macros do nothing, so you always have
4430to initialise the loop somewhere.
4169.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4 4431.ie n .IP """EV_DEFAULT_UC"", ""EV_DEFAULT_UC_""" 4
4170.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4 4432.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4
4171.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_" 4433.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_"
4172Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the 4434Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the
4173default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour 4435default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour
… …
4328supported). It will also not define any of the structs usually found in 4590supported). It will also not define any of the structs usually found in
4329\&\fIevent.h\fR that are not directly supported by the libev core alone. 4591\&\fIevent.h\fR that are not directly supported by the libev core alone.
4330.Sp 4592.Sp
4331In standalone mode, libev will still try to automatically deduce the 4593In standalone mode, libev will still try to automatically deduce the
4332configuration, but has to be more conservative. 4594configuration, but has to be more conservative.
4595.IP "\s-1EV_USE_FLOOR\s0" 4
4596.IX Item "EV_USE_FLOOR"
4597If defined to be \f(CW1\fR, libev will use the \f(CW\*(C`floor ()\*(C'\fR function for its
4598periodic reschedule calculations, otherwise libev will fall back on a
4599portable (slower) implementation. If you enable this, you usually have to
4600link against libm or something equivalent. Enabling this when the \f(CW\*(C`floor\*(C'\fR
4601function is not available will fail, so the safe default is to not enable
4602this.
4333.IP "\s-1EV_USE_MONOTONIC\s0" 4 4603.IP "\s-1EV_USE_MONOTONIC\s0" 4
4334.IX Item "EV_USE_MONOTONIC" 4604.IX Item "EV_USE_MONOTONIC"
4335If defined to be \f(CW1\fR, libev will try to detect the availability of the 4605If defined to be \f(CW1\fR, libev will try to detect the availability of the
4336monotonic clock option at both compile time and runtime. Otherwise no 4606monotonic clock option at both compile time and runtime. Otherwise no
4337use of the monotonic clock option will be attempted. If you enable this, 4607use of the monotonic clock option will be attempted. If you enable this,
… …
4411.IX Item "EV_WIN32_CLOSE_FD(fd)" 4681.IX Item "EV_WIN32_CLOSE_FD(fd)"
4412If programs implement their own fd to handle mapping on win32, then this 4682If programs implement their own fd to handle mapping on win32, then this
4413macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister 4683macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister
4414file descriptors again. Note that the replacement function has to close 4684file descriptors again. Note that the replacement function has to close
4415the underlying \s-1OS\s0 handle. 4685the underlying \s-1OS\s0 handle.
4686.IP "\s-1EV_USE_WSASOCKET\s0" 4
4687.IX Item "EV_USE_WSASOCKET"
4688If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal
4689communication socket, which works better in some environments. Otherwise,
4690the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other
4691environments.
4416.IP "\s-1EV_USE_POLL\s0" 4 4692.IP "\s-1EV_USE_POLL\s0" 4
4417.IX Item "EV_USE_POLL" 4693.IX Item "EV_USE_POLL"
4418If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) 4694If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
4419backend. Otherwise it will be enabled on non\-win32 platforms. It 4695backend. Otherwise it will be enabled on non\-win32 platforms. It
4420takes precedence over select. 4696takes precedence over select.
… …
4449.IX Item "EV_USE_INOTIFY" 4725.IX Item "EV_USE_INOTIFY"
4450If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify 4726If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify
4451interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will 4727interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
4452be detected at runtime. If undefined, it will be enabled if the headers 4728be detected at runtime. If undefined, it will be enabled if the headers
4453indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4729indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4730.IP "\s-1EV_NO_SMP\s0" 4
4731.IX Item "EV_NO_SMP"
4732If defined to be \f(CW1\fR, libev will assume that memory is always coherent
4733between threads, that is, threads can be used, but threads never run on
4734different cpus (or different cpu cores). This reduces dependencies
4735and makes libev faster.
4736.IP "\s-1EV_NO_THREADS\s0" 4
4737.IX Item "EV_NO_THREADS"
4738If defined to be \f(CW1\fR, libev will assume that it will never be called from
4739different threads (that includes signal handlers), which is a stronger
4740assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes
4741libev faster.
4454.IP "\s-1EV_ATOMIC_T\s0" 4 4742.IP "\s-1EV_ATOMIC_T\s0" 4
4455.IX Item "EV_ATOMIC_T" 4743.IX Item "EV_ATOMIC_T"
4456Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4744Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4457access is atomic with respect to other threads or signal contexts. No such 4745access is atomic with respect to other threads or signal contexts. No
4458type is easily found in the C language, so you can provide your own type 4746such type is easily found in the C language, so you can provide your own
4459that you know is safe for your purposes. It is used both for signal handler \*(L"locking\*(R" 4747type that you know is safe for your purposes. It is used both for signal
4460as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR watchers. 4748handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4749watchers.
4461.Sp 4750.Sp
4462In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4751In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4463(from \fIsignal.h\fR), which is usually good enough on most platforms. 4752(from \fIsignal.h\fR), which is usually good enough on most platforms.
4464.IP "\s-1EV_H\s0 (h)" 4 4753.IP "\s-1EV_H\s0 (h)" 4
4465.IX Item "EV_H (h)" 4754.IX Item "EV_H (h)"
… …
4486If undefined or defined to \f(CW1\fR, then all event-loop-specific functions 4775If undefined or defined to \f(CW1\fR, then all event-loop-specific functions
4487will have the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument, and you can create 4776will have the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument, and you can create
4488additional independent event loops. Otherwise there will be no support 4777additional independent event loops. Otherwise there will be no support
4489for multiple event loops and there is no first event loop pointer 4778for multiple event loops and there is no first event loop pointer
4490argument. Instead, all functions act on the single default loop. 4779argument. Instead, all functions act on the single default loop.
4780.Sp
4781Note that \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR will no longer provide a
4782default loop when multiplicity is switched off \- you always have to
4783initialise the loop manually in this case.
4491.IP "\s-1EV_MINPRI\s0" 4 4784.IP "\s-1EV_MINPRI\s0" 4
4492.IX Item "EV_MINPRI" 4785.IX Item "EV_MINPRI"
4493.PD 0 4786.PD 0
4494.IP "\s-1EV_MAXPRI\s0" 4 4787.IP "\s-1EV_MAXPRI\s0" 4
4495.IX Item "EV_MAXPRI" 4788.IX Item "EV_MAXPRI"
… …
4531\& #define EV_CHILD_ENABLE 1 4824\& #define EV_CHILD_ENABLE 1
4532\& #define EV_ASYNC_ENABLE 1 4825\& #define EV_ASYNC_ENABLE 1
4533.Ve 4826.Ve
4534.Sp 4827.Sp
4535The actual value is a bitset, it can be a combination of the following 4828The actual value is a bitset, it can be a combination of the following
4536values: 4829values (by default, all of these are enabled):
4537.RS 4 4830.RS 4
4538.ie n .IP "1 \- faster/larger code" 4 4831.ie n .IP "1 \- faster/larger code" 4
4539.el .IP "\f(CW1\fR \- faster/larger code" 4 4832.el .IP "\f(CW1\fR \- faster/larger code" 4
4540.IX Item "1 - faster/larger code" 4833.IX Item "1 - faster/larger code"
4541Use larger code to speed up some operations. 4834Use larger code to speed up some operations.
… …
4544code size by roughly 30% on amd64). 4837code size by roughly 30% on amd64).
4545.Sp 4838.Sp
4546When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with 4839When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with
4547gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of 4840gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of
4548assertions. 4841assertions.
4842.Sp
4843The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4844(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4549.ie n .IP "2 \- faster/larger data structures" 4 4845.ie n .IP "2 \- faster/larger data structures" 4
4550.el .IP "\f(CW2\fR \- faster/larger data structures" 4 4846.el .IP "\f(CW2\fR \- faster/larger data structures" 4
4551.IX Item "2 - faster/larger data structures" 4847.IX Item "2 - faster/larger data structures"
4552Replaces the small 2\-heap for timer management by a faster 4\-heap, larger 4848Replaces the small 2\-heap for timer management by a faster 4\-heap, larger
4553hash table sizes and so on. This will usually further increase code size 4849hash table sizes and so on. This will usually further increase code size
4554and can additionally have an effect on the size of data structures at 4850and can additionally have an effect on the size of data structures at
4555runtime. 4851runtime.
4852.Sp
4853The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4854(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4556.ie n .IP "4 \- full \s-1API\s0 configuration" 4 4855.ie n .IP "4 \- full \s-1API\s0 configuration" 4
4557.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 4856.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4
4558.IX Item "4 - full API configuration" 4857.IX Item "4 - full API configuration"
4559This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and 4858This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and
4560enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). 4859enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1).
… …
4592With an intelligent-enough linker (gcc+binutils are intelligent enough 4891With an intelligent-enough linker (gcc+binutils are intelligent enough
4593when you use \f(CW\*(C`\-Wl,\-\-gc\-sections \-ffunction\-sections\*(C'\fR) functions unused by 4892when you use \f(CW\*(C`\-Wl,\-\-gc\-sections \-ffunction\-sections\*(C'\fR) functions unused by
4594your program might be left out as well \- a binary starting a timer and an 4893your program might be left out as well \- a binary starting a timer and an
4595I/O watcher then might come out at only 5Kb. 4894I/O watcher then might come out at only 5Kb.
4596.RE 4895.RE
4896.IP "\s-1EV_API_STATIC\s0" 4
4897.IX Item "EV_API_STATIC"
4898If this symbol is defined (by default it is not), then all identifiers
4899will have static linkage. This means that libev will not export any
4900identifiers, and you cannot link against libev anymore. This can be useful
4901when you embed libev, only want to use libev functions in a single file,
4902and do not want its identifiers to be visible.
4903.Sp
4904To use this, define \f(CW\*(C`EV_API_STATIC\*(C'\fR and include \fIev.c\fR in the file that
4905wants to use libev.
4906.Sp
4907This option only works when libev is compiled with a C compiler, as \*(C+
4908doesn't support the required declaration syntax.
4597.IP "\s-1EV_AVOID_STDIO\s0" 4 4909.IP "\s-1EV_AVOID_STDIO\s0" 4
4598.IX Item "EV_AVOID_STDIO" 4910.IX Item "EV_AVOID_STDIO"
4599If this is set to \f(CW1\fR at compiletime, then libev will avoid using stdio 4911If this is set to \f(CW1\fR at compiletime, then libev will avoid using stdio
4600functions (printf, scanf, perror etc.). This will increase the code size 4912functions (printf, scanf, perror etc.). This will increase the code size
4601somewhat, but if your program doesn't otherwise depend on stdio and your 4913somewhat, but if your program doesn't otherwise depend on stdio and your
… …
4978requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 5290requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
4979model. Libev still offers limited functionality on this platform in 5291model. Libev still offers limited functionality on this platform in
4980the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket 5292the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
4981descriptors. This only applies when using Win32 natively, not when using 5293descriptors. This only applies when using Win32 natively, not when using
4982e.g. cygwin. Actually, it only applies to the microsofts own compilers, 5294e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4983as every compielr comes with a slightly differently broken/incompatible 5295as every compiler comes with a slightly differently broken/incompatible
4984environment. 5296environment.
4985.PP 5297.PP
4986Lifting these limitations would basically require the full 5298Lifting these limitations would basically require the full
4987re-implementation of the I/O system. If you are into this kind of thing, 5299re-implementation of the I/O system. If you are into this kind of thing,
4988then note that glib does exactly that for you in a very portable way (note 5300then note that glib does exactly that for you in a very portable way (note
… …
5107thread\*(R" or will block signals process-wide, both behaviours would 5419thread\*(R" or will block signals process-wide, both behaviours would
5108be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and 5420be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
5109\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. 5421\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
5110.Sp 5422.Sp
5111The most portable way to handle signals is to block signals in all threads 5423The most portable way to handle signals is to block signals in all threads
5112except the initial one, and run the default loop in the initial thread as 5424except the initial one, and run the signal handling loop in the initial
5113well. 5425thread as well.
5114.ie n .IP """long"" must be large enough for common memory allocation sizes" 4 5426.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
5115.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 5427.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
5116.IX Item "long must be large enough for common memory allocation sizes" 5428.IX Item "long must be large enough for common memory allocation sizes"
5117To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5429To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally
5118instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5430instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX
… …
5124.IX Item "double must hold a time value in seconds with enough accuracy" 5436.IX Item "double must hold a time value in seconds with enough accuracy"
5125The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to 5437The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
5126have at least 51 bits of mantissa (and 9 bits of exponent), which is 5438have at least 51 bits of mantissa (and 9 bits of exponent), which is
5127good enough for at least into the year 4000 with millisecond accuracy 5439good enough for at least into the year 4000 with millisecond accuracy
5128(the design goal for libev). This requirement is overfulfilled by 5440(the design goal for libev). This requirement is overfulfilled by
5129implementations using \s-1IEEE\s0 754, which is basically all existing ones. With 5441implementations using \s-1IEEE\s0 754, which is basically all existing ones.
5442.Sp
5130\&\s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least 2200. 5443With \s-1IEEE\s0 754 doubles, you get microsecond accuracy until at least the
5444year 2255 (and millisecond accuracy till the year 287396 \- by then, libev
5445is either obsolete or somebody patched it to use \f(CW\*(C`long double\*(C'\fR or
5446something like that, just kidding).
5131.PP 5447.PP
5132If you know of other additional requirements drop me a note. 5448If you know of other additional requirements drop me a note.
5133.SH "ALGORITHMIC COMPLEXITIES" 5449.SH "ALGORITHMIC COMPLEXITIES"
5134.IX Header "ALGORITHMIC COMPLEXITIES" 5450.IX Header "ALGORITHMIC COMPLEXITIES"
5135In this section the complexities of (many of) the algorithms used inside 5451In this section the complexities of (many of) the algorithms used inside
… …
5189.IX Item "Processing ev_async_send: O(number_of_async_watchers)" 5505.IX Item "Processing ev_async_send: O(number_of_async_watchers)"
5190.IP "Processing signals: O(max_signal_number)" 4 5506.IP "Processing signals: O(max_signal_number)" 4
5191.IX Item "Processing signals: O(max_signal_number)" 5507.IX Item "Processing signals: O(max_signal_number)"
5192.PD 5508.PD
5193Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR 5509Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR
5194calls in the current loop iteration. Checking for async and signal events 5510calls in the current loop iteration and the loop is currently
5511blocked. Checking for async and signal events involves iterating over all
5195involves iterating over all running async watchers or all signal numbers. 5512running async watchers or all signal numbers.
5196.SH "PORTING FROM LIBEV 3.X TO 4.X" 5513.SH "PORTING FROM LIBEV 3.X TO 4.X"
5197.IX Header "PORTING FROM LIBEV 3.X TO 4.X" 5514.IX Header "PORTING FROM LIBEV 3.X TO 4.X"
5198The major version 4 introduced some incompatible changes to the \s-1API\s0. 5515The major version 4 introduced some incompatible changes to the \s-1API\s0.
5199.PP 5516.PP
5200At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions 5517At the moment, the \f(CW\*(C`ev.h\*(C'\fR header file provides compatibility definitions
… …
5203new \s-1API\s0 early than late. 5520new \s-1API\s0 early than late.
5204.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5521.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5205.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5522.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5206.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5523.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5207The backward compatibility mechanism can be controlled by 5524The backward compatibility mechanism can be controlled by
5208\&\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 5525\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R"
5209section. 5526section.
5210.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5527.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5211.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5528.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5212.IX Item "ev_default_destroy and ev_default_fork have been removed" 5529.IX Item "ev_default_destroy and ev_default_fork have been removed"
5213These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5530These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts:
… …
5297.IX Item "real time" 5614.IX Item "real time"
5298The physical time that is observed. It is apparently strictly monotonic :) 5615The physical time that is observed. It is apparently strictly monotonic :)
5299.IP "wall-clock time" 4 5616.IP "wall-clock time" 4
5300.IX Item "wall-clock time" 5617.IX Item "wall-clock time"
5301The time and date as shown on clocks. Unlike real time, it can actually 5618The time and date as shown on clocks. Unlike real time, it can actually
5302be wrong and jump forwards and backwards, e.g. when the you adjust your 5619be wrong and jump forwards and backwards, e.g. when you adjust your
5303clock. 5620clock.
5304.IP "watcher" 4 5621.IP "watcher" 4
5305.IX Item "watcher" 5622.IX Item "watcher"
5306A data structure that describes interest in certain events. Watchers need 5623A data structure that describes interest in certain events. Watchers need
5307to be started (attached to an event loop) before they can receive events. 5624to be started (attached to an event loop) before they can receive events.

Diff Legend

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