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

Comparing libev/ev.pod (file contents):
Revision 1.111 by root, Tue Dec 25 18:01:20 2007 UTC vs.
Revision 1.216 by root, Thu Nov 13 15:55:38 2008 UTC

2 2
3libev - a high performance full-featured event loop written in C 3libev - a high performance full-featured event loop written in C
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 #include <ev.h> 7 #include <ev.h>
8 8
9=head2 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
16 /* called when data readable on stdin */ 19 // all watcher callbacks have a similar signature
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_ 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_ 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 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://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
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 occurring), 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
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=head2 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<ev_loop *>) will not have
109this argument.
95 110
96=head2 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 some floatingpoint value. Unlike the name 118it, you should treat it as some floating point value. Unlike the name
104component C<stamp> might indicate, it is also used for time differences 119component C<stamp> might indicate, it is also used for time differences
105throughout libev. 120throughout libev.
121
122=head1 ERROR HANDLING
123
124Libev knows three classes of errors: operating system errors, usage errors
125and internal errors (bugs).
126
127When libev catches an operating system error it cannot handle (for example
128a system call indicating a condition libev cannot fix), it calls the callback
129set via C<ev_set_syserr_cb>, which is supposed to fix the problem or
130abort. The default is to print a diagnostic message and to call C<abort
131()>.
132
133When libev detects a usage error such as a negative timer interval, then
134it will print a diagnostic message and abort (via the C<assert> mechanism,
135so C<NDEBUG> will disable this checking): these are programming errors in
136the libev caller and need to be fixed there.
137
138Libev also has a few internal error-checking C<assert>ions, and also has
139extensive consistency checking code. These do not trigger under normal
140circumstances, as they indicate either a bug in libev or worse.
141
106 142
107=head1 GLOBAL FUNCTIONS 143=head1 GLOBAL FUNCTIONS
108 144
109These functions can be called anytime, even before initialising the 145These functions can be called anytime, even before initialising the
110library in any way. 146library in any way.
119 155
120=item ev_sleep (ev_tstamp interval) 156=item ev_sleep (ev_tstamp interval)
121 157
122Sleep for the given interval: The current thread will be blocked until 158Sleep for the given interval: The current thread will be blocked until
123either it is interrupted or the given time interval has passed. Basically 159either it is interrupted or the given time interval has passed. Basically
124this is a subsecond-resolution C<sleep ()>. 160this is a sub-second-resolution C<sleep ()>.
125 161
126=item int ev_version_major () 162=item int ev_version_major ()
127 163
128=item int ev_version_minor () 164=item int ev_version_minor ()
129 165
142not a problem. 178not a problem.
143 179
144Example: Make sure we haven't accidentally been linked against the wrong 180Example: Make sure we haven't accidentally been linked against the wrong
145version. 181version.
146 182
147 assert (("libev version mismatch", 183 assert (("libev version mismatch",
148 ev_version_major () == EV_VERSION_MAJOR 184 ev_version_major () == EV_VERSION_MAJOR
149 && ev_version_minor () >= EV_VERSION_MINOR)); 185 && ev_version_minor () >= EV_VERSION_MINOR));
150 186
151=item unsigned int ev_supported_backends () 187=item unsigned int ev_supported_backends ()
152 188
153Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*> 189Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
154value) compiled into this binary of libev (independent of their 190value) compiled into this binary of libev (independent of their
156a description of the set values. 192a description of the set values.
157 193
158Example: make sure we have the epoll method, because yeah this is cool and 194Example: make sure we have the epoll method, because yeah this is cool and
159a must have and can we have a torrent of it please!!!11 195a must have and can we have a torrent of it please!!!11
160 196
161 assert (("sorry, no epoll, no sex", 197 assert (("sorry, no epoll, no sex",
162 ev_supported_backends () & EVBACKEND_EPOLL)); 198 ev_supported_backends () & EVBACKEND_EPOLL));
163 199
164=item unsigned int ev_recommended_backends () 200=item unsigned int ev_recommended_backends ()
165 201
166Return the set of all backends compiled into this binary of libev and also 202Return the set of all backends compiled into this binary of libev and also
167recommended for this platform. This set is often smaller than the one 203recommended for this platform. This set is often smaller than the one
168returned by C<ev_supported_backends>, as for example kqueue is broken on 204returned by C<ev_supported_backends>, as for example kqueue is broken on
169most BSDs and will not be autodetected unless you explicitly request it 205most BSDs and will not be auto-detected unless you explicitly request it
170(assuming you know what you are doing). This is the set of backends that 206(assuming you know what you are doing). This is the set of backends that
171libev will probe for if you specify no backends explicitly. 207libev will probe for if you specify no backends explicitly.
172 208
173=item unsigned int ev_embeddable_backends () 209=item unsigned int ev_embeddable_backends ()
174 210
178C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
179recommended ones. 215recommended ones.
180 216
181See the description of C<ev_embed> watchers for more info. 217See the description of C<ev_embed> watchers for more info.
182 218
183=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
184 220
185Sets the allocation function to use (the prototype is similar - the 221Sets the allocation function to use (the prototype is similar - the
186semantics is identical - to the realloc C function). It is used to 222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
187allocate and free memory (no surprises here). If it returns zero when 223used to allocate and free memory (no surprises here). If it returns zero
188memory needs to be allocated, the library might abort or take some 224when memory needs to be allocated (C<size != 0>), the library might abort
189potentially destructive action. The default is your system realloc 225or take some potentially destructive action.
190function. 226
227Since some systems (at least OpenBSD and Darwin) fail to implement
228correct C<realloc> semantics, libev will use a wrapper around the system
229C<realloc> and C<free> functions by default.
191 230
192You could override this function in high-availability programs to, say, 231You could override this function in high-availability programs to, say,
193free some memory if it cannot allocate memory, to use a special allocator, 232free some memory if it cannot allocate memory, to use a special allocator,
194or even to sleep a while and retry until some memory is available. 233or even to sleep a while and retry until some memory is available.
195 234
196Example: Replace the libev allocator with one that waits a bit and then 235Example: Replace the libev allocator with one that waits a bit and then
197retries). 236retries (example requires a standards-compliant C<realloc>).
198 237
199 static void * 238 static void *
200 persistent_realloc (void *ptr, size_t size) 239 persistent_realloc (void *ptr, size_t size)
201 { 240 {
202 for (;;) 241 for (;;)
211 } 250 }
212 251
213 ... 252 ...
214 ev_set_allocator (persistent_realloc); 253 ev_set_allocator (persistent_realloc);
215 254
216=item ev_set_syserr_cb (void (*cb)(const char *msg)); 255=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
217 256
218Set the callback function to call on a retryable syscall error (such 257Set the callback function to call on a retryable system call error (such
219as failed select, poll, epoll_wait). The message is a printable string 258as failed select, poll, epoll_wait). The message is a printable string
220indicating the system call or subsystem causing the problem. If this 259indicating the system call or subsystem causing the problem. If this
221callback is set, then libev will expect it to remedy the sitution, no 260callback is set, then libev will expect it to remedy the situation, no
222matter what, when it returns. That is, libev will generally retry the 261matter what, when it returns. That is, libev will generally retry the
223requested operation, or, if the condition doesn't go away, do bad stuff 262requested operation, or, if the condition doesn't go away, do bad stuff
224(such as abort). 263(such as abort).
225 264
226Example: This is basically the same thing that libev does internally, too. 265Example: This is basically the same thing that libev does internally, too.
237 276
238=back 277=back
239 278
240=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
241 280
242An event loop is described by a C<struct ev_loop *>. The library knows two 281An event loop is described by a C<struct ev_loop *> (the C<struct>
243types of such loops, the I<default> loop, which supports signals and child 282is I<not> optional in this case, as there is also an C<ev_loop>
244events, and dynamically created loops which do not. 283I<function>).
245 284
246If you use threads, a common model is to run the default event loop 285The library knows two types of such loops, the I<default> loop, which
247in your main thread (or in a separate thread) and for each thread you 286supports signals and child events, and dynamically created loops which do
248create, you also create another event loop. Libev itself does no locking 287not.
249whatsoever, so if you mix calls to the same event loop in different
250threads, make sure you lock (this is usually a bad idea, though, even if
251done correctly, because it's hideous and inefficient).
252 288
253=over 4 289=over 4
254 290
255=item struct ev_loop *ev_default_loop (unsigned int flags) 291=item struct ev_loop *ev_default_loop (unsigned int flags)
256 292
260flags. If that is troubling you, check C<ev_backend ()> afterwards). 296flags. If that is troubling you, check C<ev_backend ()> afterwards).
261 297
262If you don't know what event loop to use, use the one returned from this 298If you don't know what event loop to use, use the one returned from this
263function. 299function.
264 300
301Note that this function is I<not> thread-safe, so if you want to use it
302from multiple threads, you have to lock (note also that this is unlikely,
303as loops cannot be shared easily between threads anyway).
304
305The default loop is the only loop that can handle C<ev_signal> and
306C<ev_child> watchers, and to do this, it always registers a handler
307for C<SIGCHLD>. If this is a problem for your application you can either
308create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
309can simply overwrite the C<SIGCHLD> signal handler I<after> calling
310C<ev_default_init>.
311
265The flags argument can be used to specify special behaviour or specific 312The flags argument can be used to specify special behaviour or specific
266backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>). 313backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
267 314
268The following flags are supported: 315The following flags are supported:
269 316
274The default flags value. Use this if you have no clue (it's the right 321The default flags value. Use this if you have no clue (it's the right
275thing, believe me). 322thing, believe me).
276 323
277=item C<EVFLAG_NOENV> 324=item C<EVFLAG_NOENV>
278 325
279If this flag bit is ored into the flag value (or the program runs setuid 326If this flag bit is or'ed into the flag value (or the program runs setuid
280or setgid) then libev will I<not> look at the environment variable 327or setgid) then libev will I<not> look at the environment variable
281C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 328C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
282override the flags completely if it is found in the environment. This is 329override the flags completely if it is found in the environment. This is
283useful to try out specific backends to test their performance, or to work 330useful to try out specific backends to test their performance, or to work
284around bugs. 331around bugs.
290enabling this flag. 337enabling this flag.
291 338
292This works by calling C<getpid ()> on every iteration of the loop, 339This works by calling C<getpid ()> on every iteration of the loop,
293and thus this might slow down your event loop if you do a lot of loop 340and thus this might slow down your event loop if you do a lot of loop
294iterations and little real work, but is usually not noticeable (on my 341iterations and little real work, but is usually not noticeable (on my
295Linux system for example, C<getpid> is actually a simple 5-insn sequence 342GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
296without a syscall and thus I<very> fast, but my Linux system also has 343without a system call and thus I<very> fast, but my GNU/Linux system also has
297C<pthread_atfork> which is even faster). 344C<pthread_atfork> which is even faster).
298 345
299The big advantage of this flag is that you can forget about fork (and 346The big advantage of this flag is that you can forget about fork (and
300forget about forgetting to tell libev about forking) when you use this 347forget about forgetting to tell libev about forking) when you use this
301flag. 348flag.
302 349
303This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS> 350This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
304environment variable. 351environment variable.
305 352
306=item C<EVBACKEND_SELECT> (value 1, portable select backend) 353=item C<EVBACKEND_SELECT> (value 1, portable select backend)
307 354
308This is your standard select(2) backend. Not I<completely> standard, as 355This is your standard select(2) backend. Not I<completely> standard, as
310but if that fails, expect a fairly low limit on the number of fds when 357but if that fails, expect a fairly low limit on the number of fds when
311using this backend. It doesn't scale too well (O(highest_fd)), but its 358using this backend. It doesn't scale too well (O(highest_fd)), but its
312usually the fastest backend for a low number of (low-numbered :) fds. 359usually the fastest backend for a low number of (low-numbered :) fds.
313 360
314To get good performance out of this backend you need a high amount of 361To get good performance out of this backend you need a high amount of
315parallelity (most of the file descriptors should be busy). If you are 362parallelism (most of the file descriptors should be busy). If you are
316writing a server, you should C<accept ()> in a loop to accept as many 363writing a server, you should C<accept ()> in a loop to accept as many
317connections as possible during one iteration. You might also want to have 364connections as possible during one iteration. You might also want to have
318a look at C<ev_set_io_collect_interval ()> to increase the amount of 365a look at C<ev_set_io_collect_interval ()> to increase the amount of
319readyness notifications you get per iteration. 366readiness notifications you get per iteration.
367
368This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the
369C<writefds> set (and to work around Microsoft Windows bugs, also onto the
370C<exceptfds> set on that platform).
320 371
321=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 372=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
322 373
323And this is your standard poll(2) backend. It's more complicated 374And this is your standard poll(2) backend. It's more complicated
324than select, but handles sparse fds better and has no artificial 375than select, but handles sparse fds better and has no artificial
325limit on the number of fds you can use (except it will slow down 376limit on the number of fds you can use (except it will slow down
326considerably with a lot of inactive fds). It scales similarly to select, 377considerably with a lot of inactive fds). It scales similarly to select,
327i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for 378i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
328performance tips. 379performance tips.
329 380
381This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
382C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
383
330=item C<EVBACKEND_EPOLL> (value 4, Linux) 384=item C<EVBACKEND_EPOLL> (value 4, Linux)
331 385
332For few fds, this backend is a bit little slower than poll and select, 386For few fds, this backend is a bit little slower than poll and select,
333but it scales phenomenally better. While poll and select usually scale 387but it scales phenomenally better. While poll and select usually scale
334like O(total_fds) where n is the total number of fds (or the highest fd), 388like O(total_fds) where n is the total number of fds (or the highest fd),
335epoll scales either O(1) or O(active_fds). The epoll design has a number 389epoll scales either O(1) or O(active_fds).
336of shortcomings, such as silently dropping events in some hard-to-detect 390
337cases and rewiring a syscall per fd change, no fork support and bad 391The epoll mechanism deserves honorable mention as the most misdesigned
338support for dup. 392of the more advanced event mechanisms: mere annoyances include silently
393dropping file descriptors, requiring a system call per change per file
394descriptor (and unnecessary guessing of parameters), problems with dup and
395so on. The biggest issue is fork races, however - if a program forks then
396I<both> parent and child process have to recreate the epoll set, which can
397take considerable time (one syscall per file descriptor) and is of course
398hard to detect.
399
400Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
401of course I<doesn't>, and epoll just loves to report events for totally
402I<different> file descriptors (even already closed ones, so one cannot
403even remove them from the set) than registered in the set (especially
404on SMP systems). Libev tries to counter these spurious notifications by
405employing an additional generation counter and comparing that against the
406events to filter out spurious ones, recreating the set when required.
339 407
340While stopping, setting and starting an I/O watcher in the same iteration 408While stopping, setting and starting an I/O watcher in the same iteration
341will result in some caching, there is still a syscall per such incident 409will result in some caching, there is still a system call per such
342(because the fd could point to a different file description now), so its 410incident (because the same I<file descriptor> could point to a different
343best to avoid that. Also, C<dup ()>'ed file descriptors might not work 411I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
344very well if you register events for both fds. 412file descriptors might not work very well if you register events for both
345 413file descriptors.
346Please note that epoll sometimes generates spurious notifications, so you
347need to use non-blocking I/O or other means to avoid blocking when no data
348(or space) is available.
349 414
350Best performance from this backend is achieved by not unregistering all 415Best performance from this backend is achieved by not unregistering all
351watchers for a file descriptor until it has been closed, if possible, i.e. 416watchers for a file descriptor until it has been closed, if possible,
352keep at least one watcher active per fd at all times. 417i.e. keep at least one watcher active per fd at all times. Stopping and
418starting a watcher (without re-setting it) also usually doesn't cause
419extra overhead. A fork can both result in spurious notifications as well
420as in libev having to destroy and recreate the epoll object, which can
421take considerable time and thus should be avoided.
353 422
423All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
424faster than epoll for maybe up to a hundred file descriptors, depending on
425the usage. So sad.
426
354While nominally embeddeble in other event loops, this feature is broken in 427While nominally embeddable in other event loops, this feature is broken in
355all kernel versions tested so far. 428all kernel versions tested so far.
429
430This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
431C<EVBACKEND_POLL>.
356 432
357=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 433=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
358 434
359Kqueue deserves special mention, as at the time of this writing, it 435Kqueue deserves special mention, as at the time of this writing, it
360was broken on all BSDs except NetBSD (usually it doesn't work reliably 436was broken on all BSDs except NetBSD (usually it doesn't work reliably
361with anything but sockets and pipes, except on Darwin, where of course 437with anything but sockets and pipes, except on Darwin, where of course
362it's completely useless). For this reason it's not being "autodetected" 438it's completely useless). Unlike epoll, however, whose brokenness
439is by design, these kqueue bugs can (and eventually will) be fixed
440without API changes to existing programs. For this reason it's not being
363unless you explicitly specify it explicitly in the flags (i.e. using 441"auto-detected" unless you explicitly specify it in the flags (i.e. using
364C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 442C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
365system like NetBSD. 443system like NetBSD.
366 444
367You still can embed kqueue into a normal poll or select backend and use it 445You still can embed kqueue into a normal poll or select backend and use it
368only for sockets (after having made sure that sockets work with kqueue on 446only for sockets (after having made sure that sockets work with kqueue on
369the target platform). See C<ev_embed> watchers for more info. 447the target platform). See C<ev_embed> watchers for more info.
370 448
371It scales in the same way as the epoll backend, but the interface to the 449It scales in the same way as the epoll backend, but the interface to the
372kernel is more efficient (which says nothing about its actual speed, of 450kernel is more efficient (which says nothing about its actual speed, of
373course). While stopping, setting and starting an I/O watcher does never 451course). While stopping, setting and starting an I/O watcher does never
374cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to 452cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
375two event changes per incident, support for C<fork ()> is very bad and it 453two event changes per incident. Support for C<fork ()> is very bad (but
376drops fds silently in similarly hard-to-detect cases. 454sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
455cases
377 456
378This backend usually performs well under most conditions. 457This backend usually performs well under most conditions.
379 458
380While nominally embeddable in other event loops, this doesn't work 459While nominally embeddable in other event loops, this doesn't work
381everywhere, so you might need to test for this. And since it is broken 460everywhere, so you might need to test for this. And since it is broken
382almost everywhere, you should only use it when you have a lot of sockets 461almost everywhere, you should only use it when you have a lot of sockets
383(for which it usually works), by embedding it into another event loop 462(for which it usually works), by embedding it into another event loop
384(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for 463(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it,
385sockets. 464using it only for sockets.
465
466This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
467C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
468C<NOTE_EOF>.
386 469
387=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 470=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
388 471
389This is not implemented yet (and might never be, unless you send me an 472This is not implemented yet (and might never be, unless you send me an
390implementation). According to reports, C</dev/poll> only supports sockets 473implementation). According to reports, C</dev/poll> only supports sockets
394=item C<EVBACKEND_PORT> (value 32, Solaris 10) 477=item C<EVBACKEND_PORT> (value 32, Solaris 10)
395 478
396This uses the Solaris 10 event port mechanism. As with everything on Solaris, 479This uses the Solaris 10 event port mechanism. As with everything on Solaris,
397it's really slow, but it still scales very well (O(active_fds)). 480it's really slow, but it still scales very well (O(active_fds)).
398 481
399Please note that solaris event ports can deliver a lot of spurious 482Please note that Solaris event ports can deliver a lot of spurious
400notifications, so you need to use non-blocking I/O or other means to avoid 483notifications, so you need to use non-blocking I/O or other means to avoid
401blocking when no data (or space) is available. 484blocking when no data (or space) is available.
402 485
403While this backend scales well, it requires one system call per active 486While this backend scales well, it requires one system call per active
404file descriptor per loop iteration. For small and medium numbers of file 487file descriptor per loop iteration. For small and medium numbers of file
405descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 488descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
406might perform better. 489might perform better.
407 490
491On the positive side, with the exception of the spurious readiness
492notifications, this backend actually performed fully to specification
493in all tests and is fully embeddable, which is a rare feat among the
494OS-specific backends (I vastly prefer correctness over speed hacks).
495
496This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
497C<EVBACKEND_POLL>.
498
408=item C<EVBACKEND_ALL> 499=item C<EVBACKEND_ALL>
409 500
410Try all backends (even potentially broken ones that wouldn't be tried 501Try all backends (even potentially broken ones that wouldn't be tried
411with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 502with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
412C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 503C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
413 504
414It is definitely not recommended to use this flag. 505It is definitely not recommended to use this flag.
415 506
416=back 507=back
417 508
418If one or more of these are ored into the flags value, then only these 509If one or more of these are or'ed into the flags value, then only these
419backends will be tried (in the reverse order as given here). If none are 510backends will be tried (in the reverse order as listed here). If none are
420specified, most compiled-in backend will be tried, usually in reverse 511specified, all backends in C<ev_recommended_backends ()> will be tried.
421order of their flag values :)
422 512
423The most typical usage is like this: 513Example: This is the most typical usage.
424 514
425 if (!ev_default_loop (0)) 515 if (!ev_default_loop (0))
426 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 516 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
427 517
428Restrict libev to the select and poll backends, and do not allow 518Example: Restrict libev to the select and poll backends, and do not allow
429environment settings to be taken into account: 519environment settings to be taken into account:
430 520
431 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); 521 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
432 522
433Use whatever libev has to offer, but make sure that kqueue is used if 523Example: Use whatever libev has to offer, but make sure that kqueue is
434available (warning, breaks stuff, best use only with your own private 524used if available (warning, breaks stuff, best use only with your own
435event loop and only if you know the OS supports your types of fds): 525private event loop and only if you know the OS supports your types of
526fds):
436 527
437 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 528 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
438 529
439=item struct ev_loop *ev_loop_new (unsigned int flags) 530=item struct ev_loop *ev_loop_new (unsigned int flags)
440 531
441Similar to C<ev_default_loop>, but always creates a new event loop that is 532Similar to C<ev_default_loop>, but always creates a new event loop that is
442always distinct from the default loop. Unlike the default loop, it cannot 533always distinct from the default loop. Unlike the default loop, it cannot
443handle signal and child watchers, and attempts to do so will be greeted by 534handle signal and child watchers, and attempts to do so will be greeted by
444undefined behaviour (or a failed assertion if assertions are enabled). 535undefined behaviour (or a failed assertion if assertions are enabled).
445 536
537Note that this function I<is> thread-safe, and the recommended way to use
538libev with threads is indeed to create one loop per thread, and using the
539default loop in the "main" or "initial" thread.
540
446Example: Try to create a event loop that uses epoll and nothing else. 541Example: Try to create a event loop that uses epoll and nothing else.
447 542
448 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 543 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
449 if (!epoller) 544 if (!epoller)
450 fatal ("no epoll found here, maybe it hides under your chair"); 545 fatal ("no epoll found here, maybe it hides under your chair");
451 546
452=item ev_default_destroy () 547=item ev_default_destroy ()
453 548
454Destroys the default loop again (frees all memory and kernel state 549Destroys the default loop again (frees all memory and kernel state
455etc.). None of the active event watchers will be stopped in the normal 550etc.). None of the active event watchers will be stopped in the normal
456sense, so e.g. C<ev_is_active> might still return true. It is your 551sense, so e.g. C<ev_is_active> might still return true. It is your
457responsibility to either stop all watchers cleanly yoursef I<before> 552responsibility to either stop all watchers cleanly yourself I<before>
458calling this function, or cope with the fact afterwards (which is usually 553calling this function, or cope with the fact afterwards (which is usually
459the easiest thing, you can just ignore the watchers and/or C<free ()> them 554the easiest thing, you can just ignore the watchers and/or C<free ()> them
460for example). 555for example).
461 556
462Note that certain global state, such as signal state, will not be freed by 557Note that certain global state, such as signal state (and installed signal
463this function, and related watchers (such as signal and child watchers) 558handlers), will not be freed by this function, and related watchers (such
464would need to be stopped manually. 559as signal and child watchers) would need to be stopped manually.
465 560
466In general it is not advisable to call this function except in the 561In general it is not advisable to call this function except in the
467rare occasion where you really need to free e.g. the signal handling 562rare occasion where you really need to free e.g. the signal handling
468pipe fds. If you need dynamically allocated loops it is better to use 563pipe fds. If you need dynamically allocated loops it is better to use
469C<ev_loop_new> and C<ev_loop_destroy>). 564C<ev_loop_new> and C<ev_loop_destroy>).
473Like C<ev_default_destroy>, but destroys an event loop created by an 568Like C<ev_default_destroy>, but destroys an event loop created by an
474earlier call to C<ev_loop_new>. 569earlier call to C<ev_loop_new>.
475 570
476=item ev_default_fork () 571=item ev_default_fork ()
477 572
573This function sets a flag that causes subsequent C<ev_loop> iterations
478This function reinitialises the kernel state for backends that have 574to reinitialise the kernel state for backends that have one. Despite the
479one. Despite the name, you can call it anytime, but it makes most sense 575name, you can call it anytime, but it makes most sense after forking, in
480after forking, in either the parent or child process (or both, but that 576the child process (or both child and parent, but that again makes little
481again makes little sense). 577sense). You I<must> call it in the child before using any of the libev
578functions, and it will only take effect at the next C<ev_loop> iteration.
482 579
483You I<must> call this function in the child process after forking if and 580On the other hand, you only need to call this function in the child
484only if you want to use the event library in both processes. If you just 581process if and only if you want to use the event library in the child. If
485fork+exec, you don't have to call it. 582you just fork+exec, you don't have to call it at all.
486 583
487The function itself is quite fast and it's usually not a problem to call 584The function itself is quite fast and it's usually not a problem to call
488it just in case after a fork. To make this easy, the function will fit in 585it just in case after a fork. To make this easy, the function will fit in
489quite nicely into a call to C<pthread_atfork>: 586quite nicely into a call to C<pthread_atfork>:
490 587
491 pthread_atfork (0, 0, ev_default_fork); 588 pthread_atfork (0, 0, ev_default_fork);
492 589
493At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
494without calling this function, so if you force one of those backends you
495do not need to care.
496
497=item ev_loop_fork (loop) 590=item ev_loop_fork (loop)
498 591
499Like C<ev_default_fork>, but acts on an event loop created by 592Like C<ev_default_fork>, but acts on an event loop created by
500C<ev_loop_new>. Yes, you have to call this on every allocated event loop 593C<ev_loop_new>. Yes, you have to call this on every allocated event loop
501after fork, and how you do this is entirely your own problem. 594after fork that you want to re-use in the child, and how you do this is
595entirely your own problem.
596
597=item int ev_is_default_loop (loop)
598
599Returns true when the given loop is, in fact, the default loop, and false
600otherwise.
502 601
503=item unsigned int ev_loop_count (loop) 602=item unsigned int ev_loop_count (loop)
504 603
505Returns the count of loop iterations for the loop, which is identical to 604Returns the count of loop iterations for the loop, which is identical to
506the number of times libev did poll for new events. It starts at C<0> and 605the number of times libev did poll for new events. It starts at C<0> and
521received events and started processing them. This timestamp does not 620received events and started processing them. This timestamp does not
522change as long as callbacks are being processed, and this is also the base 621change as long as callbacks are being processed, and this is also the base
523time used for relative timers. You can treat it as the timestamp of the 622time used for relative timers. You can treat it as the timestamp of the
524event occurring (or more correctly, libev finding out about it). 623event occurring (or more correctly, libev finding out about it).
525 624
625=item ev_now_update (loop)
626
627Establishes the current time by querying the kernel, updating the time
628returned by C<ev_now ()> in the progress. This is a costly operation and
629is usually done automatically within C<ev_loop ()>.
630
631This function is rarely useful, but when some event callback runs for a
632very long time without entering the event loop, updating libev's idea of
633the current time is a good idea.
634
635See also "The special problem of time updates" in the C<ev_timer> section.
636
526=item ev_loop (loop, int flags) 637=item ev_loop (loop, int flags)
527 638
528Finally, this is it, the event handler. This function usually is called 639Finally, this is it, the event handler. This function usually is called
529after you initialised all your watchers and you want to start handling 640after you initialised all your watchers and you want to start handling
530events. 641events.
532If the flags argument is specified as C<0>, it will not return until 643If the flags argument is specified as C<0>, it will not return until
533either no event watchers are active anymore or C<ev_unloop> was called. 644either no event watchers are active anymore or C<ev_unloop> was called.
534 645
535Please note that an explicit C<ev_unloop> is usually better than 646Please note that an explicit C<ev_unloop> is usually better than
536relying on all watchers to be stopped when deciding when a program has 647relying on all watchers to be stopped when deciding when a program has
537finished (especially in interactive programs), but having a program that 648finished (especially in interactive programs), but having a program
538automatically loops as long as it has to and no longer by virtue of 649that automatically loops as long as it has to and no longer by virtue
539relying on its watchers stopping correctly is a thing of beauty. 650of relying on its watchers stopping correctly, that is truly a thing of
651beauty.
540 652
541A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 653A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
542those events and any outstanding ones, but will not block your process in 654those events and any already outstanding ones, but will not block your
543case there are no events and will return after one iteration of the loop. 655process in case there are no events and will return after one iteration of
656the loop.
544 657
545A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 658A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
546neccessary) and will handle those and any outstanding ones. It will block 659necessary) and will handle those and any already outstanding ones. It
547your process until at least one new event arrives, and will return after 660will block your process until at least one new event arrives (which could
548one iteration of the loop. This is useful if you are waiting for some 661be an event internal to libev itself, so there is no guarantee that a
549external event in conjunction with something not expressible using other 662user-registered callback will be called), and will return after one
663iteration of the loop.
664
665This is useful if you are waiting for some external event in conjunction
666with something not expressible using other libev watchers (i.e. "roll your
550libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 667own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
551usually a better approach for this kind of thing. 668usually a better approach for this kind of thing.
552 669
553Here are the gory details of what C<ev_loop> does: 670Here are the gory details of what C<ev_loop> does:
554 671
555 - Before the first iteration, call any pending watchers. 672 - Before the first iteration, call any pending watchers.
556 * If there are no active watchers (reference count is zero), return. 673 * If EVFLAG_FORKCHECK was used, check for a fork.
557 - Queue all prepare watchers and then call all outstanding watchers. 674 - If a fork was detected (by any means), queue and call all fork watchers.
675 - Queue and call all prepare watchers.
558 - If we have been forked, recreate the kernel state. 676 - If we have been forked, detach and recreate the kernel state
677 as to not disturb the other process.
559 - Update the kernel state with all outstanding changes. 678 - Update the kernel state with all outstanding changes.
560 - Update the "event loop time". 679 - Update the "event loop time" (ev_now ()).
561 - Calculate for how long to block. 680 - Calculate for how long to sleep or block, if at all
681 (active idle watchers, EVLOOP_NONBLOCK or not having
682 any active watchers at all will result in not sleeping).
683 - Sleep if the I/O and timer collect interval say so.
562 - Block the process, waiting for any events. 684 - Block the process, waiting for any events.
563 - Queue all outstanding I/O (fd) events. 685 - Queue all outstanding I/O (fd) events.
564 - Update the "event loop time" and do time jump handling. 686 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
565 - Queue all outstanding timers. 687 - Queue all expired timers.
566 - Queue all outstanding periodics. 688 - Queue all expired periodics.
567 - If no events are pending now, queue all idle watchers. 689 - Unless any events are pending now, queue all idle watchers.
568 - Queue all check watchers. 690 - Queue all check watchers.
569 - Call all queued watchers in reverse order (i.e. check watchers first). 691 - Call all queued watchers in reverse order (i.e. check watchers first).
570 Signals and child watchers are implemented as I/O watchers, and will 692 Signals and child watchers are implemented as I/O watchers, and will
571 be handled here by queueing them when their watcher gets executed. 693 be handled here by queueing them when their watcher gets executed.
572 - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 694 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
573 were used, return, otherwise continue with step *. 695 were used, or there are no active watchers, return, otherwise
696 continue with step *.
574 697
575Example: Queue some jobs and then loop until no events are outsanding 698Example: Queue some jobs and then loop until no events are outstanding
576anymore. 699anymore.
577 700
578 ... queue jobs here, make sure they register event watchers as long 701 ... queue jobs here, make sure they register event watchers as long
579 ... as they still have work to do (even an idle watcher will do..) 702 ... as they still have work to do (even an idle watcher will do..)
580 ev_loop (my_loop, 0); 703 ev_loop (my_loop, 0);
581 ... jobs done. yeah! 704 ... jobs done or somebody called unloop. yeah!
582 705
583=item ev_unloop (loop, how) 706=item ev_unloop (loop, how)
584 707
585Can be used to make a call to C<ev_loop> return early (but only after it 708Can be used to make a call to C<ev_loop> return early (but only after it
586has processed all outstanding events). The C<how> argument must be either 709has processed all outstanding events). The C<how> argument must be either
587C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 710C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
588C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 711C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
589 712
713This "unloop state" will be cleared when entering C<ev_loop> again.
714
715It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls.
716
590=item ev_ref (loop) 717=item ev_ref (loop)
591 718
592=item ev_unref (loop) 719=item ev_unref (loop)
593 720
594Ref/unref can be used to add or remove a reference count on the event 721Ref/unref can be used to add or remove a reference count on the event
595loop: Every watcher keeps one reference, and as long as the reference 722loop: Every watcher keeps one reference, and as long as the reference
596count is nonzero, C<ev_loop> will not return on its own. If you have 723count is nonzero, C<ev_loop> will not return on its own.
724
597a watcher you never unregister that should not keep C<ev_loop> from 725If you have a watcher you never unregister that should not keep C<ev_loop>
598returning, ev_unref() after starting, and ev_ref() before stopping it. For 726from returning, call ev_unref() after starting, and ev_ref() before
727stopping it.
728
599example, libev itself uses this for its internal signal pipe: It is not 729As an example, libev itself uses this for its internal signal pipe: It is
600visible to the libev user and should not keep C<ev_loop> from exiting if 730not visible to the libev user and should not keep C<ev_loop> from exiting
601no event watchers registered by it are active. It is also an excellent 731if no event watchers registered by it are active. It is also an excellent
602way to do this for generic recurring timers or from within third-party 732way to do this for generic recurring timers or from within third-party
603libraries. Just remember to I<unref after start> and I<ref before stop>. 733libraries. Just remember to I<unref after start> and I<ref before stop>
734(but only if the watcher wasn't active before, or was active before,
735respectively).
604 736
605Example: Create a signal watcher, but keep it from keeping C<ev_loop> 737Example: Create a signal watcher, but keep it from keeping C<ev_loop>
606running when nothing else is active. 738running when nothing else is active.
607 739
608 struct ev_signal exitsig; 740 ev_signal exitsig;
609 ev_signal_init (&exitsig, sig_cb, SIGINT); 741 ev_signal_init (&exitsig, sig_cb, SIGINT);
610 ev_signal_start (loop, &exitsig); 742 ev_signal_start (loop, &exitsig);
611 evf_unref (loop); 743 evf_unref (loop);
612 744
613Example: For some weird reason, unregister the above signal handler again. 745Example: For some weird reason, unregister the above signal handler again.
614 746
615 ev_ref (loop); 747 ev_ref (loop);
616 ev_signal_stop (loop, &exitsig); 748 ev_signal_stop (loop, &exitsig);
617 749
618=item ev_set_io_collect_interval (loop, ev_tstamp interval) 750=item ev_set_io_collect_interval (loop, ev_tstamp interval)
619 751
620=item ev_set_timeout_collect_interval (loop, ev_tstamp interval) 752=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
621 753
622These advanced functions influence the time that libev will spend waiting 754These advanced functions influence the time that libev will spend waiting
623for events. Both are by default C<0>, meaning that libev will try to 755for events. Both time intervals are by default C<0>, meaning that libev
624invoke timer/periodic callbacks and I/O callbacks with minimum latency. 756will try to invoke timer/periodic callbacks and I/O callbacks with minimum
757latency.
625 758
626Setting these to a higher value (the C<interval> I<must> be >= C<0>) 759Setting these to a higher value (the C<interval> I<must> be >= C<0>)
627allows libev to delay invocation of I/O and timer/periodic callbacks to 760allows libev to delay invocation of I/O and timer/periodic callbacks
628increase efficiency of loop iterations. 761to increase efficiency of loop iterations (or to increase power-saving
762opportunities).
629 763
630The background is that sometimes your program runs just fast enough to 764The idea is that sometimes your program runs just fast enough to handle
631handle one (or very few) event(s) per loop iteration. While this makes 765one (or very few) event(s) per loop iteration. While this makes the
632the program responsive, it also wastes a lot of CPU time to poll for new 766program responsive, it also wastes a lot of CPU time to poll for new
633events, especially with backends like C<select ()> which have a high 767events, especially with backends like C<select ()> which have a high
634overhead for the actual polling but can deliver many events at once. 768overhead for the actual polling but can deliver many events at once.
635 769
636By setting a higher I<io collect interval> you allow libev to spend more 770By setting a higher I<io collect interval> you allow libev to spend more
637time collecting I/O events, so you can handle more events per iteration, 771time collecting I/O events, so you can handle more events per iteration,
639C<ev_timer>) will be not affected. Setting this to a non-null value will 773C<ev_timer>) will be not affected. Setting this to a non-null value will
640introduce an additional C<ev_sleep ()> call into most loop iterations. 774introduce an additional C<ev_sleep ()> call into most loop iterations.
641 775
642Likewise, by setting a higher I<timeout collect interval> you allow libev 776Likewise, by setting a higher I<timeout collect interval> you allow libev
643to spend more time collecting timeouts, at the expense of increased 777to spend more time collecting timeouts, at the expense of increased
644latency (the watcher callback will be called later). C<ev_io> watchers 778latency/jitter/inexactness (the watcher callback will be called
645will not be affected. Setting this to a non-null value will not introduce 779later). C<ev_io> watchers will not be affected. Setting this to a non-null
646any overhead in libev. 780value will not introduce any overhead in libev.
647 781
648Many (busy) programs can usually benefit by setting the io collect 782Many (busy) programs can usually benefit by setting the I/O collect
649interval to a value near C<0.1> or so, which is often enough for 783interval to a value near C<0.1> or so, which is often enough for
650interactive servers (of course not for games), likewise for timeouts. It 784interactive servers (of course not for games), likewise for timeouts. It
651usually doesn't make much sense to set it to a lower value than C<0.01>, 785usually doesn't make much sense to set it to a lower value than C<0.01>,
652as this approsaches the timing granularity of most systems. 786as this approaches the timing granularity of most systems.
787
788Setting the I<timeout collect interval> can improve the opportunity for
789saving power, as the program will "bundle" timer callback invocations that
790are "near" in time together, by delaying some, thus reducing the number of
791times the process sleeps and wakes up again. Another useful technique to
792reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
793they fire on, say, one-second boundaries only.
794
795=item ev_loop_verify (loop)
796
797This function only does something when C<EV_VERIFY> support has been
798compiled in, which is the default for non-minimal builds. It tries to go
799through all internal structures and checks them for validity. If anything
800is found to be inconsistent, it will print an error message to standard
801error and call C<abort ()>.
802
803This can be used to catch bugs inside libev itself: under normal
804circumstances, this function will never abort as of course libev keeps its
805data structures consistent.
653 806
654=back 807=back
655 808
656 809
657=head1 ANATOMY OF A WATCHER 810=head1 ANATOMY OF A WATCHER
811
812In the following description, uppercase C<TYPE> in names stands for the
813watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
814watchers and C<ev_io_start> for I/O watchers.
658 815
659A watcher is a structure that you create and register to record your 816A watcher is a structure that you create and register to record your
660interest in some event. For instance, if you want to wait for STDIN to 817interest in some event. For instance, if you want to wait for STDIN to
661become readable, you would create an C<ev_io> watcher for that: 818become readable, you would create an C<ev_io> watcher for that:
662 819
663 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 820 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
664 { 821 {
665 ev_io_stop (w); 822 ev_io_stop (w);
666 ev_unloop (loop, EVUNLOOP_ALL); 823 ev_unloop (loop, EVUNLOOP_ALL);
667 } 824 }
668 825
669 struct ev_loop *loop = ev_default_loop (0); 826 struct ev_loop *loop = ev_default_loop (0);
827
670 struct ev_io stdin_watcher; 828 ev_io stdin_watcher;
829
671 ev_init (&stdin_watcher, my_cb); 830 ev_init (&stdin_watcher, my_cb);
672 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 831 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
673 ev_io_start (loop, &stdin_watcher); 832 ev_io_start (loop, &stdin_watcher);
833
674 ev_loop (loop, 0); 834 ev_loop (loop, 0);
675 835
676As you can see, you are responsible for allocating the memory for your 836As you can see, you are responsible for allocating the memory for your
677watcher structures (and it is usually a bad idea to do this on the stack, 837watcher structures (and it is I<usually> a bad idea to do this on the
678although this can sometimes be quite valid). 838stack).
839
840Each watcher has an associated watcher structure (called C<struct ev_TYPE>
841or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
679 842
680Each watcher structure must be initialised by a call to C<ev_init 843Each watcher structure must be initialised by a call to C<ev_init
681(watcher *, callback)>, which expects a callback to be provided. This 844(watcher *, callback)>, which expects a callback to be provided. This
682callback gets invoked each time the event occurs (or, in the case of io 845callback gets invoked each time the event occurs (or, in the case of I/O
683watchers, each time the event loop detects that the file descriptor given 846watchers, each time the event loop detects that the file descriptor given
684is readable and/or writable). 847is readable and/or writable).
685 848
686Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 849Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
687with arguments specific to this watcher type. There is also a macro 850macro to configure it, with arguments specific to the watcher type. There
688to combine initialisation and setting in one call: C<< ev_<type>_init 851is also a macro to combine initialisation and setting in one call: C<<
689(watcher *, callback, ...) >>. 852ev_TYPE_init (watcher *, callback, ...) >>.
690 853
691To make the watcher actually watch out for events, you have to start it 854To make the watcher actually watch out for events, you have to start it
692with a watcher-specific start function (C<< ev_<type>_start (loop, watcher 855with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
693*) >>), and you can stop watching for events at any time by calling the 856*) >>), and you can stop watching for events at any time by calling the
694corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 857corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
695 858
696As long as your watcher is active (has been started but not stopped) you 859As long as your watcher is active (has been started but not stopped) you
697must not touch the values stored in it. Most specifically you must never 860must not touch the values stored in it. Most specifically you must never
698reinitialise it or call its C<set> macro. 861reinitialise it or call its C<ev_TYPE_set> macro.
699 862
700Each and every callback receives the event loop pointer as first, the 863Each and every callback receives the event loop pointer as first, the
701registered watcher structure as second, and a bitset of received events as 864registered watcher structure as second, and a bitset of received events as
702third argument. 865third argument.
703 866
757=item C<EV_FORK> 920=item C<EV_FORK>
758 921
759The event loop has been resumed in the child process after fork (see 922The event loop has been resumed in the child process after fork (see
760C<ev_fork>). 923C<ev_fork>).
761 924
925=item C<EV_ASYNC>
926
927The given async watcher has been asynchronously notified (see C<ev_async>).
928
762=item C<EV_ERROR> 929=item C<EV_ERROR>
763 930
764An unspecified error has occured, the watcher has been stopped. This might 931An unspecified error has occurred, the watcher has been stopped. This might
765happen because the watcher could not be properly started because libev 932happen because the watcher could not be properly started because libev
766ran out of memory, a file descriptor was found to be closed or any other 933ran out of memory, a file descriptor was found to be closed or any other
934problem. Libev considers these application bugs.
935
767problem. You best act on it by reporting the problem and somehow coping 936You best act on it by reporting the problem and somehow coping with the
768with the watcher being stopped. 937watcher being stopped. Note that well-written programs should not receive
938an error ever, so when your watcher receives it, this usually indicates a
939bug in your program.
769 940
770Libev will usually signal a few "dummy" events together with an error, 941Libev will usually signal a few "dummy" events together with an error, for
771for example it might indicate that a fd is readable or writable, and if 942example it might indicate that a fd is readable or writable, and if your
772your callbacks is well-written it can just attempt the operation and cope 943callbacks is well-written it can just attempt the operation and cope with
773with the error from read() or write(). This will not work in multithreaded 944the error from read() or write(). This will not work in multi-threaded
774programs, though, so beware. 945programs, though, as the fd could already be closed and reused for another
946thing, so beware.
775 947
776=back 948=back
777 949
778=head2 GENERIC WATCHER FUNCTIONS 950=head2 GENERIC WATCHER FUNCTIONS
779
780In the following description, C<TYPE> stands for the watcher type,
781e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
782 951
783=over 4 952=over 4
784 953
785=item C<ev_init> (ev_TYPE *watcher, callback) 954=item C<ev_init> (ev_TYPE *watcher, callback)
786 955
792which rolls both calls into one. 961which rolls both calls into one.
793 962
794You can reinitialise a watcher at any time as long as it has been stopped 963You can reinitialise a watcher at any time as long as it has been stopped
795(or never started) and there are no pending events outstanding. 964(or never started) and there are no pending events outstanding.
796 965
797The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher, 966The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
798int revents)>. 967int revents)>.
968
969Example: Initialise an C<ev_io> watcher in two steps.
970
971 ev_io w;
972 ev_init (&w, my_cb);
973 ev_io_set (&w, STDIN_FILENO, EV_READ);
799 974
800=item C<ev_TYPE_set> (ev_TYPE *, [args]) 975=item C<ev_TYPE_set> (ev_TYPE *, [args])
801 976
802This macro initialises the type-specific parts of a watcher. You need to 977This macro initialises the type-specific parts of a watcher. You need to
803call C<ev_init> at least once before you call this macro, but you can 978call C<ev_init> at least once before you call this macro, but you can
806difference to the C<ev_init> macro). 981difference to the C<ev_init> macro).
807 982
808Although some watcher types do not have type-specific arguments 983Although some watcher types do not have type-specific arguments
809(e.g. C<ev_prepare>) you still need to call its C<set> macro. 984(e.g. C<ev_prepare>) you still need to call its C<set> macro.
810 985
986See C<ev_init>, above, for an example.
987
811=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 988=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
812 989
813This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro 990This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
814calls into a single call. This is the most convinient method to initialise 991calls into a single call. This is the most convenient method to initialise
815a watcher. The same limitations apply, of course. 992a watcher. The same limitations apply, of course.
993
994Example: Initialise and set an C<ev_io> watcher in one step.
995
996 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
816 997
817=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 998=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
818 999
819Starts (activates) the given watcher. Only active watchers will receive 1000Starts (activates) the given watcher. Only active watchers will receive
820events. If the watcher is already active nothing will happen. 1001events. If the watcher is already active nothing will happen.
821 1002
1003Example: Start the C<ev_io> watcher that is being abused as example in this
1004whole section.
1005
1006 ev_io_start (EV_DEFAULT_UC, &w);
1007
822=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1008=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
823 1009
824Stops the given watcher again (if active) and clears the pending 1010Stops the given watcher if active, and clears the pending status (whether
1011the watcher was active or not).
1012
825status. It is possible that stopped watchers are pending (for example, 1013It is possible that stopped watchers are pending - for example,
826non-repeating timers are being stopped when they become pending), but 1014non-repeating timers are being stopped when they become pending - but
827C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If 1015calling C<ev_TYPE_stop> ensures that the watcher is neither active nor
828you want to free or reuse the memory used by the watcher it is therefore a 1016pending. If you want to free or reuse the memory used by the watcher it is
829good idea to always call its C<ev_TYPE_stop> function. 1017therefore a good idea to always call its C<ev_TYPE_stop> function.
830 1018
831=item bool ev_is_active (ev_TYPE *watcher) 1019=item bool ev_is_active (ev_TYPE *watcher)
832 1020
833Returns a true value iff the watcher is active (i.e. it has been started 1021Returns a true value iff the watcher is active (i.e. it has been started
834and not yet been stopped). As long as a watcher is active you must not modify 1022and not yet been stopped). As long as a watcher is active you must not modify
876The default priority used by watchers when no priority has been set is 1064The default priority used by watchers when no priority has been set is
877always C<0>, which is supposed to not be too high and not be too low :). 1065always C<0>, which is supposed to not be too high and not be too low :).
878 1066
879Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1067Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
880fine, as long as you do not mind that the priority value you query might 1068fine, as long as you do not mind that the priority value you query might
881or might not have been adjusted to be within valid range. 1069or might not have been clamped to the valid range.
882 1070
883=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1071=item ev_invoke (loop, ev_TYPE *watcher, int revents)
884 1072
885Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1073Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
886C<loop> nor C<revents> need to be valid as long as the watcher callback 1074C<loop> nor C<revents> need to be valid as long as the watcher callback
887can deal with that fact. 1075can deal with that fact, as both are simply passed through to the
1076callback.
888 1077
889=item int ev_clear_pending (loop, ev_TYPE *watcher) 1078=item int ev_clear_pending (loop, ev_TYPE *watcher)
890 1079
891If the watcher is pending, this function returns clears its pending status 1080If the watcher is pending, this function clears its pending status and
892and returns its C<revents> bitset (as if its callback was invoked). If the 1081returns its C<revents> bitset (as if its callback was invoked). If the
893watcher isn't pending it does nothing and returns C<0>. 1082watcher isn't pending it does nothing and returns C<0>.
894 1083
1084Sometimes it can be useful to "poll" a watcher instead of waiting for its
1085callback to be invoked, which can be accomplished with this function.
1086
895=back 1087=back
896 1088
897 1089
898=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1090=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
899 1091
900Each watcher has, by default, a member C<void *data> that you can change 1092Each watcher has, by default, a member C<void *data> that you can change
901and read at any time, libev will completely ignore it. This can be used 1093and read at any time: libev will completely ignore it. This can be used
902to associate arbitrary data with your watcher. If you need more data and 1094to associate arbitrary data with your watcher. If you need more data and
903don't want to allocate memory and store a pointer to it in that data 1095don't want to allocate memory and store a pointer to it in that data
904member, you can also "subclass" the watcher type and provide your own 1096member, you can also "subclass" the watcher type and provide your own
905data: 1097data:
906 1098
907 struct my_io 1099 struct my_io
908 { 1100 {
909 struct ev_io io; 1101 ev_io io;
910 int otherfd; 1102 int otherfd;
911 void *somedata; 1103 void *somedata;
912 struct whatever *mostinteresting; 1104 struct whatever *mostinteresting;
913 } 1105 };
1106
1107 ...
1108 struct my_io w;
1109 ev_io_init (&w.io, my_cb, fd, EV_READ);
914 1110
915And since your callback will be called with a pointer to the watcher, you 1111And since your callback will be called with a pointer to the watcher, you
916can cast it back to your own type: 1112can cast it back to your own type:
917 1113
918 static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) 1114 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
919 { 1115 {
920 struct my_io *w = (struct my_io *)w_; 1116 struct my_io *w = (struct my_io *)w_;
921 ... 1117 ...
922 } 1118 }
923 1119
924More interesting and less C-conformant ways of casting your callback type 1120More interesting and less C-conformant ways of casting your callback type
925instead have been omitted. 1121instead have been omitted.
926 1122
927Another common scenario is having some data structure with multiple 1123Another common scenario is to use some data structure with multiple
928watchers: 1124embedded watchers:
929 1125
930 struct my_biggy 1126 struct my_biggy
931 { 1127 {
932 int some_data; 1128 int some_data;
933 ev_timer t1; 1129 ev_timer t1;
934 ev_timer t2; 1130 ev_timer t2;
935 } 1131 }
936 1132
937In this case getting the pointer to C<my_biggy> is a bit more complicated, 1133In this case getting the pointer to C<my_biggy> is a bit more
938you need to use C<offsetof>: 1134complicated: Either you store the address of your C<my_biggy> struct
1135in the C<data> member of the watcher (for woozies), or you need to use
1136some pointer arithmetic using C<offsetof> inside your watchers (for real
1137programmers):
939 1138
940 #include <stddef.h> 1139 #include <stddef.h>
941 1140
942 static void 1141 static void
943 t1_cb (EV_P_ struct ev_timer *w, int revents) 1142 t1_cb (EV_P_ ev_timer *w, int revents)
944 { 1143 {
945 struct my_biggy big = (struct my_biggy * 1144 struct my_biggy big = (struct my_biggy *
946 (((char *)w) - offsetof (struct my_biggy, t1)); 1145 (((char *)w) - offsetof (struct my_biggy, t1));
947 } 1146 }
948 1147
949 static void 1148 static void
950 t2_cb (EV_P_ struct ev_timer *w, int revents) 1149 t2_cb (EV_P_ ev_timer *w, int revents)
951 { 1150 {
952 struct my_biggy big = (struct my_biggy * 1151 struct my_biggy big = (struct my_biggy *
953 (((char *)w) - offsetof (struct my_biggy, t2)); 1152 (((char *)w) - offsetof (struct my_biggy, t2));
954 } 1153 }
955 1154
956 1155
957=head1 WATCHER TYPES 1156=head1 WATCHER TYPES
958 1157
959This section describes each watcher in detail, but will not repeat 1158This section describes each watcher in detail, but will not repeat
983In general you can register as many read and/or write event watchers per 1182In general you can register as many read and/or write event watchers per
984fd as you want (as long as you don't confuse yourself). Setting all file 1183fd as you want (as long as you don't confuse yourself). Setting all file
985descriptors to non-blocking mode is also usually a good idea (but not 1184descriptors to non-blocking mode is also usually a good idea (but not
986required if you know what you are doing). 1185required if you know what you are doing).
987 1186
988If you must do this, then force the use of a known-to-be-good backend 1187If you cannot use non-blocking mode, then force the use of a
989(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 1188known-to-be-good backend (at the time of this writing, this includes only
990C<EVBACKEND_POLL>). 1189C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>).
991 1190
992Another thing you have to watch out for is that it is quite easy to 1191Another thing you have to watch out for is that it is quite easy to
993receive "spurious" readyness notifications, that is your callback might 1192receive "spurious" readiness notifications, that is your callback might
994be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1193be called with C<EV_READ> but a subsequent C<read>(2) will actually block
995because there is no data. Not only are some backends known to create a 1194because there is no data. Not only are some backends known to create a
996lot of those (for example solaris ports), it is very easy to get into 1195lot of those (for example Solaris ports), it is very easy to get into
997this situation even with a relatively standard program structure. Thus 1196this situation even with a relatively standard program structure. Thus
998it is best to always use non-blocking I/O: An extra C<read>(2) returning 1197it is best to always use non-blocking I/O: An extra C<read>(2) returning
999C<EAGAIN> is far preferable to a program hanging until some data arrives. 1198C<EAGAIN> is far preferable to a program hanging until some data arrives.
1000 1199
1001If you cannot run the fd in non-blocking mode (for example you should not 1200If you cannot run the fd in non-blocking mode (for example you should
1002play around with an Xlib connection), then you have to seperately re-test 1201not play around with an Xlib connection), then you have to separately
1003whether a file descriptor is really ready with a known-to-be good interface 1202re-test whether a file descriptor is really ready with a known-to-be good
1004such as poll (fortunately in our Xlib example, Xlib already does this on 1203interface such as poll (fortunately in our Xlib example, Xlib already
1005its own, so its quite safe to use). 1204does this on its own, so its quite safe to use). Some people additionally
1205use C<SIGALRM> and an interval timer, just to be sure you won't block
1206indefinitely.
1207
1208But really, best use non-blocking mode.
1006 1209
1007=head3 The special problem of disappearing file descriptors 1210=head3 The special problem of disappearing file descriptors
1008 1211
1009Some backends (e.g. kqueue, epoll) need to be told about closing a file 1212Some backends (e.g. kqueue, epoll) need to be told about closing a file
1010descriptor (either by calling C<close> explicitly or by any other means, 1213descriptor (either due to calling C<close> explicitly or any other means,
1011such as C<dup>). The reason is that you register interest in some file 1214such as C<dup2>). The reason is that you register interest in some file
1012descriptor, but when it goes away, the operating system will silently drop 1215descriptor, but when it goes away, the operating system will silently drop
1013this interest. If another file descriptor with the same number then is 1216this interest. If another file descriptor with the same number then is
1014registered with libev, there is no efficient way to see that this is, in 1217registered with libev, there is no efficient way to see that this is, in
1015fact, a different file descriptor. 1218fact, a different file descriptor.
1016 1219
1045To support fork in your programs, you either have to call 1248To support fork in your programs, you either have to call
1046C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child, 1249C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
1047enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1250enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1048C<EVBACKEND_POLL>. 1251C<EVBACKEND_POLL>.
1049 1252
1253=head3 The special problem of SIGPIPE
1254
1255While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1256when writing to a pipe whose other end has been closed, your program gets
1257sent a SIGPIPE, which, by default, aborts your program. For most programs
1258this is sensible behaviour, for daemons, this is usually undesirable.
1259
1260So when you encounter spurious, unexplained daemon exits, make sure you
1261ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1262somewhere, as that would have given you a big clue).
1263
1050 1264
1051=head3 Watcher-Specific Functions 1265=head3 Watcher-Specific Functions
1052 1266
1053=over 4 1267=over 4
1054 1268
1055=item ev_io_init (ev_io *, callback, int fd, int events) 1269=item ev_io_init (ev_io *, callback, int fd, int events)
1056 1270
1057=item ev_io_set (ev_io *, int fd, int events) 1271=item ev_io_set (ev_io *, int fd, int events)
1058 1272
1059Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1273Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1060rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or 1274receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or
1061C<EV_READ | EV_WRITE> to receive the given events. 1275C<EV_READ | EV_WRITE>, to express the desire to receive the given events.
1062 1276
1063=item int fd [read-only] 1277=item int fd [read-only]
1064 1278
1065The file descriptor being watched. 1279The file descriptor being watched.
1066 1280
1074 1288
1075Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well 1289Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1076readable, but only once. Since it is likely line-buffered, you could 1290readable, but only once. Since it is likely line-buffered, you could
1077attempt to read a whole line in the callback. 1291attempt to read a whole line in the callback.
1078 1292
1079 static void 1293 static void
1080 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1294 stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents)
1081 { 1295 {
1082 ev_io_stop (loop, w); 1296 ev_io_stop (loop, w);
1083 .. read from stdin here (or from w->fd) and haqndle any I/O errors 1297 .. read from stdin here (or from w->fd) and handle any I/O errors
1084 } 1298 }
1085 1299
1086 ... 1300 ...
1087 struct ev_loop *loop = ev_default_init (0); 1301 struct ev_loop *loop = ev_default_init (0);
1088 struct ev_io stdin_readable; 1302 ev_io stdin_readable;
1089 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1303 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1090 ev_io_start (loop, &stdin_readable); 1304 ev_io_start (loop, &stdin_readable);
1091 ev_loop (loop, 0); 1305 ev_loop (loop, 0);
1092 1306
1093 1307
1094=head2 C<ev_timer> - relative and optionally repeating timeouts 1308=head2 C<ev_timer> - relative and optionally repeating timeouts
1095 1309
1096Timer watchers are simple relative timers that generate an event after a 1310Timer watchers are simple relative timers that generate an event after a
1097given time, and optionally repeating in regular intervals after that. 1311given time, and optionally repeating in regular intervals after that.
1098 1312
1099The timers are based on real time, that is, if you register an event that 1313The timers are based on real time, that is, if you register an event that
1100times out after an hour and you reset your system clock to last years 1314times out after an hour and you reset your system clock to January last
1101time, it will still time out after (roughly) and hour. "Roughly" because 1315year, it will still time out after (roughly) one hour. "Roughly" because
1102detecting time jumps is hard, and some inaccuracies are unavoidable (the 1316detecting time jumps is hard, and some inaccuracies are unavoidable (the
1103monotonic clock option helps a lot here). 1317monotonic clock option helps a lot here).
1318
1319The callback is guaranteed to be invoked only I<after> its timeout has
1320passed, but if multiple timers become ready during the same loop iteration
1321then order of execution is undefined.
1322
1323=head3 Be smart about timeouts
1324
1325Many real-world problems involve some kind of timeout, usually for error
1326recovery. A typical example is an HTTP request - if the other side hangs,
1327you want to raise some error after a while.
1328
1329What follows are some ways to handle this problem, from obvious and
1330inefficient to smart and efficient.
1331
1332In the following, a 60 second activity timeout is assumed - a timeout that
1333gets reset to 60 seconds each time there is activity (e.g. each time some
1334data or other life sign was received).
1335
1336=over 4
1337
1338=item 1. Use a timer and stop, reinitialise and start it on activity.
1339
1340This is the most obvious, but not the most simple way: In the beginning,
1341start the watcher:
1342
1343 ev_timer_init (timer, callback, 60., 0.);
1344 ev_timer_start (loop, timer);
1345
1346Then, each time there is some activity, C<ev_timer_stop> it, initialise it
1347and start it again:
1348
1349 ev_timer_stop (loop, timer);
1350 ev_timer_set (timer, 60., 0.);
1351 ev_timer_start (loop, timer);
1352
1353This is relatively simple to implement, but means that each time there is
1354some activity, libev will first have to remove the timer from its internal
1355data structure and then add it again. Libev tries to be fast, but it's
1356still not a constant-time operation.
1357
1358=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1359
1360This is the easiest way, and involves using C<ev_timer_again> instead of
1361C<ev_timer_start>.
1362
1363To implement this, configure an C<ev_timer> with a C<repeat> value
1364of C<60> and then call C<ev_timer_again> at start and each time you
1365successfully read or write some data. If you go into an idle state where
1366you do not expect data to travel on the socket, you can C<ev_timer_stop>
1367the timer, and C<ev_timer_again> will automatically restart it if need be.
1368
1369That means you can ignore both the C<ev_timer_start> function and the
1370C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1371member and C<ev_timer_again>.
1372
1373At start:
1374
1375 ev_timer_init (timer, callback);
1376 timer->repeat = 60.;
1377 ev_timer_again (loop, timer);
1378
1379Each time there is some activity:
1380
1381 ev_timer_again (loop, timer);
1382
1383It is even possible to change the time-out on the fly, regardless of
1384whether the watcher is active or not:
1385
1386 timer->repeat = 30.;
1387 ev_timer_again (loop, timer);
1388
1389This is slightly more efficient then stopping/starting the timer each time
1390you want to modify its timeout value, as libev does not have to completely
1391remove and re-insert the timer from/into its internal data structure.
1392
1393It is, however, even simpler than the "obvious" way to do it.
1394
1395=item 3. Let the timer time out, but then re-arm it as required.
1396
1397This method is more tricky, but usually most efficient: Most timeouts are
1398relatively long compared to the intervals between other activity - in
1399our example, within 60 seconds, there are usually many I/O events with
1400associated activity resets.
1401
1402In this case, it would be more efficient to leave the C<ev_timer> alone,
1403but remember the time of last activity, and check for a real timeout only
1404within the callback:
1405
1406 ev_tstamp last_activity; // time of last activity
1407
1408 static void
1409 callback (EV_P_ ev_timer *w, int revents)
1410 {
1411 ev_tstamp now = ev_now (EV_A);
1412 ev_tstamp timeout = last_activity + 60.;
1413
1414 // if last_activity + 60. is older than now, we did time out
1415 if (timeout < now)
1416 {
1417 // timeout occured, take action
1418 }
1419 else
1420 {
1421 // callback was invoked, but there was some activity, re-arm
1422 // the watcher to fire in last_activity + 60, which is
1423 // guaranteed to be in the future, so "again" is positive:
1424 w->repeat = timeout - now;
1425 ev_timer_again (EV_A_ w);
1426 }
1427 }
1428
1429To summarise the callback: first calculate the real timeout (defined
1430as "60 seconds after the last activity"), then check if that time has
1431been reached, which means something I<did>, in fact, time out. Otherwise
1432the callback was invoked too early (C<timeout> is in the future), so
1433re-schedule the timer to fire at that future time, to see if maybe we have
1434a timeout then.
1435
1436Note how C<ev_timer_again> is used, taking advantage of the
1437C<ev_timer_again> optimisation when the timer is already running.
1438
1439This scheme causes more callback invocations (about one every 60 seconds
1440minus half the average time between activity), but virtually no calls to
1441libev to change the timeout.
1442
1443To start the timer, simply initialise the watcher and set C<last_activity>
1444to the current time (meaning we just have some activity :), then call the
1445callback, which will "do the right thing" and start the timer:
1446
1447 ev_timer_init (timer, callback);
1448 last_activity = ev_now (loop);
1449 callback (loop, timer, EV_TIMEOUT);
1450
1451And when there is some activity, simply store the current time in
1452C<last_activity>, no libev calls at all:
1453
1454 last_actiivty = ev_now (loop);
1455
1456This technique is slightly more complex, but in most cases where the
1457time-out is unlikely to be triggered, much more efficient.
1458
1459Changing the timeout is trivial as well (if it isn't hard-coded in the
1460callback :) - just change the timeout and invoke the callback, which will
1461fix things for you.
1462
1463=item 4. Wee, just use a double-linked list for your timeouts.
1464
1465If there is not one request, but many thousands (millions...), all
1466employing some kind of timeout with the same timeout value, then one can
1467do even better:
1468
1469When starting the timeout, calculate the timeout value and put the timeout
1470at the I<end> of the list.
1471
1472Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
1473the list is expected to fire (for example, using the technique #3).
1474
1475When there is some activity, remove the timer from the list, recalculate
1476the timeout, append it to the end of the list again, and make sure to
1477update the C<ev_timer> if it was taken from the beginning of the list.
1478
1479This way, one can manage an unlimited number of timeouts in O(1) time for
1480starting, stopping and updating the timers, at the expense of a major
1481complication, and having to use a constant timeout. The constant timeout
1482ensures that the list stays sorted.
1483
1484=back
1485
1486So which method the best?
1487
1488Method #2 is a simple no-brain-required solution that is adequate in most
1489situations. Method #3 requires a bit more thinking, but handles many cases
1490better, and isn't very complicated either. In most case, choosing either
1491one is fine, with #3 being better in typical situations.
1492
1493Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1494rather complicated, but extremely efficient, something that really pays
1495off after the first million or so of active timers, i.e. it's usually
1496overkill :)
1497
1498=head3 The special problem of time updates
1499
1500Establishing the current time is a costly operation (it usually takes at
1501least two system calls): EV therefore updates its idea of the current
1502time only before and after C<ev_loop> collects new events, which causes a
1503growing difference between C<ev_now ()> and C<ev_time ()> when handling
1504lots of events in one iteration.
1104 1505
1105The relative timeouts are calculated relative to the C<ev_now ()> 1506The relative timeouts are calculated relative to the C<ev_now ()>
1106time. This is usually the right thing as this timestamp refers to the time 1507time. This is usually the right thing as this timestamp refers to the time
1107of the event triggering whatever timeout you are modifying/starting. If 1508of the event triggering whatever timeout you are modifying/starting. If
1108you suspect event processing to be delayed and you I<need> to base the timeout 1509you suspect event processing to be delayed and you I<need> to base the
1109on the current time, use something like this to adjust for this: 1510timeout on the current time, use something like this to adjust for this:
1110 1511
1111 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1512 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1112 1513
1113The callback is guarenteed to be invoked only when its timeout has passed, 1514If the event loop is suspended for a long time, you can also force an
1114but if multiple timers become ready during the same loop iteration then 1515update of the time returned by C<ev_now ()> by calling C<ev_now_update
1115order of execution is undefined. 1516()>.
1116 1517
1117=head3 Watcher-Specific Functions and Data Members 1518=head3 Watcher-Specific Functions and Data Members
1118 1519
1119=over 4 1520=over 4
1120 1521
1121=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1522=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1122 1523
1123=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 1524=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
1124 1525
1125Configure the timer to trigger after C<after> seconds. If C<repeat> is 1526Configure the timer to trigger after C<after> seconds. If C<repeat>
1126C<0.>, then it will automatically be stopped. If it is positive, then the 1527is C<0.>, then it will automatically be stopped once the timeout is
1127timer will automatically be configured to trigger again C<repeat> seconds 1528reached. If it is positive, then the timer will automatically be
1128later, again, and again, until stopped manually. 1529configured to trigger again C<repeat> seconds later, again, and again,
1530until stopped manually.
1129 1531
1130The timer itself will do a best-effort at avoiding drift, that is, if you 1532The timer itself will do a best-effort at avoiding drift, that is, if
1131configure a timer to trigger every 10 seconds, then it will trigger at 1533you configure a timer to trigger every 10 seconds, then it will normally
1132exactly 10 second intervals. If, however, your program cannot keep up with 1534trigger at exactly 10 second intervals. If, however, your program cannot
1133the timer (because it takes longer than those 10 seconds to do stuff) the 1535keep up with the timer (because it takes longer than those 10 seconds to
1134timer will not fire more than once per event loop iteration. 1536do stuff) the timer will not fire more than once per event loop iteration.
1135 1537
1136=item ev_timer_again (loop) 1538=item ev_timer_again (loop, ev_timer *)
1137 1539
1138This will act as if the timer timed out and restart it again if it is 1540This will act as if the timer timed out and restart it again if it is
1139repeating. The exact semantics are: 1541repeating. The exact semantics are:
1140 1542
1141If the timer is pending, its pending status is cleared. 1543If the timer is pending, its pending status is cleared.
1142 1544
1143If the timer is started but nonrepeating, stop it (as if it timed out). 1545If the timer is started but non-repeating, stop it (as if it timed out).
1144 1546
1145If the timer is repeating, either start it if necessary (with the 1547If the timer is repeating, either start it if necessary (with the
1146C<repeat> value), or reset the running timer to the C<repeat> value. 1548C<repeat> value), or reset the running timer to the C<repeat> value.
1147 1549
1148This sounds a bit complicated, but here is a useful and typical 1550This sounds a bit complicated, see "Be smart about timeouts", above, for a
1149example: Imagine you have a tcp connection and you want a so-called idle 1551usage example.
1150timeout, that is, you want to be called when there have been, say, 60
1151seconds of inactivity on the socket. The easiest way to do this is to
1152configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1153C<ev_timer_again> each time you successfully read or write some data. If
1154you go into an idle state where you do not expect data to travel on the
1155socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
1156automatically restart it if need be.
1157
1158That means you can ignore the C<after> value and C<ev_timer_start>
1159altogether and only ever use the C<repeat> value and C<ev_timer_again>:
1160
1161 ev_timer_init (timer, callback, 0., 5.);
1162 ev_timer_again (loop, timer);
1163 ...
1164 timer->again = 17.;
1165 ev_timer_again (loop, timer);
1166 ...
1167 timer->again = 10.;
1168 ev_timer_again (loop, timer);
1169
1170This is more slightly efficient then stopping/starting the timer each time
1171you want to modify its timeout value.
1172 1552
1173=item ev_tstamp repeat [read-write] 1553=item ev_tstamp repeat [read-write]
1174 1554
1175The current C<repeat> value. Will be used each time the watcher times out 1555The current C<repeat> value. Will be used each time the watcher times out
1176or C<ev_timer_again> is called and determines the next timeout (if any), 1556or C<ev_timer_again> is called, and determines the next timeout (if any),
1177which is also when any modifications are taken into account. 1557which is also when any modifications are taken into account.
1178 1558
1179=back 1559=back
1180 1560
1181=head3 Examples 1561=head3 Examples
1182 1562
1183Example: Create a timer that fires after 60 seconds. 1563Example: Create a timer that fires after 60 seconds.
1184 1564
1185 static void 1565 static void
1186 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1566 one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents)
1187 { 1567 {
1188 .. one minute over, w is actually stopped right here 1568 .. one minute over, w is actually stopped right here
1189 } 1569 }
1190 1570
1191 struct ev_timer mytimer; 1571 ev_timer mytimer;
1192 ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1572 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1193 ev_timer_start (loop, &mytimer); 1573 ev_timer_start (loop, &mytimer);
1194 1574
1195Example: Create a timeout timer that times out after 10 seconds of 1575Example: Create a timeout timer that times out after 10 seconds of
1196inactivity. 1576inactivity.
1197 1577
1198 static void 1578 static void
1199 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1579 timeout_cb (struct ev_loop *loop, ev_timer *w, int revents)
1200 { 1580 {
1201 .. ten seconds without any activity 1581 .. ten seconds without any activity
1202 } 1582 }
1203 1583
1204 struct ev_timer mytimer; 1584 ev_timer mytimer;
1205 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1585 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1206 ev_timer_again (&mytimer); /* start timer */ 1586 ev_timer_again (&mytimer); /* start timer */
1207 ev_loop (loop, 0); 1587 ev_loop (loop, 0);
1208 1588
1209 // and in some piece of code that gets executed on any "activity": 1589 // and in some piece of code that gets executed on any "activity":
1210 // reset the timeout to start ticking again at 10 seconds 1590 // reset the timeout to start ticking again at 10 seconds
1211 ev_timer_again (&mytimer); 1591 ev_timer_again (&mytimer);
1212 1592
1213 1593
1214=head2 C<ev_periodic> - to cron or not to cron? 1594=head2 C<ev_periodic> - to cron or not to cron?
1215 1595
1216Periodic watchers are also timers of a kind, but they are very versatile 1596Periodic watchers are also timers of a kind, but they are very versatile
1217(and unfortunately a bit complex). 1597(and unfortunately a bit complex).
1218 1598
1219Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1599Unlike C<ev_timer>'s, they are not based on real time (or relative time)
1220but on wallclock time (absolute time). You can tell a periodic watcher 1600but on wall clock time (absolute time). You can tell a periodic watcher
1221to trigger "at" some specific point in time. For example, if you tell a 1601to trigger after some specific point in time. For example, if you tell a
1222periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now () 1602periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now ()
1223+ 10.>) and then reset your system clock to the last year, then it will 1603+ 10.>, that is, an absolute time not a delay) and then reset your system
1604clock to January of the previous year, then it will take more than year
1224take a year to trigger the event (unlike an C<ev_timer>, which would trigger 1605to trigger the event (unlike an C<ev_timer>, which would still trigger
1225roughly 10 seconds later). 1606roughly 10 seconds later as it uses a relative timeout).
1226 1607
1227They can also be used to implement vastly more complex timers, such as 1608C<ev_periodic>s can also be used to implement vastly more complex timers,
1228triggering an event on each midnight, local time or other, complicated, 1609such as triggering an event on each "midnight, local time", or other
1229rules. 1610complicated rules.
1230 1611
1231As with timers, the callback is guarenteed to be invoked only when the 1612As with timers, the callback is guaranteed to be invoked only when the
1232time (C<at>) has been passed, but if multiple periodic timers become ready 1613time (C<at>) has passed, but if multiple periodic timers become ready
1233during the same loop iteration then order of execution is undefined. 1614during the same loop iteration, then order of execution is undefined.
1234 1615
1235=head3 Watcher-Specific Functions and Data Members 1616=head3 Watcher-Specific Functions and Data Members
1236 1617
1237=over 4 1618=over 4
1238 1619
1239=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1620=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1240 1621
1241=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1622=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1242 1623
1243Lots of arguments, lets sort it out... There are basically three modes of 1624Lots of arguments, lets sort it out... There are basically three modes of
1244operation, and we will explain them from simplest to complex: 1625operation, and we will explain them from simplest to most complex:
1245 1626
1246=over 4 1627=over 4
1247 1628
1248=item * absolute timer (at = time, interval = reschedule_cb = 0) 1629=item * absolute timer (at = time, interval = reschedule_cb = 0)
1249 1630
1250In this configuration the watcher triggers an event at the wallclock time 1631In this configuration the watcher triggers an event after the wall clock
1251C<at> and doesn't repeat. It will not adjust when a time jump occurs, 1632time C<at> has passed. It will not repeat and will not adjust when a time
1252that is, if it is to be run at January 1st 2011 then it will run when the 1633jump occurs, that is, if it is to be run at January 1st 2011 then it will
1253system time reaches or surpasses this time. 1634only run when the system clock reaches or surpasses this time.
1254 1635
1255=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1636=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1256 1637
1257In this mode the watcher will always be scheduled to time out at the next 1638In this mode the watcher will always be scheduled to time out at the next
1258C<at + N * interval> time (for some integer N, which can also be negative) 1639C<at + N * interval> time (for some integer N, which can also be negative)
1259and then repeat, regardless of any time jumps. 1640and then repeat, regardless of any time jumps.
1260 1641
1261This can be used to create timers that do not drift with respect to system 1642This can be used to create timers that do not drift with respect to the
1262time: 1643system clock, for example, here is a C<ev_periodic> that triggers each
1644hour, on the hour:
1263 1645
1264 ev_periodic_set (&periodic, 0., 3600., 0); 1646 ev_periodic_set (&periodic, 0., 3600., 0);
1265 1647
1266This doesn't mean there will always be 3600 seconds in between triggers, 1648This doesn't mean there will always be 3600 seconds in between triggers,
1267but only that the the callback will be called when the system time shows a 1649but only that the callback will be called when the system time shows a
1268full hour (UTC), or more correctly, when the system time is evenly divisible 1650full hour (UTC), or more correctly, when the system time is evenly divisible
1269by 3600. 1651by 3600.
1270 1652
1271Another way to think about it (for the mathematically inclined) is that 1653Another way to think about it (for the mathematically inclined) is that
1272C<ev_periodic> will try to run the callback in this mode at the next possible 1654C<ev_periodic> will try to run the callback in this mode at the next possible
1273time where C<time = at (mod interval)>, regardless of any time jumps. 1655time where C<time = at (mod interval)>, regardless of any time jumps.
1274 1656
1275For numerical stability it is preferable that the C<at> value is near 1657For numerical stability it is preferable that the C<at> value is near
1276C<ev_now ()> (the current time), but there is no range requirement for 1658C<ev_now ()> (the current time), but there is no range requirement for
1277this value. 1659this value, and in fact is often specified as zero.
1660
1661Note also that there is an upper limit to how often a timer can fire (CPU
1662speed for example), so if C<interval> is very small then timing stability
1663will of course deteriorate. Libev itself tries to be exact to be about one
1664millisecond (if the OS supports it and the machine is fast enough).
1278 1665
1279=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1666=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1280 1667
1281In this mode the values for C<interval> and C<at> are both being 1668In this mode the values for C<interval> and C<at> are both being
1282ignored. Instead, each time the periodic watcher gets scheduled, the 1669ignored. Instead, each time the periodic watcher gets scheduled, the
1283reschedule callback will be called with the watcher as first, and the 1670reschedule callback will be called with the watcher as first, and the
1284current time as second argument. 1671current time as second argument.
1285 1672
1286NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1673NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1287ever, or make any event loop modifications>. If you need to stop it, 1674ever, or make ANY event loop modifications whatsoever>.
1288return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1289starting an C<ev_prepare> watcher, which is legal).
1290 1675
1676If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1677it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1678only event loop modification you are allowed to do).
1679
1291Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1680The callback prototype is C<ev_tstamp (*reschedule_cb)(ev_periodic
1292ev_tstamp now)>, e.g.: 1681*w, ev_tstamp now)>, e.g.:
1293 1682
1683 static ev_tstamp
1294 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1684 my_rescheduler (ev_periodic *w, ev_tstamp now)
1295 { 1685 {
1296 return now + 60.; 1686 return now + 60.;
1297 } 1687 }
1298 1688
1299It must return the next time to trigger, based on the passed time value 1689It must return the next time to trigger, based on the passed time value
1300(that is, the lowest time value larger than to the second argument). It 1690(that is, the lowest time value larger than to the second argument). It
1301will usually be called just before the callback will be triggered, but 1691will usually be called just before the callback will be triggered, but
1302might be called at other times, too. 1692might be called at other times, too.
1303 1693
1304NOTE: I<< This callback must always return a time that is later than the 1694NOTE: I<< This callback must always return a time that is higher than or
1305passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger. 1695equal to the passed C<now> value >>.
1306 1696
1307This can be used to create very complex timers, such as a timer that 1697This can be used to create very complex timers, such as a timer that
1308triggers on each midnight, local time. To do this, you would calculate the 1698triggers on "next midnight, local time". To do this, you would calculate the
1309next midnight after C<now> and return the timestamp value for this. How 1699next midnight after C<now> and return the timestamp value for this. How
1310you do this is, again, up to you (but it is not trivial, which is the main 1700you do this is, again, up to you (but it is not trivial, which is the main
1311reason I omitted it as an example). 1701reason I omitted it as an example).
1312 1702
1313=back 1703=back
1317Simply stops and restarts the periodic watcher again. This is only useful 1707Simply stops and restarts the periodic watcher again. This is only useful
1318when you changed some parameters or the reschedule callback would return 1708when you changed some parameters or the reschedule callback would return
1319a different time than the last time it was called (e.g. in a crond like 1709a different time than the last time it was called (e.g. in a crond like
1320program when the crontabs have changed). 1710program when the crontabs have changed).
1321 1711
1712=item ev_tstamp ev_periodic_at (ev_periodic *)
1713
1714When active, returns the absolute time that the watcher is supposed to
1715trigger next.
1716
1322=item ev_tstamp offset [read-write] 1717=item ev_tstamp offset [read-write]
1323 1718
1324When repeating, this contains the offset value, otherwise this is the 1719When repeating, this contains the offset value, otherwise this is the
1325absolute point in time (the C<at> value passed to C<ev_periodic_set>). 1720absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1326 1721
1331 1726
1332The current interval value. Can be modified any time, but changes only 1727The current interval value. Can be modified any time, but changes only
1333take effect when the periodic timer fires or C<ev_periodic_again> is being 1728take effect when the periodic timer fires or C<ev_periodic_again> is being
1334called. 1729called.
1335 1730
1336=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 1731=item ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]
1337 1732
1338The current reschedule callback, or C<0>, if this functionality is 1733The current reschedule callback, or C<0>, if this functionality is
1339switched off. Can be changed any time, but changes only take effect when 1734switched off. Can be changed any time, but changes only take effect when
1340the periodic timer fires or C<ev_periodic_again> is being called. 1735the periodic timer fires or C<ev_periodic_again> is being called.
1341 1736
1342=item ev_tstamp at [read-only]
1343
1344When active, contains the absolute time that the watcher is supposed to
1345trigger next.
1346
1347=back 1737=back
1348 1738
1349=head3 Examples 1739=head3 Examples
1350 1740
1351Example: Call a callback every hour, or, more precisely, whenever the 1741Example: Call a callback every hour, or, more precisely, whenever the
1352system clock is divisible by 3600. The callback invocation times have 1742system time is divisible by 3600. The callback invocation times have
1353potentially a lot of jittering, but good long-term stability. 1743potentially a lot of jitter, but good long-term stability.
1354 1744
1355 static void 1745 static void
1356 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1746 clock_cb (struct ev_loop *loop, ev_io *w, int revents)
1357 { 1747 {
1358 ... its now a full hour (UTC, or TAI or whatever your clock follows) 1748 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1359 } 1749 }
1360 1750
1361 struct ev_periodic hourly_tick; 1751 ev_periodic hourly_tick;
1362 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 1752 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1363 ev_periodic_start (loop, &hourly_tick); 1753 ev_periodic_start (loop, &hourly_tick);
1364 1754
1365Example: The same as above, but use a reschedule callback to do it: 1755Example: The same as above, but use a reschedule callback to do it:
1366 1756
1367 #include <math.h> 1757 #include <math.h>
1368 1758
1369 static ev_tstamp 1759 static ev_tstamp
1370 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1760 my_scheduler_cb (ev_periodic *w, ev_tstamp now)
1371 { 1761 {
1372 return fmod (now, 3600.) + 3600.; 1762 return now + (3600. - fmod (now, 3600.));
1373 } 1763 }
1374 1764
1375 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 1765 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1376 1766
1377Example: Call a callback every hour, starting now: 1767Example: Call a callback every hour, starting now:
1378 1768
1379 struct ev_periodic hourly_tick; 1769 ev_periodic hourly_tick;
1380 ev_periodic_init (&hourly_tick, clock_cb, 1770 ev_periodic_init (&hourly_tick, clock_cb,
1381 fmod (ev_now (loop), 3600.), 3600., 0); 1771 fmod (ev_now (loop), 3600.), 3600., 0);
1382 ev_periodic_start (loop, &hourly_tick); 1772 ev_periodic_start (loop, &hourly_tick);
1383 1773
1384 1774
1385=head2 C<ev_signal> - signal me when a signal gets signalled! 1775=head2 C<ev_signal> - signal me when a signal gets signalled!
1386 1776
1387Signal watchers will trigger an event when the process receives a specific 1777Signal watchers will trigger an event when the process receives a specific
1388signal one or more times. Even though signals are very asynchronous, libev 1778signal one or more times. Even though signals are very asynchronous, libev
1389will try it's best to deliver signals synchronously, i.e. as part of the 1779will try it's best to deliver signals synchronously, i.e. as part of the
1390normal event processing, like any other event. 1780normal event processing, like any other event.
1391 1781
1782If you want signals asynchronously, just use C<sigaction> as you would
1783do without libev and forget about sharing the signal. You can even use
1784C<ev_async> from a signal handler to synchronously wake up an event loop.
1785
1392You can configure as many watchers as you like per signal. Only when the 1786You can configure as many watchers as you like per signal. Only when the
1393first watcher gets started will libev actually register a signal watcher 1787first watcher gets started will libev actually register a signal handler
1394with the kernel (thus it coexists with your own signal handlers as long 1788with the kernel (thus it coexists with your own signal handlers as long as
1395as you don't register any with libev). Similarly, when the last signal 1789you don't register any with libev for the same signal). Similarly, when
1396watcher for a signal is stopped libev will reset the signal handler to 1790the last signal watcher for a signal is stopped, libev will reset the
1397SIG_DFL (regardless of what it was set to before). 1791signal handler to SIG_DFL (regardless of what it was set to before).
1792
1793If possible and supported, libev will install its handlers with
1794C<SA_RESTART> behaviour enabled, so system calls should not be unduly
1795interrupted. If you have a problem with system calls getting interrupted by
1796signals you can block all signals in an C<ev_check> watcher and unblock
1797them in an C<ev_prepare> watcher.
1398 1798
1399=head3 Watcher-Specific Functions and Data Members 1799=head3 Watcher-Specific Functions and Data Members
1400 1800
1401=over 4 1801=over 4
1402 1802
1411 1811
1412The signal the watcher watches out for. 1812The signal the watcher watches out for.
1413 1813
1414=back 1814=back
1415 1815
1816=head3 Examples
1817
1818Example: Try to exit cleanly on SIGINT.
1819
1820 static void
1821 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1822 {
1823 ev_unloop (loop, EVUNLOOP_ALL);
1824 }
1825
1826 ev_signal signal_watcher;
1827 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1828 ev_signal_start (loop, &signal_watcher);
1829
1416 1830
1417=head2 C<ev_child> - watch out for process status changes 1831=head2 C<ev_child> - watch out for process status changes
1418 1832
1419Child watchers trigger when your process receives a SIGCHLD in response to 1833Child watchers trigger when your process receives a SIGCHLD in response to
1420some child status changes (most typically when a child of yours dies). 1834some child status changes (most typically when a child of yours dies or
1835exits). It is permissible to install a child watcher I<after> the child
1836has been forked (which implies it might have already exited), as long
1837as the event loop isn't entered (or is continued from a watcher), i.e.,
1838forking and then immediately registering a watcher for the child is fine,
1839but forking and registering a watcher a few event loop iterations later is
1840not.
1841
1842Only the default event loop is capable of handling signals, and therefore
1843you can only register child watchers in the default event loop.
1844
1845=head3 Process Interaction
1846
1847Libev grabs C<SIGCHLD> as soon as the default event loop is
1848initialised. This is necessary to guarantee proper behaviour even if
1849the first child watcher is started after the child exits. The occurrence
1850of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1851synchronously as part of the event loop processing. Libev always reaps all
1852children, even ones not watched.
1853
1854=head3 Overriding the Built-In Processing
1855
1856Libev offers no special support for overriding the built-in child
1857processing, but if your application collides with libev's default child
1858handler, you can override it easily by installing your own handler for
1859C<SIGCHLD> after initialising the default loop, and making sure the
1860default loop never gets destroyed. You are encouraged, however, to use an
1861event-based approach to child reaping and thus use libev's support for
1862that, so other libev users can use C<ev_child> watchers freely.
1863
1864=head3 Stopping the Child Watcher
1865
1866Currently, the child watcher never gets stopped, even when the
1867child terminates, so normally one needs to stop the watcher in the
1868callback. Future versions of libev might stop the watcher automatically
1869when a child exit is detected.
1421 1870
1422=head3 Watcher-Specific Functions and Data Members 1871=head3 Watcher-Specific Functions and Data Members
1423 1872
1424=over 4 1873=over 4
1425 1874
1426=item ev_child_init (ev_child *, callback, int pid) 1875=item ev_child_init (ev_child *, callback, int pid, int trace)
1427 1876
1428=item ev_child_set (ev_child *, int pid) 1877=item ev_child_set (ev_child *, int pid, int trace)
1429 1878
1430Configures the watcher to wait for status changes of process C<pid> (or 1879Configures the watcher to wait for status changes of process C<pid> (or
1431I<any> process if C<pid> is specified as C<0>). The callback can look 1880I<any> process if C<pid> is specified as C<0>). The callback can look
1432at the C<rstatus> member of the C<ev_child> watcher structure to see 1881at the C<rstatus> member of the C<ev_child> watcher structure to see
1433the status word (use the macros from C<sys/wait.h> and see your systems 1882the status word (use the macros from C<sys/wait.h> and see your systems
1434C<waitpid> documentation). The C<rpid> member contains the pid of the 1883C<waitpid> documentation). The C<rpid> member contains the pid of the
1435process causing the status change. 1884process causing the status change. C<trace> must be either C<0> (only
1885activate the watcher when the process terminates) or C<1> (additionally
1886activate the watcher when the process is stopped or continued).
1436 1887
1437=item int pid [read-only] 1888=item int pid [read-only]
1438 1889
1439The process id this watcher watches out for, or C<0>, meaning any process id. 1890The process id this watcher watches out for, or C<0>, meaning any process id.
1440 1891
1449 1900
1450=back 1901=back
1451 1902
1452=head3 Examples 1903=head3 Examples
1453 1904
1454Example: Try to exit cleanly on SIGINT and SIGTERM. 1905Example: C<fork()> a new process and install a child handler to wait for
1906its completion.
1455 1907
1908 ev_child cw;
1909
1456 static void 1910 static void
1457 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1911 child_cb (EV_P_ ev_child *w, int revents)
1458 { 1912 {
1459 ev_unloop (loop, EVUNLOOP_ALL); 1913 ev_child_stop (EV_A_ w);
1914 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1460 } 1915 }
1461 1916
1462 struct ev_signal signal_watcher; 1917 pid_t pid = fork ();
1463 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1918
1464 ev_signal_start (loop, &sigint_cb); 1919 if (pid < 0)
1920 // error
1921 else if (pid == 0)
1922 {
1923 // the forked child executes here
1924 exit (1);
1925 }
1926 else
1927 {
1928 ev_child_init (&cw, child_cb, pid, 0);
1929 ev_child_start (EV_DEFAULT_ &cw);
1930 }
1465 1931
1466 1932
1467=head2 C<ev_stat> - did the file attributes just change? 1933=head2 C<ev_stat> - did the file attributes just change?
1468 1934
1469This watches a filesystem path for attribute changes. That is, it calls 1935This watches a file system path for attribute changes. That is, it calls
1470C<stat> regularly (or when the OS says it changed) and sees if it changed 1936C<stat> on that path in regular intervals (or when the OS says it changed)
1471compared to the last time, invoking the callback if it did. 1937and sees if it changed compared to the last time, invoking the callback if
1938it did.
1472 1939
1473The path does not need to exist: changing from "path exists" to "path does 1940The path does not need to exist: changing from "path exists" to "path does
1474not exist" is a status change like any other. The condition "path does 1941not exist" is a status change like any other. The condition "path does not
1475not exist" is signified by the C<st_nlink> field being zero (which is 1942exist" (or more correctly "path cannot be stat'ed") is signified by the
1476otherwise always forced to be at least one) and all the other fields of 1943C<st_nlink> field being zero (which is otherwise always forced to be at
1477the stat buffer having unspecified contents. 1944least one) and all the other fields of the stat buffer having unspecified
1945contents.
1478 1946
1479The path I<should> be absolute and I<must not> end in a slash. If it is 1947The path I<must not> end in a slash or contain special components such as
1948C<.> or C<..>. The path I<should> be absolute: If it is relative and
1480relative and your working directory changes, the behaviour is undefined. 1949your working directory changes, then the behaviour is undefined.
1481 1950
1482Since there is no standard to do this, the portable implementation simply 1951Since there is no portable change notification interface available, the
1483calls C<stat (2)> regularly on the path to see if it changed somehow. You 1952portable implementation simply calls C<stat(2)> regularly on the path
1484can specify a recommended polling interval for this case. If you specify 1953to see if it changed somehow. You can specify a recommended polling
1485a polling interval of C<0> (highly recommended!) then a I<suitable, 1954interval for this case. If you specify a polling interval of C<0> (highly
1486unspecified default> value will be used (which you can expect to be around 1955recommended!) then a I<suitable, unspecified default> value will be used
1487five seconds, although this might change dynamically). Libev will also 1956(which you can expect to be around five seconds, although this might
1488impose a minimum interval which is currently around C<0.1>, but thats 1957change dynamically). Libev will also impose a minimum interval which is
1489usually overkill. 1958currently around C<0.1>, but that's usually overkill.
1490 1959
1491This watcher type is not meant for massive numbers of stat watchers, 1960This watcher type is not meant for massive numbers of stat watchers,
1492as even with OS-supported change notifications, this can be 1961as even with OS-supported change notifications, this can be
1493resource-intensive. 1962resource-intensive.
1494 1963
1495At the time of this writing, only the Linux inotify interface is 1964At the time of this writing, the only OS-specific interface implemented
1496implemented (implementing kqueue support is left as an exercise for the 1965is the Linux inotify interface (implementing kqueue support is left as an
1497reader). Inotify will be used to give hints only and should not change the 1966exercise for the reader. Note, however, that the author sees no way of
1498semantics of C<ev_stat> watchers, which means that libev sometimes needs 1967implementing C<ev_stat> semantics with kqueue, except as a hint).
1499to fall back to regular polling again even with inotify, but changes are
1500usually detected immediately, and if the file exists there will be no
1501polling.
1502 1968
1503=head3 Inotify 1969=head3 ABI Issues (Largefile Support)
1504 1970
1971Libev by default (unless the user overrides this) uses the default
1972compilation environment, which means that on systems with large file
1973support disabled by default, you get the 32 bit version of the stat
1974structure. When using the library from programs that change the ABI to
1975use 64 bit file offsets the programs will fail. In that case you have to
1976compile libev with the same flags to get binary compatibility. This is
1977obviously the case with any flags that change the ABI, but the problem is
1978most noticeably displayed with ev_stat and large file support.
1979
1980The solution for this is to lobby your distribution maker to make large
1981file interfaces available by default (as e.g. FreeBSD does) and not
1982optional. Libev cannot simply switch on large file support because it has
1983to exchange stat structures with application programs compiled using the
1984default compilation environment.
1985
1986=head3 Inotify and Kqueue
1987
1505When C<inotify (7)> support has been compiled into libev (generally only 1988When C<inotify (7)> support has been compiled into libev and present at
1506available on Linux) and present at runtime, it will be used to speed up 1989runtime, it will be used to speed up change detection where possible. The
1507change detection where possible. The inotify descriptor will be created lazily 1990inotify descriptor will be created lazily when the first C<ev_stat>
1508when the first C<ev_stat> watcher is being started. 1991watcher is being started.
1509 1992
1510Inotify presense does not change the semantics of C<ev_stat> watchers 1993Inotify presence does not change the semantics of C<ev_stat> watchers
1511except that changes might be detected earlier, and in some cases, to avoid 1994except that changes might be detected earlier, and in some cases, to avoid
1512making regular C<stat> calls. Even in the presense of inotify support 1995making regular C<stat> calls. Even in the presence of inotify support
1513there are many cases where libev has to resort to regular C<stat> polling. 1996there are many cases where libev has to resort to regular C<stat> polling,
1997but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
1998many bugs), the path exists (i.e. stat succeeds), and the path resides on
1999a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2000xfs are fully working) libev usually gets away without polling.
1514 2001
1515(There is no support for kqueue, as apparently it cannot be used to 2002There is no support for kqueue, as apparently it cannot be used to
1516implement this functionality, due to the requirement of having a file 2003implement this functionality, due to the requirement of having a file
1517descriptor open on the object at all times). 2004descriptor open on the object at all times, and detecting renames, unlinks
2005etc. is difficult.
2006
2007=head3 C<stat ()> is a synchronous operation
2008
2009Libev doesn't normally do any kind of I/O itself, and so is not blocking
2010the process. The exception are C<ev_stat> watchers - those call C<stat
2011()>, which is a synchronous operation.
2012
2013For local paths, this usually doesn't matter: unless the system is very
2014busy or the intervals between stat's are large, a stat call will be fast,
2015as the path data is suually in memory already (except when starting the
2016watcher).
2017
2018For networked file systems, calling C<stat ()> can block an indefinite
2019time due to network issues, and even under good conditions, a stat call
2020often takes multiple milliseconds.
2021
2022Therefore, it is best to avoid using C<ev_stat> watchers on networked
2023paths, although this is fully supported by libev.
1518 2024
1519=head3 The special problem of stat time resolution 2025=head3 The special problem of stat time resolution
1520 2026
1521The C<stat ()> syscall only supports full-second resolution portably, and 2027The C<stat ()> system call only supports full-second resolution portably,
1522even on systems where the resolution is higher, many filesystems still 2028and even on systems where the resolution is higher, most file systems
1523only support whole seconds. 2029still only support whole seconds.
1524 2030
1525That means that, if the time is the only thing that changes, you might 2031That means that, if the time is the only thing that changes, you can
1526miss updates: on the first update, C<ev_stat> detects a change and calls 2032easily miss updates: on the first update, C<ev_stat> detects a change and
1527your callback, which does something. When there is another update within 2033calls your callback, which does something. When there is another update
1528the same second, C<ev_stat> will be unable to detect it. 2034within the same second, C<ev_stat> will be unable to detect unless the
2035stat data does change in other ways (e.g. file size).
1529 2036
1530The solution to this is to delay acting on a change for a second (or till 2037The solution to this is to delay acting on a change for slightly more
1531the next second boundary), using a roughly one-second delay C<ev_timer> 2038than a second (or till slightly after the next full second boundary), using
1532(C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01> 2039a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
1533is added to work around small timing inconsistencies of some operating 2040ev_timer_again (loop, w)>).
1534systems. 2041
2042The C<.02> offset is added to work around small timing inconsistencies
2043of some operating systems (where the second counter of the current time
2044might be be delayed. One such system is the Linux kernel, where a call to
2045C<gettimeofday> might return a timestamp with a full second later than
2046a subsequent C<time> call - if the equivalent of C<time ()> is used to
2047update file times then there will be a small window where the kernel uses
2048the previous second to update file times but libev might already execute
2049the timer callback).
1535 2050
1536=head3 Watcher-Specific Functions and Data Members 2051=head3 Watcher-Specific Functions and Data Members
1537 2052
1538=over 4 2053=over 4
1539 2054
1545C<path>. The C<interval> is a hint on how quickly a change is expected to 2060C<path>. The C<interval> is a hint on how quickly a change is expected to
1546be detected and should normally be specified as C<0> to let libev choose 2061be detected and should normally be specified as C<0> to let libev choose
1547a suitable value. The memory pointed to by C<path> must point to the same 2062a suitable value. The memory pointed to by C<path> must point to the same
1548path for as long as the watcher is active. 2063path for as long as the watcher is active.
1549 2064
1550The callback will be receive C<EV_STAT> when a change was detected, 2065The callback will receive an C<EV_STAT> event when a change was detected,
1551relative to the attributes at the time the watcher was started (or the 2066relative to the attributes at the time the watcher was started (or the
1552last change was detected). 2067last change was detected).
1553 2068
1554=item ev_stat_stat (ev_stat *) 2069=item ev_stat_stat (loop, ev_stat *)
1555 2070
1556Updates the stat buffer immediately with new values. If you change the 2071Updates the stat buffer immediately with new values. If you change the
1557watched path in your callback, you could call this fucntion to avoid 2072watched path in your callback, you could call this function to avoid
1558detecting this change (while introducing a race condition). Can also be 2073detecting this change (while introducing a race condition if you are not
1559useful simply to find out the new values. 2074the only one changing the path). Can also be useful simply to find out the
2075new values.
1560 2076
1561=item ev_statdata attr [read-only] 2077=item ev_statdata attr [read-only]
1562 2078
1563The most-recently detected attributes of the file. Although the type is of 2079The most-recently detected attributes of the file. Although the type is
1564C<ev_statdata>, this is usually the (or one of the) C<struct stat> types 2080C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
1565suitable for your system. If the C<st_nlink> member is C<0>, then there 2081suitable for your system, but you can only rely on the POSIX-standardised
2082members to be present. If the C<st_nlink> member is C<0>, then there was
1566was some error while C<stat>ing the file. 2083some error while C<stat>ing the file.
1567 2084
1568=item ev_statdata prev [read-only] 2085=item ev_statdata prev [read-only]
1569 2086
1570The previous attributes of the file. The callback gets invoked whenever 2087The previous attributes of the file. The callback gets invoked whenever
1571C<prev> != C<attr>. 2088C<prev> != C<attr>, or, more precisely, one or more of these members
2089differ: C<st_dev>, C<st_ino>, C<st_mode>, C<st_nlink>, C<st_uid>,
2090C<st_gid>, C<st_rdev>, C<st_size>, C<st_atime>, C<st_mtime>, C<st_ctime>.
1572 2091
1573=item ev_tstamp interval [read-only] 2092=item ev_tstamp interval [read-only]
1574 2093
1575The specified interval. 2094The specified interval.
1576 2095
1577=item const char *path [read-only] 2096=item const char *path [read-only]
1578 2097
1579The filesystem path that is being watched. 2098The file system path that is being watched.
1580 2099
1581=back 2100=back
1582 2101
1583=head3 Examples 2102=head3 Examples
1584 2103
1585Example: Watch C</etc/passwd> for attribute changes. 2104Example: Watch C</etc/passwd> for attribute changes.
1586 2105
1587 static void 2106 static void
1588 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 2107 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1589 { 2108 {
1590 /* /etc/passwd changed in some way */ 2109 /* /etc/passwd changed in some way */
1591 if (w->attr.st_nlink) 2110 if (w->attr.st_nlink)
1592 { 2111 {
1593 printf ("passwd current size %ld\n", (long)w->attr.st_size); 2112 printf ("passwd current size %ld\n", (long)w->attr.st_size);
1594 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime); 2113 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
1595 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime); 2114 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
1596 } 2115 }
1597 else 2116 else
1598 /* you shalt not abuse printf for puts */ 2117 /* you shalt not abuse printf for puts */
1599 puts ("wow, /etc/passwd is not there, expect problems. " 2118 puts ("wow, /etc/passwd is not there, expect problems. "
1600 "if this is windows, they already arrived\n"); 2119 "if this is windows, they already arrived\n");
1601 } 2120 }
1602 2121
1603 ... 2122 ...
1604 ev_stat passwd; 2123 ev_stat passwd;
1605 2124
1606 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); 2125 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1607 ev_stat_start (loop, &passwd); 2126 ev_stat_start (loop, &passwd);
1608 2127
1609Example: Like above, but additionally use a one-second delay so we do not 2128Example: Like above, but additionally use a one-second delay so we do not
1610miss updates (however, frequent updates will delay processing, too, so 2129miss updates (however, frequent updates will delay processing, too, so
1611one might do the work both on C<ev_stat> callback invocation I<and> on 2130one might do the work both on C<ev_stat> callback invocation I<and> on
1612C<ev_timer> callback invocation). 2131C<ev_timer> callback invocation).
1613 2132
1614 static ev_stat passwd; 2133 static ev_stat passwd;
1615 static ev_timer timer; 2134 static ev_timer timer;
1616 2135
1617 static void 2136 static void
1618 timer_cb (EV_P_ ev_timer *w, int revents) 2137 timer_cb (EV_P_ ev_timer *w, int revents)
1619 { 2138 {
1620 ev_timer_stop (EV_A_ w); 2139 ev_timer_stop (EV_A_ w);
1621 2140
1622 /* now it's one second after the most recent passwd change */ 2141 /* now it's one second after the most recent passwd change */
1623 } 2142 }
1624 2143
1625 static void 2144 static void
1626 stat_cb (EV_P_ ev_stat *w, int revents) 2145 stat_cb (EV_P_ ev_stat *w, int revents)
1627 { 2146 {
1628 /* reset the one-second timer */ 2147 /* reset the one-second timer */
1629 ev_timer_again (EV_A_ &timer); 2148 ev_timer_again (EV_A_ &timer);
1630 } 2149 }
1631 2150
1632 ... 2151 ...
1633 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 2152 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1634 ev_stat_start (loop, &passwd); 2153 ev_stat_start (loop, &passwd);
1635 ev_timer_init (&timer, timer_cb, 0., 1.01); 2154 ev_timer_init (&timer, timer_cb, 0., 1.02);
1636 2155
1637 2156
1638=head2 C<ev_idle> - when you've got nothing better to do... 2157=head2 C<ev_idle> - when you've got nothing better to do...
1639 2158
1640Idle watchers trigger events when no other events of the same or higher 2159Idle watchers trigger events when no other events of the same or higher
1641priority are pending (prepare, check and other idle watchers do not 2160priority are pending (prepare, check and other idle watchers do not count
1642count). 2161as receiving "events").
1643 2162
1644That is, as long as your process is busy handling sockets or timeouts 2163That is, as long as your process is busy handling sockets or timeouts
1645(or even signals, imagine) of the same or higher priority it will not be 2164(or even signals, imagine) of the same or higher priority it will not be
1646triggered. But when your process is idle (or only lower-priority watchers 2165triggered. But when your process is idle (or only lower-priority watchers
1647are pending), the idle watchers are being called once per event loop 2166are pending), the idle watchers are being called once per event loop
1671=head3 Examples 2190=head3 Examples
1672 2191
1673Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the 2192Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1674callback, free it. Also, use no error checking, as usual. 2193callback, free it. Also, use no error checking, as usual.
1675 2194
1676 static void 2195 static void
1677 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 2196 idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
1678 { 2197 {
1679 free (w); 2198 free (w);
1680 // now do something you wanted to do when the program has 2199 // now do something you wanted to do when the program has
1681 // no longer asnything immediate to do. 2200 // no longer anything immediate to do.
1682 } 2201 }
1683 2202
1684 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 2203 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
1685 ev_idle_init (idle_watcher, idle_cb); 2204 ev_idle_init (idle_watcher, idle_cb);
1686 ev_idle_start (loop, idle_cb); 2205 ev_idle_start (loop, idle_cb);
1687 2206
1688 2207
1689=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2208=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1690 2209
1691Prepare and check watchers are usually (but not always) used in tandem: 2210Prepare and check watchers are usually (but not always) used in pairs:
1692prepare watchers get invoked before the process blocks and check watchers 2211prepare watchers get invoked before the process blocks and check watchers
1693afterwards. 2212afterwards.
1694 2213
1695You I<must not> call C<ev_loop> or similar functions that enter 2214You I<must not> call C<ev_loop> or similar functions that enter
1696the current event loop from either C<ev_prepare> or C<ev_check> 2215the current event loop from either C<ev_prepare> or C<ev_check>
1699those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2218those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1700C<ev_check> so if you have one watcher of each kind they will always be 2219C<ev_check> so if you have one watcher of each kind they will always be
1701called in pairs bracketing the blocking call. 2220called in pairs bracketing the blocking call.
1702 2221
1703Their main purpose is to integrate other event mechanisms into libev and 2222Their main purpose is to integrate other event mechanisms into libev and
1704their use is somewhat advanced. This could be used, for example, to track 2223their use is somewhat advanced. They could be used, for example, to track
1705variable changes, implement your own watchers, integrate net-snmp or a 2224variable changes, implement your own watchers, integrate net-snmp or a
1706coroutine library and lots more. They are also occasionally useful if 2225coroutine library and lots more. They are also occasionally useful if
1707you cache some data and want to flush it before blocking (for example, 2226you cache some data and want to flush it before blocking (for example,
1708in X programs you might want to do an C<XFlush ()> in an C<ev_prepare> 2227in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1709watcher). 2228watcher).
1710 2229
1711This is done by examining in each prepare call which file descriptors need 2230This is done by examining in each prepare call which file descriptors
1712to be watched by the other library, registering C<ev_io> watchers for 2231need to be watched by the other library, registering C<ev_io> watchers
1713them and starting an C<ev_timer> watcher for any timeouts (many libraries 2232for them and starting an C<ev_timer> watcher for any timeouts (many
1714provide just this functionality). Then, in the check watcher you check for 2233libraries provide exactly this functionality). Then, in the check watcher,
1715any events that occured (by checking the pending status of all watchers 2234you check for any events that occurred (by checking the pending status
1716and stopping them) and call back into the library. The I/O and timer 2235of all watchers and stopping them) and call back into the library. The
1717callbacks will never actually be called (but must be valid nevertheless, 2236I/O and timer callbacks will never actually be called (but must be valid
1718because you never know, you know?). 2237nevertheless, because you never know, you know?).
1719 2238
1720As another example, the Perl Coro module uses these hooks to integrate 2239As another example, the Perl Coro module uses these hooks to integrate
1721coroutines into libev programs, by yielding to other active coroutines 2240coroutines into libev programs, by yielding to other active coroutines
1722during each prepare and only letting the process block if no coroutines 2241during each prepare and only letting the process block if no coroutines
1723are ready to run (it's actually more complicated: it only runs coroutines 2242are ready to run (it's actually more complicated: it only runs coroutines
1726loop from blocking if lower-priority coroutines are active, thus mapping 2245loop from blocking if lower-priority coroutines are active, thus mapping
1727low-priority coroutines to idle/background tasks). 2246low-priority coroutines to idle/background tasks).
1728 2247
1729It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 2248It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1730priority, to ensure that they are being run before any other watchers 2249priority, to ensure that they are being run before any other watchers
2250after the poll (this doesn't matter for C<ev_prepare> watchers).
2251
1731after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers, 2252Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
1732too) should not activate ("feed") events into libev. While libev fully 2253activate ("feed") events into libev. While libev fully supports this, they
1733supports this, they will be called before other C<ev_check> watchers 2254might get executed before other C<ev_check> watchers did their job. As
1734did their job. As C<ev_check> watchers are often used to embed other 2255C<ev_check> watchers are often used to embed other (non-libev) event
1735(non-libev) event loops those other event loops might be in an unusable 2256loops those other event loops might be in an unusable state until their
1736state until their C<ev_check> watcher ran (always remind yourself to 2257C<ev_check> watcher ran (always remind yourself to coexist peacefully with
1737coexist peacefully with others). 2258others).
1738 2259
1739=head3 Watcher-Specific Functions and Data Members 2260=head3 Watcher-Specific Functions and Data Members
1740 2261
1741=over 4 2262=over 4
1742 2263
1744 2265
1745=item ev_check_init (ev_check *, callback) 2266=item ev_check_init (ev_check *, callback)
1746 2267
1747Initialises and configures the prepare or check watcher - they have no 2268Initialises and configures the prepare or check watcher - they have no
1748parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 2269parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1749macros, but using them is utterly, utterly and completely pointless. 2270macros, but using them is utterly, utterly, utterly and completely
2271pointless.
1750 2272
1751=back 2273=back
1752 2274
1753=head3 Examples 2275=head3 Examples
1754 2276
1755There are a number of principal ways to embed other event loops or modules 2277There are a number of principal ways to embed other event loops or modules
1756into libev. Here are some ideas on how to include libadns into libev 2278into libev. Here are some ideas on how to include libadns into libev
1757(there is a Perl module named C<EV::ADNS> that does this, which you could 2279(there is a Perl module named C<EV::ADNS> that does this, which you could
1758use for an actually working example. Another Perl module named C<EV::Glib> 2280use as a working example. Another Perl module named C<EV::Glib> embeds a
1759embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV 2281Glib main context into libev, and finally, C<Glib::EV> embeds EV into the
1760into the Glib event loop). 2282Glib event loop).
1761 2283
1762Method 1: Add IO watchers and a timeout watcher in a prepare handler, 2284Method 1: Add IO watchers and a timeout watcher in a prepare handler,
1763and in a check watcher, destroy them and call into libadns. What follows 2285and in a check watcher, destroy them and call into libadns. What follows
1764is pseudo-code only of course. This requires you to either use a low 2286is pseudo-code only of course. This requires you to either use a low
1765priority for the check watcher or use C<ev_clear_pending> explicitly, as 2287priority for the check watcher or use C<ev_clear_pending> explicitly, as
1766the callbacks for the IO/timeout watchers might not have been called yet. 2288the callbacks for the IO/timeout watchers might not have been called yet.
1767 2289
1768 static ev_io iow [nfd]; 2290 static ev_io iow [nfd];
1769 static ev_timer tw; 2291 static ev_timer tw;
1770 2292
1771 static void 2293 static void
1772 io_cb (ev_loop *loop, ev_io *w, int revents) 2294 io_cb (struct ev_loop *loop, ev_io *w, int revents)
1773 { 2295 {
1774 } 2296 }
1775 2297
1776 // create io watchers for each fd and a timer before blocking 2298 // create io watchers for each fd and a timer before blocking
1777 static void 2299 static void
1778 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2300 adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents)
1779 { 2301 {
1780 int timeout = 3600000; 2302 int timeout = 3600000;
1781 struct pollfd fds [nfd]; 2303 struct pollfd fds [nfd];
1782 // actual code will need to loop here and realloc etc. 2304 // actual code will need to loop here and realloc etc.
1783 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2305 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1784 2306
1785 /* the callback is illegal, but won't be called as we stop during check */ 2307 /* the callback is illegal, but won't be called as we stop during check */
1786 ev_timer_init (&tw, 0, timeout * 1e-3); 2308 ev_timer_init (&tw, 0, timeout * 1e-3);
1787 ev_timer_start (loop, &tw); 2309 ev_timer_start (loop, &tw);
1788 2310
1789 // create one ev_io per pollfd 2311 // create one ev_io per pollfd
1790 for (int i = 0; i < nfd; ++i) 2312 for (int i = 0; i < nfd; ++i)
1791 { 2313 {
1792 ev_io_init (iow + i, io_cb, fds [i].fd, 2314 ev_io_init (iow + i, io_cb, fds [i].fd,
1793 ((fds [i].events & POLLIN ? EV_READ : 0) 2315 ((fds [i].events & POLLIN ? EV_READ : 0)
1794 | (fds [i].events & POLLOUT ? EV_WRITE : 0))); 2316 | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1795 2317
1796 fds [i].revents = 0; 2318 fds [i].revents = 0;
1797 ev_io_start (loop, iow + i); 2319 ev_io_start (loop, iow + i);
1798 } 2320 }
1799 } 2321 }
1800 2322
1801 // stop all watchers after blocking 2323 // stop all watchers after blocking
1802 static void 2324 static void
1803 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2325 adns_check_cb (struct ev_loop *loop, ev_check *w, int revents)
1804 { 2326 {
1805 ev_timer_stop (loop, &tw); 2327 ev_timer_stop (loop, &tw);
1806 2328
1807 for (int i = 0; i < nfd; ++i) 2329 for (int i = 0; i < nfd; ++i)
1808 { 2330 {
1809 // set the relevant poll flags 2331 // set the relevant poll flags
1810 // could also call adns_processreadable etc. here 2332 // could also call adns_processreadable etc. here
1811 struct pollfd *fd = fds + i; 2333 struct pollfd *fd = fds + i;
1812 int revents = ev_clear_pending (iow + i); 2334 int revents = ev_clear_pending (iow + i);
1813 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN; 2335 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1814 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT; 2336 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1815 2337
1816 // now stop the watcher 2338 // now stop the watcher
1817 ev_io_stop (loop, iow + i); 2339 ev_io_stop (loop, iow + i);
1818 } 2340 }
1819 2341
1820 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); 2342 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1821 } 2343 }
1822 2344
1823Method 2: This would be just like method 1, but you run C<adns_afterpoll> 2345Method 2: This would be just like method 1, but you run C<adns_afterpoll>
1824in the prepare watcher and would dispose of the check watcher. 2346in the prepare watcher and would dispose of the check watcher.
1825 2347
1826Method 3: If the module to be embedded supports explicit event 2348Method 3: If the module to be embedded supports explicit event
1827notification (adns does), you can also make use of the actual watcher 2349notification (libadns does), you can also make use of the actual watcher
1828callbacks, and only destroy/create the watchers in the prepare watcher. 2350callbacks, and only destroy/create the watchers in the prepare watcher.
1829 2351
1830 static void 2352 static void
1831 timer_cb (EV_P_ ev_timer *w, int revents) 2353 timer_cb (EV_P_ ev_timer *w, int revents)
1832 { 2354 {
1833 adns_state ads = (adns_state)w->data; 2355 adns_state ads = (adns_state)w->data;
1834 update_now (EV_A); 2356 update_now (EV_A);
1835 2357
1836 adns_processtimeouts (ads, &tv_now); 2358 adns_processtimeouts (ads, &tv_now);
1837 } 2359 }
1838 2360
1839 static void 2361 static void
1840 io_cb (EV_P_ ev_io *w, int revents) 2362 io_cb (EV_P_ ev_io *w, int revents)
1841 { 2363 {
1842 adns_state ads = (adns_state)w->data; 2364 adns_state ads = (adns_state)w->data;
1843 update_now (EV_A); 2365 update_now (EV_A);
1844 2366
1845 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now); 2367 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
1846 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now); 2368 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
1847 } 2369 }
1848 2370
1849 // do not ever call adns_afterpoll 2371 // do not ever call adns_afterpoll
1850 2372
1851Method 4: Do not use a prepare or check watcher because the module you 2373Method 4: Do not use a prepare or check watcher because the module you
1852want to embed is too inflexible to support it. Instead, youc na override 2374want to embed is not flexible enough to support it. Instead, you can
1853their poll function. The drawback with this solution is that the main 2375override their poll function. The drawback with this solution is that the
1854loop is now no longer controllable by EV. The C<Glib::EV> module does 2376main loop is now no longer controllable by EV. The C<Glib::EV> module uses
1855this. 2377this approach, effectively embedding EV as a client into the horrible
2378libglib event loop.
1856 2379
1857 static gint 2380 static gint
1858 event_poll_func (GPollFD *fds, guint nfds, gint timeout) 2381 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
1859 { 2382 {
1860 int got_events = 0; 2383 int got_events = 0;
1861 2384
1862 for (n = 0; n < nfds; ++n) 2385 for (n = 0; n < nfds; ++n)
1863 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events 2386 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
1864 2387
1865 if (timeout >= 0) 2388 if (timeout >= 0)
1866 // create/start timer 2389 // create/start timer
1867 2390
1868 // poll 2391 // poll
1869 ev_loop (EV_A_ 0); 2392 ev_loop (EV_A_ 0);
1870 2393
1871 // stop timer again 2394 // stop timer again
1872 if (timeout >= 0) 2395 if (timeout >= 0)
1873 ev_timer_stop (EV_A_ &to); 2396 ev_timer_stop (EV_A_ &to);
1874 2397
1875 // stop io watchers again - their callbacks should have set 2398 // stop io watchers again - their callbacks should have set
1876 for (n = 0; n < nfds; ++n) 2399 for (n = 0; n < nfds; ++n)
1877 ev_io_stop (EV_A_ iow [n]); 2400 ev_io_stop (EV_A_ iow [n]);
1878 2401
1879 return got_events; 2402 return got_events;
1880 } 2403 }
1881 2404
1882 2405
1883=head2 C<ev_embed> - when one backend isn't enough... 2406=head2 C<ev_embed> - when one backend isn't enough...
1884 2407
1885This is a rather advanced watcher type that lets you embed one event loop 2408This is a rather advanced watcher type that lets you embed one event loop
1891prioritise I/O. 2414prioritise I/O.
1892 2415
1893As an example for a bug workaround, the kqueue backend might only support 2416As an example for a bug workaround, the kqueue backend might only support
1894sockets on some platform, so it is unusable as generic backend, but you 2417sockets on some platform, so it is unusable as generic backend, but you
1895still want to make use of it because you have many sockets and it scales 2418still want to make use of it because you have many sockets and it scales
1896so nicely. In this case, you would create a kqueue-based loop and embed it 2419so nicely. In this case, you would create a kqueue-based loop and embed
1897into your default loop (which might use e.g. poll). Overall operation will 2420it into your default loop (which might use e.g. poll). Overall operation
1898be a bit slower because first libev has to poll and then call kevent, but 2421will be a bit slower because first libev has to call C<poll> and then
1899at least you can use both at what they are best. 2422C<kevent>, but at least you can use both mechanisms for what they are
2423best: C<kqueue> for scalable sockets and C<poll> if you want it to work :)
1900 2424
1901As for prioritising I/O: rarely you have the case where some fds have 2425As for prioritising I/O: under rare circumstances you have the case where
1902to be watched and handled very quickly (with low latency), and even 2426some fds have to be watched and handled very quickly (with low latency),
1903priorities and idle watchers might have too much overhead. In this case 2427and even priorities and idle watchers might have too much overhead. In
1904you would put all the high priority stuff in one loop and all the rest in 2428this case you would put all the high priority stuff in one loop and all
1905a second one, and embed the second one in the first. 2429the rest in a second one, and embed the second one in the first.
1906 2430
1907As long as the watcher is active, the callback will be invoked every time 2431As long as the watcher is active, the callback will be invoked every time
1908there might be events pending in the embedded loop. The callback must then 2432there might be events pending in the embedded loop. The callback must then
1909call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2433call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke
1910their callbacks (you could also start an idle watcher to give the embedded 2434their callbacks (you could also start an idle watcher to give the embedded
1918interested in that. 2442interested in that.
1919 2443
1920Also, there have not currently been made special provisions for forking: 2444Also, there have not currently been made special provisions for forking:
1921when you fork, you not only have to call C<ev_loop_fork> on both loops, 2445when you fork, you not only have to call C<ev_loop_fork> on both loops,
1922but you will also have to stop and restart any C<ev_embed> watchers 2446but you will also have to stop and restart any C<ev_embed> watchers
1923yourself. 2447yourself - but you can use a fork watcher to handle this automatically,
2448and future versions of libev might do just that.
1924 2449
1925Unfortunately, not all backends are embeddable, only the ones returned by 2450Unfortunately, not all backends are embeddable: only the ones returned by
1926C<ev_embeddable_backends> are, which, unfortunately, does not include any 2451C<ev_embeddable_backends> are, which, unfortunately, does not include any
1927portable one. 2452portable one.
1928 2453
1929So when you want to use this feature you will always have to be prepared 2454So when you want to use this feature you will always have to be prepared
1930that you cannot get an embeddable loop. The recommended way to get around 2455that you cannot get an embeddable loop. The recommended way to get around
1931this is to have a separate variables for your embeddable loop, try to 2456this is to have a separate variables for your embeddable loop, try to
1932create it, and if that fails, use the normal loop for everything. 2457create it, and if that fails, use the normal loop for everything.
1933 2458
2459=head3 C<ev_embed> and fork
2460
2461While the C<ev_embed> watcher is running, forks in the embedding loop will
2462automatically be applied to the embedded loop as well, so no special
2463fork handling is required in that case. When the watcher is not running,
2464however, it is still the task of the libev user to call C<ev_loop_fork ()>
2465as applicable.
2466
1934=head3 Watcher-Specific Functions and Data Members 2467=head3 Watcher-Specific Functions and Data Members
1935 2468
1936=over 4 2469=over 4
1937 2470
1938=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 2471=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
1941 2474
1942Configures the watcher to embed the given loop, which must be 2475Configures the watcher to embed the given loop, which must be
1943embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 2476embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
1944invoked automatically, otherwise it is the responsibility of the callback 2477invoked automatically, otherwise it is the responsibility of the callback
1945to invoke it (it will continue to be called until the sweep has been done, 2478to invoke it (it will continue to be called until the sweep has been done,
1946if you do not want thta, you need to temporarily stop the embed watcher). 2479if you do not want that, you need to temporarily stop the embed watcher).
1947 2480
1948=item ev_embed_sweep (loop, ev_embed *) 2481=item ev_embed_sweep (loop, ev_embed *)
1949 2482
1950Make a single, non-blocking sweep over the embedded loop. This works 2483Make a single, non-blocking sweep over the embedded loop. This works
1951similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 2484similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1952apropriate way for embedded loops. 2485appropriate way for embedded loops.
1953 2486
1954=item struct ev_loop *other [read-only] 2487=item struct ev_loop *other [read-only]
1955 2488
1956The embedded event loop. 2489The embedded event loop.
1957 2490
1959 2492
1960=head3 Examples 2493=head3 Examples
1961 2494
1962Example: Try to get an embeddable event loop and embed it into the default 2495Example: Try to get an embeddable event loop and embed it into the default
1963event loop. If that is not possible, use the default loop. The default 2496event loop. If that is not possible, use the default loop. The default
1964loop is stored in C<loop_hi>, while the mebeddable loop is stored in 2497loop is stored in C<loop_hi>, while the embeddable loop is stored in
1965C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be 2498C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
1966used). 2499used).
1967 2500
1968 struct ev_loop *loop_hi = ev_default_init (0); 2501 struct ev_loop *loop_hi = ev_default_init (0);
1969 struct ev_loop *loop_lo = 0; 2502 struct ev_loop *loop_lo = 0;
1970 struct ev_embed embed; 2503 ev_embed embed;
1971 2504
1972 // see if there is a chance of getting one that works 2505 // see if there is a chance of getting one that works
1973 // (remember that a flags value of 0 means autodetection) 2506 // (remember that a flags value of 0 means autodetection)
1974 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2507 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
1975 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2508 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
1976 : 0; 2509 : 0;
1977 2510
1978 // if we got one, then embed it, otherwise default to loop_hi 2511 // if we got one, then embed it, otherwise default to loop_hi
1979 if (loop_lo) 2512 if (loop_lo)
1980 { 2513 {
1981 ev_embed_init (&embed, 0, loop_lo); 2514 ev_embed_init (&embed, 0, loop_lo);
1982 ev_embed_start (loop_hi, &embed); 2515 ev_embed_start (loop_hi, &embed);
1983 } 2516 }
1984 else 2517 else
1985 loop_lo = loop_hi; 2518 loop_lo = loop_hi;
1986 2519
1987Example: Check if kqueue is available but not recommended and create 2520Example: Check if kqueue is available but not recommended and create
1988a kqueue backend for use with sockets (which usually work with any 2521a kqueue backend for use with sockets (which usually work with any
1989kqueue implementation). Store the kqueue/socket-only event loop in 2522kqueue implementation). Store the kqueue/socket-only event loop in
1990C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 2523C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
1991 2524
1992 struct ev_loop *loop = ev_default_init (0); 2525 struct ev_loop *loop = ev_default_init (0);
1993 struct ev_loop *loop_socket = 0; 2526 struct ev_loop *loop_socket = 0;
1994 struct ev_embed embed; 2527 ev_embed embed;
1995 2528
1996 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2529 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
1997 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2530 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
1998 { 2531 {
1999 ev_embed_init (&embed, 0, loop_socket); 2532 ev_embed_init (&embed, 0, loop_socket);
2000 ev_embed_start (loop, &embed); 2533 ev_embed_start (loop, &embed);
2001 } 2534 }
2002 2535
2003 if (!loop_socket) 2536 if (!loop_socket)
2004 loop_socket = loop; 2537 loop_socket = loop;
2005 2538
2006 // now use loop_socket for all sockets, and loop for everything else 2539 // now use loop_socket for all sockets, and loop for everything else
2007 2540
2008 2541
2009=head2 C<ev_fork> - the audacity to resume the event loop after a fork 2542=head2 C<ev_fork> - the audacity to resume the event loop after a fork
2010 2543
2011Fork watchers are called when a C<fork ()> was detected (usually because 2544Fork watchers are called when a C<fork ()> was detected (usually because
2027believe me. 2560believe me.
2028 2561
2029=back 2562=back
2030 2563
2031 2564
2565=head2 C<ev_async> - how to wake up another event loop
2566
2567In general, you cannot use an C<ev_loop> from multiple threads or other
2568asynchronous sources such as signal handlers (as opposed to multiple event
2569loops - those are of course safe to use in different threads).
2570
2571Sometimes, however, you need to wake up another event loop you do not
2572control, for example because it belongs to another thread. This is what
2573C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
2574can signal it by calling C<ev_async_send>, which is thread- and signal
2575safe.
2576
2577This functionality is very similar to C<ev_signal> watchers, as signals,
2578too, are asynchronous in nature, and signals, too, will be compressed
2579(i.e. the number of callback invocations may be less than the number of
2580C<ev_async_sent> calls).
2581
2582Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
2583just the default loop.
2584
2585=head3 Queueing
2586
2587C<ev_async> does not support queueing of data in any way. The reason
2588is that the author does not know of a simple (or any) algorithm for a
2589multiple-writer-single-reader queue that works in all cases and doesn't
2590need elaborate support such as pthreads.
2591
2592That means that if you want to queue data, you have to provide your own
2593queue. But at least I can tell you how to implement locking around your
2594queue:
2595
2596=over 4
2597
2598=item queueing from a signal handler context
2599
2600To implement race-free queueing, you simply add to the queue in the signal
2601handler but you block the signal handler in the watcher callback. Here is
2602an example that does that for some fictitious SIGUSR1 handler:
2603
2604 static ev_async mysig;
2605
2606 static void
2607 sigusr1_handler (void)
2608 {
2609 sometype data;
2610
2611 // no locking etc.
2612 queue_put (data);
2613 ev_async_send (EV_DEFAULT_ &mysig);
2614 }
2615
2616 static void
2617 mysig_cb (EV_P_ ev_async *w, int revents)
2618 {
2619 sometype data;
2620 sigset_t block, prev;
2621
2622 sigemptyset (&block);
2623 sigaddset (&block, SIGUSR1);
2624 sigprocmask (SIG_BLOCK, &block, &prev);
2625
2626 while (queue_get (&data))
2627 process (data);
2628
2629 if (sigismember (&prev, SIGUSR1)
2630 sigprocmask (SIG_UNBLOCK, &block, 0);
2631 }
2632
2633(Note: pthreads in theory requires you to use C<pthread_setmask>
2634instead of C<sigprocmask> when you use threads, but libev doesn't do it
2635either...).
2636
2637=item queueing from a thread context
2638
2639The strategy for threads is different, as you cannot (easily) block
2640threads but you can easily preempt them, so to queue safely you need to
2641employ a traditional mutex lock, such as in this pthread example:
2642
2643 static ev_async mysig;
2644 static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
2645
2646 static void
2647 otherthread (void)
2648 {
2649 // only need to lock the actual queueing operation
2650 pthread_mutex_lock (&mymutex);
2651 queue_put (data);
2652 pthread_mutex_unlock (&mymutex);
2653
2654 ev_async_send (EV_DEFAULT_ &mysig);
2655 }
2656
2657 static void
2658 mysig_cb (EV_P_ ev_async *w, int revents)
2659 {
2660 pthread_mutex_lock (&mymutex);
2661
2662 while (queue_get (&data))
2663 process (data);
2664
2665 pthread_mutex_unlock (&mymutex);
2666 }
2667
2668=back
2669
2670
2671=head3 Watcher-Specific Functions and Data Members
2672
2673=over 4
2674
2675=item ev_async_init (ev_async *, callback)
2676
2677Initialises and configures the async watcher - it has no parameters of any
2678kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2679trust me.
2680
2681=item ev_async_send (loop, ev_async *)
2682
2683Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2684an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2685C<ev_feed_event>, this call is safe to do from other threads, signal or
2686similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2687section below on what exactly this means).
2688
2689This call incurs the overhead of a system call only once per loop iteration,
2690so while the overhead might be noticeable, it doesn't apply to repeated
2691calls to C<ev_async_send>.
2692
2693=item bool = ev_async_pending (ev_async *)
2694
2695Returns a non-zero value when C<ev_async_send> has been called on the
2696watcher but the event has not yet been processed (or even noted) by the
2697event loop.
2698
2699C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2700the loop iterates next and checks for the watcher to have become active,
2701it will reset the flag again. C<ev_async_pending> can be used to very
2702quickly check whether invoking the loop might be a good idea.
2703
2704Not that this does I<not> check whether the watcher itself is pending, only
2705whether it has been requested to make this watcher pending.
2706
2707=back
2708
2709
2032=head1 OTHER FUNCTIONS 2710=head1 OTHER FUNCTIONS
2033 2711
2034There are some other functions of possible interest. Described. Here. Now. 2712There are some other functions of possible interest. Described. Here. Now.
2035 2713
2036=over 4 2714=over 4
2037 2715
2038=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 2716=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
2039 2717
2040This function combines a simple timer and an I/O watcher, calls your 2718This function combines a simple timer and an I/O watcher, calls your
2041callback on whichever event happens first and automatically stop both 2719callback on whichever event happens first and automatically stops both
2042watchers. This is useful if you want to wait for a single event on an fd 2720watchers. This is useful if you want to wait for a single event on an fd
2043or timeout without having to allocate/configure/start/stop/free one or 2721or timeout without having to allocate/configure/start/stop/free one or
2044more watchers yourself. 2722more watchers yourself.
2045 2723
2046If C<fd> is less than 0, then no I/O watcher will be started and events 2724If C<fd> is less than 0, then no I/O watcher will be started and the
2047is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and 2725C<events> argument is being ignored. Otherwise, an C<ev_io> watcher for
2048C<events> set will be craeted and started. 2726the given C<fd> and C<events> set will be created and started.
2049 2727
2050If C<timeout> is less than 0, then no timeout watcher will be 2728If C<timeout> is less than 0, then no timeout watcher will be
2051started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 2729started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2052repeat = 0) will be started. While C<0> is a valid timeout, it is of 2730repeat = 0) will be started. C<0> is a valid timeout.
2053dubious value.
2054 2731
2055The callback has the type C<void (*cb)(int revents, void *arg)> and gets 2732The callback has the type C<void (*cb)(int revents, void *arg)> and gets
2056passed an C<revents> set like normal event callbacks (a combination of 2733passed an C<revents> set like normal event callbacks (a combination of
2057C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 2734C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
2058value passed to C<ev_once>: 2735value passed to C<ev_once>. Note that it is possible to receive I<both>
2736a timeout and an io event at the same time - you probably should give io
2737events precedence.
2059 2738
2739Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2740
2060 static void stdin_ready (int revents, void *arg) 2741 static void stdin_ready (int revents, void *arg)
2061 { 2742 {
2062 if (revents & EV_TIMEOUT)
2063 /* doh, nothing entered */;
2064 else if (revents & EV_READ) 2743 if (revents & EV_READ)
2065 /* stdin might have data for us, joy! */; 2744 /* stdin might have data for us, joy! */;
2745 else if (revents & EV_TIMEOUT)
2746 /* doh, nothing entered */;
2066 } 2747 }
2067 2748
2068 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 2749 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2069 2750
2070=item ev_feed_event (ev_loop *, watcher *, int revents) 2751=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2071 2752
2072Feeds the given event set into the event loop, as if the specified event 2753Feeds the given event set into the event loop, as if the specified event
2073had happened for the specified watcher (which must be a pointer to an 2754had happened for the specified watcher (which must be a pointer to an
2074initialised but not necessarily started event watcher). 2755initialised but not necessarily started event watcher).
2075 2756
2076=item ev_feed_fd_event (ev_loop *, int fd, int revents) 2757=item ev_feed_fd_event (struct ev_loop *, int fd, int revents)
2077 2758
2078Feed an event on the given fd, as if a file descriptor backend detected 2759Feed an event on the given fd, as if a file descriptor backend detected
2079the given events it. 2760the given events it.
2080 2761
2081=item ev_feed_signal_event (ev_loop *loop, int signum) 2762=item ev_feed_signal_event (struct ev_loop *loop, int signum)
2082 2763
2083Feed an event as if the given signal occured (C<loop> must be the default 2764Feed an event as if the given signal occurred (C<loop> must be the default
2084loop!). 2765loop!).
2085 2766
2086=back 2767=back
2087 2768
2088 2769
2104 2785
2105=item * Priorities are not currently supported. Initialising priorities 2786=item * Priorities are not currently supported. Initialising priorities
2106will fail and all watchers will have the same priority, even though there 2787will fail and all watchers will have the same priority, even though there
2107is an ev_pri field. 2788is an ev_pri field.
2108 2789
2790=item * In libevent, the last base created gets the signals, in libev, the
2791first base created (== the default loop) gets the signals.
2792
2109=item * Other members are not supported. 2793=item * Other members are not supported.
2110 2794
2111=item * The libev emulation is I<not> ABI compatible to libevent, you need 2795=item * The libev emulation is I<not> ABI compatible to libevent, you need
2112to use the libev header file and library. 2796to use the libev header file and library.
2113 2797
2114=back 2798=back
2115 2799
2116=head1 C++ SUPPORT 2800=head1 C++ SUPPORT
2117 2801
2118Libev comes with some simplistic wrapper classes for C++ that mainly allow 2802Libev comes with some simplistic wrapper classes for C++ that mainly allow
2119you to use some convinience methods to start/stop watchers and also change 2803you to use some convenience methods to start/stop watchers and also change
2120the callback model to a model using method callbacks on objects. 2804the callback model to a model using method callbacks on objects.
2121 2805
2122To use it, 2806To use it,
2123 2807
2124 #include <ev++.h> 2808 #include <ev++.h>
2125 2809
2126This automatically includes F<ev.h> and puts all of its definitions (many 2810This automatically includes F<ev.h> and puts all of its definitions (many
2127of them macros) into the global namespace. All C++ specific things are 2811of them macros) into the global namespace. All C++ specific things are
2128put into the C<ev> namespace. It should support all the same embedding 2812put into the C<ev> namespace. It should support all the same embedding
2129options as F<ev.h>, most notably C<EV_MULTIPLICITY>. 2813options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
2196your compiler is good :), then the method will be fully inlined into the 2880your compiler is good :), then the method will be fully inlined into the
2197thunking function, making it as fast as a direct C callback. 2881thunking function, making it as fast as a direct C callback.
2198 2882
2199Example: simple class declaration and watcher initialisation 2883Example: simple class declaration and watcher initialisation
2200 2884
2201 struct myclass 2885 struct myclass
2202 { 2886 {
2203 void io_cb (ev::io &w, int revents) { } 2887 void io_cb (ev::io &w, int revents) { }
2204 } 2888 }
2205 2889
2206 myclass obj; 2890 myclass obj;
2207 ev::io iow; 2891 ev::io iow;
2208 iow.set <myclass, &myclass::io_cb> (&obj); 2892 iow.set <myclass, &myclass::io_cb> (&obj);
2209 2893
2210=item w->set<function> (void *data = 0) 2894=item w->set<function> (void *data = 0)
2211 2895
2212Also sets a callback, but uses a static method or plain function as 2896Also sets a callback, but uses a static method or plain function as
2213callback. The optional C<data> argument will be stored in the watcher's 2897callback. The optional C<data> argument will be stored in the watcher's
2215 2899
2216The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. 2900The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
2217 2901
2218See the method-C<set> above for more details. 2902See the method-C<set> above for more details.
2219 2903
2220Example: 2904Example: Use a plain function as callback.
2221 2905
2222 static void io_cb (ev::io &w, int revents) { } 2906 static void io_cb (ev::io &w, int revents) { }
2223 iow.set <io_cb> (); 2907 iow.set <io_cb> ();
2224 2908
2225=item w->set (struct ev_loop *) 2909=item w->set (struct ev_loop *)
2226 2910
2227Associates a different C<struct ev_loop> with this watcher. You can only 2911Associates a different C<struct ev_loop> with this watcher. You can only
2228do this when the watcher is inactive (and not pending either). 2912do this when the watcher is inactive (and not pending either).
2229 2913
2230=item w->set ([args]) 2914=item w->set ([arguments])
2231 2915
2232Basically the same as C<ev_TYPE_set>, with the same args. Must be 2916Basically the same as C<ev_TYPE_set>, with the same arguments. Must be
2233called at least once. Unlike the C counterpart, an active watcher gets 2917called at least once. Unlike the C counterpart, an active watcher gets
2234automatically stopped and restarted when reconfiguring it with this 2918automatically stopped and restarted when reconfiguring it with this
2235method. 2919method.
2236 2920
2237=item w->start () 2921=item w->start ()
2261=back 2945=back
2262 2946
2263Example: Define a class with an IO and idle watcher, start one of them in 2947Example: Define a class with an IO and idle watcher, start one of them in
2264the constructor. 2948the constructor.
2265 2949
2266 class myclass 2950 class myclass
2267 { 2951 {
2268 ev_io io; void io_cb (ev::io &w, int revents); 2952 ev::io io ; void io_cb (ev::io &w, int revents);
2269 ev_idle idle void idle_cb (ev::idle &w, int revents); 2953 ev::idle idle; void idle_cb (ev::idle &w, int revents);
2270 2954
2271 myclass (); 2955 myclass (int fd)
2272 } 2956 {
2273
2274 myclass::myclass (int fd)
2275 {
2276 io .set <myclass, &myclass::io_cb > (this); 2957 io .set <myclass, &myclass::io_cb > (this);
2277 idle.set <myclass, &myclass::idle_cb> (this); 2958 idle.set <myclass, &myclass::idle_cb> (this);
2278 2959
2279 io.start (fd, ev::READ); 2960 io.start (fd, ev::READ);
2961 }
2280 } 2962 };
2963
2964
2965=head1 OTHER LANGUAGE BINDINGS
2966
2967Libev does not offer other language bindings itself, but bindings for a
2968number of languages exist in the form of third-party packages. If you know
2969any interesting language binding in addition to the ones listed here, drop
2970me a note.
2971
2972=over 4
2973
2974=item Perl
2975
2976The EV module implements the full libev API and is actually used to test
2977libev. EV is developed together with libev. Apart from the EV core module,
2978there are additional modules that implement libev-compatible interfaces
2979to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays),
2980C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV>
2981and C<EV::Glib>).
2982
2983It can be found and installed via CPAN, its homepage is at
2984L<http://software.schmorp.de/pkg/EV>.
2985
2986=item Python
2987
2988Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2989seems to be quite complete and well-documented. Note, however, that the
2990patch they require for libev is outright dangerous as it breaks the ABI
2991for everybody else, and therefore, should never be applied in an installed
2992libev (if python requires an incompatible ABI then it needs to embed
2993libev).
2994
2995=item Ruby
2996
2997Tony Arcieri has written a ruby extension that offers access to a subset
2998of the libev API and adds file handle abstractions, asynchronous DNS and
2999more on top of it. It can be found via gem servers. Its homepage is at
3000L<http://rev.rubyforge.org/>.
3001
3002=item D
3003
3004Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3005be found at L<http://proj.llucax.com.ar/wiki/evd>.
3006
3007=item Ocaml
3008
3009Erkki Seppala has written Ocaml bindings for libev, to be found at
3010L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3011
3012=back
2281 3013
2282 3014
2283=head1 MACRO MAGIC 3015=head1 MACRO MAGIC
2284 3016
2285Libev can be compiled with a variety of options, the most fundamantal 3017Libev can be compiled with a variety of options, the most fundamental
2286of which is C<EV_MULTIPLICITY>. This option determines whether (most) 3018of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2287functions and callbacks have an initial C<struct ev_loop *> argument. 3019functions and callbacks have an initial C<struct ev_loop *> argument.
2288 3020
2289To make it easier to write programs that cope with either variant, the 3021To make it easier to write programs that cope with either variant, the
2290following macros are defined: 3022following macros are defined:
2295 3027
2296This provides the loop I<argument> for functions, if one is required ("ev 3028This provides the loop I<argument> for functions, if one is required ("ev
2297loop argument"). The C<EV_A> form is used when this is the sole argument, 3029loop argument"). The C<EV_A> form is used when this is the sole argument,
2298C<EV_A_> is used when other arguments are following. Example: 3030C<EV_A_> is used when other arguments are following. Example:
2299 3031
2300 ev_unref (EV_A); 3032 ev_unref (EV_A);
2301 ev_timer_add (EV_A_ watcher); 3033 ev_timer_add (EV_A_ watcher);
2302 ev_loop (EV_A_ 0); 3034 ev_loop (EV_A_ 0);
2303 3035
2304It assumes the variable C<loop> of type C<struct ev_loop *> is in scope, 3036It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
2305which is often provided by the following macro. 3037which is often provided by the following macro.
2306 3038
2307=item C<EV_P>, C<EV_P_> 3039=item C<EV_P>, C<EV_P_>
2308 3040
2309This provides the loop I<parameter> for functions, if one is required ("ev 3041This provides the loop I<parameter> for functions, if one is required ("ev
2310loop parameter"). The C<EV_P> form is used when this is the sole parameter, 3042loop parameter"). The C<EV_P> form is used when this is the sole parameter,
2311C<EV_P_> is used when other parameters are following. Example: 3043C<EV_P_> is used when other parameters are following. Example:
2312 3044
2313 // this is how ev_unref is being declared 3045 // this is how ev_unref is being declared
2314 static void ev_unref (EV_P); 3046 static void ev_unref (EV_P);
2315 3047
2316 // this is how you can declare your typical callback 3048 // this is how you can declare your typical callback
2317 static void cb (EV_P_ ev_timer *w, int revents) 3049 static void cb (EV_P_ ev_timer *w, int revents)
2318 3050
2319It declares a parameter C<loop> of type C<struct ev_loop *>, quite 3051It declares a parameter C<loop> of type C<struct ev_loop *>, quite
2320suitable for use with C<EV_A>. 3052suitable for use with C<EV_A>.
2321 3053
2322=item C<EV_DEFAULT>, C<EV_DEFAULT_> 3054=item C<EV_DEFAULT>, C<EV_DEFAULT_>
2323 3055
2324Similar to the other two macros, this gives you the value of the default 3056Similar to the other two macros, this gives you the value of the default
2325loop, if multiple loops are supported ("ev loop default"). 3057loop, if multiple loops are supported ("ev loop default").
3058
3059=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
3060
3061Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
3062default loop has been initialised (C<UC> == unchecked). Their behaviour
3063is undefined when the default loop has not been initialised by a previous
3064execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>.
3065
3066It is often prudent to use C<EV_DEFAULT> when initialising the first
3067watcher in a function but use C<EV_DEFAULT_UC> afterwards.
2326 3068
2327=back 3069=back
2328 3070
2329Example: Declare and initialise a check watcher, utilising the above 3071Example: Declare and initialise a check watcher, utilising the above
2330macros so it will work regardless of whether multiple loops are supported 3072macros so it will work regardless of whether multiple loops are supported
2331or not. 3073or not.
2332 3074
2333 static void 3075 static void
2334 check_cb (EV_P_ ev_timer *w, int revents) 3076 check_cb (EV_P_ ev_timer *w, int revents)
2335 { 3077 {
2336 ev_check_stop (EV_A_ w); 3078 ev_check_stop (EV_A_ w);
2337 } 3079 }
2338 3080
2339 ev_check check; 3081 ev_check check;
2340 ev_check_init (&check, check_cb); 3082 ev_check_init (&check, check_cb);
2341 ev_check_start (EV_DEFAULT_ &check); 3083 ev_check_start (EV_DEFAULT_ &check);
2342 ev_loop (EV_DEFAULT_ 0); 3084 ev_loop (EV_DEFAULT_ 0);
2343 3085
2344=head1 EMBEDDING 3086=head1 EMBEDDING
2345 3087
2346Libev can (and often is) directly embedded into host 3088Libev can (and often is) directly embedded into host
2347applications. Examples of applications that embed it include the Deliantra 3089applications. Examples of applications that embed it include the Deliantra
2354libev somewhere in your source tree). 3096libev somewhere in your source tree).
2355 3097
2356=head2 FILESETS 3098=head2 FILESETS
2357 3099
2358Depending on what features you need you need to include one or more sets of files 3100Depending on what features you need you need to include one or more sets of files
2359in your app. 3101in your application.
2360 3102
2361=head3 CORE EVENT LOOP 3103=head3 CORE EVENT LOOP
2362 3104
2363To include only the libev core (all the C<ev_*> functions), with manual 3105To include only the libev core (all the C<ev_*> functions), with manual
2364configuration (no autoconf): 3106configuration (no autoconf):
2365 3107
2366 #define EV_STANDALONE 1 3108 #define EV_STANDALONE 1
2367 #include "ev.c" 3109 #include "ev.c"
2368 3110
2369This will automatically include F<ev.h>, too, and should be done in a 3111This will automatically include F<ev.h>, too, and should be done in a
2370single C source file only to provide the function implementations. To use 3112single C source file only to provide the function implementations. To use
2371it, do the same for F<ev.h> in all files wishing to use this API (best 3113it, do the same for F<ev.h> in all files wishing to use this API (best
2372done by writing a wrapper around F<ev.h> that you can include instead and 3114done by writing a wrapper around F<ev.h> that you can include instead and
2373where you can put other configuration options): 3115where you can put other configuration options):
2374 3116
2375 #define EV_STANDALONE 1 3117 #define EV_STANDALONE 1
2376 #include "ev.h" 3118 #include "ev.h"
2377 3119
2378Both header files and implementation files can be compiled with a C++ 3120Both header files and implementation files can be compiled with a C++
2379compiler (at least, thats a stated goal, and breakage will be treated 3121compiler (at least, that's a stated goal, and breakage will be treated
2380as a bug). 3122as a bug).
2381 3123
2382You need the following files in your source tree, or in a directory 3124You need the following files in your source tree, or in a directory
2383in your include path (e.g. in libev/ when using -Ilibev): 3125in your include path (e.g. in libev/ when using -Ilibev):
2384 3126
2385 ev.h 3127 ev.h
2386 ev.c 3128 ev.c
2387 ev_vars.h 3129 ev_vars.h
2388 ev_wrap.h 3130 ev_wrap.h
2389 3131
2390 ev_win32.c required on win32 platforms only 3132 ev_win32.c required on win32 platforms only
2391 3133
2392 ev_select.c only when select backend is enabled (which is enabled by default) 3134 ev_select.c only when select backend is enabled (which is enabled by default)
2393 ev_poll.c only when poll backend is enabled (disabled by default) 3135 ev_poll.c only when poll backend is enabled (disabled by default)
2394 ev_epoll.c only when the epoll backend is enabled (disabled by default) 3136 ev_epoll.c only when the epoll backend is enabled (disabled by default)
2395 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 3137 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
2396 ev_port.c only when the solaris port backend is enabled (disabled by default) 3138 ev_port.c only when the solaris port backend is enabled (disabled by default)
2397 3139
2398F<ev.c> includes the backend files directly when enabled, so you only need 3140F<ev.c> includes the backend files directly when enabled, so you only need
2399to compile this single file. 3141to compile this single file.
2400 3142
2401=head3 LIBEVENT COMPATIBILITY API 3143=head3 LIBEVENT COMPATIBILITY API
2402 3144
2403To include the libevent compatibility API, also include: 3145To include the libevent compatibility API, also include:
2404 3146
2405 #include "event.c" 3147 #include "event.c"
2406 3148
2407in the file including F<ev.c>, and: 3149in the file including F<ev.c>, and:
2408 3150
2409 #include "event.h" 3151 #include "event.h"
2410 3152
2411in the files that want to use the libevent API. This also includes F<ev.h>. 3153in the files that want to use the libevent API. This also includes F<ev.h>.
2412 3154
2413You need the following additional files for this: 3155You need the following additional files for this:
2414 3156
2415 event.h 3157 event.h
2416 event.c 3158 event.c
2417 3159
2418=head3 AUTOCONF SUPPORT 3160=head3 AUTOCONF SUPPORT
2419 3161
2420Instead of using C<EV_STANDALONE=1> and providing your config in 3162Instead of using C<EV_STANDALONE=1> and providing your configuration in
2421whatever way you want, you can also C<m4_include([libev.m4])> in your 3163whatever way you want, you can also C<m4_include([libev.m4])> in your
2422F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then 3164F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
2423include F<config.h> and configure itself accordingly. 3165include F<config.h> and configure itself accordingly.
2424 3166
2425For this of course you need the m4 file: 3167For this of course you need the m4 file:
2426 3168
2427 libev.m4 3169 libev.m4
2428 3170
2429=head2 PREPROCESSOR SYMBOLS/MACROS 3171=head2 PREPROCESSOR SYMBOLS/MACROS
2430 3172
2431Libev can be configured via a variety of preprocessor symbols you have to define 3173Libev can be configured via a variety of preprocessor symbols you have to
2432before including any of its files. The default is not to build for multiplicity 3174define before including any of its files. The default in the absence of
2433and only include the select backend. 3175autoconf is documented for every option.
2434 3176
2435=over 4 3177=over 4
2436 3178
2437=item EV_STANDALONE 3179=item EV_STANDALONE
2438 3180
2443F<event.h> that are not directly supported by the libev core alone. 3185F<event.h> that are not directly supported by the libev core alone.
2444 3186
2445=item EV_USE_MONOTONIC 3187=item EV_USE_MONOTONIC
2446 3188
2447If defined to be C<1>, libev will try to detect the availability of the 3189If defined to be C<1>, libev will try to detect the availability of the
2448monotonic clock option at both compiletime and runtime. Otherwise no use 3190monotonic clock option at both compile time and runtime. Otherwise no use
2449of the monotonic clock option will be attempted. If you enable this, you 3191of the monotonic clock option will be attempted. If you enable this, you
2450usually have to link against librt or something similar. Enabling it when 3192usually have to link against librt or something similar. Enabling it when
2451the functionality isn't available is safe, though, although you have 3193the functionality isn't available is safe, though, although you have
2452to make sure you link against any libraries where the C<clock_gettime> 3194to make sure you link against any libraries where the C<clock_gettime>
2453function is hiding in (often F<-lrt>). 3195function is hiding in (often F<-lrt>).
2454 3196
2455=item EV_USE_REALTIME 3197=item EV_USE_REALTIME
2456 3198
2457If defined to be C<1>, libev will try to detect the availability of the 3199If defined to be C<1>, libev will try to detect the availability of the
2458realtime clock option at compiletime (and assume its availability at 3200real-time clock option at compile time (and assume its availability at
2459runtime if successful). Otherwise no use of the realtime clock option will 3201runtime if successful). Otherwise no use of the real-time clock option will
2460be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3202be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2461(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3203(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2462note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3204note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2463 3205
2464=item EV_USE_NANOSLEEP 3206=item EV_USE_NANOSLEEP
2465 3207
2466If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3208If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2467and will use it for delays. Otherwise it will use C<select ()>. 3209and will use it for delays. Otherwise it will use C<select ()>.
2468 3210
3211=item EV_USE_EVENTFD
3212
3213If defined to be C<1>, then libev will assume that C<eventfd ()> is
3214available and will probe for kernel support at runtime. This will improve
3215C<ev_signal> and C<ev_async> performance and reduce resource consumption.
3216If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
32172.7 or newer, otherwise disabled.
3218
2469=item EV_USE_SELECT 3219=item EV_USE_SELECT
2470 3220
2471If undefined or defined to be C<1>, libev will compile in support for the 3221If undefined or defined to be C<1>, libev will compile in support for the
2472C<select>(2) backend. No attempt at autodetection will be done: if no 3222C<select>(2) backend. No attempt at auto-detection will be done: if no
2473other method takes over, select will be it. Otherwise the select backend 3223other method takes over, select will be it. Otherwise the select backend
2474will not be compiled in. 3224will not be compiled in.
2475 3225
2476=item EV_SELECT_USE_FD_SET 3226=item EV_SELECT_USE_FD_SET
2477 3227
2478If defined to C<1>, then the select backend will use the system C<fd_set> 3228If defined to C<1>, then the select backend will use the system C<fd_set>
2479structure. This is useful if libev doesn't compile due to a missing 3229structure. This is useful if libev doesn't compile due to a missing
2480C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on 3230C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on
2481exotic systems. This usually limits the range of file descriptors to some 3231exotic systems. This usually limits the range of file descriptors to some
2482low limit such as 1024 or might have other limitations (winsocket only 3232low limit such as 1024 or might have other limitations (winsocket only
2483allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3233allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
2484influence the size of the C<fd_set> used. 3234influence the size of the C<fd_set> used.
2485 3235
2491be used is the winsock select). This means that it will call 3241be used is the winsock select). This means that it will call
2492C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3242C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
2493it is assumed that all these functions actually work on fds, even 3243it is assumed that all these functions actually work on fds, even
2494on win32. Should not be defined on non-win32 platforms. 3244on win32. Should not be defined on non-win32 platforms.
2495 3245
3246=item EV_FD_TO_WIN32_HANDLE
3247
3248If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3249file descriptors to socket handles. When not defining this symbol (the
3250default), then libev will call C<_get_osfhandle>, which is usually
3251correct. In some cases, programs use their own file descriptor management,
3252in which case they can provide this function to map fds to socket handles.
3253
2496=item EV_USE_POLL 3254=item EV_USE_POLL
2497 3255
2498If defined to be C<1>, libev will compile in support for the C<poll>(2) 3256If defined to be C<1>, libev will compile in support for the C<poll>(2)
2499backend. Otherwise it will be enabled on non-win32 platforms. It 3257backend. Otherwise it will be enabled on non-win32 platforms. It
2500takes precedence over select. 3258takes precedence over select.
2501 3259
2502=item EV_USE_EPOLL 3260=item EV_USE_EPOLL
2503 3261
2504If defined to be C<1>, libev will compile in support for the Linux 3262If defined to be C<1>, libev will compile in support for the Linux
2505C<epoll>(7) backend. Its availability will be detected at runtime, 3263C<epoll>(7) backend. Its availability will be detected at runtime,
2506otherwise another method will be used as fallback. This is the 3264otherwise another method will be used as fallback. This is the preferred
2507preferred backend for GNU/Linux systems. 3265backend for GNU/Linux systems. If undefined, it will be enabled if the
3266headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2508 3267
2509=item EV_USE_KQUEUE 3268=item EV_USE_KQUEUE
2510 3269
2511If defined to be C<1>, libev will compile in support for the BSD style 3270If defined to be C<1>, libev will compile in support for the BSD style
2512C<kqueue>(2) backend. Its actual availability will be detected at runtime, 3271C<kqueue>(2) backend. Its actual availability will be detected at runtime,
2525otherwise another method will be used as fallback. This is the preferred 3284otherwise another method will be used as fallback. This is the preferred
2526backend for Solaris 10 systems. 3285backend for Solaris 10 systems.
2527 3286
2528=item EV_USE_DEVPOLL 3287=item EV_USE_DEVPOLL
2529 3288
2530reserved for future expansion, works like the USE symbols above. 3289Reserved for future expansion, works like the USE symbols above.
2531 3290
2532=item EV_USE_INOTIFY 3291=item EV_USE_INOTIFY
2533 3292
2534If defined to be C<1>, libev will compile in support for the Linux inotify 3293If defined to be C<1>, libev will compile in support for the Linux inotify
2535interface to speed up C<ev_stat> watchers. Its actual availability will 3294interface to speed up C<ev_stat> watchers. Its actual availability will
2536be detected at runtime. 3295be detected at runtime. If undefined, it will be enabled if the headers
3296indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
3297
3298=item EV_ATOMIC_T
3299
3300Libev requires an integer type (suitable for storing C<0> or C<1>) whose
3301access is atomic with respect to other threads or signal contexts. No such
3302type is easily found in the C language, so you can provide your own type
3303that you know is safe for your purposes. It is used both for signal handler "locking"
3304as well as for signal and thread safety in C<ev_async> watchers.
3305
3306In the absence of this define, libev will use C<sig_atomic_t volatile>
3307(from F<signal.h>), which is usually good enough on most platforms.
2537 3308
2538=item EV_H 3309=item EV_H
2539 3310
2540The name of the F<ev.h> header file used to include it. The default if 3311The name of the F<ev.h> header file used to include it. The default if
2541undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to 3312undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2542virtually rename the F<ev.h> header file in case of conflicts. 3313used to virtually rename the F<ev.h> header file in case of conflicts.
2543 3314
2544=item EV_CONFIG_H 3315=item EV_CONFIG_H
2545 3316
2546If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3317If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2547F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3318F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2548C<EV_H>, above. 3319C<EV_H>, above.
2549 3320
2550=item EV_EVENT_H 3321=item EV_EVENT_H
2551 3322
2552Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3323Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2553of how the F<event.h> header can be found, the dfeault is C<"event.h">. 3324of how the F<event.h> header can be found, the default is C<"event.h">.
2554 3325
2555=item EV_PROTOTYPES 3326=item EV_PROTOTYPES
2556 3327
2557If defined to be C<0>, then F<ev.h> will not define any function 3328If defined to be C<0>, then F<ev.h> will not define any function
2558prototypes, but still define all the structs and other symbols. This is 3329prototypes, but still define all the structs and other symbols. This is
2579When doing priority-based operations, libev usually has to linearly search 3350When doing priority-based operations, libev usually has to linearly search
2580all the priorities, so having many of them (hundreds) uses a lot of space 3351all the priorities, so having many of them (hundreds) uses a lot of space
2581and time, so using the defaults of five priorities (-2 .. +2) is usually 3352and time, so using the defaults of five priorities (-2 .. +2) is usually
2582fine. 3353fine.
2583 3354
2584If your embedding app does not need any priorities, defining these both to 3355If your embedding application does not need any priorities, defining these
2585C<0> will save some memory and cpu. 3356both to C<0> will save some memory and CPU.
2586 3357
2587=item EV_PERIODIC_ENABLE 3358=item EV_PERIODIC_ENABLE
2588 3359
2589If undefined or defined to be C<1>, then periodic timers are supported. If 3360If undefined or defined to be C<1>, then periodic timers are supported. If
2590defined to be C<0>, then they are not. Disabling them saves a few kB of 3361defined to be C<0>, then they are not. Disabling them saves a few kB of
2597code. 3368code.
2598 3369
2599=item EV_EMBED_ENABLE 3370=item EV_EMBED_ENABLE
2600 3371
2601If undefined or defined to be C<1>, then embed watchers are supported. If 3372If undefined or defined to be C<1>, then embed watchers are supported. If
2602defined to be C<0>, then they are not. 3373defined to be C<0>, then they are not. Embed watchers rely on most other
3374watcher types, which therefore must not be disabled.
2603 3375
2604=item EV_STAT_ENABLE 3376=item EV_STAT_ENABLE
2605 3377
2606If undefined or defined to be C<1>, then stat watchers are supported. If 3378If undefined or defined to be C<1>, then stat watchers are supported. If
2607defined to be C<0>, then they are not. 3379defined to be C<0>, then they are not.
2609=item EV_FORK_ENABLE 3381=item EV_FORK_ENABLE
2610 3382
2611If undefined or defined to be C<1>, then fork watchers are supported. If 3383If undefined or defined to be C<1>, then fork watchers are supported. If
2612defined to be C<0>, then they are not. 3384defined to be C<0>, then they are not.
2613 3385
3386=item EV_ASYNC_ENABLE
3387
3388If undefined or defined to be C<1>, then async watchers are supported. If
3389defined to be C<0>, then they are not.
3390
2614=item EV_MINIMAL 3391=item EV_MINIMAL
2615 3392
2616If you need to shave off some kilobytes of code at the expense of some 3393If you need to shave off some kilobytes of code at the expense of some
2617speed, define this symbol to C<1>. Currently only used for gcc to override 3394speed, define this symbol to C<1>. Currently this is used to override some
2618some inlining decisions, saves roughly 30% codesize of amd64. 3395inlining decisions, saves roughly 30% code size on amd64. It also selects a
3396much smaller 2-heap for timer management over the default 4-heap.
2619 3397
2620=item EV_PID_HASHSIZE 3398=item EV_PID_HASHSIZE
2621 3399
2622C<ev_child> watchers use a small hash table to distribute workload by 3400C<ev_child> watchers use a small hash table to distribute workload by
2623pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3401pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
2630inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 3408inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2631usually more than enough. If you need to manage thousands of C<ev_stat> 3409usually more than enough. If you need to manage thousands of C<ev_stat>
2632watchers you might want to increase this value (I<must> be a power of 3410watchers you might want to increase this value (I<must> be a power of
2633two). 3411two).
2634 3412
3413=item EV_USE_4HEAP
3414
3415Heaps are not very cache-efficient. To improve the cache-efficiency of the
3416timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3417to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3418faster performance with many (thousands) of watchers.
3419
3420The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3421(disabled).
3422
3423=item EV_HEAP_CACHE_AT
3424
3425Heaps are not very cache-efficient. To improve the cache-efficiency of the
3426timer and periodics heaps, libev can cache the timestamp (I<at>) within
3427the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3428which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3429but avoids random read accesses on heap changes. This improves performance
3430noticeably with many (hundreds) of watchers.
3431
3432The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3433(disabled).
3434
3435=item EV_VERIFY
3436
3437Controls how much internal verification (see C<ev_loop_verify ()>) will
3438be done: If set to C<0>, no internal verification code will be compiled
3439in. If set to C<1>, then verification code will be compiled in, but not
3440called. If set to C<2>, then the internal verification code will be
3441called once per loop, which can slow down libev. If set to C<3>, then the
3442verification code will be called very frequently, which will slow down
3443libev considerably.
3444
3445The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
3446C<0>.
3447
2635=item EV_COMMON 3448=item EV_COMMON
2636 3449
2637By default, all watchers have a C<void *data> member. By redefining 3450By default, all watchers have a C<void *data> member. By redefining
2638this macro to a something else you can include more and other types of 3451this macro to a something else you can include more and other types of
2639members. You have to define it each time you include one of the files, 3452members. You have to define it each time you include one of the files,
2640though, and it must be identical each time. 3453though, and it must be identical each time.
2641 3454
2642For example, the perl EV module uses something like this: 3455For example, the perl EV module uses something like this:
2643 3456
2644 #define EV_COMMON \ 3457 #define EV_COMMON \
2645 SV *self; /* contains this struct */ \ 3458 SV *self; /* contains this struct */ \
2646 SV *cb_sv, *fh /* note no trailing ";" */ 3459 SV *cb_sv, *fh /* note no trailing ";" */
2647 3460
2648=item EV_CB_DECLARE (type) 3461=item EV_CB_DECLARE (type)
2649 3462
2650=item EV_CB_INVOKE (watcher, revents) 3463=item EV_CB_INVOKE (watcher, revents)
2651 3464
2656definition and a statement, respectively. See the F<ev.h> header file for 3469definition and a statement, respectively. See the F<ev.h> header file for
2657their default definitions. One possible use for overriding these is to 3470their default definitions. One possible use for overriding these is to
2658avoid the C<struct ev_loop *> as first argument in all cases, or to use 3471avoid the C<struct ev_loop *> as first argument in all cases, or to use
2659method calls instead of plain function calls in C++. 3472method calls instead of plain function calls in C++.
2660 3473
3474=back
3475
2661=head2 EXPORTED API SYMBOLS 3476=head2 EXPORTED API SYMBOLS
2662 3477
2663If you need to re-export the API (e.g. via a dll) and you need a list of 3478If you need to re-export the API (e.g. via a DLL) and you need a list of
2664exported symbols, you can use the provided F<Symbol.*> files which list 3479exported symbols, you can use the provided F<Symbol.*> files which list
2665all public symbols, one per line: 3480all public symbols, one per line:
2666 3481
2667 Symbols.ev for libev proper 3482 Symbols.ev for libev proper
2668 Symbols.event for the libevent emulation 3483 Symbols.event for the libevent emulation
2669 3484
2670This can also be used to rename all public symbols to avoid clashes with 3485This can also be used to rename all public symbols to avoid clashes with
2671multiple versions of libev linked together (which is obviously bad in 3486multiple versions of libev linked together (which is obviously bad in
2672itself, but sometimes it is inconvinient to avoid this). 3487itself, but sometimes it is inconvenient to avoid this).
2673 3488
2674A sed command like this will create wrapper C<#define>'s that you need to 3489A sed command like this will create wrapper C<#define>'s that you need to
2675include before including F<ev.h>: 3490include before including F<ev.h>:
2676 3491
2677 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h 3492 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2694file. 3509file.
2695 3510
2696The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 3511The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2697that everybody includes and which overrides some configure choices: 3512that everybody includes and which overrides some configure choices:
2698 3513
2699 #define EV_MINIMAL 1 3514 #define EV_MINIMAL 1
2700 #define EV_USE_POLL 0 3515 #define EV_USE_POLL 0
2701 #define EV_MULTIPLICITY 0 3516 #define EV_MULTIPLICITY 0
2702 #define EV_PERIODIC_ENABLE 0 3517 #define EV_PERIODIC_ENABLE 0
2703 #define EV_STAT_ENABLE 0 3518 #define EV_STAT_ENABLE 0
2704 #define EV_FORK_ENABLE 0 3519 #define EV_FORK_ENABLE 0
2705 #define EV_CONFIG_H <config.h> 3520 #define EV_CONFIG_H <config.h>
2706 #define EV_MINPRI 0 3521 #define EV_MINPRI 0
2707 #define EV_MAXPRI 0 3522 #define EV_MAXPRI 0
2708 3523
2709 #include "ev++.h" 3524 #include "ev++.h"
2710 3525
2711And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 3526And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2712 3527
2713 #include "ev_cpp.h" 3528 #include "ev_cpp.h"
2714 #include "ev.c" 3529 #include "ev.c"
2715 3530
3531=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
2716 3532
3533=head2 THREADS AND COROUTINES
3534
3535=head3 THREADS
3536
3537All libev functions are reentrant and thread-safe unless explicitly
3538documented otherwise, but libev implements no locking itself. This means
3539that you can use as many loops as you want in parallel, as long as there
3540are no concurrent calls into any libev function with the same loop
3541parameter (C<ev_default_*> calls have an implicit default loop parameter,
3542of course): libev guarantees that different event loops share no data
3543structures that need any locking.
3544
3545Or to put it differently: calls with different loop parameters can be done
3546concurrently from multiple threads, calls with the same loop parameter
3547must be done serially (but can be done from different threads, as long as
3548only one thread ever is inside a call at any point in time, e.g. by using
3549a mutex per loop).
3550
3551Specifically to support threads (and signal handlers), libev implements
3552so-called C<ev_async> watchers, which allow some limited form of
3553concurrency on the same event loop, namely waking it up "from the
3554outside".
3555
3556If you want to know which design (one loop, locking, or multiple loops
3557without or something else still) is best for your problem, then I cannot
3558help you, but here is some generic advice:
3559
3560=over 4
3561
3562=item * most applications have a main thread: use the default libev loop
3563in that thread, or create a separate thread running only the default loop.
3564
3565This helps integrating other libraries or software modules that use libev
3566themselves and don't care/know about threading.
3567
3568=item * one loop per thread is usually a good model.
3569
3570Doing this is almost never wrong, sometimes a better-performance model
3571exists, but it is always a good start.
3572
3573=item * other models exist, such as the leader/follower pattern, where one
3574loop is handed through multiple threads in a kind of round-robin fashion.
3575
3576Choosing a model is hard - look around, learn, know that usually you can do
3577better than you currently do :-)
3578
3579=item * often you need to talk to some other thread which blocks in the
3580event loop.
3581
3582C<ev_async> watchers can be used to wake them up from other threads safely
3583(or from signal contexts...).
3584
3585An example use would be to communicate signals or other events that only
3586work in the default loop by registering the signal watcher with the
3587default loop and triggering an C<ev_async> watcher from the default loop
3588watcher callback into the event loop interested in the signal.
3589
3590=back
3591
3592=head3 COROUTINES
3593
3594Libev is very accommodating to coroutines ("cooperative threads"):
3595libev fully supports nesting calls to its functions from different
3596coroutines (e.g. you can call C<ev_loop> on the same loop from two
3597different coroutines, and switch freely between both coroutines running the
3598loop, as long as you don't confuse yourself). The only exception is that
3599you must not do this from C<ev_periodic> reschedule callbacks.
3600
3601Care has been taken to ensure that libev does not keep local state inside
3602C<ev_loop>, and other calls do not usually allow for coroutine switches as
3603they do not call any callbacks.
3604
3605=head2 COMPILER WARNINGS
3606
3607Depending on your compiler and compiler settings, you might get no or a
3608lot of warnings when compiling libev code. Some people are apparently
3609scared by this.
3610
3611However, these are unavoidable for many reasons. For one, each compiler
3612has different warnings, and each user has different tastes regarding
3613warning options. "Warn-free" code therefore cannot be a goal except when
3614targeting a specific compiler and compiler-version.
3615
3616Another reason is that some compiler warnings require elaborate
3617workarounds, or other changes to the code that make it less clear and less
3618maintainable.
3619
3620And of course, some compiler warnings are just plain stupid, or simply
3621wrong (because they don't actually warn about the condition their message
3622seems to warn about). For example, certain older gcc versions had some
3623warnings that resulted an extreme number of false positives. These have
3624been fixed, but some people still insist on making code warn-free with
3625such buggy versions.
3626
3627While libev is written to generate as few warnings as possible,
3628"warn-free" code is not a goal, and it is recommended not to build libev
3629with any compiler warnings enabled unless you are prepared to cope with
3630them (e.g. by ignoring them). Remember that warnings are just that:
3631warnings, not errors, or proof of bugs.
3632
3633
3634=head2 VALGRIND
3635
3636Valgrind has a special section here because it is a popular tool that is
3637highly useful. Unfortunately, valgrind reports are very hard to interpret.
3638
3639If you think you found a bug (memory leak, uninitialised data access etc.)
3640in libev, then check twice: If valgrind reports something like:
3641
3642 ==2274== definitely lost: 0 bytes in 0 blocks.
3643 ==2274== possibly lost: 0 bytes in 0 blocks.
3644 ==2274== still reachable: 256 bytes in 1 blocks.
3645
3646Then there is no memory leak, just as memory accounted to global variables
3647is not a memleak - the memory is still being referenced, and didn't leak.
3648
3649Similarly, under some circumstances, valgrind might report kernel bugs
3650as if it were a bug in libev (e.g. in realloc or in the poll backend,
3651although an acceptable workaround has been found here), or it might be
3652confused.
3653
3654Keep in mind that valgrind is a very good tool, but only a tool. Don't
3655make it into some kind of religion.
3656
3657If you are unsure about something, feel free to contact the mailing list
3658with the full valgrind report and an explanation on why you think this
3659is a bug in libev (best check the archives, too :). However, don't be
3660annoyed when you get a brisk "this is no bug" answer and take the chance
3661of learning how to interpret valgrind properly.
3662
3663If you need, for some reason, empty reports from valgrind for your project
3664I suggest using suppression lists.
3665
3666
3667=head1 PORTABILITY NOTES
3668
3669=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
3670
3671Win32 doesn't support any of the standards (e.g. POSIX) that libev
3672requires, and its I/O model is fundamentally incompatible with the POSIX
3673model. Libev still offers limited functionality on this platform in
3674the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3675descriptors. This only applies when using Win32 natively, not when using
3676e.g. cygwin.
3677
3678Lifting these limitations would basically require the full
3679re-implementation of the I/O system. If you are into these kinds of
3680things, then note that glib does exactly that for you in a very portable
3681way (note also that glib is the slowest event library known to man).
3682
3683There is no supported compilation method available on windows except
3684embedding it into other applications.
3685
3686Not a libev limitation but worth mentioning: windows apparently doesn't
3687accept large writes: instead of resulting in a partial write, windows will
3688either accept everything or return C<ENOBUFS> if the buffer is too large,
3689so make sure you only write small amounts into your sockets (less than a
3690megabyte seems safe, but this apparently depends on the amount of memory
3691available).
3692
3693Due to the many, low, and arbitrary limits on the win32 platform and
3694the abysmal performance of winsockets, using a large number of sockets
3695is not recommended (and not reasonable). If your program needs to use
3696more than a hundred or so sockets, then likely it needs to use a totally
3697different implementation for windows, as libev offers the POSIX readiness
3698notification model, which cannot be implemented efficiently on windows
3699(Microsoft monopoly games).
3700
3701A typical way to use libev under windows is to embed it (see the embedding
3702section for details) and use the following F<evwrap.h> header file instead
3703of F<ev.h>:
3704
3705 #define EV_STANDALONE /* keeps ev from requiring config.h */
3706 #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */
3707
3708 #include "ev.h"
3709
3710And compile the following F<evwrap.c> file into your project (make sure
3711you do I<not> compile the F<ev.c> or any other embedded source files!):
3712
3713 #include "evwrap.h"
3714 #include "ev.c"
3715
3716=over 4
3717
3718=item The winsocket select function
3719
3720The winsocket C<select> function doesn't follow POSIX in that it
3721requires socket I<handles> and not socket I<file descriptors> (it is
3722also extremely buggy). This makes select very inefficient, and also
3723requires a mapping from file descriptors to socket handles (the Microsoft
3724C runtime provides the function C<_open_osfhandle> for this). See the
3725discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
3726C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
3727
3728The configuration for a "naked" win32 using the Microsoft runtime
3729libraries and raw winsocket select is:
3730
3731 #define EV_USE_SELECT 1
3732 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3733
3734Note that winsockets handling of fd sets is O(n), so you can easily get a
3735complexity in the O(n²) range when using win32.
3736
3737=item Limited number of file descriptors
3738
3739Windows has numerous arbitrary (and low) limits on things.
3740
3741Early versions of winsocket's select only supported waiting for a maximum
3742of C<64> handles (probably owning to the fact that all windows kernels
3743can only wait for C<64> things at the same time internally; Microsoft
3744recommends spawning a chain of threads and wait for 63 handles and the
3745previous thread in each. Great).
3746
3747Newer versions support more handles, but you need to define C<FD_SETSIZE>
3748to some high number (e.g. C<2048>) before compiling the winsocket select
3749call (which might be in libev or elsewhere, for example, perl does its own
3750select emulation on windows).
3751
3752Another limit is the number of file descriptors in the Microsoft runtime
3753libraries, which by default is C<64> (there must be a hidden I<64> fetish
3754or something like this inside Microsoft). You can increase this by calling
3755C<_setmaxstdio>, which can increase this limit to C<2048> (another
3756arbitrary limit), but is broken in many versions of the Microsoft runtime
3757libraries.
3758
3759This might get you to about C<512> or C<2048> sockets (depending on
3760windows version and/or the phase of the moon). To get more, you need to
3761wrap all I/O functions and provide your own fd management, but the cost of
3762calling select (O(n²)) will likely make this unworkable.
3763
3764=back
3765
3766=head2 PORTABILITY REQUIREMENTS
3767
3768In addition to a working ISO-C implementation and of course the
3769backend-specific APIs, libev relies on a few additional extensions:
3770
3771=over 4
3772
3773=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
3774calling conventions regardless of C<ev_watcher_type *>.
3775
3776Libev assumes not only that all watcher pointers have the same internal
3777structure (guaranteed by POSIX but not by ISO C for example), but it also
3778assumes that the same (machine) code can be used to call any watcher
3779callback: The watcher callbacks have different type signatures, but libev
3780calls them using an C<ev_watcher *> internally.
3781
3782=item C<sig_atomic_t volatile> must be thread-atomic as well
3783
3784The type C<sig_atomic_t volatile> (or whatever is defined as
3785C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
3786threads. This is not part of the specification for C<sig_atomic_t>, but is
3787believed to be sufficiently portable.
3788
3789=item C<sigprocmask> must work in a threaded environment
3790
3791Libev uses C<sigprocmask> to temporarily block signals. This is not
3792allowed in a threaded program (C<pthread_sigmask> has to be used). Typical
3793pthread implementations will either allow C<sigprocmask> in the "main
3794thread" or will block signals process-wide, both behaviours would
3795be compatible with libev. Interaction between C<sigprocmask> and
3796C<pthread_sigmask> could complicate things, however.
3797
3798The most portable way to handle signals is to block signals in all threads
3799except the initial one, and run the default loop in the initial thread as
3800well.
3801
3802=item C<long> must be large enough for common memory allocation sizes
3803
3804To improve portability and simplify its API, libev uses C<long> internally
3805instead of C<size_t> when allocating its data structures. On non-POSIX
3806systems (Microsoft...) this might be unexpectedly low, but is still at
3807least 31 bits everywhere, which is enough for hundreds of millions of
3808watchers.
3809
3810=item C<double> must hold a time value in seconds with enough accuracy
3811
3812The type C<double> is used to represent timestamps. It is required to
3813have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3814enough for at least into the year 4000. This requirement is fulfilled by
3815implementations implementing IEEE 754 (basically all existing ones).
3816
3817=back
3818
3819If you know of other additional requirements drop me a note.
3820
3821
2717=head1 COMPLEXITIES 3822=head1 ALGORITHMIC COMPLEXITIES
2718 3823
2719In this section the complexities of (many of) the algorithms used inside 3824In this section the complexities of (many of) the algorithms used inside
2720libev will be explained. For complexity discussions about backends see the 3825libev will be documented. For complexity discussions about backends see
2721documentation for C<ev_default_init>. 3826the documentation for C<ev_default_init>.
2722 3827
2723All of the following are about amortised time: If an array needs to be 3828All of the following are about amortised time: If an array needs to be
2724extended, libev needs to realloc and move the whole array, but this 3829extended, libev needs to realloc and move the whole array, but this
2725happens asymptotically never with higher number of elements, so O(1) might 3830happens asymptotically rarer with higher number of elements, so O(1) might
2726mean it might do a lengthy realloc operation in rare cases, but on average 3831mean that libev does a lengthy realloc operation in rare cases, but on
2727it is much faster and asymptotically approaches constant time. 3832average it is much faster and asymptotically approaches constant time.
2728 3833
2729=over 4 3834=over 4
2730 3835
2731=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 3836=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2732 3837
2733This means that, when you have a watcher that triggers in one hour and 3838This means that, when you have a watcher that triggers in one hour and
2734there are 100 watchers that would trigger before that then inserting will 3839there are 100 watchers that would trigger before that, then inserting will
2735have to skip roughly seven (C<ld 100>) of these watchers. 3840have to skip roughly seven (C<ld 100>) of these watchers.
2736 3841
2737=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) 3842=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2738 3843
2739That means that changing a timer costs less than removing/adding them 3844That means that changing a timer costs less than removing/adding them,
2740as only the relative motion in the event queue has to be paid for. 3845as only the relative motion in the event queue has to be paid for.
2741 3846
2742=item Starting io/check/prepare/idle/signal/child watchers: O(1) 3847=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
2743 3848
2744These just add the watcher into an array or at the head of a list. 3849These just add the watcher into an array or at the head of a list.
2745 3850
2746=item Stopping check/prepare/idle watchers: O(1) 3851=item Stopping check/prepare/idle/fork/async watchers: O(1)
2747 3852
2748=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 3853=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2749 3854
2750These watchers are stored in lists then need to be walked to find the 3855These watchers are stored in lists, so they need to be walked to find the
2751correct watcher to remove. The lists are usually short (you don't usually 3856correct watcher to remove. The lists are usually short (you don't usually
2752have many watchers waiting for the same fd or signal). 3857have many watchers waiting for the same fd or signal: one is typical, two
3858is rare).
2753 3859
2754=item Finding the next timer in each loop iteration: O(1) 3860=item Finding the next timer in each loop iteration: O(1)
2755 3861
2756By virtue of using a binary heap, the next timer is always found at the 3862By virtue of using a binary or 4-heap, the next timer is always found at a
2757beginning of the storage array. 3863fixed position in the storage array.
2758 3864
2759=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 3865=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2760 3866
2761A change means an I/O watcher gets started or stopped, which requires 3867A change means an I/O watcher gets started or stopped, which requires
2762libev to recalculate its status (and possibly tell the kernel, depending 3868libev to recalculate its status (and possibly tell the kernel, depending
2763on backend and wether C<ev_io_set> was used). 3869on backend and whether C<ev_io_set> was used).
2764 3870
2765=item Activating one watcher (putting it into the pending state): O(1) 3871=item Activating one watcher (putting it into the pending state): O(1)
2766 3872
2767=item Priority handling: O(number_of_priorities) 3873=item Priority handling: O(number_of_priorities)
2768 3874
2769Priorities are implemented by allocating some space for each 3875Priorities are implemented by allocating some space for each
2770priority. When doing priority-based operations, libev usually has to 3876priority. When doing priority-based operations, libev usually has to
2771linearly search all the priorities, but starting/stopping and activating 3877linearly search all the priorities, but starting/stopping and activating
2772watchers becomes O(1) w.r.t. prioritiy handling. 3878watchers becomes O(1) with respect to priority handling.
3879
3880=item Sending an ev_async: O(1)
3881
3882=item Processing ev_async_send: O(number_of_async_watchers)
3883
3884=item Processing signals: O(max_signal_number)
3885
3886Sending involves a system call I<iff> there were no other C<ev_async_send>
3887calls in the current loop iteration. Checking for async and signal events
3888involves iterating over all running async watchers or all signal numbers.
2773 3889
2774=back 3890=back
2775 3891
2776 3892
2777=head1 AUTHOR 3893=head1 AUTHOR
2778 3894
2779Marc Lehmann <libev@schmorp.de>. 3895Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
2780 3896

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines