… | |
… | |
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 "2012-02-04" "libev-4.11" "libev - high performance full featured event loop" |
127 | .TH LIBEV 3 "2012-05-06" "libev-4.11" "libev - high performance full featured event loop" |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
129 | .\" way too many mistakes in technical documents. |
129 | .\" way too many mistakes in technical documents. |
130 | .if n .ad l |
130 | .if n .ad l |
131 | .nh |
131 | .nh |
132 | .SH "NAME" |
132 | .SH "NAME" |
… | |
… | |
367 | current system. To find which embeddable backends might be supported on |
367 | current system. To find which embeddable backends might be supported on |
368 | the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () |
368 | the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () |
369 | & ev_supported_backends ()\*(C'\fR, likewise for recommended ones. |
369 | & ev_supported_backends ()\*(C'\fR, likewise for recommended ones. |
370 | .Sp |
370 | .Sp |
371 | See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
371 | See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
372 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
372 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" 4 |
373 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
373 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" |
374 | Sets the allocation function to use (the prototype is similar \- the |
374 | Sets the allocation function to use (the prototype is similar \- the |
375 | semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is |
375 | semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is |
376 | used to allocate and free memory (no surprises here). If it returns zero |
376 | used to allocate and free memory (no surprises here). If it returns zero |
377 | when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort |
377 | when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort |
378 | or take some potentially destructive action. |
378 | or take some potentially destructive action. |
… | |
… | |
404 | \& } |
404 | \& } |
405 | \& |
405 | \& |
406 | \& ... |
406 | \& ... |
407 | \& ev_set_allocator (persistent_realloc); |
407 | \& ev_set_allocator (persistent_realloc); |
408 | .Ve |
408 | .Ve |
409 | .IP "ev_set_syserr_cb (void (*cb)(const char *msg))" 4 |
409 | .IP "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" 4 |
410 | .IX Item "ev_set_syserr_cb (void (*cb)(const char *msg))" |
410 | .IX Item "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" |
411 | Set the callback function to call on a retryable system call error (such |
411 | Set the callback function to call on a retryable system call error (such |
412 | as failed select, poll, epoll_wait). The message is a printable string |
412 | as failed select, poll, epoll_wait). The message is a printable string |
413 | indicating the system call or subsystem causing the problem. If this |
413 | indicating the system call or subsystem causing the problem. If this |
414 | callback is set, then libev will expect it to remedy the situation, no |
414 | callback is set, then libev will expect it to remedy the situation, no |
415 | matter what, when it returns. That is, libev will generally retry the |
415 | matter what, when it returns. That is, libev will generally retry the |
… | |
… | |
685 | .Sp |
685 | .Sp |
686 | It scales in the same way as the epoll backend, but the interface to the |
686 | It scales in the same way as the epoll backend, but the interface to the |
687 | kernel is more efficient (which says nothing about its actual speed, of |
687 | kernel is more efficient (which says nothing about its actual speed, of |
688 | course). While stopping, setting and starting an I/O watcher does never |
688 | course). While stopping, setting and starting an I/O watcher does never |
689 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
689 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
690 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but |
690 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you |
691 | sane, unlike epoll) and it drops fds silently in similarly hard-to-detect |
691 | might have to leak fd's on fork, but it's more sane than epoll) and it |
692 | cases |
692 | drops fds silently in similarly hard-to-detect cases |
693 | .Sp |
693 | .Sp |
694 | This backend usually performs well under most conditions. |
694 | This backend usually performs well under most conditions. |
695 | .Sp |
695 | .Sp |
696 | While nominally embeddable in other event loops, this doesn't work |
696 | While nominally embeddable in other event loops, this doesn't work |
697 | everywhere, so you might need to test for this. And since it is broken |
697 | everywhere, so you might need to test for this. And since it is broken |
… | |
… | |
909 | given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR |
909 | given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR |
910 | without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. |
910 | without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. |
911 | .Sp |
911 | .Sp |
912 | Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the |
912 | Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the |
913 | event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). |
913 | event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). |
914 | .IP "ev_run (loop, int flags)" 4 |
914 | .IP "bool ev_run (loop, int flags)" 4 |
915 | .IX Item "ev_run (loop, int flags)" |
915 | .IX Item "bool ev_run (loop, int flags)" |
916 | Finally, this is it, the event handler. This function usually is called |
916 | Finally, this is it, the event handler. This function usually is called |
917 | after you have initialised all your watchers and you want to start |
917 | after you have initialised all your watchers and you want to start |
918 | handling events. It will ask the operating system for any new events, call |
918 | handling events. It will ask the operating system for any new events, call |
919 | the watcher callbacks, an then repeat the whole process indefinitely: This |
919 | the watcher callbacks, and then repeat the whole process indefinitely: This |
920 | is why event loops are called \fIloops\fR. |
920 | is why event loops are called \fIloops\fR. |
921 | .Sp |
921 | .Sp |
922 | If the flags argument is specified as \f(CW0\fR, it will keep handling events |
922 | If the flags argument is specified as \f(CW0\fR, it will keep handling events |
923 | until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was |
923 | until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was |
924 | called. |
924 | called. |
|
|
925 | .Sp |
|
|
926 | The return value is false if there are no more active watchers (which |
|
|
927 | usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases |
|
|
928 | (which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again"). |
925 | .Sp |
929 | .Sp |
926 | Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than |
930 | Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than |
927 | relying on all watchers to be stopped when deciding when a program has |
931 | relying on all watchers to be stopped when deciding when a program has |
928 | finished (especially in interactive programs), but having a program |
932 | finished (especially in interactive programs), but having a program |
929 | that automatically loops as long as it has to and no longer by virtue |
933 | that automatically loops as long as it has to and no longer by virtue |
930 | of relying on its watchers stopping correctly, that is truly a thing of |
934 | of relying on its watchers stopping correctly, that is truly a thing of |
931 | beauty. |
935 | beauty. |
932 | .Sp |
936 | .Sp |
933 | This function is also \fImostly\fR exception-safe \- you can break out of |
937 | This function is \fImostly\fR exception-safe \- you can break out of a |
934 | a \f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ |
938 | \&\f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ |
935 | exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor |
939 | exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor |
936 | will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. |
940 | will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. |
937 | .Sp |
941 | .Sp |
938 | A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle |
942 | A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle |
939 | those events and any already outstanding ones, but will not wait and |
943 | those events and any already outstanding ones, but will not wait and |
… | |
… | |
1136 | this callback instead. This is useful, for example, when you want to |
1140 | this callback instead. This is useful, for example, when you want to |
1137 | invoke the actual watchers inside another context (another thread etc.). |
1141 | invoke the actual watchers inside another context (another thread etc.). |
1138 | .Sp |
1142 | .Sp |
1139 | If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new |
1143 | If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new |
1140 | callback. |
1144 | callback. |
1141 | .IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0), void (*acquire)(\s-1EV_P\s0))" 4 |
1145 | .IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0) throw (), void (*acquire)(\s-1EV_P\s0) throw ())" 4 |
1142 | .IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))" |
1146 | .IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())" |
1143 | Sometimes you want to share the same loop between multiple threads. This |
1147 | Sometimes you want to share the same loop between multiple threads. This |
1144 | can be done relatively simply by putting mutex_lock/unlock calls around |
1148 | can be done relatively simply by putting mutex_lock/unlock calls around |
1145 | each call to a libev function. |
1149 | each call to a libev function. |
1146 | .Sp |
1150 | .Sp |
1147 | However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible |
1151 | However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible |
… | |
… | |
1295 | .PD 0 |
1299 | .PD 0 |
1296 | .ie n .IP """EV_CHECK""" 4 |
1300 | .ie n .IP """EV_CHECK""" 4 |
1297 | .el .IP "\f(CWEV_CHECK\fR" 4 |
1301 | .el .IP "\f(CWEV_CHECK\fR" 4 |
1298 | .IX Item "EV_CHECK" |
1302 | .IX Item "EV_CHECK" |
1299 | .PD |
1303 | .PD |
1300 | All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts |
1304 | All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts to |
1301 | to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after |
1305 | gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are queued (not invoked) |
1302 | \&\f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it invokes any callbacks for any |
1306 | just after \f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it queues any callbacks |
|
|
1307 | for any received events. That means \f(CW\*(C`ev_prepare\*(C'\fR watchers are the last |
|
|
1308 | watchers invoked before the event loop sleeps or polls for new events, and |
|
|
1309 | \&\f(CW\*(C`ev_check\*(C'\fR watchers will be invoked before any other watchers of the same |
|
|
1310 | or lower priority within an event loop iteration. |
|
|
1311 | .Sp |
1303 | received events. Callbacks of both watcher types can start and stop as |
1312 | Callbacks of both watcher types can start and stop as many watchers as |
1304 | many watchers as they want, and all of them will be taken into account |
1313 | they want, and all of them will be taken into account (for example, a |
1305 | (for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep |
1314 | \&\f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep \f(CW\*(C`ev_run\*(C'\fR from |
1306 | \&\f(CW\*(C`ev_run\*(C'\fR from blocking). |
1315 | blocking). |
1307 | .ie n .IP """EV_EMBED""" 4 |
1316 | .ie n .IP """EV_EMBED""" 4 |
1308 | .el .IP "\f(CWEV_EMBED\fR" 4 |
1317 | .el .IP "\f(CWEV_EMBED\fR" 4 |
1309 | .IX Item "EV_EMBED" |
1318 | .IX Item "EV_EMBED" |
1310 | The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. |
1319 | The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. |
1311 | .ie n .IP """EV_FORK""" 4 |
1320 | .ie n .IP """EV_FORK""" 4 |
… | |
… | |
1432 | make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR |
1441 | make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR |
1433 | it). |
1442 | it). |
1434 | .IP "callback ev_cb (ev_TYPE *watcher)" 4 |
1443 | .IP "callback ev_cb (ev_TYPE *watcher)" 4 |
1435 | .IX Item "callback ev_cb (ev_TYPE *watcher)" |
1444 | .IX Item "callback ev_cb (ev_TYPE *watcher)" |
1436 | Returns the callback currently set on the watcher. |
1445 | Returns the callback currently set on the watcher. |
1437 | .IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 |
1446 | .IP "ev_set_cb (ev_TYPE *watcher, callback)" 4 |
1438 | .IX Item "ev_cb_set (ev_TYPE *watcher, callback)" |
1447 | .IX Item "ev_set_cb (ev_TYPE *watcher, callback)" |
1439 | Change the callback. You can change the callback at virtually any time |
1448 | Change the callback. You can change the callback at virtually any time |
1440 | (modulo threads). |
1449 | (modulo threads). |
1441 | .IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 |
1450 | .IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 |
1442 | .IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" |
1451 | .IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" |
1443 | .PD 0 |
1452 | .PD 0 |
… | |
… | |
1990 | \& callback (EV_P_ ev_timer *w, int revents) |
1999 | \& callback (EV_P_ ev_timer *w, int revents) |
1991 | \& { |
2000 | \& { |
1992 | \& // calculate when the timeout would happen |
2001 | \& // calculate when the timeout would happen |
1993 | \& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout; |
2002 | \& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout; |
1994 | \& |
2003 | \& |
1995 | \& // if negative, it means we the timeout already occured |
2004 | \& // if negative, it means we the timeout already occurred |
1996 | \& if (after < 0.) |
2005 | \& if (after < 0.) |
1997 | \& { |
2006 | \& { |
1998 | \& // timeout occurred, take action |
2007 | \& // timeout occurred, take action |
1999 | \& } |
2008 | \& } |
2000 | \& else |
2009 | \& else |
… | |
… | |
2019 | .Sp |
2028 | .Sp |
2020 | Otherwise, we now the earliest time at which the timeout would trigger, |
2029 | Otherwise, we now the earliest time at which the timeout would trigger, |
2021 | and simply start the timer with this timeout value. |
2030 | and simply start the timer with this timeout value. |
2022 | .Sp |
2031 | .Sp |
2023 | In other words, each time the callback is invoked it will check whether |
2032 | In other words, each time the callback is invoked it will check whether |
2024 | the timeout cocured. If not, it will simply reschedule itself to check |
2033 | the timeout occurred. If not, it will simply reschedule itself to check |
2025 | again at the earliest time it could time out. Rinse. Repeat. |
2034 | again at the earliest time it could time out. Rinse. Repeat. |
2026 | .Sp |
2035 | .Sp |
2027 | This scheme causes more callback invocations (about one every 60 seconds |
2036 | This scheme causes more callback invocations (about one every 60 seconds |
2028 | minus half the average time between activity), but virtually no calls to |
2037 | minus half the average time between activity), but virtually no calls to |
2029 | libev to change the timeout. |
2038 | libev to change the timeout. |
… | |
… | |
2047 | \& last_activity = ev_now (EV_A); |
2056 | \& last_activity = ev_now (EV_A); |
2048 | .Ve |
2057 | .Ve |
2049 | .Sp |
2058 | .Sp |
2050 | When your timeout value changes, then the timeout can be changed by simply |
2059 | When your timeout value changes, then the timeout can be changed by simply |
2051 | providing a new value, stopping the timer and calling the callback, which |
2060 | providing a new value, stopping the timer and calling the callback, which |
2052 | will agaion do the right thing (for example, time out immediately :). |
2061 | will again do the right thing (for example, time out immediately :). |
2053 | .Sp |
2062 | .Sp |
2054 | .Vb 3 |
2063 | .Vb 3 |
2055 | \& timeout = new_value; |
2064 | \& timeout = new_value; |
2056 | \& ev_timer_stop (EV_A_ &timer); |
2065 | \& ev_timer_stop (EV_A_ &timer); |
2057 | \& callback (EV_A_ &timer, 0); |
2066 | \& callback (EV_A_ &timer, 0); |
… | |
… | |
2973 | Apart from keeping your process non-blocking (which is a useful |
2982 | Apart from keeping your process non-blocking (which is a useful |
2974 | effect on its own sometimes), idle watchers are a good place to do |
2983 | effect on its own sometimes), idle watchers are a good place to do |
2975 | \&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the |
2984 | \&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the |
2976 | event loop has handled all outstanding events. |
2985 | event loop has handled all outstanding events. |
2977 | .PP |
2986 | .PP |
|
|
2987 | \fIAbusing an \f(CI\*(C`ev_idle\*(C'\fI watcher for its side-effect\fR |
|
|
2988 | .IX Subsection "Abusing an ev_idle watcher for its side-effect" |
|
|
2989 | .PP |
|
|
2990 | As long as there is at least one active idle watcher, libev will never |
|
|
2991 | sleep unnecessarily. Or in other words, it will loop as fast as possible. |
|
|
2992 | For this to work, the idle watcher doesn't need to be invoked at all \- the |
|
|
2993 | lowest priority will do. |
|
|
2994 | .PP |
|
|
2995 | This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher, |
|
|
2996 | to do something on each event loop iteration \- for example to balance load |
|
|
2997 | between different connections. |
|
|
2998 | .PP |
|
|
2999 | See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer |
|
|
3000 | example. |
|
|
3001 | .PP |
2978 | \fIWatcher-Specific Functions and Data Members\fR |
3002 | \fIWatcher-Specific Functions and Data Members\fR |
2979 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3003 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2980 | .IP "ev_idle_init (ev_idle *, callback)" 4 |
3004 | .IP "ev_idle_init (ev_idle *, callback)" 4 |
2981 | .IX Item "ev_idle_init (ev_idle *, callback)" |
3005 | .IX Item "ev_idle_init (ev_idle *, callback)" |
2982 | Initialises and configures the idle watcher \- it has no parameters of any |
3006 | Initialises and configures the idle watcher \- it has no parameters of any |
… | |
… | |
2987 | .IX Subsection "Examples" |
3011 | .IX Subsection "Examples" |
2988 | .PP |
3012 | .PP |
2989 | Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the |
3013 | Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the |
2990 | callback, free it. Also, use no error checking, as usual. |
3014 | callback, free it. Also, use no error checking, as usual. |
2991 | .PP |
3015 | .PP |
2992 | .Vb 7 |
3016 | .Vb 5 |
2993 | \& static void |
3017 | \& static void |
2994 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
3018 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
2995 | \& { |
3019 | \& { |
|
|
3020 | \& // stop the watcher |
|
|
3021 | \& ev_idle_stop (loop, w); |
|
|
3022 | \& |
|
|
3023 | \& // now we can free it |
2996 | \& free (w); |
3024 | \& free (w); |
|
|
3025 | \& |
2997 | \& // now do something you wanted to do when the program has |
3026 | \& // now do something you wanted to do when the program has |
2998 | \& // no longer anything immediate to do. |
3027 | \& // no longer anything immediate to do. |
2999 | \& } |
3028 | \& } |
3000 | \& |
3029 | \& |
3001 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
3030 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
… | |
… | |
3003 | \& ev_idle_start (loop, idle_watcher); |
3032 | \& ev_idle_start (loop, idle_watcher); |
3004 | .Ve |
3033 | .Ve |
3005 | .ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" |
3034 | .ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" |
3006 | .el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" |
3035 | .el .SS "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" |
3007 | .IX Subsection "ev_prepare and ev_check - customise your event loop!" |
3036 | .IX Subsection "ev_prepare and ev_check - customise your event loop!" |
3008 | Prepare and check watchers are usually (but not always) used in pairs: |
3037 | Prepare and check watchers are often (but not always) used in pairs: |
3009 | prepare watchers get invoked before the process blocks and check watchers |
3038 | prepare watchers get invoked before the process blocks and check watchers |
3010 | afterwards. |
3039 | afterwards. |
3011 | .PP |
3040 | .PP |
3012 | You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter |
3041 | You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter |
3013 | the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR |
3042 | the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR |
… | |
… | |
3041 | with priority higher than or equal to the event loop and one coroutine |
3070 | with priority higher than or equal to the event loop and one coroutine |
3042 | of lower priority, but only once, using idle watchers to keep the event |
3071 | of lower priority, but only once, using idle watchers to keep the event |
3043 | loop from blocking if lower-priority coroutines are active, thus mapping |
3072 | loop from blocking if lower-priority coroutines are active, thus mapping |
3044 | low-priority coroutines to idle/background tasks). |
3073 | low-priority coroutines to idle/background tasks). |
3045 | .PP |
3074 | .PP |
3046 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
3075 | When used for this purpose, it is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers |
3047 | priority, to ensure that they are being run before any other watchers |
3076 | highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) priority, to ensure that they are being run before |
3048 | after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR watchers). |
3077 | any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR |
|
|
3078 | watchers). |
3049 | .PP |
3079 | .PP |
3050 | Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not |
3080 | Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not |
3051 | activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they |
3081 | activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they |
3052 | might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As |
3082 | might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As |
3053 | \&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event |
3083 | \&\f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other (non-libev) event |
3054 | loops those other event loops might be in an unusable state until their |
3084 | loops those other event loops might be in an unusable state until their |
3055 | \&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with |
3085 | \&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with |
3056 | others). |
3086 | others). |
|
|
3087 | .PP |
|
|
3088 | \fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR |
|
|
3089 | .IX Subsection "Abusing an ev_check watcher for its side-effect" |
|
|
3090 | .PP |
|
|
3091 | \&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be |
|
|
3092 | useful because they are called once per event loop iteration. For |
|
|
3093 | example, if you want to handle a large number of connections fairly, you |
|
|
3094 | normally only do a bit of work for each active connection, and if there |
|
|
3095 | is more work to do, you wait for the next event loop iteration, so other |
|
|
3096 | connections have a chance of making progress. |
|
|
3097 | .PP |
|
|
3098 | Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the |
|
|
3099 | next event loop iteration. However, that isn't as soon as possible \- |
|
|
3100 | without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked. |
|
|
3101 | .PP |
|
|
3102 | This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a |
|
|
3103 | single global idle watcher that is active as long as you have one active |
|
|
3104 | \&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop |
|
|
3105 | will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets |
|
|
3106 | invoked. Neither watcher alone can do that. |
3057 | .PP |
3107 | .PP |
3058 | \fIWatcher-Specific Functions and Data Members\fR |
3108 | \fIWatcher-Specific Functions and Data Members\fR |
3059 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3109 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3060 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
3110 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
3061 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
3111 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
… | |
… | |
3440 | it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe. |
3490 | it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe. |
3441 | .PP |
3491 | .PP |
3442 | This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, |
3492 | This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, |
3443 | too, are asynchronous in nature, and signals, too, will be compressed |
3493 | too, are asynchronous in nature, and signals, too, will be compressed |
3444 | (i.e. the number of callback invocations may be less than the number of |
3494 | (i.e. the number of callback invocations may be less than the number of |
3445 | \&\f(CW\*(C`ev_async_sent\*(C'\fR calls). In fact, you could use signal watchers as a kind |
3495 | \&\f(CW\*(C`ev_async_send\*(C'\fR calls). In fact, you could use signal watchers as a kind |
3446 | of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused |
3496 | of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused |
3447 | signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread, |
3497 | signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread, |
3448 | even without knowing which loop owns the signal. |
3498 | even without knowing which loop owns the signal. |
3449 | .PP |
3499 | .PP |
3450 | \fIQueueing\fR |
3500 | \fIQueueing\fR |
… | |
… | |
3967 | .PP |
4017 | .PP |
3968 | .Vb 6 |
4018 | .Vb 6 |
3969 | \& void |
4019 | \& void |
3970 | \& wait_for_event (ev_watcher *w) |
4020 | \& wait_for_event (ev_watcher *w) |
3971 | \& { |
4021 | \& { |
3972 | \& ev_cb_set (w) = current_coro; |
4022 | \& ev_set_cb (w, current_coro); |
3973 | \& switch_to (libev_coro); |
4023 | \& switch_to (libev_coro); |
3974 | \& } |
4024 | \& } |
3975 | .Ve |
4025 | .Ve |
3976 | .PP |
4026 | .PP |
3977 | That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and |
4027 | That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and |
… | |
… | |
3981 | You can do similar tricks if you have, say, threads with an event queue \- |
4031 | You can do similar tricks if you have, say, threads with an event queue \- |
3982 | instead of storing a coroutine, you store the queue object and instead of |
4032 | instead of storing a coroutine, you store the queue object and instead of |
3983 | switching to a coroutine, you push the watcher onto the queue and notify |
4033 | switching to a coroutine, you push the watcher onto the queue and notify |
3984 | any waiters. |
4034 | any waiters. |
3985 | .PP |
4035 | .PP |
3986 | To embed libev, see \s-1EMBEDDING\s0, but in short, it's easiest to create two |
4036 | To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two |
3987 | files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: |
4037 | files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: |
3988 | .PP |
4038 | .PP |
3989 | .Vb 4 |
4039 | .Vb 4 |
3990 | \& // my_ev.h |
4040 | \& // my_ev.h |
3991 | \& #define EV_CB_DECLARE(type) struct my_coro *cb; |
4041 | \& #define EV_CB_DECLARE(type) struct my_coro *cb; |
… | |
… | |
4030 | .IP "\(bu" 4 |
4080 | .IP "\(bu" 4 |
4031 | The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need |
4081 | The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need |
4032 | to use the libev header file and library. |
4082 | to use the libev header file and library. |
4033 | .SH "\*(C+ SUPPORT" |
4083 | .SH "\*(C+ SUPPORT" |
4034 | .IX Header " SUPPORT" |
4084 | .IX Header " SUPPORT" |
|
|
4085 | .SS "C \s-1API\s0" |
|
|
4086 | .IX Subsection "C API" |
|
|
4087 | The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the |
|
|
4088 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
|
|
4089 | will work fine. |
|
|
4090 | .PP |
|
|
4091 | Proper exception specifications might have to be added to callbacks passed |
|
|
4092 | to libev: exceptions may be thrown only from watcher callbacks, all |
|
|
4093 | other callbacks (allocator, syserr, loop acquire/release and periodioc |
|
|
4094 | reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw |
|
|
4095 | ()\*(C'\fR specification. If you have code that needs to be compiled as both C |
|
|
4096 | and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: |
|
|
4097 | .PP |
|
|
4098 | .Vb 6 |
|
|
4099 | \& static void |
|
|
4100 | \& fatal_error (const char *msg) EV_THROW |
|
|
4101 | \& { |
|
|
4102 | \& perror (msg); |
|
|
4103 | \& abort (); |
|
|
4104 | \& } |
|
|
4105 | \& |
|
|
4106 | \& ... |
|
|
4107 | \& ev_set_syserr_cb (fatal_error); |
|
|
4108 | .Ve |
|
|
4109 | .PP |
|
|
4110 | The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR, |
|
|
4111 | \&\f(CW\*(C`ev_invoke\*(C'\fR, \f(CW\*(C`ev_invoke_pending\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR (the latter |
|
|
4112 | because it runs cleanup watchers). |
|
|
4113 | .PP |
|
|
4114 | Throwing exceptions in watcher callbacks is only supported if libev itself |
|
|
4115 | is compiled with a \*(C+ compiler or your C and \*(C+ environments allow |
|
|
4116 | throwing exceptions through C libraries (most do). |
|
|
4117 | .SS "\*(C+ \s-1API\s0" |
|
|
4118 | .IX Subsection " API" |
4035 | Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow |
4119 | Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow |
4036 | you to use some convenience methods to start/stop watchers and also change |
4120 | you to use some convenience methods to start/stop watchers and also change |
4037 | the callback model to a model using method callbacks on objects. |
4121 | the callback model to a model using method callbacks on objects. |
4038 | .PP |
4122 | .PP |
4039 | To use it, |
4123 | To use it, |
… | |
… | |
4055 | Currently, functions, static and non-static member functions and classes |
4139 | Currently, functions, static and non-static member functions and classes |
4056 | with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy |
4140 | with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy |
4057 | to add as long as they only need one additional pointer for context. If |
4141 | to add as long as they only need one additional pointer for context. If |
4058 | you need support for other types of functors please contact the author |
4142 | you need support for other types of functors please contact the author |
4059 | (preferably after implementing it). |
4143 | (preferably after implementing it). |
|
|
4144 | .PP |
|
|
4145 | For all this to work, your \*(C+ compiler either has to use the same calling |
|
|
4146 | conventions as your C compiler (for static member functions), or you have |
|
|
4147 | to embed libev and compile libev itself as \*(C+. |
4060 | .PP |
4148 | .PP |
4061 | Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: |
4149 | Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: |
4062 | .ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4 |
4150 | .ie n .IP """ev::READ"", ""ev::WRITE"" etc." 4 |
4063 | .el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4 |
4151 | .el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4 |
4064 | .IX Item "ev::READ, ev::WRITE etc." |
4152 | .IX Item "ev::READ, ev::WRITE etc." |
… | |
… | |
4718 | \& #define EV_CHILD_ENABLE 1 |
4806 | \& #define EV_CHILD_ENABLE 1 |
4719 | \& #define EV_ASYNC_ENABLE 1 |
4807 | \& #define EV_ASYNC_ENABLE 1 |
4720 | .Ve |
4808 | .Ve |
4721 | .Sp |
4809 | .Sp |
4722 | The actual value is a bitset, it can be a combination of the following |
4810 | The actual value is a bitset, it can be a combination of the following |
4723 | values: |
4811 | values (by default, all of these are enabled): |
4724 | .RS 4 |
4812 | .RS 4 |
4725 | .ie n .IP "1 \- faster/larger code" 4 |
4813 | .ie n .IP "1 \- faster/larger code" 4 |
4726 | .el .IP "\f(CW1\fR \- faster/larger code" 4 |
4814 | .el .IP "\f(CW1\fR \- faster/larger code" 4 |
4727 | .IX Item "1 - faster/larger code" |
4815 | .IX Item "1 - faster/larger code" |
4728 | Use larger code to speed up some operations. |
4816 | Use larger code to speed up some operations. |
… | |
… | |
4731 | code size by roughly 30% on amd64). |
4819 | code size by roughly 30% on amd64). |
4732 | .Sp |
4820 | .Sp |
4733 | When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with |
4821 | When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with |
4734 | gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of |
4822 | gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of |
4735 | assertions. |
4823 | assertions. |
|
|
4824 | .Sp |
|
|
4825 | The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler |
|
|
4826 | (e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR). |
4736 | .ie n .IP "2 \- faster/larger data structures" 4 |
4827 | .ie n .IP "2 \- faster/larger data structures" 4 |
4737 | .el .IP "\f(CW2\fR \- faster/larger data structures" 4 |
4828 | .el .IP "\f(CW2\fR \- faster/larger data structures" 4 |
4738 | .IX Item "2 - faster/larger data structures" |
4829 | .IX Item "2 - faster/larger data structures" |
4739 | Replaces the small 2\-heap for timer management by a faster 4\-heap, larger |
4830 | Replaces the small 2\-heap for timer management by a faster 4\-heap, larger |
4740 | hash table sizes and so on. This will usually further increase code size |
4831 | hash table sizes and so on. This will usually further increase code size |
4741 | and can additionally have an effect on the size of data structures at |
4832 | and can additionally have an effect on the size of data structures at |
4742 | runtime. |
4833 | runtime. |
|
|
4834 | .Sp |
|
|
4835 | The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler |
|
|
4836 | (e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR). |
4743 | .ie n .IP "4 \- full \s-1API\s0 configuration" 4 |
4837 | .ie n .IP "4 \- full \s-1API\s0 configuration" 4 |
4744 | .el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 |
4838 | .el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 |
4745 | .IX Item "4 - full API configuration" |
4839 | .IX Item "4 - full API configuration" |
4746 | This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and |
4840 | This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and |
4747 | enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). |
4841 | enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). |
… | |
… | |
5408 | new \s-1API\s0 early than late. |
5502 | new \s-1API\s0 early than late. |
5409 | .ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 |
5503 | .ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 |
5410 | .el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 |
5504 | .el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 |
5411 | .IX Item "EV_COMPAT3 backwards compatibility mechanism" |
5505 | .IX Item "EV_COMPAT3 backwards compatibility mechanism" |
5412 | The backward compatibility mechanism can be controlled by |
5506 | The backward compatibility mechanism can be controlled by |
5413 | \&\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 |
5507 | \&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R" |
5414 | section. |
5508 | section. |
5415 | .ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 |
5509 | .ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 |
5416 | .el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 |
5510 | .el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 |
5417 | .IX Item "ev_default_destroy and ev_default_fork have been removed" |
5511 | .IX Item "ev_default_destroy and ev_default_fork have been removed" |
5418 | These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: |
5512 | These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: |