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

Comparing libev/ev.3 (file contents):
Revision 1.91 by root, Mon Apr 2 23:46:27 2012 UTC vs.
Revision 1.99 by root, Mon Jun 10 00:14:23 2013 UTC

1.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
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-03" "libev-4.11" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2013-06-07" "libev-4.15" "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
… …
514.IX Item "EVFLAG_NOENV" 514.IX Item "EVFLAG_NOENV"
515If this flag bit is or'ed into the flag value (or the program runs setuid 515If this flag bit is or'ed into the flag value (or the program runs setuid
516or setgid) then libev will \fInot\fR look at the environment variable 516or setgid) then libev will \fInot\fR look at the environment variable
517\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will 517\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will
518override the flags completely if it is found in the environment. This is 518override the flags completely if it is found in the environment. This is
519useful to try out specific backends to test their performance, or to work 519useful to try out specific backends to test their performance, to work
520around bugs. 520around bugs, or to make libev threadsafe (accessing environment variables
521cannot be done in a threadsafe way, but usually it works if no other
522thread modifies them).
521.ie n .IP """EVFLAG_FORKCHECK""" 4 523.ie n .IP """EVFLAG_FORKCHECK""" 4
522.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 524.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
523.IX Item "EVFLAG_FORKCHECK" 525.IX Item "EVFLAG_FORKCHECK"
524Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also 526Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also
525make libev check for a fork in each iteration by enabling this flag. 527make libev check for a fork in each iteration by enabling this flag.
… …
687kernel is more efficient (which says nothing about its actual speed, of 689kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 690course). 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 691cause 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 (you 692two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
691might have to leak fd's on fork, but it's more sane than epoll) and it 693might have to leak fd's on fork, but it's more sane than epoll) and it
692drops fds silently in similarly hard-to-detect cases 694drops fds silently in similarly hard-to-detect cases.
693.Sp 695.Sp
694This backend usually performs well under most conditions. 696This backend usually performs well under most conditions.
695.Sp 697.Sp
696While nominally embeddable in other event loops, this doesn't work 698While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 699everywhere, so you might need to test for this. And since it is broken
… …
1140this callback instead. This is useful, for example, when you want to 1142this callback instead. This is useful, for example, when you want to
1141invoke the actual watchers inside another context (another thread etc.). 1143invoke the actual watchers inside another context (another thread etc.).
1142.Sp 1144.Sp
1143If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new 1145If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new
1144callback. 1146callback.
1145.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0), void (*acquire)(\s-1EV_P\s0))" 4 1147.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0) throw (), void (*acquire)(\s-1EV_P\s0) throw ())" 4
1146.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))" 1148.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())"
1147Sometimes you want to share the same loop between multiple threads. This 1149Sometimes you want to share the same loop between multiple threads. This
1148can be done relatively simply by putting mutex_lock/unlock calls around 1150can be done relatively simply by putting mutex_lock/unlock calls around
1149each call to a libev function. 1151each call to a libev function.
1150.Sp 1152.Sp
1151However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible 1153However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible
… …
1299.PD 0 1301.PD 0
1300.ie n .IP """EV_CHECK""" 4 1302.ie n .IP """EV_CHECK""" 4
1301.el .IP "\f(CWEV_CHECK\fR" 4 1303.el .IP "\f(CWEV_CHECK\fR" 4
1302.IX Item "EV_CHECK" 1304.IX Item "EV_CHECK"
1303.PD 1305.PD
1304All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_run\*(C'\fR starts 1306All \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 1307gather 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 1308just after \f(CW\*(C`ev_run\*(C'\fR has gathered them, but before it queues any callbacks
1309for any received events. That means \f(CW\*(C`ev_prepare\*(C'\fR watchers are the last
1310watchers invoked before the event loop sleeps or polls for new events, and
1311\&\f(CW\*(C`ev_check\*(C'\fR watchers will be invoked before any other watchers of the same
1312or lower priority within an event loop iteration.
1313.Sp
1307received events. Callbacks of both watcher types can start and stop as 1314Callbacks 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 1315they 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 1316\&\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). 1317blocking).
1311.ie n .IP """EV_EMBED""" 4 1318.ie n .IP """EV_EMBED""" 4
1312.el .IP "\f(CWEV_EMBED\fR" 4 1319.el .IP "\f(CWEV_EMBED\fR" 4
1313.IX Item "EV_EMBED" 1320.IX Item "EV_EMBED"
1314The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention. 1321The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention.
1315.ie n .IP """EV_FORK""" 4 1322.ie n .IP """EV_FORK""" 4
… …
1436make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR 1443make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR
1437it). 1444it).
1438.IP "callback ev_cb (ev_TYPE *watcher)" 4 1445.IP "callback ev_cb (ev_TYPE *watcher)" 4
1439.IX Item "callback ev_cb (ev_TYPE *watcher)" 1446.IX Item "callback ev_cb (ev_TYPE *watcher)"
1440Returns the callback currently set on the watcher. 1447Returns the callback currently set on the watcher.
1441.IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 1448.IP "ev_set_cb (ev_TYPE *watcher, callback)" 4
1442.IX Item "ev_cb_set (ev_TYPE *watcher, callback)" 1449.IX Item "ev_set_cb (ev_TYPE *watcher, callback)"
1443Change the callback. You can change the callback at virtually any time 1450Change the callback. You can change the callback at virtually any time
1444(modulo threads). 1451(modulo threads).
1445.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 1452.IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4
1446.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" 1453.IX Item "ev_set_priority (ev_TYPE *watcher, int priority)"
1447.PD 0 1454.PD 0
… …
1503.IX Subsection "WATCHER STATES" 1510.IX Subsection "WATCHER STATES"
1504There are various watcher states mentioned throughout this manual \- 1511There are various watcher states mentioned throughout this manual \-
1505active, pending and so on. In this section these states and the rules to 1512active, pending and so on. In this section these states and the rules to
1506transition between them will be described in more detail \- and while these 1513transition between them will be described in more detail \- and while these
1507rules might look complicated, they usually do \*(L"the right thing\*(R". 1514rules might look complicated, they usually do \*(L"the right thing\*(R".
1508.IP "initialiased" 4 1515.IP "initialised" 4
1509.IX Item "initialiased" 1516.IX Item "initialised"
1510Before a watcher can be registered with the event loop it has to be 1517Before a watcher can be registered with the event loop it has to be
1511initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to 1518initialised. 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. 1519\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1513.Sp 1520.Sp
1514In this state it is simply some block of memory that is suitable for 1521In this state it is simply some block of memory that is suitable for
… …
1994\& callback (EV_P_ ev_timer *w, int revents) 2001\& callback (EV_P_ ev_timer *w, int revents)
1995\& { 2002\& {
1996\& // calculate when the timeout would happen 2003\& // calculate when the timeout would happen
1997\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout; 2004\& ev_tstamp after = last_activity \- ev_now (EV_A) + timeout;
1998\& 2005\&
1999\& // if negative, it means we the timeout already occured 2006\& // if negative, it means we the timeout already occurred
2000\& if (after < 0.) 2007\& if (after < 0.)
2001\& { 2008\& {
2002\& // timeout occurred, take action 2009\& // timeout occurred, take action
2003\& } 2010\& }
2004\& else 2011\& else
… …
2023.Sp 2030.Sp
2024Otherwise, we now the earliest time at which the timeout would trigger, 2031Otherwise, we now the earliest time at which the timeout would trigger,
2025and simply start the timer with this timeout value. 2032and simply start the timer with this timeout value.
2026.Sp 2033.Sp
2027In other words, each time the callback is invoked it will check whether 2034In other words, each time the callback is invoked it will check whether
2028the timeout cocured. If not, it will simply reschedule itself to check 2035the timeout occurred. If not, it will simply reschedule itself to check
2029again at the earliest time it could time out. Rinse. Repeat. 2036again at the earliest time it could time out. Rinse. Repeat.
2030.Sp 2037.Sp
2031This scheme causes more callback invocations (about one every 60 seconds 2038This scheme causes more callback invocations (about one every 60 seconds
2032minus half the average time between activity), but virtually no calls to 2039minus half the average time between activity), but virtually no calls to
2033libev to change the timeout. 2040libev to change the timeout.
… …
2051\& last_activity = ev_now (EV_A); 2058\& last_activity = ev_now (EV_A);
2052.Ve 2059.Ve
2053.Sp 2060.Sp
2054When your timeout value changes, then the timeout can be changed by simply 2061When your timeout value changes, then the timeout can be changed by simply
2055providing a new value, stopping the timer and calling the callback, which 2062providing a new value, stopping the timer and calling the callback, which
2056will agaion do the right thing (for example, time out immediately :). 2063will again do the right thing (for example, time out immediately :).
2057.Sp 2064.Sp
2058.Vb 3 2065.Vb 3
2059\& timeout = new_value; 2066\& timeout = new_value;
2060\& ev_timer_stop (EV_A_ &timer); 2067\& ev_timer_stop (EV_A_ &timer);
2061\& callback (EV_A_ &timer, 0); 2068\& callback (EV_A_ &timer, 0);
… …
2735.ie n .SS """ev_stat"" \- did the file attributes just change?" 2742.ie n .SS """ev_stat"" \- did the file attributes just change?"
2736.el .SS "\f(CWev_stat\fP \- did the file attributes just change?" 2743.el .SS "\f(CWev_stat\fP \- did the file attributes just change?"
2737.IX Subsection "ev_stat - did the file attributes just change?" 2744.IX Subsection "ev_stat - did the file attributes just change?"
2738This watches a file system path for attribute changes. That is, it calls 2745This 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) 2746\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed)
2740and sees if it changed compared to the last time, invoking the callback if 2747and sees if it changed compared to the last time, invoking the callback
2741it did. 2748if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that
2749happen after the watcher has been started will be reported.
2742.PP 2750.PP
2743The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 2751The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
2744not exist\*(R" is a status change like any other. The condition \*(L"path does not 2752not exist\*(R" is a status change like any other. The condition \*(L"path does not
2745exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the 2753exist\*(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 2754\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at
… …
2977Apart from keeping your process non-blocking (which is a useful 2985Apart from keeping your process non-blocking (which is a useful
2978effect on its own sometimes), idle watchers are a good place to do 2986effect 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 2987\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the
2980event loop has handled all outstanding events. 2988event loop has handled all outstanding events.
2981.PP 2989.PP
2990\fIAbusing an \f(CI\*(C`ev_idle\*(C'\fI watcher for its side-effect\fR
2991.IX Subsection "Abusing an ev_idle watcher for its side-effect"
2992.PP
2993As long as there is at least one active idle watcher, libev will never
2994sleep unnecessarily. Or in other words, it will loop as fast as possible.
2995For this to work, the idle watcher doesn't need to be invoked at all \- the
2996lowest priority will do.
2997.PP
2998This mode of operation can be useful together with an \f(CW\*(C`ev_check\*(C'\fR watcher,
2999to do something on each event loop iteration \- for example to balance load
3000between different connections.
3001.PP
3002See \*(L"Abusing an ev_check watcher for its side-effect\*(R" for a longer
3003example.
3004.PP
2982\fIWatcher-Specific Functions and Data Members\fR 3005\fIWatcher-Specific Functions and Data Members\fR
2983.IX Subsection "Watcher-Specific Functions and Data Members" 3006.IX Subsection "Watcher-Specific Functions and Data Members"
2984.IP "ev_idle_init (ev_idle *, callback)" 4 3007.IP "ev_idle_init (ev_idle *, callback)" 4
2985.IX Item "ev_idle_init (ev_idle *, callback)" 3008.IX Item "ev_idle_init (ev_idle *, callback)"
2986Initialises and configures the idle watcher \- it has no parameters of any 3009Initialises and configures the idle watcher \- it has no parameters of any
… …
2991.IX Subsection "Examples" 3014.IX Subsection "Examples"
2992.PP 3015.PP
2993Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the 3016Example: 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. 3017callback, free it. Also, use no error checking, as usual.
2995.PP 3018.PP
2996.Vb 7 3019.Vb 5
2997\& static void 3020\& static void
2998\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents) 3021\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
2999\& { 3022\& {
3023\& // stop the watcher
3024\& ev_idle_stop (loop, w);
3025\&
3026\& // now we can free it
3000\& free (w); 3027\& free (w);
3028\&
3001\& // now do something you wanted to do when the program has 3029\& // now do something you wanted to do when the program has
3002\& // no longer anything immediate to do. 3030\& // no longer anything immediate to do.
3003\& } 3031\& }
3004\& 3032\&
3005\& ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 3033\& ev_idle *idle_watcher = malloc (sizeof (ev_idle));
… …
3007\& ev_idle_start (loop, idle_watcher); 3035\& ev_idle_start (loop, idle_watcher);
3008.Ve 3036.Ve
3009.ie n .SS """ev_prepare"" and ""ev_check"" \- customise your event loop!" 3037.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!" 3038.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!" 3039.IX Subsection "ev_prepare and ev_check - customise your event loop!"
3012Prepare and check watchers are usually (but not always) used in pairs: 3040Prepare and check watchers are often (but not always) used in pairs:
3013prepare watchers get invoked before the process blocks and check watchers 3041prepare watchers get invoked before the process blocks and check watchers
3014afterwards. 3042afterwards.
3015.PP 3043.PP
3016You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3044You \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 3045the 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 3073with 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 3074of lower priority, but only once, using idle watchers to keep the event
3047loop from blocking if lower-priority coroutines are active, thus mapping 3075loop from blocking if lower-priority coroutines are active, thus mapping
3048low-priority coroutines to idle/background tasks). 3076low-priority coroutines to idle/background tasks).
3049.PP 3077.PP
3050It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 3078When 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 3079highest (\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). 3080any other watchers after the poll (this doesn't matter for \f(CW\*(C`ev_prepare\*(C'\fR
3081watchers).
3053.PP 3082.PP
3054Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, too) should not 3083Also, \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 3084activate (\*(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 3085might 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 3086\&\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 3087loops 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 3088\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with
3060others). 3089others).
3090.PP
3091\fIAbusing an \f(CI\*(C`ev_check\*(C'\fI watcher for its side-effect\fR
3092.IX Subsection "Abusing an ev_check watcher for its side-effect"
3093.PP
3094\&\f(CW\*(C`ev_check\*(C'\fR (and less often also \f(CW\*(C`ev_prepare\*(C'\fR) watchers can also be
3095useful because they are called once per event loop iteration. For
3096example, if you want to handle a large number of connections fairly, you
3097normally only do a bit of work for each active connection, and if there
3098is more work to do, you wait for the next event loop iteration, so other
3099connections have a chance of making progress.
3100.PP
3101Using an \f(CW\*(C`ev_check\*(C'\fR watcher is almost enough: it will be called on the
3102next event loop iteration. However, that isn't as soon as possible \-
3103without external events, your \f(CW\*(C`ev_check\*(C'\fR watcher will not be invoked.
3104.PP
3105This is where \f(CW\*(C`ev_idle\*(C'\fR watchers come in handy \- all you need is a
3106single global idle watcher that is active as long as you have one active
3107\&\f(CW\*(C`ev_check\*(C'\fR watcher. The \f(CW\*(C`ev_idle\*(C'\fR watcher makes sure the event loop
3108will not sleep, and the \f(CW\*(C`ev_check\*(C'\fR watcher makes sure a callback gets
3109invoked. Neither watcher alone can do that.
3061.PP 3110.PP
3062\fIWatcher-Specific Functions and Data Members\fR 3111\fIWatcher-Specific Functions and Data Members\fR
3063.IX Subsection "Watcher-Specific Functions and Data Members" 3112.IX Subsection "Watcher-Specific Functions and Data Members"
3064.IP "ev_prepare_init (ev_prepare *, callback)" 4 3113.IP "ev_prepare_init (ev_prepare *, callback)" 4
3065.IX Item "ev_prepare_init (ev_prepare *, callback)" 3114.IX Item "ev_prepare_init (ev_prepare *, callback)"
… …
3270\fIWatcher-Specific Functions and Data Members\fR 3319\fIWatcher-Specific Functions and Data Members\fR
3271.IX Subsection "Watcher-Specific Functions and Data Members" 3320.IX Subsection "Watcher-Specific Functions and Data Members"
3272.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3321.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)" 3322.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
3274.PD 0 3323.PD 0
3275.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3324.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)" 3325.IX Item "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)"
3277.PD 3326.PD
3278Configures the watcher to embed the given loop, which must be 3327Configures the watcher to embed the given loop, which must be
3279embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be 3328embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be
3280invoked automatically, otherwise it is the responsibility of the callback 3329invoked automatically, otherwise it is the responsibility of the callback
3281to invoke it (it will continue to be called until the sweep has been done, 3330to 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" 3393.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" 3394.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" 3395.IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
3347Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 3396Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
3348whoever is a good citizen cared to tell libev about it by calling 3397whoever 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 3398\&\f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the event loop blocks next
3350event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, 3399and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, and only in the child
3351and only in the child after the fork. If whoever good citizen calling 3400after 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 3401and calls it in the wrong process, the fork handlers will be invoked, too,
3353handlers will be invoked, too, of course. 3402of course.
3354.PP 3403.PP
3355\fIThe special problem of life after fork \- how is it possible?\fR 3404\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?" 3405.IX Subsection "The special problem of life after fork - how is it possible?"
3357.PP 3406.PP
3358Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3407Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set
… …
3444it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe. 3493it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal safe.
3445.PP 3494.PP
3446This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals, 3495This 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 3496too, 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 3497(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 3498\&\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 3499of \*(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, 3500signal, and \f(CW\*(C`ev_feed_signal\*(C'\fR to signal this watcher from another thread,
3452even without knowing which loop owns the signal. 3501even without knowing which loop owns the signal.
3453.PP 3502.PP
3454\fIQueueing\fR 3503\fIQueueing\fR
… …
3735already been invoked. 3784already been invoked.
3736.PP 3785.PP
3737A common way around all these issues is to make sure that 3786A 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 3787\&\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 3788\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
3740delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher 3789delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for
3741for example, or more sneakily, by reusing an existing (stopped) watcher 3790example, or more sneakily, by reusing an existing (stopped) watcher and
3742and pushing it into the pending queue: 3791pushing it into the pending queue:
3743.PP 3792.PP
3744.Vb 2 3793.Vb 2
3745\& ev_set_cb (watcher, callback); 3794\& ev_set_cb (watcher, callback);
3746\& ev_feed_event (EV_A_ watcher, 0); 3795\& ev_feed_event (EV_A_ watcher, 0);
3747.Ve 3796.Ve
… …
3756.PP 3805.PP
3757This brings the problem of exiting \- a callback might want to finish the 3806This brings the problem of exiting \- a callback might want to finish the
3758main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but 3807main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but
3759a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one 3808a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one
3760and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some 3809and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some
3761other combination: In these cases, \f(CW\*(C`ev_break\*(C'\fR will not work alone. 3810other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work.
3762.PP 3811.PP
3763The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR 3812The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR
3764invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is 3813invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is
3765triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: 3814triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR:
3766.PP 3815.PP
… …
3971.PP 4020.PP
3972.Vb 6 4021.Vb 6
3973\& void 4022\& void
3974\& wait_for_event (ev_watcher *w) 4023\& wait_for_event (ev_watcher *w)
3975\& { 4024\& {
3976\& ev_cb_set (w) = current_coro; 4025\& ev_set_cb (w, current_coro);
3977\& switch_to (libev_coro); 4026\& switch_to (libev_coro);
3978\& } 4027\& }
3979.Ve 4028.Ve
3980.PP 4029.PP
3981That basically suspends the coroutine inside \f(CW\*(C`wait_for_event\*(C'\fR and 4030That 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 \- 4034You 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 4035instead 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 4036switching to a coroutine, you push the watcher onto the queue and notify
3988any waiters. 4037any waiters.
3989.PP 4038.PP
3990To embed libev, see \s-1EMBEDDING\s0, but in short, it's easiest to create two 4039To 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: 4040files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
3992.PP 4041.PP
3993.Vb 4 4042.Vb 4
3994\& // my_ev.h 4043\& // my_ev.h
3995\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4044\& #define EV_CB_DECLARE(type) struct my_coro *cb;
… …
4034.IP "\(bu" 4 4083.IP "\(bu" 4
4035The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need 4084The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
4036to use the libev header file and library. 4085to use the libev header file and library.
4037.SH "\*(C+ SUPPORT" 4086.SH "\*(C+ SUPPORT"
4038.IX Header " SUPPORT" 4087.IX Header " SUPPORT"
4088.SS "C \s-1API\s0"
4089.IX Subsection "C API"
4090The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4091libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4092will work fine.
4093.PP
4094Proper exception specifications might have to be added to callbacks passed
4095to libev: exceptions may be thrown only from watcher callbacks, all
4096other callbacks (allocator, syserr, loop acquire/release and periodic
4097reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw
4098()\*(C'\fR specification. If you have code that needs to be compiled as both C
4099and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
4100.PP
4101.Vb 6
4102\& static void
4103\& fatal_error (const char *msg) EV_THROW
4104\& {
4105\& perror (msg);
4106\& abort ();
4107\& }
4108\&
4109\& ...
4110\& ev_set_syserr_cb (fatal_error);
4111.Ve
4112.PP
4113The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR,
4114\&\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
4115because it runs cleanup watchers).
4116.PP
4117Throwing exceptions in watcher callbacks is only supported if libev itself
4118is compiled with a \*(C+ compiler or your C and \*(C+ environments allow
4119throwing exceptions through C libraries (most do).
4120.SS "\*(C+ \s-1API\s0"
4121.IX Subsection " API"
4039Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow 4122Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
4040you to use some convenience methods to start/stop watchers and also change 4123you to use some convenience methods to start/stop watchers and also change
4041the callback model to a model using method callbacks on objects. 4124the callback model to a model using method callbacks on objects.
4042.PP 4125.PP
4043To use it, 4126To use it,
… …
4181.IX Item "w->set (loop)" 4264.IX Item "w->set (loop)"
4182Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only 4265Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only
4183do this when the watcher is inactive (and not pending either). 4266do this when the watcher is inactive (and not pending either).
4184.IP "w\->set ([arguments])" 4 4267.IP "w\->set ([arguments])" 4
4185.IX Item "w->set ([arguments])" 4268.IX Item "w->set ([arguments])"
4186Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this 4269Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR (except for \f(CW\*(C`ev::embed\*(C'\fR watchers>),
4187method or a suitable start method must be called at least once. Unlike the 4270with the same arguments. Either this method or a suitable start method
4188C counterpart, an active watcher gets automatically stopped and restarted 4271must be called at least once. Unlike the C counterpart, an active watcher
4189when reconfiguring it with this method. 4272gets automatically stopped and restarted when reconfiguring it with this
4273method.
4274.Sp
4275For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4276clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4190.IP "w\->start ()" 4 4277.IP "w\->start ()" 4
4191.IX Item "w->start ()" 4278.IX Item "w->start ()"
4192Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4279Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4193constructor already stores the event loop. 4280constructor already stores the event loop.
4194.IP "w\->start ([arguments])" 4 4281.IP "w\->start ([arguments])" 4
… …
4284.IP "Lua" 4 4371.IP "Lua" 4
4285.IX Item "Lua" 4372.IX Item "Lua"
4286Brian Maher has written a partial interface to libev for lua (at the 4373Brian Maher has written a partial interface to libev for lua (at the
4287time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4374time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4288http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. 4375http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4376.IP "Javascript" 4
4377.IX Item "Javascript"
4378Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4379.IP "Others" 4
4380.IX Item "Others"
4381There are others, and I stopped counting.
4289.SH "MACRO MAGIC" 4382.SH "MACRO MAGIC"
4290.IX Header "MACRO MAGIC" 4383.IX Header "MACRO MAGIC"
4291Libev can be compiled with a variety of options, the most fundamental 4384Libev can be compiled with a variety of options, the most fundamental
4292of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 4385of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
4293functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 4386functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
4588.IX Item "EV_WIN32_CLOSE_FD(fd)" 4681.IX Item "EV_WIN32_CLOSE_FD(fd)"
4589If programs implement their own fd to handle mapping on win32, then this 4682If programs implement their own fd to handle mapping on win32, then this
4590macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister 4683macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister
4591file descriptors again. Note that the replacement function has to close 4684file descriptors again. Note that the replacement function has to close
4592the underlying \s-1OS\s0 handle. 4685the underlying \s-1OS\s0 handle.
4686.IP "\s-1EV_USE_WSASOCKET\s0" 4
4687.IX Item "EV_USE_WSASOCKET"
4688If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal
4689communication socket, which works better in some environments. Otherwise,
4690the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other
4691environments.
4593.IP "\s-1EV_USE_POLL\s0" 4 4692.IP "\s-1EV_USE_POLL\s0" 4
4594.IX Item "EV_USE_POLL" 4693.IX Item "EV_USE_POLL"
4595If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) 4694If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
4596backend. Otherwise it will be enabled on non\-win32 platforms. It 4695backend. Otherwise it will be enabled on non\-win32 platforms. It
4597takes precedence over select. 4696takes precedence over select.
… …
4634between threads, that is, threads can be used, but threads never run on 4733between threads, that is, threads can be used, but threads never run on
4635different cpus (or different cpu cores). This reduces dependencies 4734different cpus (or different cpu cores). This reduces dependencies
4636and makes libev faster. 4735and makes libev faster.
4637.IP "\s-1EV_NO_THREADS\s0" 4 4736.IP "\s-1EV_NO_THREADS\s0" 4
4638.IX Item "EV_NO_THREADS" 4737.IX Item "EV_NO_THREADS"
4639If defined to be \f(CW1\fR, libev will assume that it will never be called 4738If defined to be \f(CW1\fR, libev will assume that it will never be called from
4640from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, 4739different threads (that includes signal handlers), which is a stronger
4641above. This reduces dependencies and makes libev faster. 4740assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes
4741libev faster.
4642.IP "\s-1EV_ATOMIC_T\s0" 4 4742.IP "\s-1EV_ATOMIC_T\s0" 4
4643.IX Item "EV_ATOMIC_T" 4743.IX Item "EV_ATOMIC_T"
4644Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4744Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4645access is atomic and serialised with respect to other threads or signal 4745access is atomic with respect to other threads or signal contexts. No
4646contexts. No such type is easily found in the C language, so you can 4746such type is easily found in the C language, so you can provide your own
4647provide your own type that you know is safe for your purposes. It is used 4747type that you know is safe for your purposes. It is used both for signal
4648both for signal handler \*(L"locking\*(R" as well as for signal and thread safety 4748handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4649in \f(CW\*(C`ev_async\*(C'\fR watchers. 4749watchers.
4650.Sp 4750.Sp
4651In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4751In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4652(from \fIsignal.h\fR), which is usually good enough on most platforms, 4752(from \fIsignal.h\fR), which is usually good enough on most platforms.
4653although strictly speaking using a type that also implies a memory fence
4654is required.
4655.IP "\s-1EV_H\s0 (h)" 4 4753.IP "\s-1EV_H\s0 (h)" 4
4656.IX Item "EV_H (h)" 4754.IX Item "EV_H (h)"
4657The name of the \fIev.h\fR header file used to include it. The default if 4755The name of the \fIev.h\fR header file used to include it. The default if
4658undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4756undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4659used to virtually rename the \fIev.h\fR header file in case of conflicts. 4757used to virtually rename the \fIev.h\fR header file in case of conflicts.
… …
5321thread\*(R" or will block signals process-wide, both behaviours would 5419thread\*(R" or will block signals process-wide, both behaviours would
5322be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and 5420be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
5323\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. 5421\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
5324.Sp 5422.Sp
5325The most portable way to handle signals is to block signals in all threads 5423The most portable way to handle signals is to block signals in all threads
5326except the initial one, and run the default loop in the initial thread as 5424except the initial one, and run the signal handling loop in the initial
5327well. 5425thread as well.
5328.ie n .IP """long"" must be large enough for common memory allocation sizes" 4 5426.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
5329.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 5427.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
5330.IX Item "long must be large enough for common memory allocation sizes" 5428.IX Item "long must be large enough for common memory allocation sizes"
5331To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5429To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally
5332instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5430instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX
… …
5422new \s-1API\s0 early than late. 5520new \s-1API\s0 early than late.
5423.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4 5521.ie n .IP """EV_COMPAT3"" backwards compatibility mechanism" 4
5424.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4 5522.el .IP "\f(CWEV_COMPAT3\fR backwards compatibility mechanism" 4
5425.IX Item "EV_COMPAT3 backwards compatibility mechanism" 5523.IX Item "EV_COMPAT3 backwards compatibility mechanism"
5426The backward compatibility mechanism can be controlled by 5524The backward compatibility mechanism can be controlled by
5427\&\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 5525\&\f(CW\*(C`EV_COMPAT3\*(C'\fR. See \*(L"\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0\*(R" in the \*(L"\s-1EMBEDDING\s0\*(R"
5428section. 5526section.
5429.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4 5527.ie n .IP """ev_default_destroy"" and ""ev_default_fork"" have been removed" 4
5430.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4 5528.el .IP "\f(CWev_default_destroy\fR and \f(CWev_default_fork\fR have been removed" 4
5431.IX Item "ev_default_destroy and ev_default_fork have been removed" 5529.IX Item "ev_default_destroy and ev_default_fork have been removed"
5432These calls can be replaced easily by their \f(CW\*(C`ev_loop_xxx\*(C'\fR counterparts: 5530These 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