1 | .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) |
1 | .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) |
2 | .\" |
2 | .\" |
3 | .\" Standard preamble: |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
4 | .\" ======================================================================== |
5 | .de Sp \" Vertical space (when we can't use .PP) |
5 | .de Sp \" Vertical space (when we can't use .PP) |
6 | .if t .sp .5v |
6 | .if t .sp .5v |
… | |
… | |
122 | .\} |
122 | .\} |
123 | .rm #[ #] #H #V #F C |
123 | .rm #[ #] #H #V #F C |
124 | .\" ======================================================================== |
124 | .\" ======================================================================== |
125 | .\" |
125 | .\" |
126 | .IX Title "LIBEV 3" |
126 | .IX Title "LIBEV 3" |
127 | .TH LIBEV 3 "2012-04-19" "libev-4.11" "libev - high performance full featured event loop" |
127 | .TH LIBEV 3 "2012-11-13" "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" |
… | |
… | |
1299 | .PD 0 |
1299 | .PD 0 |
1300 | .ie n .IP """EV_CHECK""" 4 |
1300 | .ie n .IP """EV_CHECK""" 4 |
1301 | .el .IP "\f(CWEV_CHECK\fR" 4 |
1301 | .el .IP "\f(CWEV_CHECK\fR" 4 |
1302 | .IX Item "EV_CHECK" |
1302 | .IX Item "EV_CHECK" |
1303 | .PD |
1303 | .PD |
1304 | 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 |
1305 | 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) |
1306 | \&\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 |
1307 | 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 |
1308 | 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 |
1309 | (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 |
1310 | \&\f(CW\*(C`ev_run\*(C'\fR from blocking). |
1315 | blocking). |
1311 | .ie n .IP """EV_EMBED""" 4 |
1316 | .ie n .IP """EV_EMBED""" 4 |
1312 | .el .IP "\f(CWEV_EMBED\fR" 4 |
1317 | .el .IP "\f(CWEV_EMBED\fR" 4 |
1313 | .IX Item "EV_EMBED" |
1318 | .IX Item "EV_EMBED" |
1314 | 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. |
1315 | .ie n .IP """EV_FORK""" 4 |
1320 | .ie n .IP """EV_FORK""" 4 |
… | |
… | |
1436 | 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 |
1437 | it). |
1442 | it). |
1438 | .IP "callback ev_cb (ev_TYPE *watcher)" 4 |
1443 | .IP "callback ev_cb (ev_TYPE *watcher)" 4 |
1439 | .IX Item "callback ev_cb (ev_TYPE *watcher)" |
1444 | .IX Item "callback ev_cb (ev_TYPE *watcher)" |
1440 | Returns the callback currently set on the watcher. |
1445 | Returns the callback currently set on the watcher. |
1441 | .IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 |
1446 | .IP "ev_set_cb (ev_TYPE *watcher, callback)" 4 |
1442 | .IX Item "ev_cb_set (ev_TYPE *watcher, callback)" |
1447 | .IX Item "ev_set_cb (ev_TYPE *watcher, callback)" |
1443 | 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 |
1444 | (modulo threads). |
1449 | (modulo threads). |
1445 | .IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 |
1450 | .IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 |
1446 | .IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" |
1451 | .IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" |
1447 | .PD 0 |
1452 | .PD 0 |
… | |
… | |
1994 | \& callback (EV_P_ ev_timer *w, int revents) |
1999 | \& callback (EV_P_ ev_timer *w, int revents) |
1995 | \& { |
2000 | \& { |
1996 | \& // calculate when the timeout would happen |
2001 | \& // calculate when the timeout would happen |
1997 | \& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout; |
2002 | \& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout; |
1998 | \& |
2003 | \& |
1999 | \& // if negative, it means we the timeout already occured |
2004 | \& // if negative, it means we the timeout already occurred |
2000 | \& if (after < 0.) |
2005 | \& if (after < 0.) |
2001 | \& { |
2006 | \& { |
2002 | \& // timeout occurred, take action |
2007 | \& // timeout occurred, take action |
2003 | \& } |
2008 | \& } |
2004 | \& else |
2009 | \& else |
… | |
… | |
2023 | .Sp |
2028 | .Sp |
2024 | 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, |
2025 | and simply start the timer with this timeout value. |
2030 | and simply start the timer with this timeout value. |
2026 | .Sp |
2031 | .Sp |
2027 | 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 |
2028 | 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 |
2029 | again at the earliest time it could time out. Rinse. Repeat. |
2034 | again at the earliest time it could time out. Rinse. Repeat. |
2030 | .Sp |
2035 | .Sp |
2031 | This scheme causes more callback invocations (about one every 60 seconds |
2036 | This scheme causes more callback invocations (about one every 60 seconds |
2032 | 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 |
2033 | libev to change the timeout. |
2038 | libev to change the timeout. |
… | |
… | |
2051 | \& last_activity = ev_now (EV_A); |
2056 | \& last_activity = ev_now (EV_A); |
2052 | .Ve |
2057 | .Ve |
2053 | .Sp |
2058 | .Sp |
2054 | 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 |
2055 | 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 |
2056 | will agaion do the right thing (for example, time out immediately :). |
2061 | will again do the right thing (for example, time out immediately :). |
2057 | .Sp |
2062 | .Sp |
2058 | .Vb 3 |
2063 | .Vb 3 |
2059 | \& timeout = new_value; |
2064 | \& timeout = new_value; |
2060 | \& ev_timer_stop (EV_A_ &timer); |
2065 | \& ev_timer_stop (EV_A_ &timer); |
2061 | \& callback (EV_A_ &timer, 0); |
2066 | \& callback (EV_A_ &timer, 0); |
… | |
… | |
2977 | Apart from keeping your process non-blocking (which is a useful |
2982 | Apart from keeping your process non-blocking (which is a useful |
2978 | 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 |
2979 | \&\*(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 |
2980 | event loop has handled all outstanding events. |
2985 | event loop has handled all outstanding events. |
2981 | .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 |
2982 | \fIWatcher-Specific Functions and Data Members\fR |
3002 | \fIWatcher-Specific Functions and Data Members\fR |
2983 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3003 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2984 | .IP "ev_idle_init (ev_idle *, callback)" 4 |
3004 | .IP "ev_idle_init (ev_idle *, callback)" 4 |
2985 | .IX Item "ev_idle_init (ev_idle *, callback)" |
3005 | .IX Item "ev_idle_init (ev_idle *, callback)" |
2986 | 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 |
… | |
… | |
2991 | .IX Subsection "Examples" |
3011 | .IX Subsection "Examples" |
2992 | .PP |
3012 | .PP |
2993 | 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 |
2994 | callback, free it. Also, use no error checking, as usual. |
3014 | callback, free it. Also, use no error checking, as usual. |
2995 | .PP |
3015 | .PP |
2996 | .Vb 7 |
3016 | .Vb 5 |
2997 | \& static void |
3017 | \& static void |
2998 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
3018 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
2999 | \& { |
3019 | \& { |
|
|
3020 | \& // stop the watcher |
|
|
3021 | \& ev_idle_stop (loop, w); |
|
|
3022 | \& |
|
|
3023 | \& // now we can free it |
3000 | \& free (w); |
3024 | \& free (w); |
|
|
3025 | \& |
3001 | \& // now do something you wanted to do when the program has |
3026 | \& // now do something you wanted to do when the program has |
3002 | \& // no longer anything immediate to do. |
3027 | \& // no longer anything immediate to do. |
3003 | \& } |
3028 | \& } |
3004 | \& |
3029 | \& |
3005 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
3030 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
… | |
… | |
3007 | \& ev_idle_start (loop, idle_watcher); |
3032 | \& ev_idle_start (loop, idle_watcher); |
3008 | .Ve |
3033 | .Ve |
3009 | .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!" |
3010 | .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!" |
3011 | .IX Subsection "ev_prepare and ev_check - customise your event loop!" |
3036 | .IX Subsection "ev_prepare and ev_check - customise your event loop!" |
3012 | 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: |
3013 | prepare watchers get invoked before the process blocks and check watchers |
3038 | prepare watchers get invoked before the process blocks and check watchers |
3014 | afterwards. |
3039 | afterwards. |
3015 | .PP |
3040 | .PP |
3016 | 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 |
3017 | 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 |
… | |
… | |
3045 | 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 |
3046 | 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 |
3047 | loop from blocking if lower-priority coroutines are active, thus mapping |
3072 | loop from blocking if lower-priority coroutines are active, thus mapping |
3048 | low-priority coroutines to idle/background tasks). |
3073 | low-priority coroutines to idle/background tasks). |
3049 | .PP |
3074 | .PP |
3050 | 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 |
3051 | 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 |
3052 | 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). |
3053 | .PP |
3079 | .PP |
3054 | 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 |
3055 | 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 |
3056 | 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 |
3057 | \&\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 |
3058 | 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 |
3059 | \&\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 |
3060 | 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. |
3061 | .PP |
3107 | .PP |
3062 | \fIWatcher-Specific Functions and Data Members\fR |
3108 | \fIWatcher-Specific Functions and Data Members\fR |
3063 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3109 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3064 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
3110 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
3065 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
3111 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
… | |
… | |
3344 | .ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" |
3390 | .ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" |
3345 | .el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" |
3391 | .el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" |
3346 | .IX Subsection "ev_fork - the audacity to resume the event loop after a fork" |
3392 | .IX Subsection "ev_fork - the audacity to resume the event loop after a fork" |
3347 | Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because |
3393 | Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because |
3348 | whoever is a good citizen cared to tell libev about it by calling |
3394 | whoever is a good citizen cared to tell libev about it by calling |
3349 | \&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the |
3395 | \&\f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the event loop blocks next |
3350 | event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, |
3396 | and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, and only in the child |
3351 | and only in the child after the fork. If whoever good citizen calling |
3397 | after the fork. If whoever good citizen calling \f(CW\*(C`ev_default_fork\*(C'\fR cheats |
3352 | \&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork |
3398 | and calls it in the wrong process, the fork handlers will be invoked, too, |
3353 | handlers will be invoked, too, of course. |
3399 | of course. |
3354 | .PP |
3400 | .PP |
3355 | \fIThe special problem of life after fork \- how is it possible?\fR |
3401 | \fIThe special problem of life after fork \- how is it possible?\fR |
3356 | .IX Subsection "The special problem of life after fork - how is it possible?" |
3402 | .IX Subsection "The special problem of life after fork - how is it possible?" |
3357 | .PP |
3403 | .PP |
3358 | Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set |
3404 | Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set |
… | |
… | |
3444 | 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. |
3445 | .PP |
3491 | .PP |
3446 | 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, |
3447 | too, are asynchronous in nature, and signals, too, will be compressed |
3493 | too, are asynchronous in nature, and signals, too, will be compressed |
3448 | (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 |
3449 | \&\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 |
3450 | 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 |
3451 | 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, |
3452 | even without knowing which loop owns the signal. |
3498 | even without knowing which loop owns the signal. |
3453 | .PP |
3499 | .PP |
3454 | \fIQueueing\fR |
3500 | \fIQueueing\fR |
… | |
… | |
3971 | .PP |
4017 | .PP |
3972 | .Vb 6 |
4018 | .Vb 6 |
3973 | \& void |
4019 | \& void |
3974 | \& wait_for_event (ev_watcher *w) |
4020 | \& wait_for_event (ev_watcher *w) |
3975 | \& { |
4021 | \& { |
3976 | \& ev_cb_set (w) = current_coro; |
4022 | \& ev_set_cb (w, current_coro); |
3977 | \& switch_to (libev_coro); |
4023 | \& switch_to (libev_coro); |
3978 | \& } |
4024 | \& } |
3979 | .Ve |
4025 | .Ve |
3980 | .PP |
4026 | .PP |
3981 | 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 |
… | |
… | |
3985 | 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 \- |
3986 | 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 |
3987 | 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 |
3988 | any waiters. |
4034 | any waiters. |
3989 | .PP |
4035 | .PP |
3990 | 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 |
3991 | 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: |
3992 | .PP |
4038 | .PP |
3993 | .Vb 4 |
4039 | .Vb 4 |
3994 | \& // my_ev.h |
4040 | \& // my_ev.h |
3995 | \& #define EV_CB_DECLARE(type) struct my_coro *cb; |
4041 | \& #define EV_CB_DECLARE(type) struct my_coro *cb; |
… | |
… | |
4042 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
4088 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
4043 | will work fine. |
4089 | will work fine. |
4044 | .PP |
4090 | .PP |
4045 | Proper exception specifications might have to be added to callbacks passed |
4091 | Proper exception specifications might have to be added to callbacks passed |
4046 | to libev: exceptions may be thrown only from watcher callbacks, all |
4092 | to libev: exceptions may be thrown only from watcher callbacks, all |
4047 | other callbacks (allocator, syserr, loop acquire/release and periodioc |
4093 | other callbacks (allocator, syserr, loop acquire/release and periodic |
4048 | reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw |
4094 | reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw |
4049 | ()\*(C'\fR specification. If you have code that needs to be compiled as both C |
4095 | ()\*(C'\fR specification. If you have code that needs to be compiled as both C |
4050 | and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: |
4096 | and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: |
4051 | .PP |
4097 | .PP |
4052 | .Vb 6 |
4098 | .Vb 6 |
… | |
… | |
4060 | \& ... |
4106 | \& ... |
4061 | \& ev_set_syserr_cb (fatal_error); |
4107 | \& ev_set_syserr_cb (fatal_error); |
4062 | .Ve |
4108 | .Ve |
4063 | .PP |
4109 | .PP |
4064 | The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR, |
4110 | The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR, |
4065 | \&\f(CW\*(C`ev_inoke\*(C'\fR, \f(CW\*(C`ev_invoke_pending\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR (the latter |
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 |
4066 | because it runs cleanup watchers). |
4112 | because it runs cleanup watchers). |
4067 | .PP |
4113 | .PP |
4068 | Throwing exceptions in watcher callbacks is only supported if libev itself |
4114 | Throwing exceptions in watcher callbacks is only supported if libev itself |
4069 | is compiled with a \*(C+ compiler or your C and \*(C+ environments allow |
4115 | is compiled with a \*(C+ compiler or your C and \*(C+ environments allow |
4070 | throwing exceptions through C libraries (most do). |
4116 | throwing exceptions through C libraries (most do). |
… | |
… | |
4215 | .IX Item "w->set (loop)" |
4261 | .IX Item "w->set (loop)" |
4216 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
4262 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
4217 | do this when the watcher is inactive (and not pending either). |
4263 | do this when the watcher is inactive (and not pending either). |
4218 | .IP "w\->set ([arguments])" 4 |
4264 | .IP "w\->set ([arguments])" 4 |
4219 | .IX Item "w->set ([arguments])" |
4265 | .IX Item "w->set ([arguments])" |
4220 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this |
4266 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR (except for \f(CW\*(C`ev::embed\*(C'\fR watchers>), |
4221 | method or a suitable start method must be called at least once. Unlike the |
4267 | with the same arguments. Either this method or a suitable start method |
4222 | C counterpart, an active watcher gets automatically stopped and restarted |
4268 | must be called at least once. Unlike the C counterpart, an active watcher |
4223 | when reconfiguring it with this method. |
4269 | gets automatically stopped and restarted when reconfiguring it with this |
|
|
4270 | method. |
|
|
4271 | .Sp |
|
|
4272 | For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid |
|
|
4273 | clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. |
4224 | .IP "w\->start ()" 4 |
4274 | .IP "w\->start ()" 4 |
4225 | .IX Item "w->start ()" |
4275 | .IX Item "w->start ()" |
4226 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4276 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4227 | constructor already stores the event loop. |
4277 | constructor already stores the event loop. |
4228 | .IP "w\->start ([arguments])" 4 |
4278 | .IP "w\->start ([arguments])" 4 |
… | |
… | |
4318 | .IP "Lua" 4 |
4368 | .IP "Lua" 4 |
4319 | .IX Item "Lua" |
4369 | .IX Item "Lua" |
4320 | Brian Maher has written a partial interface to libev for lua (at the |
4370 | Brian Maher has written a partial interface to libev for lua (at the |
4321 | time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at |
4371 | time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at |
4322 | http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. |
4372 | http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. |
|
|
4373 | .IP "Javascript" 4 |
|
|
4374 | .IX Item "Javascript" |
|
|
4375 | Node.js (<http://nodejs.org>) uses libev as the underlying event library. |
|
|
4376 | .IP "Others" 4 |
|
|
4377 | .IX Item "Others" |
|
|
4378 | There are others, and I stopped counting. |
4323 | .SH "MACRO MAGIC" |
4379 | .SH "MACRO MAGIC" |
4324 | .IX Header "MACRO MAGIC" |
4380 | .IX Header "MACRO MAGIC" |
4325 | Libev can be compiled with a variety of options, the most fundamental |
4381 | Libev can be compiled with a variety of options, the most fundamental |
4326 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
4382 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
4327 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
4383 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
… | |
… | |
4622 | .IX Item "EV_WIN32_CLOSE_FD(fd)" |
4678 | .IX Item "EV_WIN32_CLOSE_FD(fd)" |
4623 | If programs implement their own fd to handle mapping on win32, then this |
4679 | If programs implement their own fd to handle mapping on win32, then this |
4624 | macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister |
4680 | macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister |
4625 | file descriptors again. Note that the replacement function has to close |
4681 | file descriptors again. Note that the replacement function has to close |
4626 | the underlying \s-1OS\s0 handle. |
4682 | the underlying \s-1OS\s0 handle. |
|
|
4683 | .IP "\s-1EV_USE_WSASOCKET\s0" 4 |
|
|
4684 | .IX Item "EV_USE_WSASOCKET" |
|
|
4685 | If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal |
|
|
4686 | communication socket, which works better in some environments. Otherwise, |
|
|
4687 | the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other |
|
|
4688 | environments. |
4627 | .IP "\s-1EV_USE_POLL\s0" 4 |
4689 | .IP "\s-1EV_USE_POLL\s0" 4 |
4628 | .IX Item "EV_USE_POLL" |
4690 | .IX Item "EV_USE_POLL" |
4629 | If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) |
4691 | If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) |
4630 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
4692 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
4631 | takes precedence over select. |
4693 | takes precedence over select. |
… | |
… | |
4674 | from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, |
4736 | from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, |
4675 | above. This reduces dependencies and makes libev faster. |
4737 | above. This reduces dependencies and makes libev faster. |
4676 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4738 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4677 | .IX Item "EV_ATOMIC_T" |
4739 | .IX Item "EV_ATOMIC_T" |
4678 | Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose |
4740 | Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose |
4679 | access is atomic and serialised with respect to other threads or signal |
4741 | access is atomic with respect to other threads or signal contexts. No |
4680 | contexts. No such type is easily found in the C language, so you can |
4742 | such type is easily found in the C language, so you can provide your own |
4681 | provide your own type that you know is safe for your purposes. It is used |
4743 | type that you know is safe for your purposes. It is used both for signal |
4682 | both for signal handler \*(L"locking\*(R" as well as for signal and thread safety |
4744 | handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR |
4683 | in \f(CW\*(C`ev_async\*(C'\fR watchers. |
4745 | watchers. |
4684 | .Sp |
4746 | .Sp |
4685 | In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR |
4747 | In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR |
4686 | (from \fIsignal.h\fR), which is usually good enough on most platforms, |
4748 | (from \fIsignal.h\fR), which is usually good enough on most platforms. |
4687 | although strictly speaking using a type that also implies a memory fence |
|
|
4688 | is required. |
|
|
4689 | .IP "\s-1EV_H\s0 (h)" 4 |
4749 | .IP "\s-1EV_H\s0 (h)" 4 |
4690 | .IX Item "EV_H (h)" |
4750 | .IX Item "EV_H (h)" |
4691 | The name of the \fIev.h\fR header file used to include it. The default if |
4751 | The name of the \fIev.h\fR header file used to include it. The default if |
4692 | undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be |
4752 | undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be |
4693 | used to virtually rename the \fIev.h\fR header file in case of conflicts. |
4753 | used to virtually rename the \fIev.h\fR header file in case of conflicts. |
… | |
… | |
5355 | thread\*(R" or will block signals process-wide, both behaviours would |
5415 | thread\*(R" or will block signals process-wide, both behaviours would |
5356 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
5416 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
5357 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
5417 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
5358 | .Sp |
5418 | .Sp |
5359 | The most portable way to handle signals is to block signals in all threads |
5419 | The most portable way to handle signals is to block signals in all threads |
5360 | except the initial one, and run the default loop in the initial thread as |
5420 | except the initial one, and run the signal handling loop in the initial |
5361 | well. |
5421 | thread as well. |
5362 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
5422 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
5363 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
5423 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
5364 | .IX Item "long must be large enough for common memory allocation sizes" |
5424 | .IX Item "long must be large enough for common memory allocation sizes" |
5365 | To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally |
5425 | To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally |
5366 | instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX |
5426 | instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX |
… | |
… | |
5456 | new \s-1API\s0 early than late. |
5516 | new \s-1API\s0 early than late. |
5457 | .ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 |
5517 | .ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 |
5458 | .el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 |
5518 | .el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 |
5459 | .IX Item "EV_COMPAT3 backwards compatibility mechanism" |
5519 | .IX Item "EV_COMPAT3 backwards compatibility mechanism" |
5460 | The backward compatibility mechanism can be controlled by |
5520 | The backward compatibility mechanism can be controlled by |
5461 | \&\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 |
5521 | \&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R" |
5462 | section. |
5522 | section. |
5463 | .ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 |
5523 | .ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 |
5464 | .el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 |
5524 | .el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 |
5465 | .IX Item "ev_default_destroy and ev_default_fork have been removed" |
5525 | .IX Item "ev_default_destroy and ev_default_fork have been removed" |
5466 | These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: |
5526 | These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: |