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

Comparing libev/ev.3 (file contents):
Revision 1.60 by root, Mon Jan 28 12:23:02 2008 UTC vs.
Revision 1.64 by root, Wed Apr 16 17:08:29 2008 UTC

… …
130.\} 130.\}
131.rm #[ #] #H #V #F C 131.rm #[ #] #H #V #F C
132.\" ======================================================================== 132.\" ========================================================================
133.\" 133.\"
134.IX Title "EV 1" 134.IX Title "EV 1"
135.TH EV 1 "2008-01-28" "perl v5.10.0" "User Contributed Perl Documentation" 135.TH EV 1 "2008-04-11" "perl v5.10.0" "User Contributed Perl Documentation"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes 136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents. 137.\" way too many mistakes in technical documents.
138.if n .ad l 138.if n .ad l
139.nh 139.nh
140.SH "NAME" 140.SH "NAME"
… …
144.Vb 1 144.Vb 1
145\& #include <ev.h> 145\& #include <ev.h>
146.Ve 146.Ve
147.Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0" 147.Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0"
148.IX Subsection "EXAMPLE PROGRAM" 148.IX Subsection "EXAMPLE PROGRAM"
149.Vb 1 149.Vb 2
150\& // a single header file is required
150\& #include <ev.h> 151\& #include <ev.h>
151\& 152\&
153\& // every watcher type has its own typedef\*(Aqd struct
154\& // with the name ev_<type>
152\& ev_io stdin_watcher; 155\& ev_io stdin_watcher;
153\& ev_timer timeout_watcher; 156\& ev_timer timeout_watcher;
154\& 157\&
158\& // all watcher callbacks have a similar signature
155\& /* called when data readable on stdin */ 159\& // this callback is called when data is readable on stdin
156\& static void 160\& static void
157\& stdin_cb (EV_P_ struct ev_io *w, int revents) 161\& stdin_cb (EV_P_ struct ev_io *w, int revents)
158\& { 162\& {
159\& /* puts ("stdin ready"); */ 163\& puts ("stdin ready");
160\& ev_io_stop (EV_A_ w); /* just a syntax example */ 164\& // for one\-shot events, one must manually stop the watcher
161\& ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */ 165\& // with its corresponding stop function.
166\& ev_io_stop (EV_A_ w);
167\&
168\& // this causes all nested ev_loop\*(Aqs to stop iterating
169\& ev_unloop (EV_A_ EVUNLOOP_ALL);
162\& } 170\& }
163\& 171\&
172\& // another callback, this time for a time\-out
164\& static void 173\& static void
165\& timeout_cb (EV_P_ struct ev_timer *w, int revents) 174\& timeout_cb (EV_P_ struct ev_timer *w, int revents)
166\& { 175\& {
167\& /* puts ("timeout"); */ 176\& puts ("timeout");
168\& ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */ 177\& // this causes the innermost ev_loop to stop iterating
178\& ev_unloop (EV_A_ EVUNLOOP_ONE);
169\& } 179\& }
170\& 180\&
171\& int 181\& int
172\& main (void) 182\& main (void)
173\& { 183\& {
184\& // use the default event loop unless you have special needs
174\& struct ev_loop *loop = ev_default_loop (0); 185\& struct ev_loop *loop = ev_default_loop (0);
175\& 186\&
176\& /* initialise an io watcher, then start it */ 187\& // initialise an io watcher, then start it
188\& // this one will watch for stdin to become readable
177\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 189\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
178\& ev_io_start (loop, &stdin_watcher); 190\& ev_io_start (loop, &stdin_watcher);
179\& 191\&
192\& // initialise a timer watcher, then start it
180\& /* simple non\-repeating 5.5 second timeout */ 193\& // simple non\-repeating 5.5 second timeout
181\& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 194\& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
182\& ev_timer_start (loop, &timeout_watcher); 195\& ev_timer_start (loop, &timeout_watcher);
183\& 196\&
184\& /* loop till timeout or data ready */ 197\& // now wait for events to arrive
185\& ev_loop (loop, 0); 198\& ev_loop (loop, 0);
186\& 199\&
200\& // unloop was called, so exit
187\& return 0; 201\& return 0;
188\& } 202\& }
189.Ve 203.Ve
190.SH "DESCRIPTION" 204.SH "DESCRIPTION"
191.IX Header "DESCRIPTION" 205.IX Header "DESCRIPTION"
192The newest version of this document is also available as a html-formatted 206The newest version of this document is also available as an html-formatted
193web page you might find easier to navigate when reading it for the first 207web page you might find easier to navigate when reading it for the first
194time: <http://cvs.schmorp.de/libev/ev.html>. 208time: <http://cvs.schmorp.de/libev/ev.html>.
195.PP 209.PP
196Libev is an event loop: you register interest in certain events (such as a 210Libev is an event loop: you register interest in certain events (such as a
197file descriptor being readable or a timeout occurring), and it will manage 211file descriptor being readable or a timeout occurring), and it will manage
… …
221It also is quite fast (see this 235It also is quite fast (see this
222benchmark comparing it to libevent 236benchmark comparing it to libevent
223for example). 237for example).
224.Sh "\s-1CONVENTIONS\s0" 238.Sh "\s-1CONVENTIONS\s0"
225.IX Subsection "CONVENTIONS" 239.IX Subsection "CONVENTIONS"
226Libev is very configurable. In this manual the default configuration will 240Libev is very configurable. In this manual the default (and most common)
227be described, which supports multiple event loops. For more info about 241configuration will be described, which supports multiple event loops. For
228various configuration options please have a look at \fB\s-1EMBED\s0\fR section in 242more info about various configuration options please have a look at
229this manual. If libev was configured without support for multiple event 243\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support
230loops, then all functions taking an initial argument of name \f(CW\*(C`loop\*(C'\fR 244for multiple event loops, then all functions taking an initial argument of
231(which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have this argument. 245name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have
246this argument.
232.Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0" 247.Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0"
233.IX Subsection "TIME REPRESENTATION" 248.IX Subsection "TIME REPRESENTATION"
234Libev represents time as a single floating point number, representing the 249Libev represents time as a single floating point number, representing the
235(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near 250(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near
236the beginning of 1970, details are complicated, don't ask). This type is 251the beginning of 1970, details are complicated, don't ask). This type is
… …
313.Sp 328.Sp
314See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 329See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
315.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 330.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4
316.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" 331.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))"
317Sets the allocation function to use (the prototype is similar \- the 332Sets the allocation function to use (the prototype is similar \- the
318semantics is identical \- to the realloc C function). It is used to 333semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is
319allocate and free memory (no surprises here). If it returns zero when 334used to allocate and free memory (no surprises here). If it returns zero
320memory needs to be allocated, the library might abort or take some 335when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort
321potentially destructive action. The default is your system realloc 336or take some potentially destructive action.
322function. 337.Sp
338Since some systems (at least OpenBSD and Darwin) fail to implement
339correct \f(CW\*(C`realloc\*(C'\fR semantics, libev will use a wrapper around the system
340\&\f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions by default.
323.Sp 341.Sp
324You could override this function in high-availability programs to, say, 342You could override this function in high-availability programs to, say,
325free some memory if it cannot allocate memory, to use a special allocator, 343free some memory if it cannot allocate memory, to use a special allocator,
326or even to sleep a while and retry until some memory is available. 344or even to sleep a while and retry until some memory is available.
327.Sp 345.Sp
328Example: Replace the libev allocator with one that waits a bit and then 346Example: Replace the libev allocator with one that waits a bit and then
329retries). 347retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR).
330.Sp 348.Sp
331.Vb 6 349.Vb 6
332\& static void * 350\& static void *
333\& persistent_realloc (void *ptr, size_t size) 351\& persistent_realloc (void *ptr, size_t size)
334\& { 352\& {
… …
372.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" 390.SH "FUNCTIONS CONTROLLING THE EVENT LOOP"
373.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" 391.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"
374An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two 392An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two
375types of such loops, the \fIdefault\fR loop, which supports signals and child 393types of such loops, the \fIdefault\fR loop, which supports signals and child
376events, and dynamically created loops which do not. 394events, and dynamically created loops which do not.
377.PP
378If you use threads, a common model is to run the default event loop
379in your main thread (or in a separate thread) and for each thread you
380create, you also create another event loop. Libev itself does no locking
381whatsoever, so if you mix calls to the same event loop in different
382threads, make sure you lock (this is usually a bad idea, though, even if
383done correctly, because it's hideous and inefficient).
384.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 395.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4
385.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" 396.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)"
386This will initialise the default event loop if it hasn't been initialised 397This will initialise the default event loop if it hasn't been initialised
387yet and return it. If the default loop could not be initialised, returns 398yet and return it. If the default loop could not be initialised, returns
388false. If it already was initialised it simply returns it (and ignores the 399false. If it already was initialised it simply returns it (and ignores the
389flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). 400flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards).
390.Sp 401.Sp
391If you don't know what event loop to use, use the one returned from this 402If you don't know what event loop to use, use the one returned from this
392function. 403function.
404.Sp
405Note that this function is \fInot\fR thread-safe, so if you want to use it
406from multiple threads, you have to lock (note also that this is unlikely,
407as loops cannot bes hared easily between threads anyway).
393.Sp 408.Sp
394The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and 409The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and
395\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler 410\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler
396for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either 411for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either
397create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you 412create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you
… …
425enabling this flag. 440enabling this flag.
426.Sp 441.Sp
427This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, 442This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop,
428and thus this might slow down your event loop if you do a lot of loop 443and thus this might slow down your event loop if you do a lot of loop
429iterations and little real work, but is usually not noticeable (on my 444iterations and little real work, but is usually not noticeable (on my
430Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence 445GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence
431without a syscall and thus \fIvery\fR fast, but my Linux system also has 446without a syscall and thus \fIvery\fR fast, but my GNU/Linux system also has
432\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). 447\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster).
433.Sp 448.Sp
434The big advantage of this flag is that you can forget about fork (and 449The big advantage of this flag is that you can forget about fork (and
435forget about forgetting to tell libev about forking) when you use this 450forget about forgetting to tell libev about forking) when you use this
436flag. 451flag.
… …
467For few fds, this backend is a bit little slower than poll and select, 482For few fds, this backend is a bit little slower than poll and select,
468but it scales phenomenally better. While poll and select usually scale 483but it scales phenomenally better. While poll and select usually scale
469like O(total_fds) where n is the total number of fds (or the highest fd), 484like O(total_fds) where n is the total number of fds (or the highest fd),
470epoll scales either O(1) or O(active_fds). The epoll design has a number 485epoll scales either O(1) or O(active_fds). The epoll design has a number
471of shortcomings, such as silently dropping events in some hard-to-detect 486of shortcomings, such as silently dropping events in some hard-to-detect
472cases and rewiring a syscall per fd change, no fork support and bad 487cases and requiring a syscall per fd change, no fork support and bad
473support for dup. 488support for dup.
474.Sp 489.Sp
475While stopping, setting and starting an I/O watcher in the same iteration 490While stopping, setting and starting an I/O watcher in the same iteration
476will result in some caching, there is still a syscall per such incident 491will result in some caching, there is still a syscall per such incident
477(because the fd could point to a different file description now), so its 492(because the fd could point to a different file description now), so its
… …
585Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is 600Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is
586always distinct from the default loop. Unlike the default loop, it cannot 601always distinct from the default loop. Unlike the default loop, it cannot
587handle signal and child watchers, and attempts to do so will be greeted by 602handle signal and child watchers, and attempts to do so will be greeted by
588undefined behaviour (or a failed assertion if assertions are enabled). 603undefined behaviour (or a failed assertion if assertions are enabled).
589.Sp 604.Sp
605Note that this function \fIis\fR thread-safe, and the recommended way to use
606libev with threads is indeed to create one loop per thread, and using the
607default loop in the \*(L"main\*(R" or \*(L"initial\*(R" thread.
608.Sp
590Example: Try to create a event loop that uses epoll and nothing else. 609Example: Try to create a event loop that uses epoll and nothing else.
591.Sp 610.Sp
592.Vb 3 611.Vb 3
593\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 612\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
594\& if (!epoller) 613\& if (!epoller)
… …
639.IP "ev_loop_fork (loop)" 4 658.IP "ev_loop_fork (loop)" 4
640.IX Item "ev_loop_fork (loop)" 659.IX Item "ev_loop_fork (loop)"
641Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by 660Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by
642\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop 661\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop
643after fork, and how you do this is entirely your own problem. 662after fork, and how you do this is entirely your own problem.
663.IP "int ev_is_default_loop (loop)" 4
664.IX Item "int ev_is_default_loop (loop)"
665Returns true when the given loop actually is the default loop, false otherwise.
644.IP "unsigned int ev_loop_count (loop)" 4 666.IP "unsigned int ev_loop_count (loop)" 4
645.IX Item "unsigned int ev_loop_count (loop)" 667.IX Item "unsigned int ev_loop_count (loop)"
646Returns the count of loop iterations for the loop, which is identical to 668Returns the count of loop iterations for the loop, which is identical to
647the number of times libev did poll for new events. It starts at \f(CW0\fR and 669the number of times libev did poll for new events. It starts at \f(CW0\fR and
648happily wraps around with enough iterations. 670happily wraps around with enough iterations.
… …
914.ie n .IP """EV_FORK""" 4 936.ie n .IP """EV_FORK""" 4
915.el .IP "\f(CWEV_FORK\fR" 4 937.el .IP "\f(CWEV_FORK\fR" 4
916.IX Item "EV_FORK" 938.IX Item "EV_FORK"
917The event loop has been resumed in the child process after fork (see 939The event loop has been resumed in the child process after fork (see
918\&\f(CW\*(C`ev_fork\*(C'\fR). 940\&\f(CW\*(C`ev_fork\*(C'\fR).
941.ie n .IP """EV_ASYNC""" 4
942.el .IP "\f(CWEV_ASYNC\fR" 4
943.IX Item "EV_ASYNC"
944The given async watcher has been asynchronously notified (see \f(CW\*(C`ev_async\*(C'\fR).
919.ie n .IP """EV_ERROR""" 4 945.ie n .IP """EV_ERROR""" 4
920.el .IP "\f(CWEV_ERROR\fR" 4 946.el .IP "\f(CWEV_ERROR\fR" 4
921.IX Item "EV_ERROR" 947.IX Item "EV_ERROR"
922An unspecified error has occured, the watcher has been stopped. This might 948An unspecified error has occured, the watcher has been stopped. This might
923happen because the watcher could not be properly started because libev 949happen because the watcher could not be properly started because libev
… …
1197To support fork in your programs, you either have to call 1223To support fork in your programs, you either have to call
1198\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child, 1224\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child,
1199enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or 1225enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or
1200\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1226\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1201.PP 1227.PP
1228\fIThe special problem of \s-1SIGPIPE\s0\fR
1229.IX Subsection "The special problem of SIGPIPE"
1230.PP
1231While not really specific to libev, it is easy to forget about \s-1SIGPIPE:\s0
1232when reading from a pipe whose other end has been closed, your program
1233gets send a \s-1SIGPIPE\s0, which, by default, aborts your program. For most
1234programs this is sensible behaviour, for daemons, this is usually
1235undesirable.
1236.PP
1237So when you encounter spurious, unexplained daemon exits, make sure you
1238ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1239somewhere, as that would have given you a big clue).
1240.PP
1202\fIWatcher-Specific Functions\fR 1241\fIWatcher-Specific Functions\fR
1203.IX Subsection "Watcher-Specific Functions" 1242.IX Subsection "Watcher-Specific Functions"
1204.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 1243.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
1205.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" 1244.IX Item "ev_io_init (ev_io *, callback, int fd, int events)"
1206.PD 0 1245.PD 0
… …
1281The timer itself will do a best-effort at avoiding drift, that is, if you 1320The timer itself will do a best-effort at avoiding drift, that is, if you
1282configure a timer to trigger every 10 seconds, then it will trigger at 1321configure a timer to trigger every 10 seconds, then it will trigger at
1283exactly 10 second intervals. If, however, your program cannot keep up with 1322exactly 10 second intervals. If, however, your program cannot keep up with
1284the timer (because it takes longer than those 10 seconds to do stuff) the 1323the timer (because it takes longer than those 10 seconds to do stuff) the
1285timer will not fire more than once per event loop iteration. 1324timer will not fire more than once per event loop iteration.
1286.IP "ev_timer_again (loop)" 4 1325.IP "ev_timer_again (loop, ev_timer *)" 4
1287.IX Item "ev_timer_again (loop)" 1326.IX Item "ev_timer_again (loop, ev_timer *)"
1288This will act as if the timer timed out and restart it again if it is 1327This will act as if the timer timed out and restart it again if it is
1289repeating. The exact semantics are: 1328repeating. The exact semantics are:
1290.Sp 1329.Sp
1291If the timer is pending, its pending status is cleared. 1330If the timer is pending, its pending status is cleared.
1292.Sp 1331.Sp
… …
1402In this configuration the watcher triggers an event at the wallclock time 1441In this configuration the watcher triggers an event at the wallclock time
1403\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, 1442\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs,
1404that is, if it is to be run at January 1st 2011 then it will run when the 1443that is, if it is to be run at January 1st 2011 then it will run when the
1405system time reaches or surpasses this time. 1444system time reaches or surpasses this time.
1406.IP "\(bu" 4 1445.IP "\(bu" 4
1407non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1446repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1408.Sp 1447.Sp
1409In this mode the watcher will always be scheduled to time out at the next 1448In this mode the watcher will always be scheduled to time out at the next
1410\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative) 1449\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative)
1411and then repeat, regardless of any time jumps. 1450and then repeat, regardless of any time jumps.
1412.Sp 1451.Sp
… …
1550with the kernel (thus it coexists with your own signal handlers as long 1589with the kernel (thus it coexists with your own signal handlers as long
1551as you don't register any with libev). Similarly, when the last signal 1590as you don't register any with libev). Similarly, when the last signal
1552watcher for a signal is stopped libev will reset the signal handler to 1591watcher for a signal is stopped libev will reset the signal handler to
1553\&\s-1SIG_DFL\s0 (regardless of what it was set to before). 1592\&\s-1SIG_DFL\s0 (regardless of what it was set to before).
1554.PP 1593.PP
1594If possible and supported, libev will install its handlers with
1595\&\f(CW\*(C`SA_RESTART\*(C'\fR behaviour enabled, so syscalls should not be unduly
1596interrupted. If you have a problem with syscalls getting interrupted by
1597signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher and unblock
1598them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher.
1599.PP
1555\fIWatcher-Specific Functions and Data Members\fR 1600\fIWatcher-Specific Functions and Data Members\fR
1556.IX Subsection "Watcher-Specific Functions and Data Members" 1601.IX Subsection "Watcher-Specific Functions and Data Members"
1557.IP "ev_signal_init (ev_signal *, callback, int signum)" 4 1602.IP "ev_signal_init (ev_signal *, callback, int signum)" 4
1558.IX Item "ev_signal_init (ev_signal *, callback, int signum)" 1603.IX Item "ev_signal_init (ev_signal *, callback, int signum)"
1559.PD 0 1604.PD 0
… …
1563Configures the watcher to trigger on the given signal number (usually one 1608Configures the watcher to trigger on the given signal number (usually one
1564of the \f(CW\*(C`SIGxxx\*(C'\fR constants). 1609of the \f(CW\*(C`SIGxxx\*(C'\fR constants).
1565.IP "int signum [read\-only]" 4 1610.IP "int signum [read\-only]" 4
1566.IX Item "int signum [read-only]" 1611.IX Item "int signum [read-only]"
1567The signal the watcher watches out for. 1612The signal the watcher watches out for.
1613.PP
1614\fIExamples\fR
1615.IX Subsection "Examples"
1616.PP
1617Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0.
1618.PP
1619.Vb 5
1620\& static void
1621\& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1622\& {
1623\& ev_unloop (loop, EVUNLOOP_ALL);
1624\& }
1625\&
1626\& struct ev_signal signal_watcher;
1627\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1628\& ev_signal_start (loop, &sigint_cb);
1629.Ve
1568.ie n .Sh """ev_child"" \- watch out for process status changes" 1630.ie n .Sh """ev_child"" \- watch out for process status changes"
1569.el .Sh "\f(CWev_child\fP \- watch out for process status changes" 1631.el .Sh "\f(CWev_child\fP \- watch out for process status changes"
1570.IX Subsection "ev_child - watch out for process status changes" 1632.IX Subsection "ev_child - watch out for process status changes"
1571Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to 1633Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to
1572some child status changes (most typically when a child of yours dies). 1634some child status changes (most typically when a child of yours dies). It
1635is permissible to install a child watcher \fIafter\fR the child has been
1636forked (which implies it might have already exited), as long as the event
1637loop isn't entered (or is continued from a watcher).
1638.PP
1639Only the default event loop is capable of handling signals, and therefore
1640you can only rgeister child watchers in the default event loop.
1641.PP
1642\fIProcess Interaction\fR
1643.IX Subsection "Process Interaction"
1644.PP
1645Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is
1646initialised. This is necessary to guarantee proper behaviour even if
1647the first child watcher is started after the child exits. The occurance
1648of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done
1649synchronously as part of the event loop processing. Libev always reaps all
1650children, even ones not watched.
1651.PP
1652\fIOverriding the Built-In Processing\fR
1653.IX Subsection "Overriding the Built-In Processing"
1654.PP
1655Libev offers no special support for overriding the built-in child
1656processing, but if your application collides with libev's default child
1657handler, you can override it easily by installing your own handler for
1658\&\f(CW\*(C`SIGCHLD\*(C'\fR after initialising the default loop, and making sure the
1659default loop never gets destroyed. You are encouraged, however, to use an
1660event-based approach to child reaping and thus use libev's support for
1661that, so other libev users can use \f(CW\*(C`ev_child\*(C'\fR watchers freely.
1573.PP 1662.PP
1574\fIWatcher-Specific Functions and Data Members\fR 1663\fIWatcher-Specific Functions and Data Members\fR
1575.IX Subsection "Watcher-Specific Functions and Data Members" 1664.IX Subsection "Watcher-Specific Functions and Data Members"
1576.IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4 1665.IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4
1577.IX Item "ev_child_init (ev_child *, callback, int pid, int trace)" 1666.IX Item "ev_child_init (ev_child *, callback, int pid, int trace)"
… …
1599\&\f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`sys/wait.h\*(C'\fR documentation for details). 1688\&\f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`sys/wait.h\*(C'\fR documentation for details).
1600.PP 1689.PP
1601\fIExamples\fR 1690\fIExamples\fR
1602.IX Subsection "Examples" 1691.IX Subsection "Examples"
1603.PP 1692.PP
1604Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0. 1693Example: \f(CW\*(C`fork()\*(C'\fR a new process and install a child handler to wait for
1694its completion.
1605.PP 1695.PP
1606.Vb 5 1696.Vb 1
1697\& ev_child cw;
1698\&
1607\& static void 1699\& static void
1608\& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1700\& child_cb (EV_P_ struct ev_child *w, int revents)
1609\& { 1701\& {
1610\& ev_unloop (loop, EVUNLOOP_ALL); 1702\& ev_child_stop (EV_A_ w);
1703\& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus);
1611\& } 1704\& }
1612\& 1705\&
1613\& struct ev_signal signal_watcher; 1706\& pid_t pid = fork ();
1614\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1707\&
1615\& ev_signal_start (loop, &sigint_cb); 1708\& if (pid < 0)
1709\& // error
1710\& else if (pid == 0)
1711\& {
1712\& // the forked child executes here
1713\& exit (1);
1714\& }
1715\& else
1716\& {
1717\& ev_child_init (&cw, child_cb, pid, 0);
1718\& ev_child_start (EV_DEFAULT_ &cw);
1719\& }
1616.Ve 1720.Ve
1617.ie n .Sh """ev_stat"" \- did the file attributes just change?" 1721.ie n .Sh """ev_stat"" \- did the file attributes just change?"
1618.el .Sh "\f(CWev_stat\fP \- did the file attributes just change?" 1722.el .Sh "\f(CWev_stat\fP \- did the file attributes just change?"
1619.IX Subsection "ev_stat - did the file attributes just change?" 1723.IX Subsection "ev_stat - did the file attributes just change?"
1620This watches a filesystem path for attribute changes. That is, it calls 1724This watches a filesystem path for attribute changes. That is, it calls
… …
1648reader). Inotify will be used to give hints only and should not change the 1752reader). Inotify will be used to give hints only and should not change the
1649semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs 1753semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs
1650to fall back to regular polling again even with inotify, but changes are 1754to fall back to regular polling again even with inotify, but changes are
1651usually detected immediately, and if the file exists there will be no 1755usually detected immediately, and if the file exists there will be no
1652polling. 1756polling.
1757.PP
1758\fI\s-1ABI\s0 Issues (Largefile Support)\fR
1759.IX Subsection "ABI Issues (Largefile Support)"
1760.PP
1761Libev by default (unless the user overrides this) uses the default
1762compilation environment, which means that on systems with optionally
1763disabled large file support, you get the 32 bit version of the stat
1764structure. When using the library from programs that change the \s-1ABI\s0 to
1765use 64 bit file offsets the programs will fail. In that case you have to
1766compile libev with the same flags to get binary compatibility. This is
1767obviously the case with any flags that change the \s-1ABI\s0, but the problem is
1768most noticably with ev_stat and largefile support.
1653.PP 1769.PP
1654\fIInotify\fR 1770\fIInotify\fR
1655.IX Subsection "Inotify" 1771.IX Subsection "Inotify"
1656.PP 1772.PP
1657When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only 1773When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only
… …
1701path for as long as the watcher is active. 1817path for as long as the watcher is active.
1702.Sp 1818.Sp
1703The callback will be receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, 1819The callback will be receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected,
1704relative to the attributes at the time the watcher was started (or the 1820relative to the attributes at the time the watcher was started (or the
1705last change was detected). 1821last change was detected).
1706.IP "ev_stat_stat (ev_stat *)" 4 1822.IP "ev_stat_stat (loop, ev_stat *)" 4
1707.IX Item "ev_stat_stat (ev_stat *)" 1823.IX Item "ev_stat_stat (loop, ev_stat *)"
1708Updates the stat buffer immediately with new values. If you change the 1824Updates the stat buffer immediately with new values. If you change the
1709watched path in your callback, you could call this fucntion to avoid 1825watched path in your callback, you could call this fucntion to avoid
1710detecting this change (while introducing a race condition). Can also be 1826detecting this change (while introducing a race condition). Can also be
1711useful simply to find out the new values. 1827useful simply to find out the new values.
1712.IP "ev_statdata attr [read\-only]" 4 1828.IP "ev_statdata attr [read\-only]" 4
… …
2173.IP "ev_fork_init (ev_signal *, callback)" 4 2289.IP "ev_fork_init (ev_signal *, callback)" 4
2174.IX Item "ev_fork_init (ev_signal *, callback)" 2290.IX Item "ev_fork_init (ev_signal *, callback)"
2175Initialises and configures the fork watcher \- it has no parameters of any 2291Initialises and configures the fork watcher \- it has no parameters of any
2176kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless, 2292kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless,
2177believe me. 2293believe me.
2294.ie n .Sh """ev_async"" \- how to wake up another event loop"
2295.el .Sh "\f(CWev_async\fP \- how to wake up another event loop"
2296.IX Subsection "ev_async - how to wake up another event loop"
2297In general, you cannot use an \f(CW\*(C`ev_loop\*(C'\fR from multiple threads or other
2298asynchronous sources such as signal handlers (as opposed to multiple event
2299loops \- those are of course safe to use in different threads).
2300.PP
2301Sometimes, however, you need to wake up another event loop you do not
2302control, for example because it belongs to another thread. This is what
2303\&\f(CW\*(C`ev_async\*(C'\fR watchers do: as long as the \f(CW\*(C`ev_async\*(C'\fR watcher is active, you
2304can signal it by calling \f(CW\*(C`ev_async_send\*(C'\fR, which is thread\- and signal
2305safe.
2306.PP
2307This functionality is very similar to \f(CW\*(C`ev_signal\*(C'\fR watchers, as signals,
2308too, are asynchronous in nature, and signals, too, will be compressed
2309(i.e. the number of callback invocations may be less than the number of
2310\&\f(CW\*(C`ev_async_sent\*(C'\fR calls).
2311.PP
2312Unlike \f(CW\*(C`ev_signal\*(C'\fR watchers, \f(CW\*(C`ev_async\*(C'\fR works with any event loop, not
2313just the default loop.
2314.PP
2315\fIQueueing\fR
2316.IX Subsection "Queueing"
2317.PP
2318\&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason
2319is that the author does not know of a simple (or any) algorithm for a
2320multiple-writer-single-reader queue that works in all cases and doesn't
2321need elaborate support such as pthreads.
2322.PP
2323That means that if you want to queue data, you have to provide your own
2324queue. But at least I can tell you would implement locking around your
2325queue:
2326.IP "queueing from a signal handler context" 4
2327.IX Item "queueing from a signal handler context"
2328To implement race-free queueing, you simply add to the queue in the signal
2329handler but you block the signal handler in the watcher callback. Here is an example that does that for
2330some fictitiuous \s-1SIGUSR1\s0 handler:
2331.Sp
2332.Vb 1
2333\& static ev_async mysig;
2334\&
2335\& static void
2336\& sigusr1_handler (void)
2337\& {
2338\& sometype data;
2339\&
2340\& // no locking etc.
2341\& queue_put (data);
2342\& ev_async_send (EV_DEFAULT_ &mysig);
2343\& }
2344\&
2345\& static void
2346\& mysig_cb (EV_P_ ev_async *w, int revents)
2347\& {
2348\& sometype data;
2349\& sigset_t block, prev;
2350\&
2351\& sigemptyset (&block);
2352\& sigaddset (&block, SIGUSR1);
2353\& sigprocmask (SIG_BLOCK, &block, &prev);
2354\&
2355\& while (queue_get (&data))
2356\& process (data);
2357\&
2358\& if (sigismember (&prev, SIGUSR1)
2359\& sigprocmask (SIG_UNBLOCK, &block, 0);
2360\& }
2361.Ve
2362.Sp
2363(Note: pthreads in theory requires you to use \f(CW\*(C`pthread_setmask\*(C'\fR
2364instead of \f(CW\*(C`sigprocmask\*(C'\fR when you use threads, but libev doesn't do it
2365either...).
2366.IP "queueing from a thread context" 4
2367.IX Item "queueing from a thread context"
2368The strategy for threads is different, as you cannot (easily) block
2369threads but you can easily preempt them, so to queue safely you need to
2370employ a traditional mutex lock, such as in this pthread example:
2371.Sp
2372.Vb 2
2373\& static ev_async mysig;
2374\& static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
2375\&
2376\& static void
2377\& otherthread (void)
2378\& {
2379\& // only need to lock the actual queueing operation
2380\& pthread_mutex_lock (&mymutex);
2381\& queue_put (data);
2382\& pthread_mutex_unlock (&mymutex);
2383\&
2384\& ev_async_send (EV_DEFAULT_ &mysig);
2385\& }
2386\&
2387\& static void
2388\& mysig_cb (EV_P_ ev_async *w, int revents)
2389\& {
2390\& pthread_mutex_lock (&mymutex);
2391\&
2392\& while (queue_get (&data))
2393\& process (data);
2394\&
2395\& pthread_mutex_unlock (&mymutex);
2396\& }
2397.Ve
2398.PP
2399\fIWatcher-Specific Functions and Data Members\fR
2400.IX Subsection "Watcher-Specific Functions and Data Members"
2401.IP "ev_async_init (ev_async *, callback)" 4
2402.IX Item "ev_async_init (ev_async *, callback)"
2403Initialises and configures the async watcher \- it has no parameters of any
2404kind. There is a \f(CW\*(C`ev_asynd_set\*(C'\fR macro, but using it is utterly pointless,
2405believe me.
2406.IP "ev_async_send (loop, ev_async *)" 4
2407.IX Item "ev_async_send (loop, ev_async *)"
2408Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds
2409an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike
2410\&\f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do in other threads, signal or
2411similar contexts (see the dicusssion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the embedding
2412section below on what exactly this means).
2413.Sp
2414This call incurs the overhead of a syscall only once per loop iteration,
2415so while the overhead might be noticable, it doesn't apply to repeated
2416calls to \f(CW\*(C`ev_async_send\*(C'\fR.
2417.IP "bool = ev_async_pending (ev_async *)" 4
2418.IX Item "bool = ev_async_pending (ev_async *)"
2419Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the
2420watcher but the event has not yet been processed (or even noted) by the
2421event loop.
2422.Sp
2423\&\f(CW\*(C`ev_async_send\*(C'\fR sets a flag in the watcher and wakes up the loop. When
2424the loop iterates next and checks for the watcher to have become active,
2425it will reset the flag again. \f(CW\*(C`ev_async_pending\*(C'\fR can be used to very
2426quickly check wether invoking the loop might be a good idea.
2427.Sp
2428Not that this does \fInot\fR check wether the watcher itself is pending, only
2429wether it has been requested to make this watcher pending.
2178.SH "OTHER FUNCTIONS" 2430.SH "OTHER FUNCTIONS"
2179.IX Header "OTHER FUNCTIONS" 2431.IX Header "OTHER FUNCTIONS"
2180There are some other functions of possible interest. Described. Here. Now. 2432There are some other functions of possible interest. Described. Here. Now.
2181.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 2433.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
2182.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 2434.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
… …
2239it a private \s-1API\s0). 2491it a private \s-1API\s0).
2240.IP "\(bu" 4 2492.IP "\(bu" 4
2241Priorities are not currently supported. Initialising priorities 2493Priorities are not currently supported. Initialising priorities
2242will fail and all watchers will have the same priority, even though there 2494will fail and all watchers will have the same priority, even though there
2243is an ev_pri field. 2495is an ev_pri field.
2496.IP "\(bu" 4
2497In libevent, the last base created gets the signals, in libev, the
2498first base created (== the default loop) gets the signals.
2244.IP "\(bu" 4 2499.IP "\(bu" 4
2245Other members are not supported. 2500Other members are not supported.
2246.IP "\(bu" 4 2501.IP "\(bu" 4
2247The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need 2502The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
2248to use the libev header file and library. 2503to use the libev header file and library.
… …
2406\& 2661\&
2407\& io.start (fd, ev::READ); 2662\& io.start (fd, ev::READ);
2408\& } 2663\& }
2409\& }; 2664\& };
2410.Ve 2665.Ve
2666.SH "OTHER LANGUAGE BINDINGS"
2667.IX Header "OTHER LANGUAGE BINDINGS"
2668Libev does not offer other language bindings itself, but bindings for a
2669numbe rof languages exist in the form of third-party packages. If you know
2670any interesting language binding in addition to the ones listed here, drop
2671me a note.
2672.IP "Perl" 4
2673.IX Item "Perl"
2674The \s-1EV\s0 module implements the full libev \s-1API\s0 and is actually used to test
2675libev. \s-1EV\s0 is developed together with libev. Apart from the \s-1EV\s0 core module,
2676there are additional modules that implement libev-compatible interfaces
2677to \f(CW\*(C`libadns\*(C'\fR (\f(CW\*(C`EV::ADNS\*(C'\fR), \f(CW\*(C`Net::SNMP\*(C'\fR (\f(CW\*(C`Net::SNMP::EV\*(C'\fR) and the
2678\&\f(CW\*(C`libglib\*(C'\fR event core (\f(CW\*(C`Glib::EV\*(C'\fR and \f(CW\*(C`EV::Glib\*(C'\fR).
2679.Sp
2680It can be found and installed via \s-1CPAN\s0, its homepage is found at
2681<http://software.schmorp.de/pkg/EV>.
2682.IP "Ruby" 4
2683.IX Item "Ruby"
2684Tony Arcieri has written a ruby extension that offers access to a subset
2685of the libev \s-1API\s0 and adds filehandle abstractions, asynchronous \s-1DNS\s0 and
2686more on top of it. It can be found via gem servers. Its homepage is at
2687<http://rev.rubyforge.org/>.
2688.IP "D" 4
2689.IX Item "D"
2690Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
2691be found at <http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>.
2411.SH "MACRO MAGIC" 2692.SH "MACRO MAGIC"
2412.IX Header "MACRO MAGIC" 2693.IX Header "MACRO MAGIC"
2413Libev can be compiled with a variety of options, the most fundamantal 2694Libev can be compiled with a variety of options, the most fundamantal
2414of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 2695of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
2415functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 2696functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
2451.ie n .IP """EV_DEFAULT""\fR, \f(CW""EV_DEFAULT_""" 4 2732.ie n .IP """EV_DEFAULT""\fR, \f(CW""EV_DEFAULT_""" 4
2452.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 2733.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
2453.IX Item "EV_DEFAULT, EV_DEFAULT_" 2734.IX Item "EV_DEFAULT, EV_DEFAULT_"
2454Similar to the other two macros, this gives you the value of the default 2735Similar to the other two macros, this gives you the value of the default
2455loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 2736loop, if multiple loops are supported (\*(L"ev loop default\*(R").
2737.ie n .IP """EV_DEFAULT_UC""\fR, \f(CW""EV_DEFAULT_UC_""" 4
2738.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4
2739.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_"
2740Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the
2741default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour
2742is undefined when the default loop has not been initialised by a previous
2743execution of \f(CW\*(C`EV_DEFAULT\*(C'\fR, \f(CW\*(C`EV_DEFAULT_\*(C'\fR or \f(CW\*(C`ev_default_init (...)\*(C'\fR.
2744.Sp
2745It is often prudent to use \f(CW\*(C`EV_DEFAULT\*(C'\fR when initialising the first
2746watcher in a function but use \f(CW\*(C`EV_DEFAULT_UC\*(C'\fR afterwards.
2456.PP 2747.PP
2457Example: Declare and initialise a check watcher, utilising the above 2748Example: Declare and initialise a check watcher, utilising the above
2458macros so it will work regardless of whether multiple loops are supported 2749macros so it will work regardless of whether multiple loops are supported
2459or not. 2750or not.
2460.PP 2751.PP
… …
2570.Vb 1 2861.Vb 1
2571\& libev.m4 2862\& libev.m4
2572.Ve 2863.Ve
2573.Sh "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0" 2864.Sh "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0"
2574.IX Subsection "PREPROCESSOR SYMBOLS/MACROS" 2865.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
2575Libev can be configured via a variety of preprocessor symbols you have to define 2866Libev can be configured via a variety of preprocessor symbols you have to
2576before including any of its files. The default is not to build for multiplicity 2867define before including any of its files. The default in the absense of
2577and only include the select backend. 2868autoconf is noted for every option.
2578.IP "\s-1EV_STANDALONE\s0" 4 2869.IP "\s-1EV_STANDALONE\s0" 4
2579.IX Item "EV_STANDALONE" 2870.IX Item "EV_STANDALONE"
2580Must always be \f(CW1\fR if you do not use autoconf configuration, which 2871Must always be \f(CW1\fR if you do not use autoconf configuration, which
2581keeps libev from including \fIconfig.h\fR, and it also defines dummy 2872keeps libev from including \fIconfig.h\fR, and it also defines dummy
2582implementations for some libevent functions (such as logging, which is not 2873implementations for some libevent functions (such as logging, which is not
… …
2601note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. 2892note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
2602.IP "\s-1EV_USE_NANOSLEEP\s0" 4 2893.IP "\s-1EV_USE_NANOSLEEP\s0" 4
2603.IX Item "EV_USE_NANOSLEEP" 2894.IX Item "EV_USE_NANOSLEEP"
2604If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 2895If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
2605and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 2896and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
2897.IP "\s-1EV_USE_EVENTFD\s0" 4
2898.IX Item "EV_USE_EVENTFD"
2899If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
2900available and will probe for kernel support at runtime. This will improve
2901\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
2902If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
29032.7 or newer, otherwise disabled.
2606.IP "\s-1EV_USE_SELECT\s0" 4 2904.IP "\s-1EV_USE_SELECT\s0" 4
2607.IX Item "EV_USE_SELECT" 2905.IX Item "EV_USE_SELECT"
2608If undefined or defined to be \f(CW1\fR, libev will compile in support for the 2906If undefined or defined to be \f(CW1\fR, libev will compile in support for the
2609\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no 2907\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no
2610other method takes over, select will be it. Otherwise the select backend 2908other method takes over, select will be it. Otherwise the select backend
… …
2641takes precedence over select. 2939takes precedence over select.
2642.IP "\s-1EV_USE_EPOLL\s0" 4 2940.IP "\s-1EV_USE_EPOLL\s0" 4
2643.IX Item "EV_USE_EPOLL" 2941.IX Item "EV_USE_EPOLL"
2644If defined to be \f(CW1\fR, libev will compile in support for the Linux 2942If defined to be \f(CW1\fR, libev will compile in support for the Linux
2645\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 2943\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
2646otherwise another method will be used as fallback. This is the 2944otherwise another method will be used as fallback. This is the preferred
2647preferred backend for GNU/Linux systems. 2945backend for GNU/Linux systems. If undefined, it will be enabled if the
2946headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2648.IP "\s-1EV_USE_KQUEUE\s0" 4 2947.IP "\s-1EV_USE_KQUEUE\s0" 4
2649.IX Item "EV_USE_KQUEUE" 2948.IX Item "EV_USE_KQUEUE"
2650If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 2949If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
2651\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 2950\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
2652otherwise another method will be used as fallback. This is the preferred 2951otherwise another method will be used as fallback. This is the preferred
… …
2667reserved for future expansion, works like the \s-1USE\s0 symbols above. 2966reserved for future expansion, works like the \s-1USE\s0 symbols above.
2668.IP "\s-1EV_USE_INOTIFY\s0" 4 2967.IP "\s-1EV_USE_INOTIFY\s0" 4
2669.IX Item "EV_USE_INOTIFY" 2968.IX Item "EV_USE_INOTIFY"
2670If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify 2969If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify
2671interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will 2970interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
2672be detected at runtime. 2971be detected at runtime. If undefined, it will be enabled if the headers
2972indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2973.IP "\s-1EV_ATOMIC_T\s0" 4
2974.IX Item "EV_ATOMIC_T"
2975Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
2976access is atomic with respect to other threads or signal contexts. No such
2977type is easily found in the C language, so you can provide your own type
2978that you know is safe for your purposes. It is used both for signal handler \*(L"locking\*(R"
2979as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR watchers.
2980.Sp
2981In the absense of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
2982(from \fIsignal.h\fR), which is usually good enough on most platforms.
2673.IP "\s-1EV_H\s0" 4 2983.IP "\s-1EV_H\s0" 4
2674.IX Item "EV_H" 2984.IX Item "EV_H"
2675The name of the \fIev.h\fR header file used to include it. The default if 2985The name of the \fIev.h\fR header file used to include it. The default if
2676undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 2986undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
2677used to virtually rename the \fIev.h\fR header file in case of conflicts. 2987used to virtually rename the \fIev.h\fR header file in case of conflicts.
… …
2735defined to be \f(CW0\fR, then they are not. 3045defined to be \f(CW0\fR, then they are not.
2736.IP "\s-1EV_FORK_ENABLE\s0" 4 3046.IP "\s-1EV_FORK_ENABLE\s0" 4
2737.IX Item "EV_FORK_ENABLE" 3047.IX Item "EV_FORK_ENABLE"
2738If undefined or defined to be \f(CW1\fR, then fork watchers are supported. If 3048If undefined or defined to be \f(CW1\fR, then fork watchers are supported. If
2739defined to be \f(CW0\fR, then they are not. 3049defined to be \f(CW0\fR, then they are not.
3050.IP "\s-1EV_ASYNC_ENABLE\s0" 4
3051.IX Item "EV_ASYNC_ENABLE"
3052If undefined or defined to be \f(CW1\fR, then async watchers are supported. If
3053defined to be \f(CW0\fR, then they are not.
2740.IP "\s-1EV_MINIMAL\s0" 4 3054.IP "\s-1EV_MINIMAL\s0" 4
2741.IX Item "EV_MINIMAL" 3055.IX Item "EV_MINIMAL"
2742If you need to shave off some kilobytes of code at the expense of some 3056If you need to shave off some kilobytes of code at the expense of some
2743speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override 3057speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override
2744some inlining decisions, saves roughly 30% codesize of amd64. 3058some inlining decisions, saves roughly 30% codesize of amd64.
… …
2844.PP 3158.PP
2845.Vb 2 3159.Vb 2
2846\& #include "ev_cpp.h" 3160\& #include "ev_cpp.h"
2847\& #include "ev.c" 3161\& #include "ev.c"
2848.Ve 3162.Ve
3163.SH "THREADS AND COROUTINES"
3164.IX Header "THREADS AND COROUTINES"
3165.Sh "\s-1THREADS\s0"
3166.IX Subsection "THREADS"
3167Libev itself is completely threadsafe, but it uses no locking. This
3168means that you can use as many loops as you want in parallel, as long as
3169only one thread ever calls into one libev function with the same loop
3170parameter.
3171.PP
3172Or put differently: calls with different loop parameters can be done in
3173parallel from multiple threads, calls with the same loop parameter must be
3174done serially (but can be done from different threads, as long as only one
3175thread ever is inside a call at any point in time, e.g. by using a mutex
3176per loop).
3177.PP
3178If you want to know which design is best for your problem, then I cannot
3179help you but by giving some generic advice:
3180.IP "\(bu" 4
3181most applications have a main thread: use the default libev loop
3182in that thread, or create a seperate thread running only the default loop.
3183.Sp
3184This helps integrating other libraries or software modules that use libev
3185themselves and don't care/know about threading.
3186.IP "\(bu" 4
3187one loop per thread is usually a good model.
3188.Sp
3189Doing this is almost never wrong, sometimes a better-performance model
3190exists, but it is always a good start.
3191.IP "\(bu" 4
3192other models exist, such as the leader/follower pattern, where one
3193loop is handed through multiple threads in a kind of round-robbin fashion.
3194.Sp
3195Chosing a model is hard \- look around, learn, know that usually you cna do
3196better than you currently do :\-)
3197.IP "\(bu" 4
3198often you need to talk to some other thread which blocks in the
3199event loop \- \f(CW\*(C`ev_async\*(C'\fR watchers can be used to wake them up from other
3200threads safely (or from signal contexts...).
3201.Sh "\s-1COROUTINES\s0"
3202.IX Subsection "COROUTINES"
3203Libev is much more accomodating to coroutines (\*(L"cooperative threads\*(R"):
3204libev fully supports nesting calls to it's functions from different
3205coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two
3206different coroutines and switch freely between both coroutines running the
3207loop, as long as you don't confuse yourself). The only exception is that
3208you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
3209.PP
3210Care has been invested into making sure that libev does not keep local
3211state inside \f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow coroutine
3212switches.
2849.SH "COMPLEXITIES" 3213.SH "COMPLEXITIES"
2850.IX Header "COMPLEXITIES" 3214.IX Header "COMPLEXITIES"
2851In this section the complexities of (many of) the algorithms used inside 3215In this section the complexities of (many of) the algorithms used inside
2852libev will be explained. For complexity discussions about backends see the 3216libev will be explained. For complexity discussions about backends see the
2853documentation for \f(CW\*(C`ev_default_init\*(C'\fR. 3217documentation for \f(CW\*(C`ev_default_init\*(C'\fR.
… …
2864have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. 3228have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers.
2865.IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4 3229.IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4
2866.IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 3230.IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)"
2867That means that changing a timer costs less than removing/adding them 3231That means that changing a timer costs less than removing/adding them
2868as only the relative motion in the event queue has to be paid for. 3232as only the relative motion in the event queue has to be paid for.
2869.IP "Starting io/check/prepare/idle/signal/child watchers: O(1)" 4 3233.IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4
2870.IX Item "Starting io/check/prepare/idle/signal/child watchers: O(1)" 3234.IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)"
2871These just add the watcher into an array or at the head of a list. 3235These just add the watcher into an array or at the head of a list.
2872.IP "Stopping check/prepare/idle watchers: O(1)" 4 3236.IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4
2873.IX Item "Stopping check/prepare/idle watchers: O(1)" 3237.IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)"
2874.PD 0 3238.PD 0
2875.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 3239.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4
2876.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" 3240.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))"
2877.PD 3241.PD
2878These watchers are stored in lists then need to be walked to find the 3242These watchers are stored in lists then need to be walked to find the
… …
2894.IX Item "Priority handling: O(number_of_priorities)" 3258.IX Item "Priority handling: O(number_of_priorities)"
2895.PD 3259.PD
2896Priorities are implemented by allocating some space for each 3260Priorities are implemented by allocating some space for each
2897priority. When doing priority-based operations, libev usually has to 3261priority. When doing priority-based operations, libev usually has to
2898linearly search all the priorities, but starting/stopping and activating 3262linearly search all the priorities, but starting/stopping and activating
2899watchers becomes O(1) w.r.t. prioritiy handling. 3263watchers becomes O(1) w.r.t. priority handling.
3264.IP "Sending an ev_async: O(1)" 4
3265.IX Item "Sending an ev_async: O(1)"
3266.PD 0
3267.IP "Processing ev_async_send: O(number_of_async_watchers)" 4
3268.IX Item "Processing ev_async_send: O(number_of_async_watchers)"
3269.IP "Processing signals: O(max_signal_number)" 4
3270.IX Item "Processing signals: O(max_signal_number)"
3271.PD
3272Sending involves a syscall \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR
3273calls in the current loop iteration. Checking for async and signal events
3274involves iterating over all running async watchers or all signal numbers.
2900.SH "Win32 platform limitations and workarounds" 3275.SH "Win32 platform limitations and workarounds"
2901.IX Header "Win32 platform limitations and workarounds" 3276.IX Header "Win32 platform limitations and workarounds"
2902Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev 3277Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
2903requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 3278requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
2904model. Libev still offers limited functionality on this platform in 3279model. Libev still offers limited functionality on this platform in
… …
2962.IX Header "AUTHOR" 3337.IX Header "AUTHOR"
2963Marc Lehmann <libev@schmorp.de>. 3338Marc Lehmann <libev@schmorp.de>.
2964.SH "POD ERRORS" 3339.SH "POD ERRORS"
2965.IX Header "POD ERRORS" 3340.IX Header "POD ERRORS"
2966Hey! \fBThe above document had some coding errors, which are explained below:\fR 3341Hey! \fBThe above document had some coding errors, which are explained below:\fR
2967.IP "Around line 2686:" 4 3342.IP "Around line 3015:" 4
2968.IX Item "Around line 2686:" 3343.IX Item "Around line 3015:"
2969You forgot a '=back' before '=head2' 3344You forgot a '=back' before '=head2'

Diff Legend

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