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

Comparing libev/ev.3 (file contents):
Revision 1.88 by root, Sat Feb 4 18:55:50 2012 UTC vs.
Revision 1.95 by root, Sat May 26 08:52:09 2012 UTC

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-02-04" "libev-4.11" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2012-05-26" "libev-4.11" "libev - high performance full featured event loop"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 129.\" way too many mistakes in technical documents.
130.if n .ad l 130.if n .ad l
131.nh 131.nh
132.SH "NAME" 132.SH "NAME"
… …
367current system. To find which embeddable backends might be supported on 367current system. To find which embeddable backends might be supported on
368the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () 368the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends ()
369& ev_supported_backends ()\*(C'\fR, likewise for recommended ones. 369& ev_supported_backends ()\*(C'\fR, likewise for recommended ones.
370.Sp 370.Sp
371See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 371See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
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 ())"
374Sets the allocation function to use (the prototype is similar \- the 374Sets the allocation function to use (the prototype is similar \- the
375semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is 375semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is
376used to allocate and free memory (no surprises here). If it returns zero 376used to allocate and free memory (no surprises here). If it returns zero
377when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort 377when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort
378or take some potentially destructive action. 378or 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 ())"
411Set the callback function to call on a retryable system call error (such 411Set the callback function to call on a retryable system call error (such
412as failed select, poll, epoll_wait). The message is a printable string 412as failed select, poll, epoll_wait). The message is a printable string
413indicating the system call or subsystem causing the problem. If this 413indicating the system call or subsystem causing the problem. If this
414callback is set, then libev will expect it to remedy the situation, no 414callback is set, then libev will expect it to remedy the situation, no
415matter what, when it returns. That is, libev will generally retry the 415matter what, when it returns. That is, libev will generally retry the
… …
685.Sp 685.Sp
686It scales in the same way as the epoll backend, but the interface to the 686It scales in the same way as the epoll backend, but the interface to the
687kernel is more efficient (which says nothing about its actual speed, of 687kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 688course). While stopping, setting and starting an I/O watcher does never
689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but 690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
691sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 691might have to leak fd's on fork, but it's more sane than epoll) and it
692cases 692drops fds silently in similarly hard-to-detect cases
693.Sp 693.Sp
694This backend usually performs well under most conditions. 694This backend usually performs well under most conditions.
695.Sp 695.Sp
696While nominally embeddable in other event loops, this doesn't work 696While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 697everywhere, so you might need to test for this. And since it is broken
… …
909given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR 909given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR
910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. 910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR.
911.Sp 911.Sp
912Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the 912Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the
913event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). 913event 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)"
916Finally, this is it, the event handler. This function usually is called 916Finally, this is it, the event handler. This function usually is called
917after you have initialised all your watchers and you want to start 917after you have initialised all your watchers and you want to start
918handling events. It will ask the operating system for any new events, call 918handling events. It will ask the operating system for any new events, call
919the watcher callbacks, an then repeat the whole process indefinitely: This 919the watcher callbacks, and then repeat the whole process indefinitely: This
920is why event loops are called \fIloops\fR. 920is why event loops are called \fIloops\fR.
921.Sp 921.Sp
922If the flags argument is specified as \f(CW0\fR, it will keep handling events 922If the flags argument is specified as \f(CW0\fR, it will keep handling events
923until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was 923until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was
924called. 924called.
925.Sp
926The return value is false if there are no more active watchers (which
927usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases
928(which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again").
925.Sp 929.Sp
926Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than 930Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than
927relying on all watchers to be stopped when deciding when a program has 931relying on all watchers to be stopped when deciding when a program has
928finished (especially in interactive programs), but having a program 932finished (especially in interactive programs), but having a program
929that automatically loops as long as it has to and no longer by virtue 933that automatically loops as long as it has to and no longer by virtue
930of relying on its watchers stopping correctly, that is truly a thing of 934of relying on its watchers stopping correctly, that is truly a thing of
931beauty. 935beauty.
932.Sp 936.Sp
933This function is also \fImostly\fR exception-safe \- you can break out of 937This function is \fImostly\fR exception-safe \- you can break out of a
934a \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+
935exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor 939exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor
936will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. 940will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks.
937.Sp 941.Sp
938A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle 942A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle
939those events and any already outstanding ones, but will not wait and 943those events and any already outstanding ones, but will not wait and
… …
1136this callback instead. This is useful, for example, when you want to 1140this callback instead. This is useful, for example, when you want to
1137invoke the actual watchers inside another context (another thread etc.). 1141invoke the actual watchers inside another context (another thread etc.).
1138.Sp 1142.Sp
1139If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new 1143If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new
1140callback. 1144callback.
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 ())"
1143Sometimes you want to share the same loop between multiple threads. This 1147Sometimes you want to share the same loop between multiple threads. This
1144can be done relatively simply by putting mutex_lock/unlock calls around 1148can be done relatively simply by putting mutex_lock/unlock calls around
1145each call to a libev function. 1149each call to a libev function.
1146.Sp 1150.Sp
1147However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible 1151However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible
… …
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
1300All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts 1304All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts to
1301to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after 1305gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are queued (not invoked)
1302\&\f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it invokes any callbacks for any 1306just after \f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it queues any callbacks
1307for any received events. That means \f(CW\*(C`ev_prepare\*(C'\fR watchers are the last
1308watchers invoked before the event loop sleeps or polls for new events, and
1309\&\f(CW\*(C`ev_check\*(C'\fR watchers will be invoked before any other watchers of the same
1310or lower priority within an event loop iteration.
1311.Sp
1303received events. Callbacks of both watcher types can start and stop as 1312Callbacks of both watcher types can start and stop as many watchers as
1304many watchers as they want, and all of them will be taken into account 1313they want, and all of them will be taken into account (for example, a
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). 1315blocking).
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"
1310The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. 1319The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention.
1311.ie n .IP """EV_FORK""" 4 1320.ie n .IP """EV_FORK""" 4
… …
1432make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR 1441make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR
1433it). 1442it).
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)"
1436Returns the callback currently set on the watcher. 1445Returns 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)"
1439Change the callback. You can change the callback at virtually any time 1448Change 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
2020Otherwise, we now the earliest time at which the timeout would trigger, 2029Otherwise, we now the earliest time at which the timeout would trigger,
2021and simply start the timer with this timeout value. 2030and simply start the timer with this timeout value.
2022.Sp 2031.Sp
2023In other words, each time the callback is invoked it will check whether 2032In other words, each time the callback is invoked it will check whether
2024the timeout cocured. If not, it will simply reschedule itself to check 2033the timeout occurred. If not, it will simply reschedule itself to check
2025again at the earliest time it could time out. Rinse. Repeat. 2034again at the earliest time it could time out. Rinse. Repeat.
2026.Sp 2035.Sp
2027This scheme causes more callback invocations (about one every 60 seconds 2036This scheme causes more callback invocations (about one every 60 seconds
2028minus half the average time between activity), but virtually no calls to 2037minus half the average time between activity), but virtually no calls to
2029libev to change the timeout. 2038libev 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
2050When your timeout value changes, then the timeout can be changed by simply 2059When your timeout value changes, then the timeout can be changed by simply
2051providing a new value, stopping the timer and calling the callback, which 2060providing a new value, stopping the timer and calling the callback, which
2052will agaion do the right thing (for example, time out immediately :). 2061will 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);
… …
2973Apart from keeping your process non-blocking (which is a useful 2982Apart from keeping your process non-blocking (which is a useful
2974effect on its own sometimes), idle watchers are a good place to do 2983effect on its own sometimes), idle watchers are a good place to do
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
2976event loop has handled all outstanding events. 2985event 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
2990As long as there is at least one active idle watcher, libev will never
2991sleep unnecessarily. Or in other words, it will loop as fast as possible.
2992For this to work, the idle watcher doesn't need to be invoked at all \- the
2993lowest priority will do.
2994.PP
2995This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher,
2996to do something on each event loop iteration \- for example to balance load
2997between different connections.
2998.PP
2999See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer
3000example.
3001.PP
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)"
2982Initialises and configures the idle watcher \- it has no parameters of any 3006Initialises and configures the idle watcher \- it has no parameters of any
… …
2987.IX Subsection "Examples" 3011.IX Subsection "Examples"
2988.PP 3012.PP
2989Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the 3013Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the
2990callback, free it. Also, use no error checking, as usual. 3014callback, 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!"
3008Prepare and check watchers are usually (but not always) used in pairs: 3037Prepare and check watchers are often (but not always) used in pairs:
3009prepare watchers get invoked before the process blocks and check watchers 3038prepare watchers get invoked before the process blocks and check watchers
3010afterwards. 3039afterwards.
3011.PP 3040.PP
3012You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3041You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter
3013the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR 3042the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR
… …
3041with priority higher than or equal to the event loop and one coroutine 3070with priority higher than or equal to the event loop and one coroutine
3042of lower priority, but only once, using idle watchers to keep the event 3071of lower priority, but only once, using idle watchers to keep the event
3043loop from blocking if lower-priority coroutines are active, thus mapping 3072loop from blocking if lower-priority coroutines are active, thus mapping
3044low-priority coroutines to idle/background tasks). 3073low-priority coroutines to idle/background tasks).
3045.PP 3074.PP
3046It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 3075When used for this purpose, it is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers
3047priority, to ensure that they are being run before any other watchers 3076highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) priority, to ensure that they are being run before
3048after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR watchers). 3077any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR
3078watchers).
3049.PP 3079.PP
3050Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not 3080Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not
3051activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they 3081activate (\*(L"feed\*(R") events into libev. While libev fully supports this, they
3052might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As 3082might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers did their job. As
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
3054loops those other event loops might be in an unusable state until their 3084loops those other event loops might be in an unusable state until their
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
3056others). 3086others).
3087.PP
3088\fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR
3089.IX Subsection "Abusing an ev_check watcher for its side-effect"
3090.PP
3091\&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be
3092useful because they are called once per event loop iteration. For
3093example, if you want to handle a large number of connections fairly, you
3094normally only do a bit of work for each active connection, and if there
3095is more work to do, you wait for the next event loop iteration, so other
3096connections have a chance of making progress.
3097.PP
3098Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the
3099next event loop iteration. However, that isn't as soon as possible \-
3100without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked.
3101.PP
3102This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a
3103single global idle watcher that is active as long as you have one active
3104\&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop
3105will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets
3106invoked. Neither watcher alone can do that.
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)"
… …
3440it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe. 3490it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe.
3441.PP 3491.PP
3442This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, 3492This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals,
3443too, are asynchronous in nature, and signals, too, will be compressed 3493too, 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
3446of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused 3496of \*(L"global async watchers\*(R" by using a watcher on an otherwise unused
3447signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread, 3497signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread,
3448even without knowing which loop owns the signal. 3498even 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
3977That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and 4027That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and
… …
3981You can do similar tricks if you have, say, threads with an event queue \- 4031You can do similar tricks if you have, say, threads with an event queue \-
3982instead of storing a coroutine, you store the queue object and instead of 4032instead of storing a coroutine, you store the queue object and instead of
3983switching to a coroutine, you push the watcher onto the queue and notify 4033switching to a coroutine, you push the watcher onto the queue and notify
3984any waiters. 4034any waiters.
3985.PP 4035.PP
3986To embed libev, see \s-1EMBEDDING\s0, but in short, it's easiest to create two 4036To embed libev, see \*(L"\s-1EMBEDDING\s0\*(R", but in short, it's easiest to create two
3987files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4037files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
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
4031The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need 4081The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
4032to use the libev header file and library. 4082to 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"
4087The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4088libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4089will work fine.
4090.PP
4091Proper exception specifications might have to be added to callbacks passed
4092to libev: exceptions may be thrown only from watcher callbacks, all
4093other callbacks (allocator, syserr, loop acquire/release and periodic
4094reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw
4095()\*(C'\fR specification. If you have code that needs to be compiled as both C
4096and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
4097.PP
4098.Vb 6
4099\& static void
4100\& fatal_error (const char *msg) EV_THROW
4101\& {
4102\& perror (msg);
4103\& abort ();
4104\& }
4105\&
4106\& ...
4107\& ev_set_syserr_cb (fatal_error);
4108.Ve
4109.PP
4110The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR,
4111\&\f(CW\*(C`ev_invoke\*(C'\fR, \f(CW\*(C`ev_invoke_pending\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR (the latter
4112because it runs cleanup watchers).
4113.PP
4114Throwing exceptions in watcher callbacks is only supported if libev itself
4115is compiled with a \*(C+ compiler or your C and \*(C+ environments allow
4116throwing exceptions through C libraries (most do).
4117.SS "\*(C+ \s-1API\s0"
4118.IX Subsection " API"
4035Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow 4119Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
4036you to use some convenience methods to start/stop watchers and also change 4120you to use some convenience methods to start/stop watchers and also change
4037the callback model to a model using method callbacks on objects. 4121the callback model to a model using method callbacks on objects.
4038.PP 4122.PP
4039To use it, 4123To use it,
… …
4055Currently, functions, static and non-static member functions and classes 4139Currently, functions, static and non-static member functions and classes
4056with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy 4140with \f(CW\*(C`operator ()\*(C'\fR can be used as callbacks. Other types should be easy
4057to add as long as they only need one additional pointer for context. If 4141to add as long as they only need one additional pointer for context. If
4058you need support for other types of functors please contact the author 4142you need support for other types of functors please contact the author
4059(preferably after implementing it). 4143(preferably after implementing it).
4144.PP
4145For all this to work, your \*(C+ compiler either has to use the same calling
4146conventions as your C compiler (for static member functions), or you have
4147to embed libev and compile libev itself as \*(C+.
4060.PP 4148.PP
4061Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace: 4149Here is a list of things available in the \f(CW\*(C`ev\*(C'\fR namespace:
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."
… …
4276.IP "Lua" 4 4364.IP "Lua" 4
4277.IX Item "Lua" 4365.IX Item "Lua"
4278Brian Maher has written a partial interface to libev for lua (at the 4366Brian Maher has written a partial interface to libev for lua (at the
4279time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4367time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4280http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. 4368http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4369.IP "Javascript" 4
4370.IX Item "Javascript"
4371Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4372.IP "Others" 4
4373.IX Item "Others"
4374There are others, and I stopped counting.
4281.SH "MACRO MAGIC" 4375.SH "MACRO MAGIC"
4282.IX Header "MACRO MAGIC" 4376.IX Header "MACRO MAGIC"
4283Libev can be compiled with a variety of options, the most fundamental 4377Libev can be compiled with a variety of options, the most fundamental
4284of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 4378of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
4285functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 4379functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
4580.IX Item "EV_WIN32_CLOSE_FD(fd)" 4674.IX Item "EV_WIN32_CLOSE_FD(fd)"
4581If programs implement their own fd to handle mapping on win32, then this 4675If programs implement their own fd to handle mapping on win32, then this
4582macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister 4676macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister
4583file descriptors again. Note that the replacement function has to close 4677file descriptors again. Note that the replacement function has to close
4584the underlying \s-1OS\s0 handle. 4678the underlying \s-1OS\s0 handle.
4679.IP "\s-1EV_USE_WSASOCKET\s0" 4
4680.IX Item "EV_USE_WSASOCKET"
4681If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal
4682communication socket, which works better in some environments. Otherwise,
4683the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other
4684environments.
4585.IP "\s-1EV_USE_POLL\s0" 4 4685.IP "\s-1EV_USE_POLL\s0" 4
4586.IX Item "EV_USE_POLL" 4686.IX Item "EV_USE_POLL"
4587If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) 4687If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
4588backend. Otherwise it will be enabled on non\-win32 platforms. It 4688backend. Otherwise it will be enabled on non\-win32 platforms. It
4589takes precedence over select. 4689takes precedence over select.
… …
4718\& #define EV_CHILD_ENABLE 1 4818\& #define EV_CHILD_ENABLE 1
4719\& #define EV_ASYNC_ENABLE 1 4819\& #define EV_ASYNC_ENABLE 1
4720.Ve 4820.Ve
4721.Sp 4821.Sp
4722The actual value is a bitset, it can be a combination of the following 4822The actual value is a bitset, it can be a combination of the following
4723values: 4823values (by default, all of these are enabled):
4724.RS 4 4824.RS 4
4725.ie n .IP "1 \- faster/larger code" 4 4825.ie n .IP "1 \- faster/larger code" 4
4726.el .IP "\f(CW1\fR \- faster/larger code" 4 4826.el .IP "\f(CW1\fR \- faster/larger code" 4
4727.IX Item "1 - faster/larger code" 4827.IX Item "1 - faster/larger code"
4728Use larger code to speed up some operations. 4828Use larger code to speed up some operations.
… …
4731code size by roughly 30% on amd64). 4831code size by roughly 30% on amd64).
4732.Sp 4832.Sp
4733When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with 4833When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with
4734gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of 4834gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of
4735assertions. 4835assertions.
4836.Sp
4837The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4838(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4736.ie n .IP "2 \- faster/larger data structures" 4 4839.ie n .IP "2 \- faster/larger data structures" 4
4737.el .IP "\f(CW2\fR \- faster/larger data structures" 4 4840.el .IP "\f(CW2\fR \- faster/larger data structures" 4
4738.IX Item "2 - faster/larger data structures" 4841.IX Item "2 - faster/larger data structures"
4739Replaces the small 2\-heap for timer management by a faster 4\-heap, larger 4842Replaces the small 2\-heap for timer management by a faster 4\-heap, larger
4740hash table sizes and so on. This will usually further increase code size 4843hash table sizes and so on. This will usually further increase code size
4741and can additionally have an effect on the size of data structures at 4844and can additionally have an effect on the size of data structures at
4742runtime. 4845runtime.
4846.Sp
4847The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4848(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4743.ie n .IP "4 \- full \s-1API\s0 configuration" 4 4849.ie n .IP "4 \- full \s-1API\s0 configuration" 4
4744.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 4850.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4
4745.IX Item "4 - full API configuration" 4851.IX Item "4 - full API configuration"
4746This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and 4852This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and
4747enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). 4853enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1).
… …
5408new \s-1API\s0 early than late. 5514new \s-1API\s0 early than late.
5409.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5515.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5410.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5516.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5411.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5517.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5412The backward compatibility mechanism can be controlled by 5518The 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 5519\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R"
5414section. 5520section.
5415.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5521.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5416.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5522.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5417.IX Item "ev_default_destroy and ev_default_fork have been removed" 5523.IX Item "ev_default_destroy and ev_default_fork have been removed"
5418These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5524These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts:

Diff Legend

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