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

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines