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 "2013-02-28" "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" |
… | |
… | |
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 (you |
690 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you |
691 | might have to leak fd's on fork, but it's more sane than epoll) and it |
691 | might have to leak fd's on fork, but it's more sane than epoll) and it |
692 | drops fds silently in similarly hard-to-detect 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 |
… | |
… | |
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 |
… | |
… | |
1503 | .IX Subsection "WATCHER STATES" |
1508 | .IX Subsection "WATCHER STATES" |
1504 | There are various watcher states mentioned throughout this manual \- |
1509 | There are various watcher states mentioned throughout this manual \- |
1505 | active, pending and so on. In this section these states and the rules to |
1510 | active, pending and so on. In this section these states and the rules to |
1506 | transition between them will be described in more detail \- and while these |
1511 | transition between them will be described in more detail \- and while these |
1507 | rules might look complicated, they usually do \*(L"the right thing\*(R". |
1512 | rules might look complicated, they usually do \*(L"the right thing\*(R". |
1508 | .IP "initialiased" 4 |
1513 | .IP "initialised" 4 |
1509 | .IX Item "initialiased" |
1514 | .IX Item "initialised" |
1510 | Before a watcher can be registered with the event loop it has to be |
1515 | Before a watcher can be registered with the event loop it has to be |
1511 | initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to |
1516 | initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to |
1512 | \&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. |
1517 | \&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. |
1513 | .Sp |
1518 | .Sp |
1514 | In this state it is simply some block of memory that is suitable for |
1519 | In this state it is simply some block of memory that is suitable for |
… | |
… | |
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); |
… | |
… | |
2735 | .ie n .SS """ev_stat"" \- did the file attributes just change?" |
2740 | .ie n .SS """ev_stat"" \- did the file attributes just change?" |
2736 | .el .SS "\f(CWev_stat\fP \- did the file attributes just change?" |
2741 | .el .SS "\f(CWev_stat\fP \- did the file attributes just change?" |
2737 | .IX Subsection "ev_stat - did the file attributes just change?" |
2742 | .IX Subsection "ev_stat - did the file attributes just change?" |
2738 | This watches a file system path for attribute changes. That is, it calls |
2743 | This watches a file system path for attribute changes. That is, it calls |
2739 | \&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) |
2744 | \&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) |
2740 | and sees if it changed compared to the last time, invoking the callback if |
2745 | and sees if it changed compared to the last time, invoking the callback |
2741 | it did. |
2746 | if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that |
|
|
2747 | happen after the watcher has been started will be reported. |
2742 | .PP |
2748 | .PP |
2743 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2749 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2744 | not exist\*(R" is a status change like any other. The condition \*(L"path does not |
2750 | not exist\*(R" is a status change like any other. The condition \*(L"path does not |
2745 | exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the |
2751 | exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the |
2746 | \&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at |
2752 | \&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at |
… | |
… | |
2977 | Apart from keeping your process non-blocking (which is a useful |
2983 | 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 |
2984 | 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 |
2985 | \&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the |
2980 | event loop has handled all outstanding events. |
2986 | event loop has handled all outstanding events. |
2981 | .PP |
2987 | .PP |
|
|
2988 | \fIAbusing an \f(CI\*(C`ev_idle\*(C'\fI watcher for its side-effect\fR |
|
|
2989 | .IX Subsection "Abusing an ev_idle watcher for its side-effect" |
|
|
2990 | .PP |
|
|
2991 | As long as there is at least one active idle watcher, libev will never |
|
|
2992 | sleep unnecessarily. Or in other words, it will loop as fast as possible. |
|
|
2993 | For this to work, the idle watcher doesn't need to be invoked at all \- the |
|
|
2994 | lowest priority will do. |
|
|
2995 | .PP |
|
|
2996 | This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher, |
|
|
2997 | to do something on each event loop iteration \- for example to balance load |
|
|
2998 | between different connections. |
|
|
2999 | .PP |
|
|
3000 | See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer |
|
|
3001 | example. |
|
|
3002 | .PP |
2982 | \fIWatcher-Specific Functions and Data Members\fR |
3003 | \fIWatcher-Specific Functions and Data Members\fR |
2983 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3004 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2984 | .IP "ev_idle_init (ev_idle *, callback)" 4 |
3005 | .IP "ev_idle_init (ev_idle *, callback)" 4 |
2985 | .IX Item "ev_idle_init (ev_idle *, callback)" |
3006 | .IX Item "ev_idle_init (ev_idle *, callback)" |
2986 | Initialises and configures the idle watcher \- it has no parameters of any |
3007 | Initialises and configures the idle watcher \- it has no parameters of any |
… | |
… | |
2991 | .IX Subsection "Examples" |
3012 | .IX Subsection "Examples" |
2992 | .PP |
3013 | .PP |
2993 | Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the |
3014 | 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. |
3015 | callback, free it. Also, use no error checking, as usual. |
2995 | .PP |
3016 | .PP |
2996 | .Vb 7 |
3017 | .Vb 5 |
2997 | \& static void |
3018 | \& static void |
2998 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
3019 | \& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) |
2999 | \& { |
3020 | \& { |
|
|
3021 | \& // stop the watcher |
|
|
3022 | \& ev_idle_stop (loop, w); |
|
|
3023 | \& |
|
|
3024 | \& // now we can free it |
3000 | \& free (w); |
3025 | \& free (w); |
|
|
3026 | \& |
3001 | \& // now do something you wanted to do when the program has |
3027 | \& // now do something you wanted to do when the program has |
3002 | \& // no longer anything immediate to do. |
3028 | \& // no longer anything immediate to do. |
3003 | \& } |
3029 | \& } |
3004 | \& |
3030 | \& |
3005 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
3031 | \& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); |
… | |
… | |
3007 | \& ev_idle_start (loop, idle_watcher); |
3033 | \& ev_idle_start (loop, idle_watcher); |
3008 | .Ve |
3034 | .Ve |
3009 | .ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" |
3035 | .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!" |
3036 | .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!" |
3037 | .IX Subsection "ev_prepare and ev_check - customise your event loop!" |
3012 | Prepare and check watchers are usually (but not always) used in pairs: |
3038 | Prepare and check watchers are often (but not always) used in pairs: |
3013 | prepare watchers get invoked before the process blocks and check watchers |
3039 | prepare watchers get invoked before the process blocks and check watchers |
3014 | afterwards. |
3040 | afterwards. |
3015 | .PP |
3041 | .PP |
3016 | You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter |
3042 | 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 |
3043 | 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 |
3071 | 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 |
3072 | 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 |
3073 | loop from blocking if lower-priority coroutines are active, thus mapping |
3048 | low-priority coroutines to idle/background tasks). |
3074 | low-priority coroutines to idle/background tasks). |
3049 | .PP |
3075 | .PP |
3050 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
3076 | 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 |
3077 | 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). |
3078 | any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR |
|
|
3079 | watchers). |
3053 | .PP |
3080 | .PP |
3054 | Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not |
3081 | 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 |
3082 | 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 |
3083 | 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 |
3084 | \&\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 |
3085 | 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 |
3086 | \&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with |
3060 | others). |
3087 | others). |
|
|
3088 | .PP |
|
|
3089 | \fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR |
|
|
3090 | .IX Subsection "Abusing an ev_check watcher for its side-effect" |
|
|
3091 | .PP |
|
|
3092 | \&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be |
|
|
3093 | useful because they are called once per event loop iteration. For |
|
|
3094 | example, if you want to handle a large number of connections fairly, you |
|
|
3095 | normally only do a bit of work for each active connection, and if there |
|
|
3096 | is more work to do, you wait for the next event loop iteration, so other |
|
|
3097 | connections have a chance of making progress. |
|
|
3098 | .PP |
|
|
3099 | Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the |
|
|
3100 | next event loop iteration. However, that isn't as soon as possible \- |
|
|
3101 | without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked. |
|
|
3102 | .PP |
|
|
3103 | This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a |
|
|
3104 | single global idle watcher that is active as long as you have one active |
|
|
3105 | \&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop |
|
|
3106 | will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets |
|
|
3107 | invoked. Neither watcher alone can do that. |
3061 | .PP |
3108 | .PP |
3062 | \fIWatcher-Specific Functions and Data Members\fR |
3109 | \fIWatcher-Specific Functions and Data Members\fR |
3063 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3110 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3064 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
3111 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
3065 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
3112 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
… | |
… | |
3270 | \fIWatcher-Specific Functions and Data Members\fR |
3317 | \fIWatcher-Specific Functions and Data Members\fR |
3271 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3318 | .IX Subsection "Watcher-Specific Functions and Data Members" |
3272 | .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 |
3319 | .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 |
3273 | .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" |
3320 | .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" |
3274 | .PD 0 |
3321 | .PD 0 |
3275 | .IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 |
3322 | .IP "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)" 4 |
3276 | .IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" |
3323 | .IX Item "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)" |
3277 | .PD |
3324 | .PD |
3278 | Configures the watcher to embed the given loop, which must be |
3325 | Configures the watcher to embed the given loop, which must be |
3279 | embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be |
3326 | embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be |
3280 | invoked automatically, otherwise it is the responsibility of the callback |
3327 | invoked automatically, otherwise it is the responsibility of the callback |
3281 | to invoke it (it will continue to be called until the sweep has been done, |
3328 | to invoke it (it will continue to be called until the sweep has been done, |
… | |
… | |
3344 | .ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" |
3391 | .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" |
3392 | .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" |
3393 | .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 |
3394 | 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 |
3395 | 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 |
3396 | \&\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, |
3397 | 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 |
3398 | 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 |
3399 | and calls it in the wrong process, the fork handlers will be invoked, too, |
3353 | handlers will be invoked, too, of course. |
3400 | of course. |
3354 | .PP |
3401 | .PP |
3355 | \fIThe special problem of life after fork \- how is it possible?\fR |
3402 | \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?" |
3403 | .IX Subsection "The special problem of life after fork - how is it possible?" |
3357 | .PP |
3404 | .PP |
3358 | Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set |
3405 | 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. |
3491 | it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe. |
3445 | .PP |
3492 | .PP |
3446 | This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, |
3493 | 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 |
3494 | 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 |
3495 | (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 |
3496 | \&\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 |
3497 | 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, |
3498 | 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. |
3499 | even without knowing which loop owns the signal. |
3453 | .PP |
3500 | .PP |
3454 | \fIQueueing\fR |
3501 | \fIQueueing\fR |
… | |
… | |
3735 | already been invoked. |
3782 | already been invoked. |
3736 | .PP |
3783 | .PP |
3737 | A common way around all these issues is to make sure that |
3784 | A common way around all these issues is to make sure that |
3738 | \&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If |
3785 | \&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If |
3739 | \&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially |
3786 | \&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially |
3740 | delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher |
3787 | delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for |
3741 | for example, or more sneakily, by reusing an existing (stopped) watcher |
3788 | example, or more sneakily, by reusing an existing (stopped) watcher and |
3742 | and pushing it into the pending queue: |
3789 | pushing it into the pending queue: |
3743 | .PP |
3790 | .PP |
3744 | .Vb 2 |
3791 | .Vb 2 |
3745 | \& ev_set_cb (watcher, callback); |
3792 | \& ev_set_cb (watcher, callback); |
3746 | \& ev_feed_event (EV_A_ watcher, 0); |
3793 | \& ev_feed_event (EV_A_ watcher, 0); |
3747 | .Ve |
3794 | .Ve |
… | |
… | |
3756 | .PP |
3803 | .PP |
3757 | This brings the problem of exiting \- a callback might want to finish the |
3804 | This brings the problem of exiting \- a callback might want to finish the |
3758 | main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but |
3805 | main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but |
3759 | a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one |
3806 | a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one |
3760 | and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some |
3807 | and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some |
3761 | other combination: In these cases, \f(CW\*(C`ev_break\*(C'\fR will not work alone. |
3808 | other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work. |
3762 | .PP |
3809 | .PP |
3763 | The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR |
3810 | The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR |
3764 | invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is |
3811 | invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is |
3765 | triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: |
3812 | triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: |
3766 | .PP |
3813 | .PP |
… | |
… | |
3971 | .PP |
4018 | .PP |
3972 | .Vb 6 |
4019 | .Vb 6 |
3973 | \& void |
4020 | \& void |
3974 | \& wait_for_event (ev_watcher *w) |
4021 | \& wait_for_event (ev_watcher *w) |
3975 | \& { |
4022 | \& { |
3976 | \& ev_cb_set (w) = current_coro; |
4023 | \& ev_set_cb (w, current_coro); |
3977 | \& switch_to (libev_coro); |
4024 | \& switch_to (libev_coro); |
3978 | \& } |
4025 | \& } |
3979 | .Ve |
4026 | .Ve |
3980 | .PP |
4027 | .PP |
3981 | That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and |
4028 | 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 \- |
4032 | 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 |
4033 | 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 |
4034 | switching to a coroutine, you push the watcher onto the queue and notify |
3988 | any waiters. |
4035 | any waiters. |
3989 | .PP |
4036 | .PP |
3990 | To embed libev, see \s-1EMBEDDING\s0, but in short, it's easiest to create two |
4037 | 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: |
4038 | files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: |
3992 | .PP |
4039 | .PP |
3993 | .Vb 4 |
4040 | .Vb 4 |
3994 | \& // my_ev.h |
4041 | \& // my_ev.h |
3995 | \& #define EV_CB_DECLARE(type) struct my_coro *cb; |
4042 | \& #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 |
4089 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
4043 | will work fine. |
4090 | will work fine. |
4044 | .PP |
4091 | .PP |
4045 | Proper exception specifications might have to be added to callbacks passed |
4092 | Proper exception specifications might have to be added to callbacks passed |
4046 | to libev: exceptions may be thrown only from watcher callbacks, all |
4093 | to libev: exceptions may be thrown only from watcher callbacks, all |
4047 | other callbacks (allocator, syserr, loop acquire/release and periodioc |
4094 | other callbacks (allocator, syserr, loop acquire/release and periodic |
4048 | reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw |
4095 | 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 |
4096 | ()\*(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: |
4097 | and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: |
4051 | .PP |
4098 | .PP |
4052 | .Vb 6 |
4099 | .Vb 6 |
… | |
… | |
4060 | \& ... |
4107 | \& ... |
4061 | \& ev_set_syserr_cb (fatal_error); |
4108 | \& ev_set_syserr_cb (fatal_error); |
4062 | .Ve |
4109 | .Ve |
4063 | .PP |
4110 | .PP |
4064 | The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR, |
4111 | 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 |
4112 | \&\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). |
4113 | because it runs cleanup watchers). |
4067 | .PP |
4114 | .PP |
4068 | Throwing exceptions in watcher callbacks is only supported if libev itself |
4115 | 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 |
4116 | is compiled with a \*(C+ compiler or your C and \*(C+ environments allow |
4070 | throwing exceptions through C libraries (most do). |
4117 | throwing exceptions through C libraries (most do). |
… | |
… | |
4215 | .IX Item "w->set (loop)" |
4262 | .IX Item "w->set (loop)" |
4216 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
4263 | 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). |
4264 | do this when the watcher is inactive (and not pending either). |
4218 | .IP "w\->set ([arguments])" 4 |
4265 | .IP "w\->set ([arguments])" 4 |
4219 | .IX Item "w->set ([arguments])" |
4266 | .IX Item "w->set ([arguments])" |
4220 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this |
4267 | 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 |
4268 | with the same arguments. Either this method or a suitable start method |
4222 | C counterpart, an active watcher gets automatically stopped and restarted |
4269 | must be called at least once. Unlike the C counterpart, an active watcher |
4223 | when reconfiguring it with this method. |
4270 | gets automatically stopped and restarted when reconfiguring it with this |
|
|
4271 | method. |
|
|
4272 | .Sp |
|
|
4273 | For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid |
|
|
4274 | clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. |
4224 | .IP "w\->start ()" 4 |
4275 | .IP "w\->start ()" 4 |
4225 | .IX Item "w->start ()" |
4276 | .IX Item "w->start ()" |
4226 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4277 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4227 | constructor already stores the event loop. |
4278 | constructor already stores the event loop. |
4228 | .IP "w\->start ([arguments])" 4 |
4279 | .IP "w\->start ([arguments])" 4 |
… | |
… | |
4318 | .IP "Lua" 4 |
4369 | .IP "Lua" 4 |
4319 | .IX Item "Lua" |
4370 | .IX Item "Lua" |
4320 | Brian Maher has written a partial interface to libev for lua (at the |
4371 | 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 |
4372 | 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>. |
4373 | http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. |
|
|
4374 | .IP "Javascript" 4 |
|
|
4375 | .IX Item "Javascript" |
|
|
4376 | Node.js (<http://nodejs.org>) uses libev as the underlying event library. |
|
|
4377 | .IP "Others" 4 |
|
|
4378 | .IX Item "Others" |
|
|
4379 | There are others, and I stopped counting. |
4323 | .SH "MACRO MAGIC" |
4380 | .SH "MACRO MAGIC" |
4324 | .IX Header "MACRO MAGIC" |
4381 | .IX Header "MACRO MAGIC" |
4325 | Libev can be compiled with a variety of options, the most fundamental |
4382 | 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) |
4383 | 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. |
4384 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
… | |
… | |
4622 | .IX Item "EV_WIN32_CLOSE_FD(fd)" |
4679 | .IX Item "EV_WIN32_CLOSE_FD(fd)" |
4623 | If programs implement their own fd to handle mapping on win32, then this |
4680 | 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 |
4681 | 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 |
4682 | file descriptors again. Note that the replacement function has to close |
4626 | the underlying \s-1OS\s0 handle. |
4683 | the underlying \s-1OS\s0 handle. |
|
|
4684 | .IP "\s-1EV_USE_WSASOCKET\s0" 4 |
|
|
4685 | .IX Item "EV_USE_WSASOCKET" |
|
|
4686 | If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal |
|
|
4687 | communication socket, which works better in some environments. Otherwise, |
|
|
4688 | the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other |
|
|
4689 | environments. |
4627 | .IP "\s-1EV_USE_POLL\s0" 4 |
4690 | .IP "\s-1EV_USE_POLL\s0" 4 |
4628 | .IX Item "EV_USE_POLL" |
4691 | .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) |
4692 | 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 |
4693 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
4631 | takes precedence over select. |
4694 | takes precedence over select. |
… | |
… | |
4668 | between threads, that is, threads can be used, but threads never run on |
4731 | between threads, that is, threads can be used, but threads never run on |
4669 | different cpus (or different cpu cores). This reduces dependencies |
4732 | different cpus (or different cpu cores). This reduces dependencies |
4670 | and makes libev faster. |
4733 | and makes libev faster. |
4671 | .IP "\s-1EV_NO_THREADS\s0" 4 |
4734 | .IP "\s-1EV_NO_THREADS\s0" 4 |
4672 | .IX Item "EV_NO_THREADS" |
4735 | .IX Item "EV_NO_THREADS" |
4673 | If defined to be \f(CW1\fR, libev will assume that it will never be called |
4736 | If defined to be \f(CW1\fR, libev will assume that it will never be called from |
4674 | from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, |
4737 | different threads (that includes signal handlers), which is a stronger |
4675 | above. This reduces dependencies and makes libev faster. |
4738 | assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes |
|
|
4739 | libev faster. |
4676 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4740 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4677 | .IX Item "EV_ATOMIC_T" |
4741 | .IX Item "EV_ATOMIC_T" |
4678 | Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose |
4742 | 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 |
4743 | 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 |
4744 | 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 |
4745 | 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 |
4746 | 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. |
4747 | watchers. |
4684 | .Sp |
4748 | .Sp |
4685 | In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR |
4749 | 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, |
4750 | (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 |
4751 | .IP "\s-1EV_H\s0 (h)" 4 |
4690 | .IX Item "EV_H (h)" |
4752 | .IX Item "EV_H (h)" |
4691 | The name of the \fIev.h\fR header file used to include it. The default if |
4753 | 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 |
4754 | 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. |
4755 | 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 |
5417 | 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 |
5418 | 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. |
5419 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
5358 | .Sp |
5420 | .Sp |
5359 | The most portable way to handle signals is to block signals in all threads |
5421 | 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 |
5422 | except the initial one, and run the signal handling loop in the initial |
5361 | well. |
5423 | thread as well. |
5362 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
5424 | .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 |
5425 | .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" |
5426 | .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 |
5427 | 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 |
5428 | 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. |
5518 | new \s-1API\s0 early than late. |
5457 | .ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 |
5519 | .ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 |
5458 | .el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 |
5520 | .el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 |
5459 | .IX Item "EV_COMPAT3 backwards compatibility mechanism" |
5521 | .IX Item "EV_COMPAT3 backwards compatibility mechanism" |
5460 | The backward compatibility mechanism can be controlled by |
5522 | 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 |
5523 | \&\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. |
5524 | section. |
5463 | .ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 |
5525 | .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 |
5526 | .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" |
5527 | .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: |
5528 | These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: |