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

Comparing libev/ev.pod (file contents):
Revision 1.76 by root, Sat Dec 8 15:30:30 2007 UTC vs.
Revision 1.152 by root, Wed May 7 14:45:17 2008 UTC

4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 #include <ev.h> 7 #include <ev.h>
8 8
9=head1 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 // a single header file is required
11 #include <ev.h> 12 #include <ev.h>
12 13
14 // every watcher type has its own typedef'd struct
15 // with the name ev_<type>
13 ev_io stdin_watcher; 16 ev_io stdin_watcher;
14 ev_timer timeout_watcher; 17 ev_timer timeout_watcher;
15 18
19 // all watcher callbacks have a similar signature
16 /* called when data readable on stdin */ 20 // this callback is called when data is readable on stdin
17 static void 21 static void
18 stdin_cb (EV_P_ struct ev_io *w, int revents) 22 stdin_cb (EV_P_ struct ev_io *w, int revents)
19 { 23 {
20 /* puts ("stdin ready"); */ 24 puts ("stdin ready");
21 ev_io_stop (EV_A_ w); /* just a syntax example */ 25 // for one-shot events, one must manually stop the watcher
22 ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */ 26 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w);
28
29 // this causes all nested ev_loop's to stop iterating
30 ev_unloop (EV_A_ EVUNLOOP_ALL);
23 } 31 }
24 32
33 // another callback, this time for a time-out
25 static void 34 static void
26 timeout_cb (EV_P_ struct ev_timer *w, int revents) 35 timeout_cb (EV_P_ struct ev_timer *w, int revents)
27 { 36 {
28 /* puts ("timeout"); */ 37 puts ("timeout");
29 ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */ 38 // this causes the innermost ev_loop to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE);
30 } 40 }
31 41
32 int 42 int
33 main (void) 43 main (void)
34 { 44 {
45 // use the default event loop unless you have special needs
35 struct ev_loop *loop = ev_default_loop (0); 46 struct ev_loop *loop = ev_default_loop (0);
36 47
37 /* initialise an io watcher, then start it */ 48 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable
38 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
39 ev_io_start (loop, &stdin_watcher); 51 ev_io_start (loop, &stdin_watcher);
40 52
53 // initialise a timer watcher, then start it
41 /* simple non-repeating 5.5 second timeout */ 54 // simple non-repeating 5.5 second timeout
42 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
43 ev_timer_start (loop, &timeout_watcher); 56 ev_timer_start (loop, &timeout_watcher);
44 57
45 /* loop till timeout or data ready */ 58 // now wait for events to arrive
46 ev_loop (loop, 0); 59 ev_loop (loop, 0);
47 60
61 // unloop was called, so exit
48 return 0; 62 return 0;
49 } 63 }
50 64
51=head1 DESCRIPTION 65=head1 DESCRIPTION
52 66
53The newest version of this document is also available as a html-formatted 67The newest version of this document is also available as an html-formatted
54web page you might find easier to navigate when reading it for the first 68web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>. 69time: L<http://cvs.schmorp.de/libev/ev.html>.
56 70
57Libev is an event loop: you register interest in certain events (such as a 71Libev is an event loop: you register interest in certain events (such as a
58file descriptor being readable or a timeout occuring), and it will manage 72file descriptor being readable or a timeout occurring), and it will manage
59these event sources and provide your program with events. 73these event sources and provide your program with events.
60 74
61To do this, it must take more or less complete control over your process 75To do this, it must take more or less complete control over your process
62(or thread) by executing the I<event loop> handler, and will then 76(or thread) by executing the I<event loop> handler, and will then
63communicate events via a callback mechanism. 77communicate events via a callback mechanism.
65You register interest in certain events by registering so-called I<event 79You register interest in certain events by registering so-called I<event
66watchers>, which are relatively small C structures you initialise with the 80watchers>, which are relatively small C structures you initialise with the
67details of the event, and then hand it over to libev by I<starting> the 81details of the event, and then hand it over to libev by I<starting> the
68watcher. 82watcher.
69 83
70=head1 FEATURES 84=head2 FEATURES
71 85
72Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 86Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
73BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 87BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
74for file descriptor events (C<ev_io>), the Linux C<inotify> interface 88for file descriptor events (C<ev_io>), the Linux C<inotify> interface
75(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 89(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
82 96
83It also is quite fast (see this 97It also is quite fast (see this
84L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 98L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
85for example). 99for example).
86 100
87=head1 CONVENTIONS 101=head2 CONVENTIONS
88 102
89Libev is very configurable. In this manual the default configuration will 103Libev is very configurable. In this manual the default (and most common)
90be described, which supports multiple event loops. For more info about 104configuration will be described, which supports multiple event loops. For
91various configuration options please have a look at B<EMBED> section in 105more info about various configuration options please have a look at
92this manual. If libev was configured without support for multiple event 106B<EMBED> section in this manual. If libev was configured without support
93loops, then all functions taking an initial argument of name C<loop> 107for multiple event loops, then all functions taking an initial argument of
94(which is always of type C<struct ev_loop *>) will not have this argument. 108name C<loop> (which is always of type C<struct ev_loop *>) will not have
109this argument.
95 110
96=head1 TIME REPRESENTATION 111=head2 TIME REPRESENTATION
97 112
98Libev represents time as a single floating point number, representing the 113Libev represents time as a single floating point number, representing the
99(fractional) number of seconds since the (POSIX) epoch (somewhere near 114(fractional) number of seconds since the (POSIX) epoch (somewhere near
100the beginning of 1970, details are complicated, don't ask). This type is 115the beginning of 1970, details are complicated, don't ask). This type is
101called C<ev_tstamp>, which is what you should use too. It usually aliases 116called C<ev_tstamp>, which is what you should use too. It usually aliases
102to the C<double> type in C, and when you need to do any calculations on 117to the C<double> type in C, and when you need to do any calculations on
103it, you should treat it as such. 118it, you should treat it as some floatingpoint value. Unlike the name
119component C<stamp> might indicate, it is also used for time differences
120throughout libev.
104 121
105=head1 GLOBAL FUNCTIONS 122=head1 GLOBAL FUNCTIONS
106 123
107These functions can be called anytime, even before initialising the 124These functions can be called anytime, even before initialising the
108library in any way. 125library in any way.
113 130
114Returns the current time as libev would use it. Please note that the 131Returns the current time as libev would use it. Please note that the
115C<ev_now> function is usually faster and also often returns the timestamp 132C<ev_now> function is usually faster and also often returns the timestamp
116you actually want to know. 133you actually want to know.
117 134
135=item ev_sleep (ev_tstamp interval)
136
137Sleep for the given interval: The current thread will be blocked until
138either it is interrupted or the given time interval has passed. Basically
139this is a subsecond-resolution C<sleep ()>.
140
118=item int ev_version_major () 141=item int ev_version_major ()
119 142
120=item int ev_version_minor () 143=item int ev_version_minor ()
121 144
122You can find out the major and minor version numbers of the library 145You can find out the major and minor ABI version numbers of the library
123you linked against by calling the functions C<ev_version_major> and 146you linked against by calling the functions C<ev_version_major> and
124C<ev_version_minor>. If you want, you can compare against the global 147C<ev_version_minor>. If you want, you can compare against the global
125symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the 148symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
126version of the library your program was compiled against. 149version of the library your program was compiled against.
127 150
151These version numbers refer to the ABI version of the library, not the
152release version.
153
128Usually, it's a good idea to terminate if the major versions mismatch, 154Usually, it's a good idea to terminate if the major versions mismatch,
129as this indicates an incompatible change. Minor versions are usually 155as this indicates an incompatible change. Minor versions are usually
130compatible to older versions, so a larger minor version alone is usually 156compatible to older versions, so a larger minor version alone is usually
131not a problem. 157not a problem.
132 158
133Example: Make sure we haven't accidentally been linked against the wrong 159Example: Make sure we haven't accidentally been linked against the wrong
134version. 160version.
170See the description of C<ev_embed> watchers for more info. 196See the description of C<ev_embed> watchers for more info.
171 197
172=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 198=item ev_set_allocator (void *(*cb)(void *ptr, long size))
173 199
174Sets the allocation function to use (the prototype is similar - the 200Sets the allocation function to use (the prototype is similar - the
175semantics is identical - to the realloc C function). It is used to 201semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
176allocate and free memory (no surprises here). If it returns zero when 202used to allocate and free memory (no surprises here). If it returns zero
177memory needs to be allocated, the library might abort or take some 203when memory needs to be allocated (C<size != 0>), the library might abort
178potentially destructive action. The default is your system realloc 204or take some potentially destructive action.
179function. 205
206Since some systems (at least OpenBSD and Darwin) fail to implement
207correct C<realloc> semantics, libev will use a wrapper around the system
208C<realloc> and C<free> functions by default.
180 209
181You could override this function in high-availability programs to, say, 210You could override this function in high-availability programs to, say,
182free some memory if it cannot allocate memory, to use a special allocator, 211free some memory if it cannot allocate memory, to use a special allocator,
183or even to sleep a while and retry until some memory is available. 212or even to sleep a while and retry until some memory is available.
184 213
185Example: Replace the libev allocator with one that waits a bit and then 214Example: Replace the libev allocator with one that waits a bit and then
186retries). 215retries (example requires a standards-compliant C<realloc>).
187 216
188 static void * 217 static void *
189 persistent_realloc (void *ptr, size_t size) 218 persistent_realloc (void *ptr, size_t size)
190 { 219 {
191 for (;;) 220 for (;;)
230 259
231An event loop is described by a C<struct ev_loop *>. The library knows two 260An event loop is described by a C<struct ev_loop *>. The library knows two
232types of such loops, the I<default> loop, which supports signals and child 261types of such loops, the I<default> loop, which supports signals and child
233events, and dynamically created loops which do not. 262events, and dynamically created loops which do not.
234 263
235If you use threads, a common model is to run the default event loop
236in your main thread (or in a separate thread) and for each thread you
237create, you also create another event loop. Libev itself does no locking
238whatsoever, so if you mix calls to the same event loop in different
239threads, make sure you lock (this is usually a bad idea, though, even if
240done correctly, because it's hideous and inefficient).
241
242=over 4 264=over 4
243 265
244=item struct ev_loop *ev_default_loop (unsigned int flags) 266=item struct ev_loop *ev_default_loop (unsigned int flags)
245 267
246This will initialise the default event loop if it hasn't been initialised 268This will initialise the default event loop if it hasn't been initialised
248false. If it already was initialised it simply returns it (and ignores the 270false. If it already was initialised it simply returns it (and ignores the
249flags. If that is troubling you, check C<ev_backend ()> afterwards). 271flags. If that is troubling you, check C<ev_backend ()> afterwards).
250 272
251If you don't know what event loop to use, use the one returned from this 273If you don't know what event loop to use, use the one returned from this
252function. 274function.
275
276Note that this function is I<not> thread-safe, so if you want to use it
277from multiple threads, you have to lock (note also that this is unlikely,
278as loops cannot bes hared easily between threads anyway).
279
280The default loop is the only loop that can handle C<ev_signal> and
281C<ev_child> watchers, and to do this, it always registers a handler
282for C<SIGCHLD>. If this is a problem for your app you can either
283create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
284can simply overwrite the C<SIGCHLD> signal handler I<after> calling
285C<ev_default_init>.
253 286
254The flags argument can be used to specify special behaviour or specific 287The flags argument can be used to specify special behaviour or specific
255backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>). 288backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
256 289
257The following flags are supported: 290The following flags are supported:
279enabling this flag. 312enabling this flag.
280 313
281This works by calling C<getpid ()> on every iteration of the loop, 314This works by calling C<getpid ()> on every iteration of the loop,
282and thus this might slow down your event loop if you do a lot of loop 315and thus this might slow down your event loop if you do a lot of loop
283iterations and little real work, but is usually not noticeable (on my 316iterations and little real work, but is usually not noticeable (on my
284Linux system for example, C<getpid> is actually a simple 5-insn sequence 317GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
285without a syscall and thus I<very> fast, but my Linux system also has 318without a syscall and thus I<very> fast, but my GNU/Linux system also has
286C<pthread_atfork> which is even faster). 319C<pthread_atfork> which is even faster).
287 320
288The big advantage of this flag is that you can forget about fork (and 321The big advantage of this flag is that you can forget about fork (and
289forget about forgetting to tell libev about forking) when you use this 322forget about forgetting to tell libev about forking) when you use this
290flag. 323flag.
295=item C<EVBACKEND_SELECT> (value 1, portable select backend) 328=item C<EVBACKEND_SELECT> (value 1, portable select backend)
296 329
297This is your standard select(2) backend. Not I<completely> standard, as 330This is your standard select(2) backend. Not I<completely> standard, as
298libev tries to roll its own fd_set with no limits on the number of fds, 331libev tries to roll its own fd_set with no limits on the number of fds,
299but if that fails, expect a fairly low limit on the number of fds when 332but if that fails, expect a fairly low limit on the number of fds when
300using this backend. It doesn't scale too well (O(highest_fd)), but its usually 333using this backend. It doesn't scale too well (O(highest_fd)), but its
301the fastest backend for a low number of fds. 334usually the fastest backend for a low number of (low-numbered :) fds.
335
336To get good performance out of this backend you need a high amount of
337parallelity (most of the file descriptors should be busy). If you are
338writing a server, you should C<accept ()> in a loop to accept as many
339connections as possible during one iteration. You might also want to have
340a look at C<ev_set_io_collect_interval ()> to increase the amount of
341readyness notifications you get per iteration.
302 342
303=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 343=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
304 344
305And this is your standard poll(2) backend. It's more complicated than 345And this is your standard poll(2) backend. It's more complicated
306select, but handles sparse fds better and has no artificial limit on the 346than select, but handles sparse fds better and has no artificial
307number of fds you can use (except it will slow down considerably with a 347limit on the number of fds you can use (except it will slow down
308lot of inactive fds). It scales similarly to select, i.e. O(total_fds). 348considerably with a lot of inactive fds). It scales similarly to select,
349i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
350performance tips.
309 351
310=item C<EVBACKEND_EPOLL> (value 4, Linux) 352=item C<EVBACKEND_EPOLL> (value 4, Linux)
311 353
312For few fds, this backend is a bit little slower than poll and select, 354For few fds, this backend is a bit little slower than poll and select,
313but it scales phenomenally better. While poll and select usually scale like 355but it scales phenomenally better. While poll and select usually scale
314O(total_fds) where n is the total number of fds (or the highest fd), epoll scales 356like O(total_fds) where n is the total number of fds (or the highest fd),
315either O(1) or O(active_fds). 357epoll scales either O(1) or O(active_fds). The epoll design has a number
358of shortcomings, such as silently dropping events in some hard-to-detect
359cases and requiring a syscall per fd change, no fork support and bad
360support for dup.
316 361
317While stopping and starting an I/O watcher in the same iteration will 362While stopping, setting and starting an I/O watcher in the same iteration
318result in some caching, there is still a syscall per such incident 363will result in some caching, there is still a syscall per such incident
319(because the fd could point to a different file description now), so its 364(because the fd could point to a different file description now), so its
320best to avoid that. Also, dup()ed file descriptors might not work very 365best to avoid that. Also, C<dup ()>'ed file descriptors might not work
321well if you register events for both fds. 366very well if you register events for both fds.
322 367
323Please note that epoll sometimes generates spurious notifications, so you 368Please note that epoll sometimes generates spurious notifications, so you
324need to use non-blocking I/O or other means to avoid blocking when no data 369need to use non-blocking I/O or other means to avoid blocking when no data
325(or space) is available. 370(or space) is available.
326 371
372Best performance from this backend is achieved by not unregistering all
373watchers for a file descriptor until it has been closed, if possible, i.e.
374keep at least one watcher active per fd at all times.
375
376While nominally embeddeble in other event loops, this feature is broken in
377all kernel versions tested so far.
378
327=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 379=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
328 380
329Kqueue deserves special mention, as at the time of this writing, it 381Kqueue deserves special mention, as at the time of this writing, it
330was broken on all BSDs except NetBSD (usually it doesn't work with 382was broken on all BSDs except NetBSD (usually it doesn't work reliably
331anything but sockets and pipes, except on Darwin, where of course its 383with anything but sockets and pipes, except on Darwin, where of course
332completely useless). For this reason its not being "autodetected" 384it's completely useless). For this reason it's not being "autodetected"
333unless you explicitly specify it explicitly in the flags (i.e. using 385unless you explicitly specify it explicitly in the flags (i.e. using
334C<EVBACKEND_KQUEUE>). 386C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
387system like NetBSD.
388
389You still can embed kqueue into a normal poll or select backend and use it
390only for sockets (after having made sure that sockets work with kqueue on
391the target platform). See C<ev_embed> watchers for more info.
335 392
336It scales in the same way as the epoll backend, but the interface to the 393It scales in the same way as the epoll backend, but the interface to the
337kernel is more efficient (which says nothing about its actual speed, of 394kernel is more efficient (which says nothing about its actual speed, of
338course). While starting and stopping an I/O watcher does not cause an 395course). While stopping, setting and starting an I/O watcher does never
339extra syscall as with epoll, it still adds up to four event changes per 396cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
340incident, so its best to avoid that. 397two event changes per incident, support for C<fork ()> is very bad and it
398drops fds silently in similarly hard-to-detect cases.
399
400This backend usually performs well under most conditions.
401
402While nominally embeddable in other event loops, this doesn't work
403everywhere, so you might need to test for this. And since it is broken
404almost everywhere, you should only use it when you have a lot of sockets
405(for which it usually works), by embedding it into another event loop
406(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
407sockets.
341 408
342=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 409=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
343 410
344This is not implemented yet (and might never be). 411This is not implemented yet (and might never be, unless you send me an
412implementation). According to reports, C</dev/poll> only supports sockets
413and is not embeddable, which would limit the usefulness of this backend
414immensely.
345 415
346=item C<EVBACKEND_PORT> (value 32, Solaris 10) 416=item C<EVBACKEND_PORT> (value 32, Solaris 10)
347 417
348This uses the Solaris 10 port mechanism. As with everything on Solaris, 418This uses the Solaris 10 event port mechanism. As with everything on Solaris,
349it's really slow, but it still scales very well (O(active_fds)). 419it's really slow, but it still scales very well (O(active_fds)).
350 420
351Please note that solaris ports can result in a lot of spurious 421Please note that solaris event ports can deliver a lot of spurious
352notifications, so you need to use non-blocking I/O or other means to avoid 422notifications, so you need to use non-blocking I/O or other means to avoid
353blocking when no data (or space) is available. 423blocking when no data (or space) is available.
424
425While this backend scales well, it requires one system call per active
426file descriptor per loop iteration. For small and medium numbers of file
427descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
428might perform better.
429
430On the positive side, ignoring the spurious readyness notifications, this
431backend actually performed to specification in all tests and is fully
432embeddable, which is a rare feat among the OS-specific backends.
354 433
355=item C<EVBACKEND_ALL> 434=item C<EVBACKEND_ALL>
356 435
357Try all backends (even potentially broken ones that wouldn't be tried 436Try all backends (even potentially broken ones that wouldn't be tried
358with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 437with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
359C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 438C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
360 439
440It is definitely not recommended to use this flag.
441
361=back 442=back
362 443
363If one or more of these are ored into the flags value, then only these 444If one or more of these are ored into the flags value, then only these
364backends will be tried (in the reverse order as given here). If none are 445backends will be tried (in the reverse order as listed here). If none are
365specified, most compiled-in backend will be tried, usually in reverse 446specified, all backends in C<ev_recommended_backends ()> will be tried.
366order of their flag values :)
367 447
368The most typical usage is like this: 448The most typical usage is like this:
369 449
370 if (!ev_default_loop (0)) 450 if (!ev_default_loop (0))
371 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 451 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
385 465
386Similar to C<ev_default_loop>, but always creates a new event loop that is 466Similar to C<ev_default_loop>, but always creates a new event loop that is
387always distinct from the default loop. Unlike the default loop, it cannot 467always distinct from the default loop. Unlike the default loop, it cannot
388handle signal and child watchers, and attempts to do so will be greeted by 468handle signal and child watchers, and attempts to do so will be greeted by
389undefined behaviour (or a failed assertion if assertions are enabled). 469undefined behaviour (or a failed assertion if assertions are enabled).
470
471Note that this function I<is> thread-safe, and the recommended way to use
472libev with threads is indeed to create one loop per thread, and using the
473default loop in the "main" or "initial" thread.
390 474
391Example: Try to create a event loop that uses epoll and nothing else. 475Example: Try to create a event loop that uses epoll and nothing else.
392 476
393 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 477 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
394 if (!epoller) 478 if (!epoller)
399Destroys the default loop again (frees all memory and kernel state 483Destroys the default loop again (frees all memory and kernel state
400etc.). None of the active event watchers will be stopped in the normal 484etc.). None of the active event watchers will be stopped in the normal
401sense, so e.g. C<ev_is_active> might still return true. It is your 485sense, so e.g. C<ev_is_active> might still return true. It is your
402responsibility to either stop all watchers cleanly yoursef I<before> 486responsibility to either stop all watchers cleanly yoursef I<before>
403calling this function, or cope with the fact afterwards (which is usually 487calling this function, or cope with the fact afterwards (which is usually
404the easiest thing, youc na just ignore the watchers and/or C<free ()> them 488the easiest thing, you can just ignore the watchers and/or C<free ()> them
405for example). 489for example).
490
491Note that certain global state, such as signal state, will not be freed by
492this function, and related watchers (such as signal and child watchers)
493would need to be stopped manually.
494
495In general it is not advisable to call this function except in the
496rare occasion where you really need to free e.g. the signal handling
497pipe fds. If you need dynamically allocated loops it is better to use
498C<ev_loop_new> and C<ev_loop_destroy>).
406 499
407=item ev_loop_destroy (loop) 500=item ev_loop_destroy (loop)
408 501
409Like C<ev_default_destroy>, but destroys an event loop created by an 502Like C<ev_default_destroy>, but destroys an event loop created by an
410earlier call to C<ev_loop_new>. 503earlier call to C<ev_loop_new>.
411 504
412=item ev_default_fork () 505=item ev_default_fork ()
413 506
507This function sets a flag that causes subsequent C<ev_loop> iterations
414This function reinitialises the kernel state for backends that have 508to reinitialise the kernel state for backends that have one. Despite the
415one. Despite the name, you can call it anytime, but it makes most sense 509name, you can call it anytime, but it makes most sense after forking, in
416after forking, in either the parent or child process (or both, but that 510the child process (or both child and parent, but that again makes little
417again makes little sense). 511sense). You I<must> call it in the child before using any of the libev
512functions, and it will only take effect at the next C<ev_loop> iteration.
418 513
419You I<must> call this function in the child process after forking if and 514On the other hand, you only need to call this function in the child
420only if you want to use the event library in both processes. If you just 515process if and only if you want to use the event library in the child. If
421fork+exec, you don't have to call it. 516you just fork+exec, you don't have to call it at all.
422 517
423The function itself is quite fast and it's usually not a problem to call 518The function itself is quite fast and it's usually not a problem to call
424it just in case after a fork. To make this easy, the function will fit in 519it just in case after a fork. To make this easy, the function will fit in
425quite nicely into a call to C<pthread_atfork>: 520quite nicely into a call to C<pthread_atfork>:
426 521
427 pthread_atfork (0, 0, ev_default_fork); 522 pthread_atfork (0, 0, ev_default_fork);
428 523
429At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
430without calling this function, so if you force one of those backends you
431do not need to care.
432
433=item ev_loop_fork (loop) 524=item ev_loop_fork (loop)
434 525
435Like C<ev_default_fork>, but acts on an event loop created by 526Like C<ev_default_fork>, but acts on an event loop created by
436C<ev_loop_new>. Yes, you have to call this on every allocated event loop 527C<ev_loop_new>. Yes, you have to call this on every allocated event loop
437after fork, and how you do this is entirely your own problem. 528after fork, and how you do this is entirely your own problem.
529
530=item int ev_is_default_loop (loop)
531
532Returns true when the given loop actually is the default loop, false otherwise.
438 533
439=item unsigned int ev_loop_count (loop) 534=item unsigned int ev_loop_count (loop)
440 535
441Returns the count of loop iterations for the loop, which is identical to 536Returns the count of loop iterations for the loop, which is identical to
442the number of times libev did poll for new events. It starts at C<0> and 537the number of times libev did poll for new events. It starts at C<0> and
455 550
456Returns the current "event loop time", which is the time the event loop 551Returns the current "event loop time", which is the time the event loop
457received events and started processing them. This timestamp does not 552received events and started processing them. This timestamp does not
458change as long as callbacks are being processed, and this is also the base 553change as long as callbacks are being processed, and this is also the base
459time used for relative timers. You can treat it as the timestamp of the 554time used for relative timers. You can treat it as the timestamp of the
460event occuring (or more correctly, libev finding out about it). 555event occurring (or more correctly, libev finding out about it).
461 556
462=item ev_loop (loop, int flags) 557=item ev_loop (loop, int flags)
463 558
464Finally, this is it, the event handler. This function usually is called 559Finally, this is it, the event handler. This function usually is called
465after you initialised all your watchers and you want to start handling 560after you initialised all your watchers and you want to start handling
486libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 581libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
487usually a better approach for this kind of thing. 582usually a better approach for this kind of thing.
488 583
489Here are the gory details of what C<ev_loop> does: 584Here are the gory details of what C<ev_loop> does:
490 585
491 * If there are no active watchers (reference count is zero), return. 586 - Before the first iteration, call any pending watchers.
492 - Queue prepare watchers and then call all outstanding watchers. 587 * If EVFLAG_FORKCHECK was used, check for a fork.
588 - If a fork was detected, queue and call all fork watchers.
589 - Queue and call all prepare watchers.
493 - If we have been forked, recreate the kernel state. 590 - If we have been forked, recreate the kernel state.
494 - Update the kernel state with all outstanding changes. 591 - Update the kernel state with all outstanding changes.
495 - Update the "event loop time". 592 - Update the "event loop time".
496 - Calculate for how long to block. 593 - Calculate for how long to sleep or block, if at all
594 (active idle watchers, EVLOOP_NONBLOCK or not having
595 any active watchers at all will result in not sleeping).
596 - Sleep if the I/O and timer collect interval say so.
497 - Block the process, waiting for any events. 597 - Block the process, waiting for any events.
498 - Queue all outstanding I/O (fd) events. 598 - Queue all outstanding I/O (fd) events.
499 - Update the "event loop time" and do time jump handling. 599 - Update the "event loop time" and do time jump handling.
500 - Queue all outstanding timers. 600 - Queue all outstanding timers.
501 - Queue all outstanding periodics. 601 - Queue all outstanding periodics.
502 - If no events are pending now, queue all idle watchers. 602 - If no events are pending now, queue all idle watchers.
503 - Queue all check watchers. 603 - Queue all check watchers.
504 - Call all queued watchers in reverse order (i.e. check watchers first). 604 - Call all queued watchers in reverse order (i.e. check watchers first).
505 Signals and child watchers are implemented as I/O watchers, and will 605 Signals and child watchers are implemented as I/O watchers, and will
506 be handled here by queueing them when their watcher gets executed. 606 be handled here by queueing them when their watcher gets executed.
507 - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 607 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
508 were used, return, otherwise continue with step *. 608 were used, or there are no active watchers, return, otherwise
609 continue with step *.
509 610
510Example: Queue some jobs and then loop until no events are outsanding 611Example: Queue some jobs and then loop until no events are outstanding
511anymore. 612anymore.
512 613
513 ... queue jobs here, make sure they register event watchers as long 614 ... queue jobs here, make sure they register event watchers as long
514 ... as they still have work to do (even an idle watcher will do..) 615 ... as they still have work to do (even an idle watcher will do..)
515 ev_loop (my_loop, 0); 616 ev_loop (my_loop, 0);
519 620
520Can be used to make a call to C<ev_loop> return early (but only after it 621Can be used to make a call to C<ev_loop> return early (but only after it
521has processed all outstanding events). The C<how> argument must be either 622has processed all outstanding events). The C<how> argument must be either
522C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 623C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
523C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 624C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
625
626This "unloop state" will be cleared when entering C<ev_loop> again.
524 627
525=item ev_ref (loop) 628=item ev_ref (loop)
526 629
527=item ev_unref (loop) 630=item ev_unref (loop)
528 631
533returning, ev_unref() after starting, and ev_ref() before stopping it. For 636returning, ev_unref() after starting, and ev_ref() before stopping it. For
534example, libev itself uses this for its internal signal pipe: It is not 637example, libev itself uses this for its internal signal pipe: It is not
535visible to the libev user and should not keep C<ev_loop> from exiting if 638visible to the libev user and should not keep C<ev_loop> from exiting if
536no event watchers registered by it are active. It is also an excellent 639no event watchers registered by it are active. It is also an excellent
537way to do this for generic recurring timers or from within third-party 640way to do this for generic recurring timers or from within third-party
538libraries. Just remember to I<unref after start> and I<ref before stop>. 641libraries. Just remember to I<unref after start> and I<ref before stop>
642(but only if the watcher wasn't active before, or was active before,
643respectively).
539 644
540Example: Create a signal watcher, but keep it from keeping C<ev_loop> 645Example: Create a signal watcher, but keep it from keeping C<ev_loop>
541running when nothing else is active. 646running when nothing else is active.
542 647
543 struct ev_signal exitsig; 648 struct ev_signal exitsig;
547 652
548Example: For some weird reason, unregister the above signal handler again. 653Example: For some weird reason, unregister the above signal handler again.
549 654
550 ev_ref (loop); 655 ev_ref (loop);
551 ev_signal_stop (loop, &exitsig); 656 ev_signal_stop (loop, &exitsig);
657
658=item ev_set_io_collect_interval (loop, ev_tstamp interval)
659
660=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
661
662These advanced functions influence the time that libev will spend waiting
663for events. Both are by default C<0>, meaning that libev will try to
664invoke timer/periodic callbacks and I/O callbacks with minimum latency.
665
666Setting these to a higher value (the C<interval> I<must> be >= C<0>)
667allows libev to delay invocation of I/O and timer/periodic callbacks to
668increase efficiency of loop iterations.
669
670The background is that sometimes your program runs just fast enough to
671handle one (or very few) event(s) per loop iteration. While this makes
672the program responsive, it also wastes a lot of CPU time to poll for new
673events, especially with backends like C<select ()> which have a high
674overhead for the actual polling but can deliver many events at once.
675
676By setting a higher I<io collect interval> you allow libev to spend more
677time collecting I/O events, so you can handle more events per iteration,
678at the cost of increasing latency. Timeouts (both C<ev_periodic> and
679C<ev_timer>) will be not affected. Setting this to a non-null value will
680introduce an additional C<ev_sleep ()> call into most loop iterations.
681
682Likewise, by setting a higher I<timeout collect interval> you allow libev
683to spend more time collecting timeouts, at the expense of increased
684latency (the watcher callback will be called later). C<ev_io> watchers
685will not be affected. Setting this to a non-null value will not introduce
686any overhead in libev.
687
688Many (busy) programs can usually benefit by setting the io collect
689interval to a value near C<0.1> or so, which is often enough for
690interactive servers (of course not for games), likewise for timeouts. It
691usually doesn't make much sense to set it to a lower value than C<0.01>,
692as this approsaches the timing granularity of most systems.
552 693
553=back 694=back
554 695
555 696
556=head1 ANATOMY OF A WATCHER 697=head1 ANATOMY OF A WATCHER
655 796
656=item C<EV_FORK> 797=item C<EV_FORK>
657 798
658The event loop has been resumed in the child process after fork (see 799The event loop has been resumed in the child process after fork (see
659C<ev_fork>). 800C<ev_fork>).
801
802=item C<EV_ASYNC>
803
804The given async watcher has been asynchronously notified (see C<ev_async>).
660 805
661=item C<EV_ERROR> 806=item C<EV_ERROR>
662 807
663An unspecified error has occured, the watcher has been stopped. This might 808An unspecified error has occured, the watcher has been stopped. This might
664happen because the watcher could not be properly started because libev 809happen because the watcher could not be properly started because libev
882In general you can register as many read and/or write event watchers per 1027In general you can register as many read and/or write event watchers per
883fd as you want (as long as you don't confuse yourself). Setting all file 1028fd as you want (as long as you don't confuse yourself). Setting all file
884descriptors to non-blocking mode is also usually a good idea (but not 1029descriptors to non-blocking mode is also usually a good idea (but not
885required if you know what you are doing). 1030required if you know what you are doing).
886 1031
887You have to be careful with dup'ed file descriptors, though. Some backends
888(the linux epoll backend is a notable example) cannot handle dup'ed file
889descriptors correctly if you register interest in two or more fds pointing
890to the same underlying file/socket/etc. description (that is, they share
891the same underlying "file open").
892
893If you must do this, then force the use of a known-to-be-good backend 1032If you must do this, then force the use of a known-to-be-good backend
894(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 1033(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
895C<EVBACKEND_POLL>). 1034C<EVBACKEND_POLL>).
896 1035
897Another thing you have to watch out for is that it is quite easy to 1036Another thing you have to watch out for is that it is quite easy to
907play around with an Xlib connection), then you have to seperately re-test 1046play around with an Xlib connection), then you have to seperately re-test
908whether a file descriptor is really ready with a known-to-be good interface 1047whether a file descriptor is really ready with a known-to-be good interface
909such as poll (fortunately in our Xlib example, Xlib already does this on 1048such as poll (fortunately in our Xlib example, Xlib already does this on
910its own, so its quite safe to use). 1049its own, so its quite safe to use).
911 1050
1051=head3 The special problem of disappearing file descriptors
1052
1053Some backends (e.g. kqueue, epoll) need to be told about closing a file
1054descriptor (either by calling C<close> explicitly or by any other means,
1055such as C<dup>). The reason is that you register interest in some file
1056descriptor, but when it goes away, the operating system will silently drop
1057this interest. If another file descriptor with the same number then is
1058registered with libev, there is no efficient way to see that this is, in
1059fact, a different file descriptor.
1060
1061To avoid having to explicitly tell libev about such cases, libev follows
1062the following policy: Each time C<ev_io_set> is being called, libev
1063will assume that this is potentially a new file descriptor, otherwise
1064it is assumed that the file descriptor stays the same. That means that
1065you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
1066descriptor even if the file descriptor number itself did not change.
1067
1068This is how one would do it normally anyway, the important point is that
1069the libev application should not optimise around libev but should leave
1070optimisations to libev.
1071
1072=head3 The special problem of dup'ed file descriptors
1073
1074Some backends (e.g. epoll), cannot register events for file descriptors,
1075but only events for the underlying file descriptions. That means when you
1076have C<dup ()>'ed file descriptors or weirder constellations, and register
1077events for them, only one file descriptor might actually receive events.
1078
1079There is no workaround possible except not registering events
1080for potentially C<dup ()>'ed file descriptors, or to resort to
1081C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1082
1083=head3 The special problem of fork
1084
1085Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
1086useless behaviour. Libev fully supports fork, but needs to be told about
1087it in the child.
1088
1089To support fork in your programs, you either have to call
1090C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
1091enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1092C<EVBACKEND_POLL>.
1093
1094=head3 The special problem of SIGPIPE
1095
1096While not really specific to libev, it is easy to forget about SIGPIPE:
1097when reading from a pipe whose other end has been closed, your program
1098gets send a SIGPIPE, which, by default, aborts your program. For most
1099programs this is sensible behaviour, for daemons, this is usually
1100undesirable.
1101
1102So when you encounter spurious, unexplained daemon exits, make sure you
1103ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1104somewhere, as that would have given you a big clue).
1105
1106
1107=head3 Watcher-Specific Functions
1108
912=over 4 1109=over 4
913 1110
914=item ev_io_init (ev_io *, callback, int fd, int events) 1111=item ev_io_init (ev_io *, callback, int fd, int events)
915 1112
916=item ev_io_set (ev_io *, int fd, int events) 1113=item ev_io_set (ev_io *, int fd, int events)
926=item int events [read-only] 1123=item int events [read-only]
927 1124
928The events being watched. 1125The events being watched.
929 1126
930=back 1127=back
1128
1129=head3 Examples
931 1130
932Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well 1131Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
933readable, but only once. Since it is likely line-buffered, you could 1132readable, but only once. Since it is likely line-buffered, you could
934attempt to read a whole line in the callback. 1133attempt to read a whole line in the callback.
935 1134
969 1168
970The callback is guarenteed to be invoked only when its timeout has passed, 1169The callback is guarenteed to be invoked only when its timeout has passed,
971but if multiple timers become ready during the same loop iteration then 1170but if multiple timers become ready during the same loop iteration then
972order of execution is undefined. 1171order of execution is undefined.
973 1172
1173=head3 Watcher-Specific Functions and Data Members
1174
974=over 4 1175=over 4
975 1176
976=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1177=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
977 1178
978=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 1179=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
986configure a timer to trigger every 10 seconds, then it will trigger at 1187configure a timer to trigger every 10 seconds, then it will trigger at
987exactly 10 second intervals. If, however, your program cannot keep up with 1188exactly 10 second intervals. If, however, your program cannot keep up with
988the timer (because it takes longer than those 10 seconds to do stuff) the 1189the timer (because it takes longer than those 10 seconds to do stuff) the
989timer will not fire more than once per event loop iteration. 1190timer will not fire more than once per event loop iteration.
990 1191
991=item ev_timer_again (loop) 1192=item ev_timer_again (loop, ev_timer *)
992 1193
993This will act as if the timer timed out and restart it again if it is 1194This will act as if the timer timed out and restart it again if it is
994repeating. The exact semantics are: 1195repeating. The exact semantics are:
995 1196
996If the timer is pending, its pending status is cleared. 1197If the timer is pending, its pending status is cleared.
1031or C<ev_timer_again> is called and determines the next timeout (if any), 1232or C<ev_timer_again> is called and determines the next timeout (if any),
1032which is also when any modifications are taken into account. 1233which is also when any modifications are taken into account.
1033 1234
1034=back 1235=back
1035 1236
1237=head3 Examples
1238
1036Example: Create a timer that fires after 60 seconds. 1239Example: Create a timer that fires after 60 seconds.
1037 1240
1038 static void 1241 static void
1039 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1242 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1040 { 1243 {
1073but on wallclock time (absolute time). You can tell a periodic watcher 1276but on wallclock time (absolute time). You can tell a periodic watcher
1074to trigger "at" some specific point in time. For example, if you tell a 1277to trigger "at" some specific point in time. For example, if you tell a
1075periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now () 1278periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
1076+ 10.>) and then reset your system clock to the last year, then it will 1279+ 10.>) and then reset your system clock to the last year, then it will
1077take a year to trigger the event (unlike an C<ev_timer>, which would trigger 1280take a year to trigger the event (unlike an C<ev_timer>, which would trigger
1078roughly 10 seconds later and of course not if you reset your system time 1281roughly 10 seconds later).
1079again).
1080 1282
1081They can also be used to implement vastly more complex timers, such as 1283They can also be used to implement vastly more complex timers, such as
1082triggering an event on eahc midnight, local time. 1284triggering an event on each midnight, local time or other, complicated,
1285rules.
1083 1286
1084As with timers, the callback is guarenteed to be invoked only when the 1287As with timers, the callback is guarenteed to be invoked only when the
1085time (C<at>) has been passed, but if multiple periodic timers become ready 1288time (C<at>) has been passed, but if multiple periodic timers become ready
1086during the same loop iteration then order of execution is undefined. 1289during the same loop iteration then order of execution is undefined.
1087 1290
1291=head3 Watcher-Specific Functions and Data Members
1292
1088=over 4 1293=over 4
1089 1294
1090=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1295=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1091 1296
1092=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1297=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1094Lots of arguments, lets sort it out... There are basically three modes of 1299Lots of arguments, lets sort it out... There are basically three modes of
1095operation, and we will explain them from simplest to complex: 1300operation, and we will explain them from simplest to complex:
1096 1301
1097=over 4 1302=over 4
1098 1303
1099=item * absolute timer (interval = reschedule_cb = 0) 1304=item * absolute timer (at = time, interval = reschedule_cb = 0)
1100 1305
1101In this configuration the watcher triggers an event at the wallclock time 1306In this configuration the watcher triggers an event at the wallclock time
1102C<at> and doesn't repeat. It will not adjust when a time jump occurs, 1307C<at> and doesn't repeat. It will not adjust when a time jump occurs,
1103that is, if it is to be run at January 1st 2011 then it will run when the 1308that is, if it is to be run at January 1st 2011 then it will run when the
1104system time reaches or surpasses this time. 1309system time reaches or surpasses this time.
1105 1310
1106=item * non-repeating interval timer (interval > 0, reschedule_cb = 0) 1311=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1107 1312
1108In this mode the watcher will always be scheduled to time out at the next 1313In this mode the watcher will always be scheduled to time out at the next
1109C<at + N * interval> time (for some integer N) and then repeat, regardless 1314C<at + N * interval> time (for some integer N, which can also be negative)
1110of any time jumps. 1315and then repeat, regardless of any time jumps.
1111 1316
1112This can be used to create timers that do not drift with respect to system 1317This can be used to create timers that do not drift with respect to system
1113time: 1318time:
1114 1319
1115 ev_periodic_set (&periodic, 0., 3600., 0); 1320 ev_periodic_set (&periodic, 0., 3600., 0);
1121 1326
1122Another way to think about it (for the mathematically inclined) is that 1327Another way to think about it (for the mathematically inclined) is that
1123C<ev_periodic> will try to run the callback in this mode at the next possible 1328C<ev_periodic> will try to run the callback in this mode at the next possible
1124time where C<time = at (mod interval)>, regardless of any time jumps. 1329time where C<time = at (mod interval)>, regardless of any time jumps.
1125 1330
1331For numerical stability it is preferable that the C<at> value is near
1332C<ev_now ()> (the current time), but there is no range requirement for
1333this value.
1334
1126=item * manual reschedule mode (reschedule_cb = callback) 1335=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1127 1336
1128In this mode the values for C<interval> and C<at> are both being 1337In this mode the values for C<interval> and C<at> are both being
1129ignored. Instead, each time the periodic watcher gets scheduled, the 1338ignored. Instead, each time the periodic watcher gets scheduled, the
1130reschedule callback will be called with the watcher as first, and the 1339reschedule callback will be called with the watcher as first, and the
1131current time as second argument. 1340current time as second argument.
1132 1341
1133NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1342NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1134ever, or make any event loop modifications>. If you need to stop it, 1343ever, or make any event loop modifications>. If you need to stop it,
1135return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by 1344return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1136starting a prepare watcher). 1345starting an C<ev_prepare> watcher, which is legal).
1137 1346
1138Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1347Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
1139ev_tstamp now)>, e.g.: 1348ev_tstamp now)>, e.g.:
1140 1349
1141 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1350 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1164Simply stops and restarts the periodic watcher again. This is only useful 1373Simply stops and restarts the periodic watcher again. This is only useful
1165when you changed some parameters or the reschedule callback would return 1374when you changed some parameters or the reschedule callback would return
1166a different time than the last time it was called (e.g. in a crond like 1375a different time than the last time it was called (e.g. in a crond like
1167program when the crontabs have changed). 1376program when the crontabs have changed).
1168 1377
1378=item ev_tstamp ev_periodic_at (ev_periodic *)
1379
1380When active, returns the absolute time that the watcher is supposed to
1381trigger next.
1382
1383=item ev_tstamp offset [read-write]
1384
1385When repeating, this contains the offset value, otherwise this is the
1386absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1387
1388Can be modified any time, but changes only take effect when the periodic
1389timer fires or C<ev_periodic_again> is being called.
1390
1169=item ev_tstamp interval [read-write] 1391=item ev_tstamp interval [read-write]
1170 1392
1171The current interval value. Can be modified any time, but changes only 1393The current interval value. Can be modified any time, but changes only
1172take effect when the periodic timer fires or C<ev_periodic_again> is being 1394take effect when the periodic timer fires or C<ev_periodic_again> is being
1173called. 1395called.
1177The current reschedule callback, or C<0>, if this functionality is 1399The current reschedule callback, or C<0>, if this functionality is
1178switched off. Can be changed any time, but changes only take effect when 1400switched off. Can be changed any time, but changes only take effect when
1179the periodic timer fires or C<ev_periodic_again> is being called. 1401the periodic timer fires or C<ev_periodic_again> is being called.
1180 1402
1181=back 1403=back
1404
1405=head3 Examples
1182 1406
1183Example: Call a callback every hour, or, more precisely, whenever the 1407Example: Call a callback every hour, or, more precisely, whenever the
1184system clock is divisible by 3600. The callback invocation times have 1408system clock is divisible by 3600. The callback invocation times have
1185potentially a lot of jittering, but good long-term stability. 1409potentially a lot of jittering, but good long-term stability.
1186 1410
1226with the kernel (thus it coexists with your own signal handlers as long 1450with the kernel (thus it coexists with your own signal handlers as long
1227as you don't register any with libev). Similarly, when the last signal 1451as you don't register any with libev). Similarly, when the last signal
1228watcher for a signal is stopped libev will reset the signal handler to 1452watcher for a signal is stopped libev will reset the signal handler to
1229SIG_DFL (regardless of what it was set to before). 1453SIG_DFL (regardless of what it was set to before).
1230 1454
1455If possible and supported, libev will install its handlers with
1456C<SA_RESTART> behaviour enabled, so syscalls should not be unduly
1457interrupted. If you have a problem with syscalls getting interrupted by
1458signals you can block all signals in an C<ev_check> watcher and unblock
1459them in an C<ev_prepare> watcher.
1460
1461=head3 Watcher-Specific Functions and Data Members
1462
1231=over 4 1463=over 4
1232 1464
1233=item ev_signal_init (ev_signal *, callback, int signum) 1465=item ev_signal_init (ev_signal *, callback, int signum)
1234 1466
1235=item ev_signal_set (ev_signal *, int signum) 1467=item ev_signal_set (ev_signal *, int signum)
1241 1473
1242The signal the watcher watches out for. 1474The signal the watcher watches out for.
1243 1475
1244=back 1476=back
1245 1477
1478=head3 Examples
1479
1480Example: Try to exit cleanly on SIGINT and SIGTERM.
1481
1482 static void
1483 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1484 {
1485 ev_unloop (loop, EVUNLOOP_ALL);
1486 }
1487
1488 struct ev_signal signal_watcher;
1489 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1490 ev_signal_start (loop, &sigint_cb);
1491
1246 1492
1247=head2 C<ev_child> - watch out for process status changes 1493=head2 C<ev_child> - watch out for process status changes
1248 1494
1249Child watchers trigger when your process receives a SIGCHLD in response to 1495Child watchers trigger when your process receives a SIGCHLD in response to
1250some child status changes (most typically when a child of yours dies). 1496some child status changes (most typically when a child of yours dies). It
1497is permissible to install a child watcher I<after> the child has been
1498forked (which implies it might have already exited), as long as the event
1499loop isn't entered (or is continued from a watcher).
1500
1501Only the default event loop is capable of handling signals, and therefore
1502you can only rgeister child watchers in the default event loop.
1503
1504=head3 Process Interaction
1505
1506Libev grabs C<SIGCHLD> as soon as the default event loop is
1507initialised. This is necessary to guarantee proper behaviour even if
1508the first child watcher is started after the child exits. The occurance
1509of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1510synchronously as part of the event loop processing. Libev always reaps all
1511children, even ones not watched.
1512
1513=head3 Overriding the Built-In Processing
1514
1515Libev offers no special support for overriding the built-in child
1516processing, but if your application collides with libev's default child
1517handler, you can override it easily by installing your own handler for
1518C<SIGCHLD> after initialising the default loop, and making sure the
1519default loop never gets destroyed. You are encouraged, however, to use an
1520event-based approach to child reaping and thus use libev's support for
1521that, so other libev users can use C<ev_child> watchers freely.
1522
1523=head3 Watcher-Specific Functions and Data Members
1251 1524
1252=over 4 1525=over 4
1253 1526
1254=item ev_child_init (ev_child *, callback, int pid) 1527=item ev_child_init (ev_child *, callback, int pid, int trace)
1255 1528
1256=item ev_child_set (ev_child *, int pid) 1529=item ev_child_set (ev_child *, int pid, int trace)
1257 1530
1258Configures the watcher to wait for status changes of process C<pid> (or 1531Configures the watcher to wait for status changes of process C<pid> (or
1259I<any> process if C<pid> is specified as C<0>). The callback can look 1532I<any> process if C<pid> is specified as C<0>). The callback can look
1260at the C<rstatus> member of the C<ev_child> watcher structure to see 1533at the C<rstatus> member of the C<ev_child> watcher structure to see
1261the status word (use the macros from C<sys/wait.h> and see your systems 1534the status word (use the macros from C<sys/wait.h> and see your systems
1262C<waitpid> documentation). The C<rpid> member contains the pid of the 1535C<waitpid> documentation). The C<rpid> member contains the pid of the
1263process causing the status change. 1536process causing the status change. C<trace> must be either C<0> (only
1537activate the watcher when the process terminates) or C<1> (additionally
1538activate the watcher when the process is stopped or continued).
1264 1539
1265=item int pid [read-only] 1540=item int pid [read-only]
1266 1541
1267The process id this watcher watches out for, or C<0>, meaning any process id. 1542The process id this watcher watches out for, or C<0>, meaning any process id.
1268 1543
1275The process exit/trace status caused by C<rpid> (see your systems 1550The process exit/trace status caused by C<rpid> (see your systems
1276C<waitpid> and C<sys/wait.h> documentation for details). 1551C<waitpid> and C<sys/wait.h> documentation for details).
1277 1552
1278=back 1553=back
1279 1554
1280Example: Try to exit cleanly on SIGINT and SIGTERM. 1555=head3 Examples
1556
1557Example: C<fork()> a new process and install a child handler to wait for
1558its completion.
1559
1560 ev_child cw;
1281 1561
1282 static void 1562 static void
1283 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1563 child_cb (EV_P_ struct ev_child *w, int revents)
1284 { 1564 {
1285 ev_unloop (loop, EVUNLOOP_ALL); 1565 ev_child_stop (EV_A_ w);
1566 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1286 } 1567 }
1287 1568
1288 struct ev_signal signal_watcher; 1569 pid_t pid = fork ();
1289 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1570
1290 ev_signal_start (loop, &sigint_cb); 1571 if (pid < 0)
1572 // error
1573 else if (pid == 0)
1574 {
1575 // the forked child executes here
1576 exit (1);
1577 }
1578 else
1579 {
1580 ev_child_init (&cw, child_cb, pid, 0);
1581 ev_child_start (EV_DEFAULT_ &cw);
1582 }
1291 1583
1292 1584
1293=head2 C<ev_stat> - did the file attributes just change? 1585=head2 C<ev_stat> - did the file attributes just change?
1294 1586
1295This watches a filesystem path for attribute changes. That is, it calls 1587This watches a filesystem path for attribute changes. That is, it calls
1318as even with OS-supported change notifications, this can be 1610as even with OS-supported change notifications, this can be
1319resource-intensive. 1611resource-intensive.
1320 1612
1321At the time of this writing, only the Linux inotify interface is 1613At the time of this writing, only the Linux inotify interface is
1322implemented (implementing kqueue support is left as an exercise for the 1614implemented (implementing kqueue support is left as an exercise for the
1615reader, note, however, that the author sees no way of implementing ev_stat
1323reader). Inotify will be used to give hints only and should not change the 1616semantics with kqueue). Inotify will be used to give hints only and should
1324semantics of C<ev_stat> watchers, which means that libev sometimes needs 1617not change the semantics of C<ev_stat> watchers, which means that libev
1325to fall back to regular polling again even with inotify, but changes are 1618sometimes needs to fall back to regular polling again even with inotify,
1326usually detected immediately, and if the file exists there will be no 1619but changes are usually detected immediately, and if the file exists there
1327polling. 1620will be no polling.
1621
1622=head3 ABI Issues (Largefile Support)
1623
1624Libev by default (unless the user overrides this) uses the default
1625compilation environment, which means that on systems with optionally
1626disabled large file support, you get the 32 bit version of the stat
1627structure. When using the library from programs that change the ABI to
1628use 64 bit file offsets the programs will fail. In that case you have to
1629compile libev with the same flags to get binary compatibility. This is
1630obviously the case with any flags that change the ABI, but the problem is
1631most noticably with ev_stat and largefile support.
1632
1633=head3 Inotify
1634
1635When C<inotify (7)> support has been compiled into libev (generally only
1636available on Linux) and present at runtime, it will be used to speed up
1637change detection where possible. The inotify descriptor will be created lazily
1638when the first C<ev_stat> watcher is being started.
1639
1640Inotify presence does not change the semantics of C<ev_stat> watchers
1641except that changes might be detected earlier, and in some cases, to avoid
1642making regular C<stat> calls. Even in the presence of inotify support
1643there are many cases where libev has to resort to regular C<stat> polling.
1644
1645(There is no support for kqueue, as apparently it cannot be used to
1646implement this functionality, due to the requirement of having a file
1647descriptor open on the object at all times).
1648
1649=head3 The special problem of stat time resolution
1650
1651The C<stat ()> syscall only supports full-second resolution portably, and
1652even on systems where the resolution is higher, many filesystems still
1653only support whole seconds.
1654
1655That means that, if the time is the only thing that changes, you can
1656easily miss updates: on the first update, C<ev_stat> detects a change and
1657calls your callback, which does something. When there is another update
1658within the same second, C<ev_stat> will be unable to detect it as the stat
1659data does not change.
1660
1661The solution to this is to delay acting on a change for slightly more
1662than second (or till slightly after the next full second boundary), using
1663a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
1664ev_timer_again (loop, w)>).
1665
1666The C<.02> offset is added to work around small timing inconsistencies
1667of some operating systems (where the second counter of the current time
1668might be be delayed. One such system is the Linux kernel, where a call to
1669C<gettimeofday> might return a timestamp with a full second later than
1670a subsequent C<time> call - if the equivalent of C<time ()> is used to
1671update file times then there will be a small window where the kernel uses
1672the previous second to update file times but libev might already execute
1673the timer callback).
1674
1675=head3 Watcher-Specific Functions and Data Members
1328 1676
1329=over 4 1677=over 4
1330 1678
1331=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1679=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1332 1680
1336C<path>. The C<interval> is a hint on how quickly a change is expected to 1684C<path>. The C<interval> is a hint on how quickly a change is expected to
1337be detected and should normally be specified as C<0> to let libev choose 1685be detected and should normally be specified as C<0> to let libev choose
1338a suitable value. The memory pointed to by C<path> must point to the same 1686a suitable value. The memory pointed to by C<path> must point to the same
1339path for as long as the watcher is active. 1687path for as long as the watcher is active.
1340 1688
1341The callback will be receive C<EV_STAT> when a change was detected, 1689The callback will receive C<EV_STAT> when a change was detected, relative
1342relative to the attributes at the time the watcher was started (or the 1690to the attributes at the time the watcher was started (or the last change
1343last change was detected). 1691was detected).
1344 1692
1345=item ev_stat_stat (ev_stat *) 1693=item ev_stat_stat (loop, ev_stat *)
1346 1694
1347Updates the stat buffer immediately with new values. If you change the 1695Updates the stat buffer immediately with new values. If you change the
1348watched path in your callback, you could call this fucntion to avoid 1696watched path in your callback, you could call this function to avoid
1349detecting this change (while introducing a race condition). Can also be 1697detecting this change (while introducing a race condition if you are not
1350useful simply to find out the new values. 1698the only one changing the path). Can also be useful simply to find out the
1699new values.
1351 1700
1352=item ev_statdata attr [read-only] 1701=item ev_statdata attr [read-only]
1353 1702
1354The most-recently detected attributes of the file. Although the type is of 1703The most-recently detected attributes of the file. Although the type is
1355C<ev_statdata>, this is usually the (or one of the) C<struct stat> types 1704C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
1356suitable for your system. If the C<st_nlink> member is C<0>, then there 1705suitable for your system, but you can only rely on the POSIX-standardised
1706members to be present. If the C<st_nlink> member is C<0>, then there was
1357was some error while C<stat>ing the file. 1707some error while C<stat>ing the file.
1358 1708
1359=item ev_statdata prev [read-only] 1709=item ev_statdata prev [read-only]
1360 1710
1361The previous attributes of the file. The callback gets invoked whenever 1711The previous attributes of the file. The callback gets invoked whenever
1362C<prev> != C<attr>. 1712C<prev> != C<attr>, or, more precisely, one or more of these members
1713differ: C<st_dev>, C<st_ino>, C<st_mode>, C<st_nlink>, C<st_uid>,
1714C<st_gid>, C<st_rdev>, C<st_size>, C<st_atime>, C<st_mtime>, C<st_ctime>.
1363 1715
1364=item ev_tstamp interval [read-only] 1716=item ev_tstamp interval [read-only]
1365 1717
1366The specified interval. 1718The specified interval.
1367 1719
1368=item const char *path [read-only] 1720=item const char *path [read-only]
1369 1721
1370The filesystem path that is being watched. 1722The filesystem path that is being watched.
1371 1723
1372=back 1724=back
1725
1726=head3 Examples
1373 1727
1374Example: Watch C</etc/passwd> for attribute changes. 1728Example: Watch C</etc/passwd> for attribute changes.
1375 1729
1376 static void 1730 static void
1377 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1731 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1390 } 1744 }
1391 1745
1392 ... 1746 ...
1393 ev_stat passwd; 1747 ev_stat passwd;
1394 1748
1395 ev_stat_init (&passwd, passwd_cb, "/etc/passwd"); 1749 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1396 ev_stat_start (loop, &passwd); 1750 ev_stat_start (loop, &passwd);
1751
1752Example: Like above, but additionally use a one-second delay so we do not
1753miss updates (however, frequent updates will delay processing, too, so
1754one might do the work both on C<ev_stat> callback invocation I<and> on
1755C<ev_timer> callback invocation).
1756
1757 static ev_stat passwd;
1758 static ev_timer timer;
1759
1760 static void
1761 timer_cb (EV_P_ ev_timer *w, int revents)
1762 {
1763 ev_timer_stop (EV_A_ w);
1764
1765 /* now it's one second after the most recent passwd change */
1766 }
1767
1768 static void
1769 stat_cb (EV_P_ ev_stat *w, int revents)
1770 {
1771 /* reset the one-second timer */
1772 ev_timer_again (EV_A_ &timer);
1773 }
1774
1775 ...
1776 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1777 ev_stat_start (loop, &passwd);
1778 ev_timer_init (&timer, timer_cb, 0., 1.02);
1397 1779
1398 1780
1399=head2 C<ev_idle> - when you've got nothing better to do... 1781=head2 C<ev_idle> - when you've got nothing better to do...
1400 1782
1401Idle watchers trigger events when no other events of the same or higher 1783Idle watchers trigger events when no other events of the same or higher
1415Apart from keeping your process non-blocking (which is a useful 1797Apart from keeping your process non-blocking (which is a useful
1416effect on its own sometimes), idle watchers are a good place to do 1798effect on its own sometimes), idle watchers are a good place to do
1417"pseudo-background processing", or delay processing stuff to after the 1799"pseudo-background processing", or delay processing stuff to after the
1418event loop has handled all outstanding events. 1800event loop has handled all outstanding events.
1419 1801
1802=head3 Watcher-Specific Functions and Data Members
1803
1420=over 4 1804=over 4
1421 1805
1422=item ev_idle_init (ev_signal *, callback) 1806=item ev_idle_init (ev_signal *, callback)
1423 1807
1424Initialises and configures the idle watcher - it has no parameters of any 1808Initialises and configures the idle watcher - it has no parameters of any
1425kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 1809kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
1426believe me. 1810believe me.
1427 1811
1428=back 1812=back
1813
1814=head3 Examples
1429 1815
1430Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the 1816Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1431callback, free it. Also, use no error checking, as usual. 1817callback, free it. Also, use no error checking, as usual.
1432 1818
1433 static void 1819 static void
1434 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 1820 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
1435 { 1821 {
1436 free (w); 1822 free (w);
1437 // now do something you wanted to do when the program has 1823 // now do something you wanted to do when the program has
1438 // no longer asnything immediate to do. 1824 // no longer anything immediate to do.
1439 } 1825 }
1440 1826
1441 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 1827 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1442 ev_idle_init (idle_watcher, idle_cb); 1828 ev_idle_init (idle_watcher, idle_cb);
1443 ev_idle_start (loop, idle_cb); 1829 ev_idle_start (loop, idle_cb);
1481with priority higher than or equal to the event loop and one coroutine 1867with priority higher than or equal to the event loop and one coroutine
1482of lower priority, but only once, using idle watchers to keep the event 1868of lower priority, but only once, using idle watchers to keep the event
1483loop from blocking if lower-priority coroutines are active, thus mapping 1869loop from blocking if lower-priority coroutines are active, thus mapping
1484low-priority coroutines to idle/background tasks). 1870low-priority coroutines to idle/background tasks).
1485 1871
1872It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1873priority, to ensure that they are being run before any other watchers
1874after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1875too) should not activate ("feed") events into libev. While libev fully
1876supports this, they might get executed before other C<ev_check> watchers
1877did their job. As C<ev_check> watchers are often used to embed other
1878(non-libev) event loops those other event loops might be in an unusable
1879state until their C<ev_check> watcher ran (always remind yourself to
1880coexist peacefully with others).
1881
1882=head3 Watcher-Specific Functions and Data Members
1883
1486=over 4 1884=over 4
1487 1885
1488=item ev_prepare_init (ev_prepare *, callback) 1886=item ev_prepare_init (ev_prepare *, callback)
1489 1887
1490=item ev_check_init (ev_check *, callback) 1888=item ev_check_init (ev_check *, callback)
1493parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 1891parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1494macros, but using them is utterly, utterly and completely pointless. 1892macros, but using them is utterly, utterly and completely pointless.
1495 1893
1496=back 1894=back
1497 1895
1896=head3 Examples
1897
1498There are a number of principal ways to embed other event loops or modules 1898There are a number of principal ways to embed other event loops or modules
1499into libev. Here are some ideas on how to include libadns into libev 1899into libev. Here are some ideas on how to include libadns into libev
1500(there is a Perl module named C<EV::ADNS> that does this, which you could 1900(there is a Perl module named C<EV::ADNS> that does this, which you could
1501use for an actually working example. Another Perl module named C<EV::Glib> 1901use as a working example. Another Perl module named C<EV::Glib> embeds a
1502embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV 1902Glib main context into libev, and finally, C<Glib::EV> embeds EV into the
1503into the Glib event loop). 1903Glib event loop).
1504 1904
1505Method 1: Add IO watchers and a timeout watcher in a prepare handler, 1905Method 1: Add IO watchers and a timeout watcher in a prepare handler,
1506and in a check watcher, destroy them and call into libadns. What follows 1906and in a check watcher, destroy them and call into libadns. What follows
1507is pseudo-code only of course. This requires you to either use a low 1907is pseudo-code only of course. This requires you to either use a low
1508priority for the check watcher or use C<ev_clear_pending> explicitly, as 1908priority for the check watcher or use C<ev_clear_pending> explicitly, as
1670portable one. 2070portable one.
1671 2071
1672So when you want to use this feature you will always have to be prepared 2072So when you want to use this feature you will always have to be prepared
1673that you cannot get an embeddable loop. The recommended way to get around 2073that you cannot get an embeddable loop. The recommended way to get around
1674this is to have a separate variables for your embeddable loop, try to 2074this is to have a separate variables for your embeddable loop, try to
1675create it, and if that fails, use the normal loop for everything: 2075create it, and if that fails, use the normal loop for everything.
2076
2077=head3 Watcher-Specific Functions and Data Members
2078
2079=over 4
2080
2081=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
2082
2083=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
2084
2085Configures the watcher to embed the given loop, which must be
2086embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
2087invoked automatically, otherwise it is the responsibility of the callback
2088to invoke it (it will continue to be called until the sweep has been done,
2089if you do not want thta, you need to temporarily stop the embed watcher).
2090
2091=item ev_embed_sweep (loop, ev_embed *)
2092
2093Make a single, non-blocking sweep over the embedded loop. This works
2094similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
2095apropriate way for embedded loops.
2096
2097=item struct ev_loop *other [read-only]
2098
2099The embedded event loop.
2100
2101=back
2102
2103=head3 Examples
2104
2105Example: Try to get an embeddable event loop and embed it into the default
2106event loop. If that is not possible, use the default loop. The default
2107loop is stored in C<loop_hi>, while the mebeddable loop is stored in
2108C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be
2109used).
1676 2110
1677 struct ev_loop *loop_hi = ev_default_init (0); 2111 struct ev_loop *loop_hi = ev_default_init (0);
1678 struct ev_loop *loop_lo = 0; 2112 struct ev_loop *loop_lo = 0;
1679 struct ev_embed embed; 2113 struct ev_embed embed;
1680 2114
1691 ev_embed_start (loop_hi, &embed); 2125 ev_embed_start (loop_hi, &embed);
1692 } 2126 }
1693 else 2127 else
1694 loop_lo = loop_hi; 2128 loop_lo = loop_hi;
1695 2129
1696=over 4 2130Example: Check if kqueue is available but not recommended and create
2131a kqueue backend for use with sockets (which usually work with any
2132kqueue implementation). Store the kqueue/socket-only event loop in
2133C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
1697 2134
1698=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 2135 struct ev_loop *loop = ev_default_init (0);
2136 struct ev_loop *loop_socket = 0;
2137 struct ev_embed embed;
2138
2139 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2140 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2141 {
2142 ev_embed_init (&embed, 0, loop_socket);
2143 ev_embed_start (loop, &embed);
2144 }
1699 2145
1700=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 2146 if (!loop_socket)
2147 loop_socket = loop;
1701 2148
1702Configures the watcher to embed the given loop, which must be 2149 // now use loop_socket for all sockets, and loop for everything else
1703embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
1704invoked automatically, otherwise it is the responsibility of the callback
1705to invoke it (it will continue to be called until the sweep has been done,
1706if you do not want thta, you need to temporarily stop the embed watcher).
1707
1708=item ev_embed_sweep (loop, ev_embed *)
1709
1710Make a single, non-blocking sweep over the embedded loop. This works
1711similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1712apropriate way for embedded loops.
1713
1714=item struct ev_loop *loop [read-only]
1715
1716The embedded event loop.
1717
1718=back
1719 2150
1720 2151
1721=head2 C<ev_fork> - the audacity to resume the event loop after a fork 2152=head2 C<ev_fork> - the audacity to resume the event loop after a fork
1722 2153
1723Fork watchers are called when a C<fork ()> was detected (usually because 2154Fork watchers are called when a C<fork ()> was detected (usually because
1726event loop blocks next and before C<ev_check> watchers are being called, 2157event loop blocks next and before C<ev_check> watchers are being called,
1727and only in the child after the fork. If whoever good citizen calling 2158and only in the child after the fork. If whoever good citizen calling
1728C<ev_default_fork> cheats and calls it in the wrong process, the fork 2159C<ev_default_fork> cheats and calls it in the wrong process, the fork
1729handlers will be invoked, too, of course. 2160handlers will be invoked, too, of course.
1730 2161
2162=head3 Watcher-Specific Functions and Data Members
2163
1731=over 4 2164=over 4
1732 2165
1733=item ev_fork_init (ev_signal *, callback) 2166=item ev_fork_init (ev_signal *, callback)
1734 2167
1735Initialises and configures the fork watcher - it has no parameters of any 2168Initialises and configures the fork watcher - it has no parameters of any
1736kind. There is a C<ev_fork_set> macro, but using it is utterly pointless, 2169kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
1737believe me. 2170believe me.
2171
2172=back
2173
2174
2175=head2 C<ev_async> - how to wake up another event loop
2176
2177In general, you cannot use an C<ev_loop> from multiple threads or other
2178asynchronous sources such as signal handlers (as opposed to multiple event
2179loops - those are of course safe to use in different threads).
2180
2181Sometimes, however, you need to wake up another event loop you do not
2182control, for example because it belongs to another thread. This is what
2183C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
2184can signal it by calling C<ev_async_send>, which is thread- and signal
2185safe.
2186
2187This functionality is very similar to C<ev_signal> watchers, as signals,
2188too, are asynchronous in nature, and signals, too, will be compressed
2189(i.e. the number of callback invocations may be less than the number of
2190C<ev_async_sent> calls).
2191
2192Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
2193just the default loop.
2194
2195=head3 Queueing
2196
2197C<ev_async> does not support queueing of data in any way. The reason
2198is that the author does not know of a simple (or any) algorithm for a
2199multiple-writer-single-reader queue that works in all cases and doesn't
2200need elaborate support such as pthreads.
2201
2202That means that if you want to queue data, you have to provide your own
2203queue. But at least I can tell you would implement locking around your
2204queue:
2205
2206=over 4
2207
2208=item queueing from a signal handler context
2209
2210To implement race-free queueing, you simply add to the queue in the signal
2211handler but you block the signal handler in the watcher callback. Here is an example that does that for
2212some fictitiuous SIGUSR1 handler:
2213
2214 static ev_async mysig;
2215
2216 static void
2217 sigusr1_handler (void)
2218 {
2219 sometype data;
2220
2221 // no locking etc.
2222 queue_put (data);
2223 ev_async_send (EV_DEFAULT_ &mysig);
2224 }
2225
2226 static void
2227 mysig_cb (EV_P_ ev_async *w, int revents)
2228 {
2229 sometype data;
2230 sigset_t block, prev;
2231
2232 sigemptyset (&block);
2233 sigaddset (&block, SIGUSR1);
2234 sigprocmask (SIG_BLOCK, &block, &prev);
2235
2236 while (queue_get (&data))
2237 process (data);
2238
2239 if (sigismember (&prev, SIGUSR1)
2240 sigprocmask (SIG_UNBLOCK, &block, 0);
2241 }
2242
2243(Note: pthreads in theory requires you to use C<pthread_setmask>
2244instead of C<sigprocmask> when you use threads, but libev doesn't do it
2245either...).
2246
2247=item queueing from a thread context
2248
2249The strategy for threads is different, as you cannot (easily) block
2250threads but you can easily preempt them, so to queue safely you need to
2251employ a traditional mutex lock, such as in this pthread example:
2252
2253 static ev_async mysig;
2254 static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
2255
2256 static void
2257 otherthread (void)
2258 {
2259 // only need to lock the actual queueing operation
2260 pthread_mutex_lock (&mymutex);
2261 queue_put (data);
2262 pthread_mutex_unlock (&mymutex);
2263
2264 ev_async_send (EV_DEFAULT_ &mysig);
2265 }
2266
2267 static void
2268 mysig_cb (EV_P_ ev_async *w, int revents)
2269 {
2270 pthread_mutex_lock (&mymutex);
2271
2272 while (queue_get (&data))
2273 process (data);
2274
2275 pthread_mutex_unlock (&mymutex);
2276 }
2277
2278=back
2279
2280
2281=head3 Watcher-Specific Functions and Data Members
2282
2283=over 4
2284
2285=item ev_async_init (ev_async *, callback)
2286
2287Initialises and configures the async watcher - it has no parameters of any
2288kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
2289believe me.
2290
2291=item ev_async_send (loop, ev_async *)
2292
2293Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2294an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2295C<ev_feed_event>, this call is safe to do in other threads, signal or
2296similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
2297section below on what exactly this means).
2298
2299This call incurs the overhead of a syscall only once per loop iteration,
2300so while the overhead might be noticable, it doesn't apply to repeated
2301calls to C<ev_async_send>.
2302
2303=item bool = ev_async_pending (ev_async *)
2304
2305Returns a non-zero value when C<ev_async_send> has been called on the
2306watcher but the event has not yet been processed (or even noted) by the
2307event loop.
2308
2309C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2310the loop iterates next and checks for the watcher to have become active,
2311it will reset the flag again. C<ev_async_pending> can be used to very
2312quickly check wether invoking the loop might be a good idea.
2313
2314Not that this does I<not> check wether the watcher itself is pending, only
2315wether it has been requested to make this watcher pending.
1738 2316
1739=back 2317=back
1740 2318
1741 2319
1742=head1 OTHER FUNCTIONS 2320=head1 OTHER FUNCTIONS
1814 2392
1815=item * Priorities are not currently supported. Initialising priorities 2393=item * Priorities are not currently supported. Initialising priorities
1816will fail and all watchers will have the same priority, even though there 2394will fail and all watchers will have the same priority, even though there
1817is an ev_pri field. 2395is an ev_pri field.
1818 2396
2397=item * In libevent, the last base created gets the signals, in libev, the
2398first base created (== the default loop) gets the signals.
2399
1819=item * Other members are not supported. 2400=item * Other members are not supported.
1820 2401
1821=item * The libev emulation is I<not> ABI compatible to libevent, you need 2402=item * The libev emulation is I<not> ABI compatible to libevent, you need
1822to use the libev header file and library. 2403to use the libev header file and library.
1823 2404
1951 2532
1952=item w->stop () 2533=item w->stop ()
1953 2534
1954Stops the watcher if it is active. Again, no C<loop> argument. 2535Stops the watcher if it is active. Again, no C<loop> argument.
1955 2536
1956=item w->again () C<ev::timer>, C<ev::periodic> only 2537=item w->again () (C<ev::timer>, C<ev::periodic> only)
1957 2538
1958For C<ev::timer> and C<ev::periodic>, this invokes the corresponding 2539For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
1959C<ev_TYPE_again> function. 2540C<ev_TYPE_again> function.
1960 2541
1961=item w->sweep () C<ev::embed> only 2542=item w->sweep () (C<ev::embed> only)
1962 2543
1963Invokes C<ev_embed_sweep>. 2544Invokes C<ev_embed_sweep>.
1964 2545
1965=item w->update () C<ev::stat> only 2546=item w->update () (C<ev::stat> only)
1966 2547
1967Invokes C<ev_stat_stat>. 2548Invokes C<ev_stat_stat>.
1968 2549
1969=back 2550=back
1970 2551
1973Example: Define a class with an IO and idle watcher, start one of them in 2554Example: Define a class with an IO and idle watcher, start one of them in
1974the constructor. 2555the constructor.
1975 2556
1976 class myclass 2557 class myclass
1977 { 2558 {
1978 ev_io io; void io_cb (ev::io &w, int revents); 2559 ev::io io; void io_cb (ev::io &w, int revents);
1979 ev_idle idle void idle_cb (ev::idle &w, int revents); 2560 ev:idle idle void idle_cb (ev::idle &w, int revents);
1980 2561
1981 myclass (); 2562 myclass (int fd)
1982 }
1983
1984 myclass::myclass (int fd)
1985 { 2563 {
1986 io .set <myclass, &myclass::io_cb > (this); 2564 io .set <myclass, &myclass::io_cb > (this);
1987 idle.set <myclass, &myclass::idle_cb> (this); 2565 idle.set <myclass, &myclass::idle_cb> (this);
1988 2566
1989 io.start (fd, ev::READ); 2567 io.start (fd, ev::READ);
2568 }
1990 } 2569 };
2570
2571
2572=head1 OTHER LANGUAGE BINDINGS
2573
2574Libev does not offer other language bindings itself, but bindings for a
2575numbe rof languages exist in the form of third-party packages. If you know
2576any interesting language binding in addition to the ones listed here, drop
2577me a note.
2578
2579=over 4
2580
2581=item Perl
2582
2583The EV module implements the full libev API and is actually used to test
2584libev. EV is developed together with libev. Apart from the EV core module,
2585there are additional modules that implement libev-compatible interfaces
2586to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the
2587C<libglib> event core (C<Glib::EV> and C<EV::Glib>).
2588
2589It can be found and installed via CPAN, its homepage is found at
2590L<http://software.schmorp.de/pkg/EV>.
2591
2592=item Ruby
2593
2594Tony Arcieri has written a ruby extension that offers access to a subset
2595of the libev API and adds filehandle abstractions, asynchronous DNS and
2596more on top of it. It can be found via gem servers. Its homepage is at
2597L<http://rev.rubyforge.org/>.
2598
2599=item D
2600
2601Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2602be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>.
2603
2604=back
1991 2605
1992 2606
1993=head1 MACRO MAGIC 2607=head1 MACRO MAGIC
1994 2608
1995Libev can be compiled with a variety of options, the most fundemantal is 2609Libev can be compiled with a variety of options, the most fundamantal
1996C<EV_MULTIPLICITY>. This option determines whether (most) functions and 2610of which is C<EV_MULTIPLICITY>. This option determines whether (most)
1997callbacks have an initial C<struct ev_loop *> argument. 2611functions and callbacks have an initial C<struct ev_loop *> argument.
1998 2612
1999To make it easier to write programs that cope with either variant, the 2613To make it easier to write programs that cope with either variant, the
2000following macros are defined: 2614following macros are defined:
2001 2615
2002=over 4 2616=over 4
2031 2645
2032=item C<EV_DEFAULT>, C<EV_DEFAULT_> 2646=item C<EV_DEFAULT>, C<EV_DEFAULT_>
2033 2647
2034Similar to the other two macros, this gives you the value of the default 2648Similar to the other two macros, this gives you the value of the default
2035loop, if multiple loops are supported ("ev loop default"). 2649loop, if multiple loops are supported ("ev loop default").
2650
2651=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
2652
2653Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
2654default loop has been initialised (C<UC> == unchecked). Their behaviour
2655is undefined when the default loop has not been initialised by a previous
2656execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>.
2657
2658It is often prudent to use C<EV_DEFAULT> when initialising the first
2659watcher in a function but use C<EV_DEFAULT_UC> afterwards.
2036 2660
2037=back 2661=back
2038 2662
2039Example: Declare and initialise a check watcher, utilising the above 2663Example: Declare and initialise a check watcher, utilising the above
2040macros so it will work regardless of whether multiple loops are supported 2664macros so it will work regardless of whether multiple loops are supported
2056Libev can (and often is) directly embedded into host 2680Libev can (and often is) directly embedded into host
2057applications. Examples of applications that embed it include the Deliantra 2681applications. Examples of applications that embed it include the Deliantra
2058Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) 2682Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
2059and rxvt-unicode. 2683and rxvt-unicode.
2060 2684
2061The goal is to enable you to just copy the neecssary files into your 2685The goal is to enable you to just copy the necessary files into your
2062source directory without having to change even a single line in them, so 2686source directory without having to change even a single line in them, so
2063you can easily upgrade by simply copying (or having a checked-out copy of 2687you can easily upgrade by simply copying (or having a checked-out copy of
2064libev somewhere in your source tree). 2688libev somewhere in your source tree).
2065 2689
2066=head2 FILESETS 2690=head2 FILESETS
2136 2760
2137 libev.m4 2761 libev.m4
2138 2762
2139=head2 PREPROCESSOR SYMBOLS/MACROS 2763=head2 PREPROCESSOR SYMBOLS/MACROS
2140 2764
2141Libev can be configured via a variety of preprocessor symbols you have to define 2765Libev can be configured via a variety of preprocessor symbols you have to
2142before including any of its files. The default is not to build for multiplicity 2766define before including any of its files. The default in the absense of
2143and only include the select backend. 2767autoconf is noted for every option.
2144 2768
2145=over 4 2769=over 4
2146 2770
2147=item EV_STANDALONE 2771=item EV_STANDALONE
2148 2772
2156 2780
2157If defined to be C<1>, libev will try to detect the availability of the 2781If defined to be C<1>, libev will try to detect the availability of the
2158monotonic clock option at both compiletime and runtime. Otherwise no use 2782monotonic clock option at both compiletime and runtime. Otherwise no use
2159of the monotonic clock option will be attempted. If you enable this, you 2783of the monotonic clock option will be attempted. If you enable this, you
2160usually have to link against librt or something similar. Enabling it when 2784usually have to link against librt or something similar. Enabling it when
2161the functionality isn't available is safe, though, althoguh you have 2785the functionality isn't available is safe, though, although you have
2162to make sure you link against any libraries where the C<clock_gettime> 2786to make sure you link against any libraries where the C<clock_gettime>
2163function is hiding in (often F<-lrt>). 2787function is hiding in (often F<-lrt>).
2164 2788
2165=item EV_USE_REALTIME 2789=item EV_USE_REALTIME
2166 2790
2167If defined to be C<1>, libev will try to detect the availability of the 2791If defined to be C<1>, libev will try to detect the availability of the
2168realtime clock option at compiletime (and assume its availability at 2792realtime clock option at compiletime (and assume its availability at
2169runtime if successful). Otherwise no use of the realtime clock option will 2793runtime if successful). Otherwise no use of the realtime clock option will
2170be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2794be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2171(CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries 2795(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2172in the description of C<EV_USE_MONOTONIC>, though. 2796note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2797
2798=item EV_USE_NANOSLEEP
2799
2800If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2801and will use it for delays. Otherwise it will use C<select ()>.
2802
2803=item EV_USE_EVENTFD
2804
2805If defined to be C<1>, then libev will assume that C<eventfd ()> is
2806available and will probe for kernel support at runtime. This will improve
2807C<ev_signal> and C<ev_async> performance and reduce resource consumption.
2808If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
28092.7 or newer, otherwise disabled.
2173 2810
2174=item EV_USE_SELECT 2811=item EV_USE_SELECT
2175 2812
2176If undefined or defined to be C<1>, libev will compile in support for the 2813If undefined or defined to be C<1>, libev will compile in support for the
2177C<select>(2) backend. No attempt at autodetection will be done: if no 2814C<select>(2) backend. No attempt at autodetection will be done: if no
2196be used is the winsock select). This means that it will call 2833be used is the winsock select). This means that it will call
2197C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 2834C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
2198it is assumed that all these functions actually work on fds, even 2835it is assumed that all these functions actually work on fds, even
2199on win32. Should not be defined on non-win32 platforms. 2836on win32. Should not be defined on non-win32 platforms.
2200 2837
2838=item EV_FD_TO_WIN32_HANDLE
2839
2840If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
2841file descriptors to socket handles. When not defining this symbol (the
2842default), then libev will call C<_get_osfhandle>, which is usually
2843correct. In some cases, programs use their own file descriptor management,
2844in which case they can provide this function to map fds to socket handles.
2845
2201=item EV_USE_POLL 2846=item EV_USE_POLL
2202 2847
2203If defined to be C<1>, libev will compile in support for the C<poll>(2) 2848If defined to be C<1>, libev will compile in support for the C<poll>(2)
2204backend. Otherwise it will be enabled on non-win32 platforms. It 2849backend. Otherwise it will be enabled on non-win32 platforms. It
2205takes precedence over select. 2850takes precedence over select.
2206 2851
2207=item EV_USE_EPOLL 2852=item EV_USE_EPOLL
2208 2853
2209If defined to be C<1>, libev will compile in support for the Linux 2854If defined to be C<1>, libev will compile in support for the Linux
2210C<epoll>(7) backend. Its availability will be detected at runtime, 2855C<epoll>(7) backend. Its availability will be detected at runtime,
2211otherwise another method will be used as fallback. This is the 2856otherwise another method will be used as fallback. This is the preferred
2212preferred backend for GNU/Linux systems. 2857backend for GNU/Linux systems. If undefined, it will be enabled if the
2858headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2213 2859
2214=item EV_USE_KQUEUE 2860=item EV_USE_KQUEUE
2215 2861
2216If defined to be C<1>, libev will compile in support for the BSD style 2862If defined to be C<1>, libev will compile in support for the BSD style
2217C<kqueue>(2) backend. Its actual availability will be detected at runtime, 2863C<kqueue>(2) backend. Its actual availability will be detected at runtime,
2236 2882
2237=item EV_USE_INOTIFY 2883=item EV_USE_INOTIFY
2238 2884
2239If defined to be C<1>, libev will compile in support for the Linux inotify 2885If defined to be C<1>, libev will compile in support for the Linux inotify
2240interface to speed up C<ev_stat> watchers. Its actual availability will 2886interface to speed up C<ev_stat> watchers. Its actual availability will
2241be detected at runtime. 2887be detected at runtime. If undefined, it will be enabled if the headers
2888indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2889
2890=item EV_ATOMIC_T
2891
2892Libev requires an integer type (suitable for storing C<0> or C<1>) whose
2893access is atomic with respect to other threads or signal contexts. No such
2894type is easily found in the C language, so you can provide your own type
2895that you know is safe for your purposes. It is used both for signal handler "locking"
2896as well as for signal and thread safety in C<ev_async> watchers.
2897
2898In the absense of this define, libev will use C<sig_atomic_t volatile>
2899(from F<signal.h>), which is usually good enough on most platforms.
2242 2900
2243=item EV_H 2901=item EV_H
2244 2902
2245The name of the F<ev.h> header file used to include it. The default if 2903The name of the F<ev.h> header file used to include it. The default if
2246undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This 2904undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2247can be used to virtually rename the F<ev.h> header file in case of conflicts. 2905used to virtually rename the F<ev.h> header file in case of conflicts.
2248 2906
2249=item EV_CONFIG_H 2907=item EV_CONFIG_H
2250 2908
2251If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 2909If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2252F<ev.c>'s idea of where to find the F<config.h> file, similarly to 2910F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2253C<EV_H>, above. 2911C<EV_H>, above.
2254 2912
2255=item EV_EVENT_H 2913=item EV_EVENT_H
2256 2914
2257Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 2915Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2258of how the F<event.h> header can be found. 2916of how the F<event.h> header can be found, the default is C<"event.h">.
2259 2917
2260=item EV_PROTOTYPES 2918=item EV_PROTOTYPES
2261 2919
2262If defined to be C<0>, then F<ev.h> will not define any function 2920If defined to be C<0>, then F<ev.h> will not define any function
2263prototypes, but still define all the structs and other symbols. This is 2921prototypes, but still define all the structs and other symbols. This is
2314=item EV_FORK_ENABLE 2972=item EV_FORK_ENABLE
2315 2973
2316If undefined or defined to be C<1>, then fork watchers are supported. If 2974If undefined or defined to be C<1>, then fork watchers are supported. If
2317defined to be C<0>, then they are not. 2975defined to be C<0>, then they are not.
2318 2976
2977=item EV_ASYNC_ENABLE
2978
2979If undefined or defined to be C<1>, then async watchers are supported. If
2980defined to be C<0>, then they are not.
2981
2319=item EV_MINIMAL 2982=item EV_MINIMAL
2320 2983
2321If you need to shave off some kilobytes of code at the expense of some 2984If you need to shave off some kilobytes of code at the expense of some
2322speed, define this symbol to C<1>. Currently only used for gcc to override 2985speed, define this symbol to C<1>. Currently this is used to override some
2323some inlining decisions, saves roughly 30% codesize of amd64. 2986inlining decisions, saves roughly 30% codesize of amd64. It also selects a
2987much smaller 2-heap for timer management over the default 4-heap.
2324 2988
2325=item EV_PID_HASHSIZE 2989=item EV_PID_HASHSIZE
2326 2990
2327C<ev_child> watchers use a small hash table to distribute workload by 2991C<ev_child> watchers use a small hash table to distribute workload by
2328pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 2992pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
2329than enough. If you need to manage thousands of children you might want to 2993than enough. If you need to manage thousands of children you might want to
2330increase this value (I<must> be a power of two). 2994increase this value (I<must> be a power of two).
2331 2995
2332=item EV_INOTIFY_HASHSIZE 2996=item EV_INOTIFY_HASHSIZE
2333 2997
2334C<ev_staz> watchers use a small hash table to distribute workload by 2998C<ev_stat> watchers use a small hash table to distribute workload by
2335inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 2999inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2336usually more than enough. If you need to manage thousands of C<ev_stat> 3000usually more than enough. If you need to manage thousands of C<ev_stat>
2337watchers you might want to increase this value (I<must> be a power of 3001watchers you might want to increase this value (I<must> be a power of
2338two). 3002two).
2339 3003
2356 3020
2357=item ev_set_cb (ev, cb) 3021=item ev_set_cb (ev, cb)
2358 3022
2359Can be used to change the callback member declaration in each watcher, 3023Can be used to change the callback member declaration in each watcher,
2360and the way callbacks are invoked and set. Must expand to a struct member 3024and the way callbacks are invoked and set. Must expand to a struct member
2361definition and a statement, respectively. See the F<ev.v> header file for 3025definition and a statement, respectively. See the F<ev.h> header file for
2362their default definitions. One possible use for overriding these is to 3026their default definitions. One possible use for overriding these is to
2363avoid the C<struct ev_loop *> as first argument in all cases, or to use 3027avoid the C<struct ev_loop *> as first argument in all cases, or to use
2364method calls instead of plain function calls in C++. 3028method calls instead of plain function calls in C++.
3029
3030=head2 EXPORTED API SYMBOLS
3031
3032If you need to re-export the API (e.g. via a dll) and you need a list of
3033exported symbols, you can use the provided F<Symbol.*> files which list
3034all public symbols, one per line:
3035
3036 Symbols.ev for libev proper
3037 Symbols.event for the libevent emulation
3038
3039This can also be used to rename all public symbols to avoid clashes with
3040multiple versions of libev linked together (which is obviously bad in
3041itself, but sometimes it is inconvinient to avoid this).
3042
3043A sed command like this will create wrapper C<#define>'s that you need to
3044include before including F<ev.h>:
3045
3046 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
3047
3048This would create a file F<wrap.h> which essentially looks like this:
3049
3050 #define ev_backend myprefix_ev_backend
3051 #define ev_check_start myprefix_ev_check_start
3052 #define ev_check_stop myprefix_ev_check_stop
3053 ...
2365 3054
2366=head2 EXAMPLES 3055=head2 EXAMPLES
2367 3056
2368For a real-world example of a program the includes libev 3057For a real-world example of a program the includes libev
2369verbatim, you can have a look at the EV perl module 3058verbatim, you can have a look at the EV perl module
2392 3081
2393 #include "ev_cpp.h" 3082 #include "ev_cpp.h"
2394 #include "ev.c" 3083 #include "ev.c"
2395 3084
2396 3085
3086=head1 THREADS AND COROUTINES
3087
3088=head2 THREADS
3089
3090Libev itself is completely threadsafe, but it uses no locking. This
3091means that you can use as many loops as you want in parallel, as long as
3092only one thread ever calls into one libev function with the same loop
3093parameter.
3094
3095Or put differently: calls with different loop parameters can be done in
3096parallel from multiple threads, calls with the same loop parameter must be
3097done serially (but can be done from different threads, as long as only one
3098thread ever is inside a call at any point in time, e.g. by using a mutex
3099per loop).
3100
3101If you want to know which design is best for your problem, then I cannot
3102help you but by giving some generic advice:
3103
3104=over 4
3105
3106=item * most applications have a main thread: use the default libev loop
3107in that thread, or create a seperate thread running only the default loop.
3108
3109This helps integrating other libraries or software modules that use libev
3110themselves and don't care/know about threading.
3111
3112=item * one loop per thread is usually a good model.
3113
3114Doing this is almost never wrong, sometimes a better-performance model
3115exists, but it is always a good start.
3116
3117=item * other models exist, such as the leader/follower pattern, where one
3118loop is handed through multiple threads in a kind of round-robbin fashion.
3119
3120Chosing a model is hard - look around, learn, know that usually you cna do
3121better than you currently do :-)
3122
3123=item * often you need to talk to some other thread which blocks in the
3124event loop - C<ev_async> watchers can be used to wake them up from other
3125threads safely (or from signal contexts...).
3126
3127=back
3128
3129=head2 COROUTINES
3130
3131Libev is much more accomodating to coroutines ("cooperative threads"):
3132libev fully supports nesting calls to it's functions from different
3133coroutines (e.g. you can call C<ev_loop> on the same loop from two
3134different coroutines and switch freely between both coroutines running the
3135loop, as long as you don't confuse yourself). The only exception is that
3136you must not do this from C<ev_periodic> reschedule callbacks.
3137
3138Care has been invested into making sure that libev does not keep local
3139state inside C<ev_loop>, and other calls do not usually allow coroutine
3140switches.
3141
3142
2397=head1 COMPLEXITIES 3143=head1 COMPLEXITIES
2398 3144
2399In this section the complexities of (many of) the algorithms used inside 3145In this section the complexities of (many of) the algorithms used inside
2400libev will be explained. For complexity discussions about backends see the 3146libev will be explained. For complexity discussions about backends see the
2401documentation for C<ev_default_init>. 3147documentation for C<ev_default_init>.
2410 3156
2411=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 3157=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2412 3158
2413This means that, when you have a watcher that triggers in one hour and 3159This means that, when you have a watcher that triggers in one hour and
2414there are 100 watchers that would trigger before that then inserting will 3160there are 100 watchers that would trigger before that then inserting will
2415have to skip those 100 watchers. 3161have to skip roughly seven (C<ld 100>) of these watchers.
2416 3162
2417=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 3163=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2418 3164
2419That means that for changing a timer costs less than removing/adding them 3165That means that changing a timer costs less than removing/adding them
2420as only the relative motion in the event queue has to be paid for. 3166as only the relative motion in the event queue has to be paid for.
2421 3167
2422=item Starting io/check/prepare/idle/signal/child watchers: O(1) 3168=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
2423 3169
2424These just add the watcher into an array or at the head of a list. 3170These just add the watcher into an array or at the head of a list.
3171
2425=item Stopping check/prepare/idle watchers: O(1) 3172=item Stopping check/prepare/idle/fork/async watchers: O(1)
2426 3173
2427=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 3174=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2428 3175
2429These watchers are stored in lists then need to be walked to find the 3176These watchers are stored in lists then need to be walked to find the
2430correct watcher to remove. The lists are usually short (you don't usually 3177correct watcher to remove. The lists are usually short (you don't usually
2431have many watchers waiting for the same fd or signal). 3178have many watchers waiting for the same fd or signal).
2432 3179
2433=item Finding the next timer per loop iteration: O(1) 3180=item Finding the next timer in each loop iteration: O(1)
3181
3182By virtue of using a binary or 4-heap, the next timer is always found at a
3183fixed position in the storage array.
2434 3184
2435=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 3185=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2436 3186
2437A change means an I/O watcher gets started or stopped, which requires 3187A change means an I/O watcher gets started or stopped, which requires
2438libev to recalculate its status (and possibly tell the kernel). 3188libev to recalculate its status (and possibly tell the kernel, depending
3189on backend and wether C<ev_io_set> was used).
2439 3190
2440=item Activating one watcher: O(1) 3191=item Activating one watcher (putting it into the pending state): O(1)
2441 3192
2442=item Priority handling: O(number_of_priorities) 3193=item Priority handling: O(number_of_priorities)
2443 3194
2444Priorities are implemented by allocating some space for each 3195Priorities are implemented by allocating some space for each
2445priority. When doing priority-based operations, libev usually has to 3196priority. When doing priority-based operations, libev usually has to
2446linearly search all the priorities. 3197linearly search all the priorities, but starting/stopping and activating
3198watchers becomes O(1) w.r.t. priority handling.
3199
3200=item Sending an ev_async: O(1)
3201
3202=item Processing ev_async_send: O(number_of_async_watchers)
3203
3204=item Processing signals: O(max_signal_number)
3205
3206Sending involves a syscall I<iff> there were no other C<ev_async_send>
3207calls in the current loop iteration. Checking for async and signal events
3208involves iterating over all running async watchers or all signal numbers.
2447 3209
2448=back 3210=back
2449 3211
2450 3212
3213=head1 Win32 platform limitations and workarounds
3214
3215Win32 doesn't support any of the standards (e.g. POSIX) that libev
3216requires, and its I/O model is fundamentally incompatible with the POSIX
3217model. Libev still offers limited functionality on this platform in
3218the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3219descriptors. This only applies when using Win32 natively, not when using
3220e.g. cygwin.
3221
3222Lifting these limitations would basically require the full
3223re-implementation of the I/O system. If you are into these kinds of
3224things, then note that glib does exactly that for you in a very portable
3225way (note also that glib is the slowest event library known to man).
3226
3227There is no supported compilation method available on windows except
3228embedding it into other applications.
3229
3230Due to the many, low, and arbitrary limits on the win32 platform and
3231the abysmal performance of winsockets, using a large number of sockets
3232is not recommended (and not reasonable). If your program needs to use
3233more than a hundred or so sockets, then likely it needs to use a totally
3234different implementation for windows, as libev offers the POSIX readyness
3235notification model, which cannot be implemented efficiently on windows
3236(microsoft monopoly games).
3237
3238=over 4
3239
3240=item The winsocket select function
3241
3242The winsocket C<select> function doesn't follow POSIX in that it requires
3243socket I<handles> and not socket I<file descriptors>. This makes select
3244very inefficient, and also requires a mapping from file descriptors
3245to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>,
3246C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor
3247symbols for more info.
3248
3249The configuration for a "naked" win32 using the microsoft runtime
3250libraries and raw winsocket select is:
3251
3252 #define EV_USE_SELECT 1
3253 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3254
3255Note that winsockets handling of fd sets is O(n), so you can easily get a
3256complexity in the O(n²) range when using win32.
3257
3258=item Limited number of file descriptors
3259
3260Windows has numerous arbitrary (and low) limits on things.
3261
3262Early versions of winsocket's select only supported waiting for a maximum
3263of C<64> handles (probably owning to the fact that all windows kernels
3264can only wait for C<64> things at the same time internally; microsoft
3265recommends spawning a chain of threads and wait for 63 handles and the
3266previous thread in each. Great).
3267
3268Newer versions support more handles, but you need to define C<FD_SETSIZE>
3269to some high number (e.g. C<2048>) before compiling the winsocket select
3270call (which might be in libev or elsewhere, for example, perl does its own
3271select emulation on windows).
3272
3273Another limit is the number of file descriptors in the microsoft runtime
3274libraries, which by default is C<64> (there must be a hidden I<64> fetish
3275or something like this inside microsoft). You can increase this by calling
3276C<_setmaxstdio>, which can increase this limit to C<2048> (another
3277arbitrary limit), but is broken in many versions of the microsoft runtime
3278libraries.
3279
3280This might get you to about C<512> or C<2048> sockets (depending on
3281windows version and/or the phase of the moon). To get more, you need to
3282wrap all I/O functions and provide your own fd management, but the cost of
3283calling select (O(n²)) will likely make this unworkable.
3284
3285=back
3286
3287
3288=head1 PORTABILITY REQUIREMENTS
3289
3290In addition to a working ISO-C implementation, libev relies on a few
3291additional extensions:
3292
3293=over 4
3294
3295=item C<sig_atomic_t volatile> must be thread-atomic as well
3296
3297The type C<sig_atomic_t volatile> (or whatever is defined as
3298C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different
3299threads. This is not part of the specification for C<sig_atomic_t>, but is
3300believed to be sufficiently portable.
3301
3302=item C<sigprocmask> must work in a threaded environment
3303
3304Libev uses C<sigprocmask> to temporarily block signals. This is not
3305allowed in a threaded program (C<pthread_sigmask> has to be used). Typical
3306pthread implementations will either allow C<sigprocmask> in the "main
3307thread" or will block signals process-wide, both behaviours would
3308be compatible with libev. Interaction between C<sigprocmask> and
3309C<pthread_sigmask> could complicate things, however.
3310
3311The most portable way to handle signals is to block signals in all threads
3312except the initial one, and run the default loop in the initial thread as
3313well.
3314
3315=item C<long> must be large enough for common memory allocation sizes
3316
3317To improve portability and simplify using libev, libev uses C<long>
3318internally instead of C<size_t> when allocating its data structures. On
3319non-POSIX systems (Microsoft...) this might be unexpectedly low, but
3320is still at least 31 bits everywhere, which is enough for hundreds of
3321millions of watchers.
3322
3323=item C<double> must hold a time value in seconds with enough accuracy
3324
3325The type C<double> is used to represent timestamps. It is required to
3326have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3327enough for at least into the year 4000. This requirement is fulfilled by
3328implementations implementing IEEE 754 (basically all existing ones).
3329
3330=back
3331
3332If you know of other additional requirements drop me a note.
3333
3334
2451=head1 AUTHOR 3335=head1 AUTHOR
2452 3336
2453Marc Lehmann <libev@schmorp.de>. 3337Marc Lehmann <libev@schmorp.de>.
2454 3338

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines