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

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines