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

Comparing libev/ev.3 (file contents):
Revision 1.92 by root, Sun Apr 22 10:14:20 2012 UTC vs.
Revision 1.93 by root, Sun May 6 13:05:35 2012 UTC

… …
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-05-06" "libev-4.11" "libev - high performance full featured event loop"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 129.\" way too many mistakes in technical documents.
130.if n .ad l 130.if n .ad l
131.nh 131.nh
132.SH "NAME" 132.SH "NAME"
… …
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
1304All \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
1305to 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)
1306\&\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
1307received events. Callbacks of both watcher types can start and stop as 1312Callbacks of both watcher types can start and stop as many watchers as
1308many 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
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). 1315blocking).
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"
1314The 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.
1315.ie n .IP """EV_FORK""" 4 1320.ie n .IP """EV_FORK""" 4
… …
1436make 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
1437it). 1442it).
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)"
1440Returns the callback currently set on the watcher. 1445Returns 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)"
1443Change the callback. You can change the callback at virtually any time 1448Change 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
2024Otherwise, we now the earliest time at which the timeout would trigger, 2029Otherwise, we now the earliest time at which the timeout would trigger,
2025and simply start the timer with this timeout value. 2030and simply start the timer with this timeout value.
2026.Sp 2031.Sp
2027In 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
2028the timeout cocured. If not, it will simply reschedule itself to check 2033the timeout occurred. If not, it will simply reschedule itself to check
2029again at the earliest time it could time out. Rinse. Repeat. 2034again at the earliest time it could time out. Rinse. Repeat.
2030.Sp 2035.Sp
2031This scheme causes more callback invocations (about one every 60 seconds 2036This scheme causes more callback invocations (about one every 60 seconds
2032minus half the average time between activity), but virtually no calls to 2037minus half the average time between activity), but virtually no calls to
2033libev to change the timeout. 2038libev 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
2054When 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
2055providing a new value, stopping the timer and calling the callback, which 2060providing a new value, stopping the timer and calling the callback, which
2056will agaion do the right thing (for example, time out immediately :). 2061will 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);
… …
2977Apart from keeping your process non-blocking (which is a useful 2982Apart from keeping your process non-blocking (which is a useful
2978effect 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
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
2980event loop has handled all outstanding events. 2985event 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
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
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)"
2986Initialises and configures the idle watcher \- it has no parameters of any 3006Initialises and configures the idle watcher \- it has no parameters of any
… …
2991.IX Subsection "Examples" 3011.IX Subsection "Examples"
2992.PP 3012.PP
2993Example: 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
2994callback, free it. Also, use no error checking, as usual. 3014callback, 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!"
3012Prepare and check watchers are usually (but not always) used in pairs: 3037Prepare and check watchers are often (but not always) used in pairs:
3013prepare watchers get invoked before the process blocks and check watchers 3038prepare watchers get invoked before the process blocks and check watchers
3014afterwards. 3039afterwards.
3015.PP 3040.PP
3016You \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
3017the 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
… …
3045with 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
3046of 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
3047loop from blocking if lower-priority coroutines are active, thus mapping 3072loop from blocking if lower-priority coroutines are active, thus mapping
3048low-priority coroutines to idle/background tasks). 3073low-priority coroutines to idle/background tasks).
3049.PP 3074.PP
3050It 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
3051priority, 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
3052after 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).
3053.PP 3079.PP
3054Also, \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
3055activate (\*(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
3056might 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
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
3058loops 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
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
3060others). 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.
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)"
… …
3444it 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.
3445.PP 3491.PP
3446This 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,
3447too, are asynchronous in nature, and signals, too, will be compressed 3493too, 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
3450of \*(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
3451signal, 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,
3452even without knowing which loop owns the signal. 3498even 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
3981That 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
… …
3985You 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 \-
3986instead 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
3987switching 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
3988any waiters. 4034any waiters.
3989.PP 4035.PP
3990To 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
3991files, \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:
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;
… …
4060\& ... 4106\& ...
4061\& ev_set_syserr_cb (fatal_error); 4107\& ev_set_syserr_cb (fatal_error);
4062.Ve 4108.Ve
4063.PP 4109.PP
4064The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR, 4110The 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
4066because it runs cleanup watchers). 4112because it runs cleanup watchers).
4067.PP 4113.PP
4068Throwing exceptions in watcher callbacks is only supported if libev itself 4114Throwing exceptions in watcher callbacks is only supported if libev itself
4069is compiled with a \*(C+ compiler or your C and \*(C+ environments allow 4115is compiled with a \*(C+ compiler or your C and \*(C+ environments allow
4070throwing exceptions through C libraries (most do). 4116throwing exceptions through C libraries (most do).
… …
5456new \s-1API\s0 early than late. 5502new \s-1API\s0 early than late.
5457.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5503.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5458.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5504.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5459.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5505.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5460The backward compatibility mechanism can be controlled by 5506The 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 5507\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R"
5462section. 5508section.
5463.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5509.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5464.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5510.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5465.IX Item "ev_default_destroy and ev_default_fork have been removed" 5511.IX Item "ev_default_destroy and ev_default_fork have been removed"
5466These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5512These 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