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

Comparing libev/ev.pod (file contents):
Revision 1.144 by root, Mon Apr 7 12:33:29 2008 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=head2 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 // a single header file is required 11 // a single header file is required
12 #include <ev.h> 12 #include <ev.h>
13 13
14 // every watcher type has its own typedef'd struct 14 // every watcher type has its own typedef'd struct
15 // with the name ev_<type> 15 // with the name ev_<type>
16 ev_io stdin_watcher; 16 ev_io stdin_watcher;
17 ev_timer timeout_watcher; 17 ev_timer timeout_watcher;
18 18
19 // all watcher callbacks have a similar signature 19 // all watcher callbacks have a similar signature
20 // this callback is called when data is readable on stdin 20 // this callback is called when data is readable on stdin
21 static void 21 static void
22 stdin_cb (EV_P_ struct ev_io *w, int revents) 22 stdin_cb (EV_P_ struct ev_io *w, int revents)
23 { 23 {
24 puts ("stdin ready"); 24 puts ("stdin ready");
25 // for one-shot events, one must manually stop the watcher 25 // for one-shot events, one must manually stop the watcher
26 // with its corresponding stop function. 26 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w); 27 ev_io_stop (EV_A_ w);
28 28
29 // this causes all nested ev_loop's to stop iterating 29 // this causes all nested ev_loop's to stop iterating
30 ev_unloop (EV_A_ EVUNLOOP_ALL); 30 ev_unloop (EV_A_ EVUNLOOP_ALL);
31 } 31 }
32 32
33 // another callback, this time for a time-out 33 // another callback, this time for a time-out
34 static void 34 static void
35 timeout_cb (EV_P_ struct ev_timer *w, int revents) 35 timeout_cb (EV_P_ struct ev_timer *w, int revents)
36 { 36 {
37 puts ("timeout"); 37 puts ("timeout");
38 // this causes the innermost ev_loop to stop iterating 38 // this causes the innermost ev_loop to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE); 39 ev_unloop (EV_A_ EVUNLOOP_ONE);
40 } 40 }
41 41
42 int 42 int
43 main (void) 43 main (void)
44 { 44 {
45 // use the default event loop unless you have special needs 45 // use the default event loop unless you have special needs
46 struct ev_loop *loop = ev_default_loop (0); 46 struct ev_loop *loop = ev_default_loop (0);
47 47
48 // 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 49 // this one will watch for stdin to become readable
50 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);
51 ev_io_start (loop, &stdin_watcher); 51 ev_io_start (loop, &stdin_watcher);
52 52
53 // initialise a timer watcher, then start it 53 // initialise a timer watcher, then start it
54 // simple non-repeating 5.5 second timeout 54 // simple non-repeating 5.5 second timeout
55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
56 ev_timer_start (loop, &timeout_watcher); 56 ev_timer_start (loop, &timeout_watcher);
57 57
58 // now wait for events to arrive 58 // now wait for events to arrive
59 ev_loop (loop, 0); 59 ev_loop (loop, 0);
60 60
61 // unloop was called, so exit 61 // unloop was called, so exit
62 return 0; 62 return 0;
63 } 63 }
64 64
65=head1 DESCRIPTION 65=head1 DESCRIPTION
66 66
67The newest version of this document is also available as an html-formatted 67The newest version of this document is also available as an html-formatted
68web 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
69time: L<http://cvs.schmorp.de/libev/ev.html>. 69time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
70 70
71Libev 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
72file descriptor being readable or a timeout occurring), and it will manage 72file descriptor being readable or a timeout occurring), and it will manage
73these event sources and provide your program with events. 73these event sources and provide your program with events.
74 74
113Libev represents time as a single floating point number, representing the 113Libev represents time as a single floating point number, representing the
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 114(fractional) number of seconds since the (POSIX) epoch (somewhere near
115the 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
116called 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
117to 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
118it, you should treat it as some floatingpoint value. Unlike the name 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 119component C<stamp> might indicate, it is also used for time differences
120throughout libev. 120throughout libev.
121
122=head1 ERROR HANDLING
123
124Libev knows three classes of errors: operating system errors, usage errors
125and internal errors (bugs).
126
127When libev catches an operating system error it cannot handle (for example
128a system call indicating a condition libev cannot fix), it calls the callback
129set via C<ev_set_syserr_cb>, which is supposed to fix the problem or
130abort. The default is to print a diagnostic message and to call C<abort
131()>.
132
133When libev detects a usage error such as a negative timer interval, then
134it will print a diagnostic message and abort (via the C<assert> mechanism,
135so C<NDEBUG> will disable this checking): these are programming errors in
136the libev caller and need to be fixed there.
137
138Libev also has a few internal error-checking C<assert>ions, and also has
139extensive consistency checking code. These do not trigger under normal
140circumstances, as they indicate either a bug in libev or worse.
141
121 142
122=head1 GLOBAL FUNCTIONS 143=head1 GLOBAL FUNCTIONS
123 144
124These functions can be called anytime, even before initialising the 145These functions can be called anytime, even before initialising the
125library in any way. 146library in any way.
134 155
135=item ev_sleep (ev_tstamp interval) 156=item ev_sleep (ev_tstamp interval)
136 157
137Sleep for the given interval: The current thread will be blocked until 158Sleep for the given interval: The current thread will be blocked until
138either it is interrupted or the given time interval has passed. Basically 159either it is interrupted or the given time interval has passed. Basically
139this is a subsecond-resolution C<sleep ()>. 160this is a sub-second-resolution C<sleep ()>.
140 161
141=item int ev_version_major () 162=item int ev_version_major ()
142 163
143=item int ev_version_minor () 164=item int ev_version_minor ()
144 165
157not a problem. 178not a problem.
158 179
159Example: Make sure we haven't accidentally been linked against the wrong 180Example: Make sure we haven't accidentally been linked against the wrong
160version. 181version.
161 182
162 assert (("libev version mismatch", 183 assert (("libev version mismatch",
163 ev_version_major () == EV_VERSION_MAJOR 184 ev_version_major () == EV_VERSION_MAJOR
164 && ev_version_minor () >= EV_VERSION_MINOR)); 185 && ev_version_minor () >= EV_VERSION_MINOR));
165 186
166=item unsigned int ev_supported_backends () 187=item unsigned int ev_supported_backends ()
167 188
168Return 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_*>
169value) compiled into this binary of libev (independent of their 190value) compiled into this binary of libev (independent of their
171a description of the set values. 192a description of the set values.
172 193
173Example: 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
174a 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
175 196
176 assert (("sorry, no epoll, no sex", 197 assert (("sorry, no epoll, no sex",
177 ev_supported_backends () & EVBACKEND_EPOLL)); 198 ev_supported_backends () & EVBACKEND_EPOLL));
178 199
179=item unsigned int ev_recommended_backends () 200=item unsigned int ev_recommended_backends ()
180 201
181Return 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
182recommended for this platform. This set is often smaller than the one 203recommended for this platform. This set is often smaller than the one
183returned 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
184most BSDs and will not be autodetected unless you explicitly request it 205most BSDs and will not be auto-detected unless you explicitly request it
185(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
186libev will probe for if you specify no backends explicitly. 207libev will probe for if you specify no backends explicitly.
187 208
188=item unsigned int ev_embeddable_backends () 209=item unsigned int ev_embeddable_backends ()
189 210
193C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
194recommended ones. 215recommended ones.
195 216
196See the description of C<ev_embed> watchers for more info. 217See the description of C<ev_embed> watchers for more info.
197 218
198=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
199 220
200Sets the allocation function to use (the prototype is similar - the 221Sets the allocation function to use (the prototype is similar - the
201semantics is identical - to the realloc C function). It is used to 222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
202allocate and free memory (no surprises here). If it returns zero when 223used to allocate and free memory (no surprises here). If it returns zero
203memory needs to be allocated, the library might abort or take some 224when memory needs to be allocated (C<size != 0>), the library might abort
204potentially destructive action. The default is your system realloc 225or take some potentially destructive action.
205function. 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.
206 230
207You could override this function in high-availability programs to, say, 231You could override this function in high-availability programs to, say,
208free 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,
209or 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.
210 234
211Example: 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
212retries). 236retries (example requires a standards-compliant C<realloc>).
213 237
214 static void * 238 static void *
215 persistent_realloc (void *ptr, size_t size) 239 persistent_realloc (void *ptr, size_t size)
216 { 240 {
217 for (;;) 241 for (;;)
226 } 250 }
227 251
228 ... 252 ...
229 ev_set_allocator (persistent_realloc); 253 ev_set_allocator (persistent_realloc);
230 254
231=item ev_set_syserr_cb (void (*cb)(const char *msg)); 255=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
232 256
233Set the callback function to call on a retryable syscall error (such 257Set the callback function to call on a retryable system call error (such
234as failed select, poll, epoll_wait). The message is a printable string 258as failed select, poll, epoll_wait). The message is a printable string
235indicating the system call or subsystem causing the problem. If this 259indicating the system call or subsystem causing the problem. If this
236callback 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
237matter what, when it returns. That is, libev will generally retry the 261matter what, when it returns. That is, libev will generally retry the
238requested 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
239(such as abort). 263(such as abort).
240 264
241Example: This is basically the same thing that libev does internally, too. 265Example: This is basically the same thing that libev does internally, too.
274from multiple threads, you have to lock (note also that this is unlikely, 298from multiple threads, you have to lock (note also that this is unlikely,
275as loops cannot bes hared easily between threads anyway). 299as loops cannot bes hared easily between threads anyway).
276 300
277The default loop is the only loop that can handle C<ev_signal> and 301The default loop is the only loop that can handle C<ev_signal> and
278C<ev_child> watchers, and to do this, it always registers a handler 302C<ev_child> watchers, and to do this, it always registers a handler
279for C<SIGCHLD>. If this is a problem for your app you can either 303for C<SIGCHLD>. If this is a problem for your application you can either
280create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 304create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
281can simply overwrite the C<SIGCHLD> signal handler I<after> calling 305can simply overwrite the C<SIGCHLD> signal handler I<after> calling
282C<ev_default_init>. 306C<ev_default_init>.
283 307
284The flags argument can be used to specify special behaviour or specific 308The flags argument can be used to specify special behaviour or specific
293The 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
294thing, believe me). 318thing, believe me).
295 319
296=item C<EVFLAG_NOENV> 320=item C<EVFLAG_NOENV>
297 321
298If 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
299or setgid) then libev will I<not> look at the environment variable 323or setgid) then libev will I<not> look at the environment variable
300C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 324C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
301override 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
302useful 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
303around bugs. 327around bugs.
310 334
311This works by calling C<getpid ()> on every iteration of the loop, 335This works by calling C<getpid ()> on every iteration of the loop,
312and 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
313iterations and little real work, but is usually not noticeable (on my 337iterations and little real work, but is usually not noticeable (on my
314GNU/Linux 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
315without a syscall and thus I<very> fast, but my GNU/Linux system also has 339without a system call and thus I<very> fast, but my GNU/Linux system also has
316C<pthread_atfork> which is even faster). 340C<pthread_atfork> which is even faster).
317 341
318The 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
319forget about forgetting to tell libev about forking) when you use this 343forget about forgetting to tell libev about forking) when you use this
320flag. 344flag.
321 345
322This 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>
323environment variable. 347environment variable.
324 348
325=item C<EVBACKEND_SELECT> (value 1, portable select backend) 349=item C<EVBACKEND_SELECT> (value 1, portable select backend)
326 350
327This is your standard select(2) backend. Not I<completely> standard, as 351This is your standard select(2) backend. Not I<completely> standard, as
329but 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
330using this backend. It doesn't scale too well (O(highest_fd)), but its 354using this backend. It doesn't scale too well (O(highest_fd)), but its
331usually the fastest backend for a low number of (low-numbered :) fds. 355usually the fastest backend for a low number of (low-numbered :) fds.
332 356
333To get good performance out of this backend you need a high amount of 357To get good performance out of this backend you need a high amount of
334parallelity (most of the file descriptors should be busy). If you are 358parallelism (most of the file descriptors should be busy). If you are
335writing a server, you should C<accept ()> in a loop to accept as many 359writing a server, you should C<accept ()> in a loop to accept as many
336connections as possible during one iteration. You might also want to have 360connections as possible during one iteration. You might also want to have
337a look at C<ev_set_io_collect_interval ()> to increase the amount of 361a look at C<ev_set_io_collect_interval ()> to increase the amount of
338readyness notifications you get per iteration. 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).
339 367
340=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)
341 369
342And this is your standard poll(2) backend. It's more complicated 370And this is your standard poll(2) backend. It's more complicated
343than select, but handles sparse fds better and has no artificial 371than select, but handles sparse fds better and has no artificial
344limit on the number of fds you can use (except it will slow down 372limit on the number of fds you can use (except it will slow down
345considerably with a lot of inactive fds). It scales similarly to select, 373considerably with a lot of inactive fds). It scales similarly to select,
346i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for 374i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
347performance tips. 375performance tips.
348 376
377This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
378C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
379
349=item C<EVBACKEND_EPOLL> (value 4, Linux) 380=item C<EVBACKEND_EPOLL> (value 4, Linux)
350 381
351For 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,
352but it scales phenomenally better. While poll and select usually scale 383but it scales phenomenally better. While poll and select usually scale
353like O(total_fds) where n is the total number of fds (or the highest fd), 384like O(total_fds) where n is the total number of fds (or the highest fd),
354epoll scales either O(1) or O(active_fds). The epoll design has a number 385epoll scales either O(1) or O(active_fds). The epoll design has a number
355of shortcomings, such as silently dropping events in some hard-to-detect 386of shortcomings, such as silently dropping events in some hard-to-detect
356cases and requiring a syscall per fd change, no fork support and bad 387cases and requiring a system call per fd change, no fork support and bad
357support for dup. 388support for dup.
358 389
359While stopping, setting and starting an I/O watcher in the same iteration 390While stopping, setting and starting an I/O watcher in the same iteration
360will result in some caching, there is still a syscall per such incident 391will result in some caching, there is still a system call per such incident
361(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
362best to avoid that. Also, C<dup ()>'ed file descriptors might not work 393best to avoid that. Also, C<dup ()>'ed file descriptors might not work
363very well if you register events for both fds. 394very well if you register events for both fds.
364 395
365Please note that epoll sometimes generates spurious notifications, so you 396Please note that epoll sometimes generates spurious notifications, so you
366need 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
367(or space) is available. 398(or space) is available.
368 399
369Best performance from this backend is achieved by not unregistering all 400Best performance from this backend is achieved by not unregistering all
370watchers for a file descriptor until it has been closed, if possible, i.e. 401watchers for a file descriptor until it has been closed, if possible,
371keep at least one watcher active per fd at all times. 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.
372 405
373While nominally embeddeble in other event loops, this feature is broken in 406While nominally embeddable in other event loops, this feature is broken in
374all kernel versions tested so far. 407all kernel versions tested so far.
375 408
409This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
410C<EVBACKEND_POLL>.
411
376=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 412=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
377 413
378Kqueue deserves special mention, as at the time of this writing, it 414Kqueue deserves special mention, as at the time of this writing, it was
379was broken on all BSDs except NetBSD (usually it doesn't work reliably 415broken on all BSDs except NetBSD (usually it doesn't work reliably with
380with anything but sockets and pipes, except on Darwin, where of course 416anything but sockets and pipes, except on Darwin, where of course it's
381it's completely useless). For this reason it's not being "autodetected" 417completely useless). For this reason it's not being "auto-detected" unless
382unless 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
383C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 419libev was compiled on a known-to-be-good (-enough) system like NetBSD.
384system like NetBSD.
385 420
386You still can embed kqueue into a normal poll or select backend and use it 421You still can embed kqueue into a normal poll or select backend and use it
387only for sockets (after having made sure that sockets work with kqueue on 422only for sockets (after having made sure that sockets work with kqueue on
388the target platform). See C<ev_embed> watchers for more info. 423the target platform). See C<ev_embed> watchers for more info.
389 424
390It 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
391kernel is more efficient (which says nothing about its actual speed, of 426kernel is more efficient (which says nothing about its actual speed, of
392course). While stopping, setting and starting an I/O watcher does never 427course). While stopping, setting and starting an I/O watcher does never
393cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to 428cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
394two event changes per incident, support for C<fork ()> is very bad and it 429two event changes per incident. Support for C<fork ()> is very bad and it
395drops fds silently in similarly hard-to-detect cases. 430drops fds silently in similarly hard-to-detect cases.
396 431
397This backend usually performs well under most conditions. 432This backend usually performs well under most conditions.
398 433
399While nominally embeddable in other event loops, this doesn't work 434While nominally embeddable in other event loops, this doesn't work
400everywhere, so you might need to test for this. And since it is broken 435everywhere, so you might need to test for this. And since it is broken
401almost everywhere, you should only use it when you have a lot of sockets 436almost everywhere, you should only use it when you have a lot of sockets
402(for which it usually works), by embedding it into another event loop 437(for which it usually works), by embedding it into another event loop
403(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for 438(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it,
404sockets. 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>.
405 444
406=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 445=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
407 446
408This is not implemented yet (and might never be, unless you send me an 447This is not implemented yet (and might never be, unless you send me an
409implementation). According to reports, C</dev/poll> only supports sockets 448implementation). According to reports, C</dev/poll> only supports sockets
413=item C<EVBACKEND_PORT> (value 32, Solaris 10) 452=item C<EVBACKEND_PORT> (value 32, Solaris 10)
414 453
415This uses the Solaris 10 event port mechanism. As with everything on Solaris, 454This uses the Solaris 10 event port mechanism. As with everything on Solaris,
416it'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)).
417 456
418Please note that solaris event ports can deliver a lot of spurious 457Please note that Solaris event ports can deliver a lot of spurious
419notifications, 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
420blocking when no data (or space) is available. 459blocking when no data (or space) is available.
421 460
422While this backend scales well, it requires one system call per active 461While this backend scales well, it requires one system call per active
423file descriptor per loop iteration. For small and medium numbers of file 462file descriptor per loop iteration. For small and medium numbers of file
424descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 463descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
425might perform better. 464might perform better.
426 465
427On the positive side, ignoring the spurious readyness notifications, this 466On the positive side, with the exception of the spurious readiness
428backend actually performed to specification in all tests and is fully 467notifications, this backend actually performed fully to specification
429embeddable, which is a rare feat among the OS-specific backends. 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>.
430 473
431=item C<EVBACKEND_ALL> 474=item C<EVBACKEND_ALL>
432 475
433Try all backends (even potentially broken ones that wouldn't be tried 476Try all backends (even potentially broken ones that wouldn't be tried
434with 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
436 479
437It is definitely not recommended to use this flag. 480It is definitely not recommended to use this flag.
438 481
439=back 482=back
440 483
441If 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
442backends will be tried (in the reverse order as listed here). If none are 485backends will be tried (in the reverse order as listed here). If none are
443specified, all backends in C<ev_recommended_backends ()> will be tried. 486specified, all backends in C<ev_recommended_backends ()> will be tried.
444 487
445The most typical usage is like this: 488Example: This is the most typical usage.
446 489
447 if (!ev_default_loop (0)) 490 if (!ev_default_loop (0))
448 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 491 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
449 492
450Restrict libev to the select and poll backends, and do not allow 493Example: Restrict libev to the select and poll backends, and do not allow
451environment settings to be taken into account: 494environment settings to be taken into account:
452 495
453 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); 496 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
454 497
455Use 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
456available (warning, breaks stuff, best use only with your own private 499used if available (warning, breaks stuff, best use only with your own
457event 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):
458 502
459 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 503 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
460 504
461=item struct ev_loop *ev_loop_new (unsigned int flags) 505=item struct ev_loop *ev_loop_new (unsigned int flags)
462 506
463Similar 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
464always distinct from the default loop. Unlike the default loop, it cannot 508always distinct from the default loop. Unlike the default loop, it cannot
469libev with threads is indeed to create one loop per thread, and using the 513libev with threads is indeed to create one loop per thread, and using the
470default loop in the "main" or "initial" thread. 514default loop in the "main" or "initial" thread.
471 515
472Example: 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.
473 517
474 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 518 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
475 if (!epoller) 519 if (!epoller)
476 fatal ("no epoll found here, maybe it hides under your chair"); 520 fatal ("no epoll found here, maybe it hides under your chair");
477 521
478=item ev_default_destroy () 522=item ev_default_destroy ()
479 523
480Destroys the default loop again (frees all memory and kernel state 524Destroys the default loop again (frees all memory and kernel state
481etc.). 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
482sense, 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
483responsibility to either stop all watchers cleanly yoursef I<before> 527responsibility to either stop all watchers cleanly yourself I<before>
484calling this function, or cope with the fact afterwards (which is usually 528calling this function, or cope with the fact afterwards (which is usually
485the easiest thing, you can just ignore the watchers and/or C<free ()> them 529the easiest thing, you can just ignore the watchers and/or C<free ()> them
486for example). 530for example).
487 531
488Note that certain global state, such as signal state, will not be freed by 532Note that certain global state, such as signal state, will not be freed by
520 564
521=item ev_loop_fork (loop) 565=item ev_loop_fork (loop)
522 566
523Like 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
524C<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
525after 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.
526 571
527=item int ev_is_default_loop (loop) 572=item int ev_is_default_loop (loop)
528 573
529Returns true when the given loop actually is the default loop, false otherwise. 574Returns true when the given loop is, in fact, the default loop, and false
575otherwise.
530 576
531=item unsigned int ev_loop_count (loop) 577=item unsigned int ev_loop_count (loop)
532 578
533Returns 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
534the 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
549received events and started processing them. This timestamp does not 595received events and started processing them. This timestamp does not
550change 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
551time 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
552event occurring (or more correctly, libev finding out about it). 598event occurring (or more correctly, libev finding out about it).
553 599
600=item ev_now_update (loop)
601
602Establishes the current time by querying the kernel, updating the time
603returned by C<ev_now ()> in the progress. This is a costly operation and
604is usually done automatically within C<ev_loop ()>.
605
606This function is rarely useful, but when some event callback runs for a
607very long time without entering the event loop, updating libev's idea of
608the current time is a good idea.
609
610See also "The special problem of time updates" in the C<ev_timer> section.
611
554=item ev_loop (loop, int flags) 612=item ev_loop (loop, int flags)
555 613
556Finally, this is it, the event handler. This function usually is called 614Finally, this is it, the event handler. This function usually is called
557after you initialised all your watchers and you want to start handling 615after you initialised all your watchers and you want to start handling
558events. 616events.
560If 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
561either 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.
562 620
563Please note that an explicit C<ev_unloop> is usually better than 621Please note that an explicit C<ev_unloop> is usually better than
564relying 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
565finished (especially in interactive programs), but having a program that 623finished (especially in interactive programs), but having a program
566automatically 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
567relying on its watchers stopping correctly is a thing of beauty. 625of relying on its watchers stopping correctly, that is truly a thing of
626beauty.
568 627
569A 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
570those events and any outstanding ones, but will not block your process in 629those events and any already outstanding ones, but will not block your
571case 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.
572 632
573A 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
574neccessary) and will handle those and any outstanding ones. It will block 634necessary) and will handle those and any already outstanding ones. It
575your 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
576one 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
577external 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
578libev 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
579usually a better approach for this kind of thing. 643usually a better approach for this kind of thing.
580 644
581Here are the gory details of what C<ev_loop> does: 645Here are the gory details of what C<ev_loop> does:
582 646
583 - Before the first iteration, call any pending watchers. 647 - Before the first iteration, call any pending watchers.
584 * If EVFLAG_FORKCHECK was used, check for a fork. 648 * If EVFLAG_FORKCHECK was used, check for a fork.
585 - If a fork was detected, queue and call all fork watchers. 649 - If a fork was detected (by any means), queue and call all fork watchers.
586 - Queue and call all prepare watchers. 650 - Queue and call all prepare watchers.
587 - 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.
588 - Update the kernel state with all outstanding changes. 653 - Update the kernel state with all outstanding changes.
589 - Update the "event loop time". 654 - Update the "event loop time" (ev_now ()).
590 - Calculate for how long to sleep or block, if at all 655 - Calculate for how long to sleep or block, if at all
591 (active idle watchers, EVLOOP_NONBLOCK or not having 656 (active idle watchers, EVLOOP_NONBLOCK or not having
592 any active watchers at all will result in not sleeping). 657 any active watchers at all will result in not sleeping).
593 - Sleep if the I/O and timer collect interval say so. 658 - Sleep if the I/O and timer collect interval say so.
594 - Block the process, waiting for any events. 659 - Block the process, waiting for any events.
595 - Queue all outstanding I/O (fd) events. 660 - Queue all outstanding I/O (fd) events.
596 - Update the "event loop time" and do time jump handling. 661 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
597 - Queue all outstanding timers. 662 - Queue all expired timers.
598 - Queue all outstanding periodics. 663 - Queue all expired periodics.
599 - If no events are pending now, queue all idle watchers. 664 - Unless any events are pending now, queue all idle watchers.
600 - Queue all check watchers. 665 - Queue all check watchers.
601 - 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).
602 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
603 be handled here by queueing them when their watcher gets executed. 668 be handled here by queueing them when their watcher gets executed.
604 - 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
609anymore. 674anymore.
610 675
611 ... queue jobs here, make sure they register event watchers as long 676 ... queue jobs here, make sure they register event watchers as long
612 ... 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..)
613 ev_loop (my_loop, 0); 678 ev_loop (my_loop, 0);
614 ... jobs done. yeah! 679 ... jobs done or somebody called unloop. yeah!
615 680
616=item ev_unloop (loop, how) 681=item ev_unloop (loop, how)
617 682
618Can 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
619has processed all outstanding events). The C<how> argument must be either 684has processed all outstanding events). The C<how> argument must be either
620C<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
621C<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.
622 687
623This "unloop state" will be cleared when entering C<ev_loop> again. 688This "unloop state" will be cleared when entering C<ev_loop> again.
624 689
690It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls.
691
625=item ev_ref (loop) 692=item ev_ref (loop)
626 693
627=item ev_unref (loop) 694=item ev_unref (loop)
628 695
629Ref/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
630loop: Every watcher keeps one reference, and as long as the reference 697loop: Every watcher keeps one reference, and as long as the reference
631count 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
632a 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>
633returning, 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
634example, 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
635visible 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
636no 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
637way 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
638libraries. 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>
639(but only if the watcher wasn't active before, or was active before, 709(but only if the watcher wasn't active before, or was active before,
640respectively). 710respectively).
641 711
642Example: 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>
643running when nothing else is active. 713running when nothing else is active.
644 714
645 struct ev_signal exitsig; 715 struct ev_signal exitsig;
646 ev_signal_init (&exitsig, sig_cb, SIGINT); 716 ev_signal_init (&exitsig, sig_cb, SIGINT);
647 ev_signal_start (loop, &exitsig); 717 ev_signal_start (loop, &exitsig);
648 evf_unref (loop); 718 evf_unref (loop);
649 719
650Example: For some weird reason, unregister the above signal handler again. 720Example: For some weird reason, unregister the above signal handler again.
651 721
652 ev_ref (loop); 722 ev_ref (loop);
653 ev_signal_stop (loop, &exitsig); 723 ev_signal_stop (loop, &exitsig);
654 724
655=item ev_set_io_collect_interval (loop, ev_tstamp interval) 725=item ev_set_io_collect_interval (loop, ev_tstamp interval)
656 726
657=item ev_set_timeout_collect_interval (loop, ev_tstamp interval) 727=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
658 728
659These advanced functions influence the time that libev will spend waiting 729These advanced functions influence the time that libev will spend waiting
660for events. Both are by default C<0>, meaning that libev will try to 730for events. Both time intervals are by default C<0>, meaning that libev
661invoke timer/periodic callbacks and I/O callbacks with minimum latency. 731will try to invoke timer/periodic callbacks and I/O callbacks with minimum
732latency.
662 733
663Setting these to a higher value (the C<interval> I<must> be >= C<0>) 734Setting these to a higher value (the C<interval> I<must> be >= C<0>)
664allows libev to delay invocation of I/O and timer/periodic callbacks to 735allows libev to delay invocation of I/O and timer/periodic callbacks
665increase efficiency of loop iterations. 736to increase efficiency of loop iterations (or to increase power-saving
737opportunities).
666 738
667The background is that sometimes your program runs just fast enough to 739The idea is that sometimes your program runs just fast enough to handle
668handle one (or very few) event(s) per loop iteration. While this makes 740one (or very few) event(s) per loop iteration. While this makes the
669the program responsive, it also wastes a lot of CPU time to poll for new 741program responsive, it also wastes a lot of CPU time to poll for new
670events, especially with backends like C<select ()> which have a high 742events, especially with backends like C<select ()> which have a high
671overhead for the actual polling but can deliver many events at once. 743overhead for the actual polling but can deliver many events at once.
672 744
673By setting a higher I<io collect interval> you allow libev to spend more 745By setting a higher I<io collect interval> you allow libev to spend more
674time collecting I/O events, so you can handle more events per iteration, 746time collecting I/O events, so you can handle more events per iteration,
676C<ev_timer>) will be not affected. Setting this to a non-null value will 748C<ev_timer>) will be not affected. Setting this to a non-null value will
677introduce an additional C<ev_sleep ()> call into most loop iterations. 749introduce an additional C<ev_sleep ()> call into most loop iterations.
678 750
679Likewise, by setting a higher I<timeout collect interval> you allow libev 751Likewise, by setting a higher I<timeout collect interval> you allow libev
680to spend more time collecting timeouts, at the expense of increased 752to spend more time collecting timeouts, at the expense of increased
681latency (the watcher callback will be called later). C<ev_io> watchers 753latency/jitter/inexactness (the watcher callback will be called
682will not be affected. Setting this to a non-null value will not introduce 754later). C<ev_io> watchers will not be affected. Setting this to a non-null
683any overhead in libev. 755value will not introduce any overhead in libev.
684 756
685Many (busy) programs can usually benefit by setting the io collect 757Many (busy) programs can usually benefit by setting the I/O collect
686interval to a value near C<0.1> or so, which is often enough for 758interval to a value near C<0.1> or so, which is often enough for
687interactive servers (of course not for games), likewise for timeouts. It 759interactive servers (of course not for games), likewise for timeouts. It
688usually doesn't make much sense to set it to a lower value than C<0.01>, 760usually doesn't make much sense to set it to a lower value than C<0.01>,
689as this approsaches the timing granularity of most systems. 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.
690 781
691=back 782=back
692 783
693 784
694=head1 ANATOMY OF A WATCHER 785=head1 ANATOMY OF A WATCHER
695 786
696A 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
697interest 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
698become readable, you would create an C<ev_io> watcher for that: 789become readable, you would create an C<ev_io> watcher for that:
699 790
700 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)
701 { 792 {
702 ev_io_stop (w); 793 ev_io_stop (w);
703 ev_unloop (loop, EVUNLOOP_ALL); 794 ev_unloop (loop, EVUNLOOP_ALL);
704 } 795 }
705 796
706 struct ev_loop *loop = ev_default_loop (0); 797 struct ev_loop *loop = ev_default_loop (0);
707 struct ev_io stdin_watcher; 798 struct ev_io stdin_watcher;
708 ev_init (&stdin_watcher, my_cb); 799 ev_init (&stdin_watcher, my_cb);
709 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 800 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
710 ev_io_start (loop, &stdin_watcher); 801 ev_io_start (loop, &stdin_watcher);
711 ev_loop (loop, 0); 802 ev_loop (loop, 0);
712 803
713As 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
714watcher 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,
715although this can sometimes be quite valid). 806although this can sometimes be quite valid).
716 807
717Each 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
718(watcher *, callback)>, which expects a callback to be provided. This 809(watcher *, callback)>, which expects a callback to be provided. This
719callback 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
720watchers, each time the event loop detects that the file descriptor given 811watchers, each time the event loop detects that the file descriptor given
721is readable and/or writable). 812is readable and/or writable).
722 813
723Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 814Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
724with arguments specific to this watcher type. There is also a macro 815with arguments specific to this watcher type. There is also a macro
800 891
801The given async watcher has been asynchronously notified (see C<ev_async>). 892The given async watcher has been asynchronously notified (see C<ev_async>).
802 893
803=item C<EV_ERROR> 894=item C<EV_ERROR>
804 895
805An unspecified error has occured, the watcher has been stopped. This might 896An unspecified error has occurred, the watcher has been stopped. This might
806happen because the watcher could not be properly started because libev 897happen because the watcher could not be properly started because libev
807ran 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
808problem. 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
809with the watcher being stopped. 900with the watcher being stopped.
810 901
811Libev will usually signal a few "dummy" events together with an error, 902Libev will usually signal a few "dummy" events together with an error, for
812for 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
813your 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
814with 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
815programs, though, so beware. 906programs, though, as the fd could already be closed and reused for another
907thing, so beware.
816 908
817=back 909=back
818 910
819=head2 GENERIC WATCHER FUNCTIONS 911=head2 GENERIC WATCHER FUNCTIONS
820 912
836(or never started) and there are no pending events outstanding. 928(or never started) and there are no pending events outstanding.
837 929
838The 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,
839int revents)>. 931int revents)>.
840 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
841=item C<ev_TYPE_set> (ev_TYPE *, [args]) 939=item C<ev_TYPE_set> (ev_TYPE *, [args])
842 940
843This 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
844call 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
845call 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
847difference to the C<ev_init> macro). 945difference to the C<ev_init> macro).
848 946
849Although some watcher types do not have type-specific arguments 947Although some watcher types do not have type-specific arguments
850(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.
851 949
950See C<ev_init>, above, for an example.
951
852=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 952=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
853 953
854This 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
855calls 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
856a 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);
857 961
858=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 962=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
859 963
860Starts (activates) the given watcher. Only active watchers will receive 964Starts (activates) the given watcher. Only active watchers will receive
861events. 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);
862 971
863=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 972=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
864 973
865Stops the given watcher again (if active) and clears the pending 974Stops the given watcher again (if active) and clears the pending
866status. It is possible that stopped watchers are pending (for example, 975status. It is possible that stopped watchers are pending (for example,
923 1032
924=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1033=item ev_invoke (loop, ev_TYPE *watcher, int revents)
925 1034
926Invoke 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
927C<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
928can deal with that fact. 1037can deal with that fact, as both are simply passed through to the
1038callback.
929 1039
930=item int ev_clear_pending (loop, ev_TYPE *watcher) 1040=item int ev_clear_pending (loop, ev_TYPE *watcher)
931 1041
932If the watcher is pending, this function returns clears its pending status 1042If the watcher is pending, this function clears its pending status and
933and 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
934watcher isn't pending it does nothing and returns C<0>. 1044watcher isn't pending it does nothing and returns C<0>.
935 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
936=back 1049=back
937 1050
938 1051
939=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1052=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
940 1053
941Each 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
942and 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
943to 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
944don'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
945member, you can also "subclass" the watcher type and provide your own 1058member, you can also "subclass" the watcher type and provide your own
946data: 1059data:
947 1060
948 struct my_io 1061 struct my_io
949 { 1062 {
950 struct ev_io io; 1063 struct ev_io io;
951 int otherfd; 1064 int otherfd;
952 void *somedata; 1065 void *somedata;
953 struct whatever *mostinteresting; 1066 struct whatever *mostinteresting;
954 } 1067 };
1068
1069 ...
1070 struct my_io w;
1071 ev_io_init (&w.io, my_cb, fd, EV_READ);
955 1072
956And 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
957can cast it back to your own type: 1074can cast it back to your own type:
958 1075
959 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)
960 { 1077 {
961 struct my_io *w = (struct my_io *)w_; 1078 struct my_io *w = (struct my_io *)w_;
962 ... 1079 ...
963 } 1080 }
964 1081
965More interesting and less C-conformant ways of casting your callback type 1082More interesting and less C-conformant ways of casting your callback type
966instead have been omitted. 1083instead have been omitted.
967 1084
968Another common scenario is having some data structure with multiple 1085Another common scenario is to use some data structure with multiple
969watchers: 1086embedded watchers:
970 1087
971 struct my_biggy 1088 struct my_biggy
972 { 1089 {
973 int some_data; 1090 int some_data;
974 ev_timer t1; 1091 ev_timer t1;
975 ev_timer t2; 1092 ev_timer t2;
976 } 1093 }
977 1094
978In 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
979you 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):
980 1100
981 #include <stddef.h> 1101 #include <stddef.h>
982 1102
983 static void 1103 static void
984 t1_cb (EV_P_ struct ev_timer *w, int revents) 1104 t1_cb (EV_P_ struct ev_timer *w, int revents)
985 { 1105 {
986 struct my_biggy big = (struct my_biggy * 1106 struct my_biggy big = (struct my_biggy *
987 (((char *)w) - offsetof (struct my_biggy, t1)); 1107 (((char *)w) - offsetof (struct my_biggy, t1));
988 } 1108 }
989 1109
990 static void 1110 static void
991 t2_cb (EV_P_ struct ev_timer *w, int revents) 1111 t2_cb (EV_P_ struct ev_timer *w, int revents)
992 { 1112 {
993 struct my_biggy big = (struct my_biggy * 1113 struct my_biggy big = (struct my_biggy *
994 (((char *)w) - offsetof (struct my_biggy, t2)); 1114 (((char *)w) - offsetof (struct my_biggy, t2));
995 } 1115 }
996 1116
997 1117
998=head1 WATCHER TYPES 1118=head1 WATCHER TYPES
999 1119
1000This section describes each watcher in detail, but will not repeat 1120This section describes each watcher in detail, but will not repeat
1024In 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
1025fd 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
1026descriptors 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
1027required if you know what you are doing). 1147required if you know what you are doing).
1028 1148
1029If you must do this, then force the use of a known-to-be-good backend 1149If you cannot use non-blocking mode, then force the use of a
1030(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 1150known-to-be-good backend (at the time of this writing, this includes only
1031C<EVBACKEND_POLL>). 1151C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>).
1032 1152
1033Another 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
1034receive "spurious" readyness notifications, that is your callback might 1154receive "spurious" readiness notifications, that is your callback might
1035be 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
1036because 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
1037lot 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
1038this situation even with a relatively standard program structure. Thus 1158this situation even with a relatively standard program structure. Thus
1039it 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
1040C<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.
1041 1161
1042If 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
1043play around with an Xlib connection), then you have to seperately re-test 1163not play around with an Xlib connection), then you have to separately
1044whether 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
1045such as poll (fortunately in our Xlib example, Xlib already does this on 1165interface such as poll (fortunately in our Xlib example, Xlib already
1046its 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.
1047 1171
1048=head3 The special problem of disappearing file descriptors 1172=head3 The special problem of disappearing file descriptors
1049 1173
1050Some 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
1051descriptor (either by calling C<close> explicitly or by any other means, 1175descriptor (either due to calling C<close> explicitly or any other means,
1052such 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
1053descriptor, but when it goes away, the operating system will silently drop 1177descriptor, but when it goes away, the operating system will silently drop
1054this interest. If another file descriptor with the same number then is 1178this interest. If another file descriptor with the same number then is
1055registered 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
1056fact, a different file descriptor. 1180fact, a different file descriptor.
1057 1181
1088enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1212enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1089C<EVBACKEND_POLL>. 1213C<EVBACKEND_POLL>.
1090 1214
1091=head3 The special problem of SIGPIPE 1215=head3 The special problem of SIGPIPE
1092 1216
1093While not really specific to libev, it is easy to forget about SIGPIPE: 1217While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1094when reading from a pipe whose other end has been closed, your program 1218when writing to a pipe whose other end has been closed, your program gets
1095gets send a SIGPIPE, which, by default, aborts your program. For most 1219sent a SIGPIPE, which, by default, aborts your program. For most programs
1096programs this is sensible behaviour, for daemons, this is usually 1220this is sensible behaviour, for daemons, this is usually undesirable.
1097undesirable.
1098 1221
1099So when you encounter spurious, unexplained daemon exits, make sure you 1222So when you encounter spurious, unexplained daemon exits, make sure you
1100ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1223ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1101somewhere, as that would have given you a big clue). 1224somewhere, as that would have given you a big clue).
1102 1225
1108=item ev_io_init (ev_io *, callback, int fd, int events) 1231=item ev_io_init (ev_io *, callback, int fd, int events)
1109 1232
1110=item ev_io_set (ev_io *, int fd, int events) 1233=item ev_io_set (ev_io *, int fd, int events)
1111 1234
1112Configures 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
1113rceeive 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
1114C<EV_READ | EV_WRITE> to receive the given events. 1237C<EV_READ | EV_WRITE>, to express the desire to receive the given events.
1115 1238
1116=item int fd [read-only] 1239=item int fd [read-only]
1117 1240
1118The file descriptor being watched. 1241The file descriptor being watched.
1119 1242
1127 1250
1128Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well 1251Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1129readable, but only once. Since it is likely line-buffered, you could 1252readable, but only once. Since it is likely line-buffered, you could
1130attempt to read a whole line in the callback. 1253attempt to read a whole line in the callback.
1131 1254
1132 static void 1255 static void
1133 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)
1134 { 1257 {
1135 ev_io_stop (loop, w); 1258 ev_io_stop (loop, w);
1136 .. 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
1137 } 1260 }
1138 1261
1139 ... 1262 ...
1140 struct ev_loop *loop = ev_default_init (0); 1263 struct ev_loop *loop = ev_default_init (0);
1141 struct ev_io stdin_readable; 1264 struct ev_io stdin_readable;
1142 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);
1143 ev_io_start (loop, &stdin_readable); 1266 ev_io_start (loop, &stdin_readable);
1144 ev_loop (loop, 0); 1267 ev_loop (loop, 0);
1145 1268
1146 1269
1147=head2 C<ev_timer> - relative and optionally repeating timeouts 1270=head2 C<ev_timer> - relative and optionally repeating timeouts
1148 1271
1149Timer watchers are simple relative timers that generate an event after a 1272Timer watchers are simple relative timers that generate an event after a
1150given time, and optionally repeating in regular intervals after that. 1273given time, and optionally repeating in regular intervals after that.
1151 1274
1152The 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
1153times 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
1154time, it will still time out after (roughly) and hour. "Roughly" because 1277year, it will still time out after (roughly) one hour. "Roughly" because
1155detecting time jumps is hard, and some inaccuracies are unavoidable (the 1278detecting time jumps is hard, and some inaccuracies are unavoidable (the
1156monotonic 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.
1157 1292
1158The relative timeouts are calculated relative to the C<ev_now ()> 1293The relative timeouts are calculated relative to the C<ev_now ()>
1159time. 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
1160of the event triggering whatever timeout you are modifying/starting. If 1295of the event triggering whatever timeout you are modifying/starting. If
1161you 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
1162on the current time, use something like this to adjust for this: 1297timeout on the current time, use something like this to adjust for this:
1163 1298
1164 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1299 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1165 1300
1166The 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
1167but 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
1168order of execution is undefined. 1303()>.
1169 1304
1170=head3 Watcher-Specific Functions and Data Members 1305=head3 Watcher-Specific Functions and Data Members
1171 1306
1172=over 4 1307=over 4
1173 1308
1174=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)
1175 1310
1176=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)
1177 1312
1178Configure the timer to trigger after C<after> seconds. If C<repeat> is 1313Configure the timer to trigger after C<after> seconds. If C<repeat>
1179C<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
1180timer will automatically be configured to trigger again C<repeat> seconds 1315reached. If it is positive, then the timer will automatically be
1181later, again, and again, until stopped manually. 1316configured to trigger again C<repeat> seconds later, again, and again,
1317until stopped manually.
1182 1318
1183The 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
1184configure 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
1185exactly 10 second intervals. If, however, your program cannot keep up with 1321trigger at exactly 10 second intervals. If, however, your program cannot
1186the 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
1187timer will not fire more than once per event loop iteration. 1323do stuff) the timer will not fire more than once per event loop iteration.
1188 1324
1189=item ev_timer_again (loop, ev_timer *) 1325=item ev_timer_again (loop, ev_timer *)
1190 1326
1191This 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
1192repeating. The exact semantics are: 1328repeating. The exact semantics are:
1193 1329
1194If the timer is pending, its pending status is cleared. 1330If the timer is pending, its pending status is cleared.
1195 1331
1196If 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).
1197 1333
1198If the timer is repeating, either start it if necessary (with the 1334If the timer is repeating, either start it if necessary (with the
1199C<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.
1200 1336
1201This sounds a bit complicated, but here is a useful and typical 1337This sounds a bit complicated, but here is a useful and typical
1202example: 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
1203timeout, 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
1204seconds 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
1205configure 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
1206C<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
1207you 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
1221 ev_timer_again (loop, timer); 1357 ev_timer_again (loop, timer);
1222 1358
1223This is more slightly efficient then stopping/starting the timer each time 1359This is more slightly efficient then stopping/starting the timer each time
1224you want to modify its timeout value. 1360you want to modify its timeout value.
1225 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
1226=item ev_tstamp repeat [read-write] 1368=item ev_tstamp repeat [read-write]
1227 1369
1228The 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
1229or 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),
1230which is also when any modifications are taken into account. 1372which is also when any modifications are taken into account.
1231 1373
1232=back 1374=back
1233 1375
1234=head3 Examples 1376=head3 Examples
1235 1377
1236Example: Create a timer that fires after 60 seconds. 1378Example: Create a timer that fires after 60 seconds.
1237 1379
1238 static void 1380 static void
1239 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)
1240 { 1382 {
1241 .. one minute over, w is actually stopped right here 1383 .. one minute over, w is actually stopped right here
1242 } 1384 }
1243 1385
1244 struct ev_timer mytimer; 1386 struct ev_timer mytimer;
1245 ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1387 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1246 ev_timer_start (loop, &mytimer); 1388 ev_timer_start (loop, &mytimer);
1247 1389
1248Example: Create a timeout timer that times out after 10 seconds of 1390Example: Create a timeout timer that times out after 10 seconds of
1249inactivity. 1391inactivity.
1250 1392
1251 static void 1393 static void
1252 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)
1253 { 1395 {
1254 .. ten seconds without any activity 1396 .. ten seconds without any activity
1255 } 1397 }
1256 1398
1257 struct ev_timer mytimer; 1399 struct ev_timer mytimer;
1258 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 */
1259 ev_timer_again (&mytimer); /* start timer */ 1401 ev_timer_again (&mytimer); /* start timer */
1260 ev_loop (loop, 0); 1402 ev_loop (loop, 0);
1261 1403
1262 // 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":
1263 // reset the timeout to start ticking again at 10 seconds 1405 // reset the timeout to start ticking again at 10 seconds
1264 ev_timer_again (&mytimer); 1406 ev_timer_again (&mytimer);
1265 1407
1266 1408
1267=head2 C<ev_periodic> - to cron or not to cron? 1409=head2 C<ev_periodic> - to cron or not to cron?
1268 1410
1269Periodic 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
1270(and unfortunately a bit complex). 1412(and unfortunately a bit complex).
1271 1413
1272Unlike 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)
1273but on wallclock time (absolute time). You can tell a periodic watcher 1415but on wall clock time (absolute time). You can tell a periodic watcher
1274to 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
1275periodic 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 ()
1276+ 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
1277take 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
1278roughly 10 seconds later). 1421roughly 10 seconds later as it uses a relative timeout).
1279 1422
1280They 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,
1281triggering an event on each midnight, local time or other, complicated, 1424such as triggering an event on each "midnight, local time", or other
1282rules. 1425complicated rules.
1283 1426
1284As 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
1285time (C<at>) has been passed, but if multiple periodic timers become ready 1428time (C<at>) has passed, but if multiple periodic timers become ready
1286during the same loop iteration then order of execution is undefined. 1429during the same loop iteration, then order of execution is undefined.
1287 1430
1288=head3 Watcher-Specific Functions and Data Members 1431=head3 Watcher-Specific Functions and Data Members
1289 1432
1290=over 4 1433=over 4
1291 1434
1292=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)
1293 1436
1294=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)
1295 1438
1296Lots 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
1297operation, and we will explain them from simplest to complex: 1440operation, and we will explain them from simplest to most complex:
1298 1441
1299=over 4 1442=over 4
1300 1443
1301=item * absolute timer (at = time, interval = reschedule_cb = 0) 1444=item * absolute timer (at = time, interval = reschedule_cb = 0)
1302 1445
1303In this configuration the watcher triggers an event at the wallclock time 1446In this configuration the watcher triggers an event after the wall clock
1304C<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
1305that 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
1306system time reaches or surpasses this time. 1449only run when the system clock reaches or surpasses this time.
1307 1450
1308=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1451=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1309 1452
1310In 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
1311C<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)
1312and then repeat, regardless of any time jumps. 1455and then repeat, regardless of any time jumps.
1313 1456
1314This 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
1315time: 1458system clock, for example, here is a C<ev_periodic> that triggers each
1459hour, on the hour:
1316 1460
1317 ev_periodic_set (&periodic, 0., 3600., 0); 1461 ev_periodic_set (&periodic, 0., 3600., 0);
1318 1462
1319This 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,
1320but 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
1321full 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
1322by 3600. 1466by 3600.
1323 1467
1324Another way to think about it (for the mathematically inclined) is that 1468Another way to think about it (for the mathematically inclined) is that
1325C<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
1326time where C<time = at (mod interval)>, regardless of any time jumps. 1470time where C<time = at (mod interval)>, regardless of any time jumps.
1327 1471
1328For 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
1329C<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
1330this 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).
1331 1480
1332=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1481=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1333 1482
1334In 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
1335ignored. Instead, each time the periodic watcher gets scheduled, the 1484ignored. Instead, each time the periodic watcher gets scheduled, the
1336reschedule callback will be called with the watcher as first, and the 1485reschedule callback will be called with the watcher as first, and the
1337current time as second argument. 1486current time as second argument.
1338 1487
1339NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1488NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1340ever, or make any event loop modifications>. If you need to stop it, 1489ever, or make ANY event loop modifications whatsoever>.
1341return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1342starting an C<ev_prepare> watcher, which is legal).
1343 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
1344Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1495The callback prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic
1345ev_tstamp now)>, e.g.: 1496*w, ev_tstamp now)>, e.g.:
1346 1497
1347 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)
1348 { 1499 {
1349 return now + 60.; 1500 return now + 60.;
1350 } 1501 }
1352It 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
1353(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
1354will usually be called just before the callback will be triggered, but 1505will usually be called just before the callback will be triggered, but
1355might be called at other times, too. 1506might be called at other times, too.
1356 1507
1357NOTE: 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
1358passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger. 1509equal to the passed C<now> value >>.
1359 1510
1360This 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
1361triggers 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
1362next 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
1363you 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
1364reason I omitted it as an example). 1515reason I omitted it as an example).
1365 1516
1366=back 1517=back
1370Simply stops and restarts the periodic watcher again. This is only useful 1521Simply stops and restarts the periodic watcher again. This is only useful
1371when you changed some parameters or the reschedule callback would return 1522when you changed some parameters or the reschedule callback would return
1372a 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
1373program when the crontabs have changed). 1524program when the crontabs have changed).
1374 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
1375=item ev_tstamp offset [read-write] 1531=item ev_tstamp offset [read-write]
1376 1532
1377When repeating, this contains the offset value, otherwise this is the 1533When repeating, this contains the offset value, otherwise this is the
1378absolute 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>).
1379 1535
1390 1546
1391The current reschedule callback, or C<0>, if this functionality is 1547The current reschedule callback, or C<0>, if this functionality is
1392switched 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
1393the periodic timer fires or C<ev_periodic_again> is being called. 1549the periodic timer fires or C<ev_periodic_again> is being called.
1394 1550
1395=item ev_tstamp at [read-only]
1396
1397When active, contains the absolute time that the watcher is supposed to
1398trigger next.
1399
1400=back 1551=back
1401 1552
1402=head3 Examples 1553=head3 Examples
1403 1554
1404Example: Call a callback every hour, or, more precisely, whenever the 1555Example: Call a callback every hour, or, more precisely, whenever the
1405system clock is divisible by 3600. The callback invocation times have 1556system time is divisible by 3600. The callback invocation times have
1406potentially a lot of jittering, but good long-term stability. 1557potentially a lot of jitter, but good long-term stability.
1407 1558
1408 static void 1559 static void
1409 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)
1410 { 1561 {
1411 ... 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)
1412 } 1563 }
1413 1564
1414 struct ev_periodic hourly_tick; 1565 struct ev_periodic hourly_tick;
1415 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 1566 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1416 ev_periodic_start (loop, &hourly_tick); 1567 ev_periodic_start (loop, &hourly_tick);
1417 1568
1418Example: 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:
1419 1570
1420 #include <math.h> 1571 #include <math.h>
1421 1572
1422 static ev_tstamp 1573 static ev_tstamp
1423 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1574 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
1424 { 1575 {
1425 return fmod (now, 3600.) + 3600.; 1576 return now + (3600. - fmod (now, 3600.));
1426 } 1577 }
1427 1578
1428 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);
1429 1580
1430Example: Call a callback every hour, starting now: 1581Example: Call a callback every hour, starting now:
1431 1582
1432 struct ev_periodic hourly_tick; 1583 struct ev_periodic hourly_tick;
1433 ev_periodic_init (&hourly_tick, clock_cb, 1584 ev_periodic_init (&hourly_tick, clock_cb,
1434 fmod (ev_now (loop), 3600.), 3600., 0); 1585 fmod (ev_now (loop), 3600.), 3600., 0);
1435 ev_periodic_start (loop, &hourly_tick); 1586 ev_periodic_start (loop, &hourly_tick);
1436 1587
1437 1588
1438=head2 C<ev_signal> - signal me when a signal gets signalled! 1589=head2 C<ev_signal> - signal me when a signal gets signalled!
1439 1590
1440Signal watchers will trigger an event when the process receives a specific 1591Signal watchers will trigger an event when the process receives a specific
1441signal one or more times. Even though signals are very asynchronous, libev 1592signal one or more times. Even though signals are very asynchronous, libev
1442will 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
1443normal event processing, like any other event. 1594normal event processing, like any other event.
1444 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
1445You 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
1446first watcher gets started will libev actually register a signal watcher 1601first watcher gets started will libev actually register a signal handler
1447with 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
1448as 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
1449watcher 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
1450SIG_DFL (regardless of what it was set to before). 1605signal handler to SIG_DFL (regardless of what it was set to before).
1451 1606
1452If possible and supported, libev will install its handlers with 1607If possible and supported, libev will install its handlers with
1453C<SA_RESTART> behaviour enabled, so syscalls should not be unduly 1608C<SA_RESTART> behaviour enabled, so system calls should not be unduly
1454interrupted. If you have a problem with syscalls getting interrupted by 1609interrupted. If you have a problem with system calls getting interrupted by
1455signals you can block all signals in an C<ev_check> watcher and unblock 1610signals you can block all signals in an C<ev_check> watcher and unblock
1456them in an C<ev_prepare> watcher. 1611them in an C<ev_prepare> watcher.
1457 1612
1458=head3 Watcher-Specific Functions and Data Members 1613=head3 Watcher-Specific Functions and Data Members
1459 1614
1472 1627
1473=back 1628=back
1474 1629
1475=head3 Examples 1630=head3 Examples
1476 1631
1477Example: Try to exit cleanly on SIGINT and SIGTERM. 1632Example: Try to exit cleanly on SIGINT.
1478 1633
1479 static void 1634 static void
1480 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1635 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1481 { 1636 {
1482 ev_unloop (loop, EVUNLOOP_ALL); 1637 ev_unloop (loop, EVUNLOOP_ALL);
1483 } 1638 }
1484 1639
1485 struct ev_signal signal_watcher; 1640 struct ev_signal signal_watcher;
1486 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1641 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1487 ev_signal_start (loop, &sigint_cb); 1642 ev_signal_start (loop, &signal_watcher);
1488 1643
1489 1644
1490=head2 C<ev_child> - watch out for process status changes 1645=head2 C<ev_child> - watch out for process status changes
1491 1646
1492Child watchers trigger when your process receives a SIGCHLD in response to 1647Child watchers trigger when your process receives a SIGCHLD in response to
1493some child status changes (most typically when a child of yours dies). It 1648some child status changes (most typically when a child of yours dies or
1494is permissible to install a child watcher I<after> the child has been 1649exits). It is permissible to install a child watcher I<after> the child
1495forked (which implies it might have already exited), as long as the event 1650has been forked (which implies it might have already exited), as long
1496loop isn't entered (or is continued from a watcher). 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.
1497 1655
1498Only the default event loop is capable of handling signals, and therefore 1656Only the default event loop is capable of handling signals, and therefore
1499you can only rgeister child watchers in the default event loop. 1657you can only register child watchers in the default event loop.
1500 1658
1501=head3 Process Interaction 1659=head3 Process Interaction
1502 1660
1503Libev grabs C<SIGCHLD> as soon as the default event loop is 1661Libev grabs C<SIGCHLD> as soon as the default event loop is
1504initialised. This is necessary to guarantee proper behaviour even if 1662initialised. This is necessary to guarantee proper behaviour even if
1505the first child watcher is started after the child exits. The occurance 1663the first child watcher is started after the child exits. The occurrence
1506of C<SIGCHLD> is recorded asynchronously, but child reaping is done 1664of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1507synchronously as part of the event loop processing. Libev always reaps all 1665synchronously as part of the event loop processing. Libev always reaps all
1508children, even ones not watched. 1666children, even ones not watched.
1509 1667
1510=head3 Overriding the Built-In Processing 1668=head3 Overriding the Built-In Processing
1514handler, you can override it easily by installing your own handler for 1672handler, you can override it easily by installing your own handler for
1515C<SIGCHLD> after initialising the default loop, and making sure the 1673C<SIGCHLD> after initialising the default loop, and making sure the
1516default loop never gets destroyed. You are encouraged, however, to use an 1674default loop never gets destroyed. You are encouraged, however, to use an
1517event-based approach to child reaping and thus use libev's support for 1675event-based approach to child reaping and thus use libev's support for
1518that, so other libev users can use C<ev_child> watchers freely. 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.
1519 1684
1520=head3 Watcher-Specific Functions and Data Members 1685=head3 Watcher-Specific Functions and Data Members
1521 1686
1522=over 4 1687=over 4
1523 1688
1552=head3 Examples 1717=head3 Examples
1553 1718
1554Example: C<fork()> a new process and install a child handler to wait for 1719Example: C<fork()> a new process and install a child handler to wait for
1555its completion. 1720its completion.
1556 1721
1557 ev_child cw; 1722 ev_child cw;
1558 1723
1559 static void 1724 static void
1560 child_cb (EV_P_ struct ev_child *w, int revents) 1725 child_cb (EV_P_ struct ev_child *w, int revents)
1561 { 1726 {
1562 ev_child_stop (EV_A_ w); 1727 ev_child_stop (EV_A_ w);
1563 printf ("process %d exited with status %x\n", w->rpid, w->rstatus); 1728 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1564 } 1729 }
1565 1730
1566 pid_t pid = fork (); 1731 pid_t pid = fork ();
1567 1732
1568 if (pid < 0) 1733 if (pid < 0)
1569 // error 1734 // error
1570 else if (pid == 0) 1735 else if (pid == 0)
1571 { 1736 {
1572 // the forked child executes here 1737 // the forked child executes here
1573 exit (1); 1738 exit (1);
1574 } 1739 }
1575 else 1740 else
1576 { 1741 {
1577 ev_child_init (&cw, child_cb, pid, 0); 1742 ev_child_init (&cw, child_cb, pid, 0);
1578 ev_child_start (EV_DEFAULT_ &cw); 1743 ev_child_start (EV_DEFAULT_ &cw);
1579 } 1744 }
1580 1745
1581 1746
1582=head2 C<ev_stat> - did the file attributes just change? 1747=head2 C<ev_stat> - did the file attributes just change?
1583 1748
1584This watches a filesystem path for attribute changes. That is, it calls 1749This watches a file system path for attribute changes. That is, it calls
1585C<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
1586compared to the last time, invoking the callback if it did. 1751compared to the last time, invoking the callback if it did.
1587 1752
1588The 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
1589not 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
1592the stat buffer having unspecified contents. 1757the stat buffer having unspecified contents.
1593 1758
1594The 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
1595relative and your working directory changes, the behaviour is undefined. 1760relative and your working directory changes, the behaviour is undefined.
1596 1761
1597Since there is no standard to do this, the portable implementation simply 1762Since there is no standard kernel interface to do this, the portable
1598calls 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
1599can specify a recommended polling interval for this case. If you specify 1764it changed somehow. You can specify a recommended polling interval for
1600a polling interval of C<0> (highly recommended!) then a I<suitable, 1765this case. If you specify a polling interval of C<0> (highly recommended!)
1601unspecified default> value will be used (which you can expect to be around 1766then a I<suitable, unspecified default> value will be used (which
1602five seconds, although this might change dynamically). Libev will also 1767you can expect to be around five seconds, although this might change
1603impose a minimum interval which is currently around C<0.1>, but thats 1768dynamically). Libev will also impose a minimum interval which is currently
1604usually overkill. 1769around C<0.1>, but thats usually overkill.
1605 1770
1606This watcher type is not meant for massive numbers of stat watchers, 1771This watcher type is not meant for massive numbers of stat watchers,
1607as even with OS-supported change notifications, this can be 1772as even with OS-supported change notifications, this can be
1608resource-intensive. 1773resource-intensive.
1609 1774
1610At the time of this writing, only the Linux inotify interface is 1775At the time of this writing, the only OS-specific interface implemented
1611implemented (implementing kqueue support is left as an exercise for the 1776is the Linux inotify interface (implementing kqueue support is left as
1612reader). 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
1613semantics of C<ev_stat> watchers, which means that libev sometimes needs 1778of implementing C<ev_stat> semantics with kqueue).
1614to fall back to regular polling again even with inotify, but changes are
1615usually detected immediately, and if the file exists there will be no
1616polling.
1617 1779
1618=head3 ABI Issues (Largefile Support) 1780=head3 ABI Issues (Largefile Support)
1619 1781
1620Libev by default (unless the user overrides this) uses the default 1782Libev by default (unless the user overrides this) uses the default
1621compilation environment, which means that on systems with optionally 1783compilation environment, which means that on systems with large file
1622disabled large file support, you get the 32 bit version of the stat 1784support disabled by default, you get the 32 bit version of the stat
1623structure. When using the library from programs that change the ABI to 1785structure. When using the library from programs that change the ABI to
1624use 64 bit file offsets the programs will fail. In that case you have to 1786use 64 bit file offsets the programs will fail. In that case you have to
1625compile libev with the same flags to get binary compatibility. This is 1787compile libev with the same flags to get binary compatibility. This is
1626obviously the case with any flags that change the ABI, but the problem is 1788obviously the case with any flags that change the ABI, but the problem is
1627most noticably with ev_stat and largefile support. 1789most noticeably disabled with ev_stat and large file support.
1628 1790
1629=head3 Inotify 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
1630 1798
1631When C<inotify (7)> support has been compiled into libev (generally only 1799When C<inotify (7)> support has been compiled into libev (generally only
1632available on Linux) and present at runtime, it will be used to speed up 1800available with Linux) and present at runtime, it will be used to speed up
1633change detection where possible. The inotify descriptor will be created lazily 1801change detection where possible. The inotify descriptor will be created lazily
1634when the first C<ev_stat> watcher is being started. 1802when the first C<ev_stat> watcher is being started.
1635 1803
1636Inotify presense does not change the semantics of C<ev_stat> watchers 1804Inotify presence does not change the semantics of C<ev_stat> watchers
1637except that changes might be detected earlier, and in some cases, to avoid 1805except that changes might be detected earlier, and in some cases, to avoid
1638making regular C<stat> calls. Even in the presense of inotify support 1806making regular C<stat> calls. Even in the presence of inotify support
1639there are many cases where libev has to resort to regular C<stat> polling. 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.
1640 1809
1641(There is no support for kqueue, as apparently it cannot be used to 1810There is no support for kqueue, as apparently it cannot be used to
1642implement this functionality, due to the requirement of having a file 1811implement this functionality, due to the requirement of having a file
1643descriptor open on the object at all times). 1812descriptor open on the object at all times, and detecting renames, unlinks
1813etc. is difficult.
1644 1814
1645=head3 The special problem of stat time resolution 1815=head3 The special problem of stat time resolution
1646 1816
1647The C<stat ()> syscall only supports full-second resolution portably, and 1817The C<stat ()> system call only supports full-second resolution portably, and
1648even on systems where the resolution is higher, many filesystems still 1818even on systems where the resolution is higher, most file systems still
1649only support whole seconds. 1819only support whole seconds.
1650 1820
1651That means that, if the time is the only thing that changes, you might 1821That means that, if the time is the only thing that changes, you can
1652miss updates: on the first update, C<ev_stat> detects a change and calls 1822easily miss updates: on the first update, C<ev_stat> detects a change and
1653your callback, which does something. When there is another update within 1823calls your callback, which does something. When there is another update
1654the same second, C<ev_stat> will be unable to detect it. 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).
1655 1826
1656The solution to this is to delay acting on a change for a second (or till 1827The solution to this is to delay acting on a change for slightly more
1657the next second boundary), using a roughly one-second delay C<ev_timer> 1828than a second (or till slightly after the next full second boundary), using
1658(C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01> 1829a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
1659is added to work around small timing inconsistencies of some operating 1830ev_timer_again (loop, w)>).
1660systems. 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).
1661 1840
1662=head3 Watcher-Specific Functions and Data Members 1841=head3 Watcher-Specific Functions and Data Members
1663 1842
1664=over 4 1843=over 4
1665 1844
1671C<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
1672be 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
1673a 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
1674path for as long as the watcher is active. 1853path for as long as the watcher is active.
1675 1854
1676The 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,
1677relative 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
1678last change was detected). 1857last change was detected).
1679 1858
1680=item ev_stat_stat (loop, ev_stat *) 1859=item ev_stat_stat (loop, ev_stat *)
1681 1860
1682Updates the stat buffer immediately with new values. If you change the 1861Updates the stat buffer immediately with new values. If you change the
1683watched path in your callback, you could call this fucntion to avoid 1862watched path in your callback, you could call this function to avoid
1684detecting this change (while introducing a race condition). Can also be 1863detecting this change (while introducing a race condition if you are not
1685useful simply to find out the new values. 1864the only one changing the path). Can also be useful simply to find out the
1865new values.
1686 1866
1687=item ev_statdata attr [read-only] 1867=item ev_statdata attr [read-only]
1688 1868
1689The most-recently detected attributes of the file. Although the type is of 1869The most-recently detected attributes of the file. Although the type is
1690C<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
1691suitable 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
1692was some error while C<stat>ing the file. 1873some error while C<stat>ing the file.
1693 1874
1694=item ev_statdata prev [read-only] 1875=item ev_statdata prev [read-only]
1695 1876
1696The previous attributes of the file. The callback gets invoked whenever 1877The previous attributes of the file. The callback gets invoked whenever
1697C<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>.
1698 1881
1699=item ev_tstamp interval [read-only] 1882=item ev_tstamp interval [read-only]
1700 1883
1701The specified interval. 1884The specified interval.
1702 1885
1703=item const char *path [read-only] 1886=item const char *path [read-only]
1704 1887
1705The filesystem path that is being watched. 1888The file system path that is being watched.
1706 1889
1707=back 1890=back
1708 1891
1709=head3 Examples 1892=head3 Examples
1710 1893
1711Example: Watch C</etc/passwd> for attribute changes. 1894Example: Watch C</etc/passwd> for attribute changes.
1712 1895
1713 static void 1896 static void
1714 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1897 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1715 { 1898 {
1716 /* /etc/passwd changed in some way */ 1899 /* /etc/passwd changed in some way */
1717 if (w->attr.st_nlink) 1900 if (w->attr.st_nlink)
1718 { 1901 {
1719 printf ("passwd current size %ld\n", (long)w->attr.st_size); 1902 printf ("passwd current size %ld\n", (long)w->attr.st_size);
1720 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime); 1903 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
1721 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime); 1904 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
1722 } 1905 }
1723 else 1906 else
1724 /* you shalt not abuse printf for puts */ 1907 /* you shalt not abuse printf for puts */
1725 puts ("wow, /etc/passwd is not there, expect problems. " 1908 puts ("wow, /etc/passwd is not there, expect problems. "
1726 "if this is windows, they already arrived\n"); 1909 "if this is windows, they already arrived\n");
1727 } 1910 }
1728 1911
1729 ... 1912 ...
1730 ev_stat passwd; 1913 ev_stat passwd;
1731 1914
1732 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); 1915 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1733 ev_stat_start (loop, &passwd); 1916 ev_stat_start (loop, &passwd);
1734 1917
1735Example: Like above, but additionally use a one-second delay so we do not 1918Example: Like above, but additionally use a one-second delay so we do not
1736miss updates (however, frequent updates will delay processing, too, so 1919miss updates (however, frequent updates will delay processing, too, so
1737one might do the work both on C<ev_stat> callback invocation I<and> on 1920one might do the work both on C<ev_stat> callback invocation I<and> on
1738C<ev_timer> callback invocation). 1921C<ev_timer> callback invocation).
1739 1922
1740 static ev_stat passwd; 1923 static ev_stat passwd;
1741 static ev_timer timer; 1924 static ev_timer timer;
1742 1925
1743 static void 1926 static void
1744 timer_cb (EV_P_ ev_timer *w, int revents) 1927 timer_cb (EV_P_ ev_timer *w, int revents)
1745 { 1928 {
1746 ev_timer_stop (EV_A_ w); 1929 ev_timer_stop (EV_A_ w);
1747 1930
1748 /* now it's one second after the most recent passwd change */ 1931 /* now it's one second after the most recent passwd change */
1749 } 1932 }
1750 1933
1751 static void 1934 static void
1752 stat_cb (EV_P_ ev_stat *w, int revents) 1935 stat_cb (EV_P_ ev_stat *w, int revents)
1753 { 1936 {
1754 /* reset the one-second timer */ 1937 /* reset the one-second timer */
1755 ev_timer_again (EV_A_ &timer); 1938 ev_timer_again (EV_A_ &timer);
1756 } 1939 }
1757 1940
1758 ... 1941 ...
1759 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 1942 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1760 ev_stat_start (loop, &passwd); 1943 ev_stat_start (loop, &passwd);
1761 ev_timer_init (&timer, timer_cb, 0., 1.01); 1944 ev_timer_init (&timer, timer_cb, 0., 1.02);
1762 1945
1763 1946
1764=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...
1765 1948
1766Idle 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
1767priority are pending (prepare, check and other idle watchers do not 1950priority are pending (prepare, check and other idle watchers do not count
1768count). 1951as receiving "events").
1769 1952
1770That 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
1771(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
1772triggered. But when your process is idle (or only lower-priority watchers 1955triggered. But when your process is idle (or only lower-priority watchers
1773are pending), the idle watchers are being called once per event loop 1956are pending), the idle watchers are being called once per event loop
1797=head3 Examples 1980=head3 Examples
1798 1981
1799Example: 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
1800callback, free it. Also, use no error checking, as usual. 1983callback, free it. Also, use no error checking, as usual.
1801 1984
1802 static void 1985 static void
1803 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)
1804 { 1987 {
1805 free (w); 1988 free (w);
1806 // now do something you wanted to do when the program has 1989 // now do something you wanted to do when the program has
1807 // no longer anything immediate to do. 1990 // no longer anything immediate to do.
1808 } 1991 }
1809 1992
1810 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 1993 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1811 ev_idle_init (idle_watcher, idle_cb); 1994 ev_idle_init (idle_watcher, idle_cb);
1812 ev_idle_start (loop, idle_cb); 1995 ev_idle_start (loop, idle_cb);
1813 1996
1814 1997
1815=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!
1816 1999
1817Prepare and check watchers are usually (but not always) used in tandem: 2000Prepare and check watchers are usually (but not always) used in pairs:
1818prepare watchers get invoked before the process blocks and check watchers 2001prepare watchers get invoked before the process blocks and check watchers
1819afterwards. 2002afterwards.
1820 2003
1821You 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
1822the 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>
1825those 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,
1826C<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
1827called in pairs bracketing the blocking call. 2010called in pairs bracketing the blocking call.
1828 2011
1829Their main purpose is to integrate other event mechanisms into libev and 2012Their main purpose is to integrate other event mechanisms into libev and
1830their 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
1831variable changes, implement your own watchers, integrate net-snmp or a 2014variable changes, implement your own watchers, integrate net-snmp or a
1832coroutine library and lots more. They are also occasionally useful if 2015coroutine library and lots more. They are also occasionally useful if
1833you 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,
1834in 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>
1835watcher). 2018watcher).
1836 2019
1837This is done by examining in each prepare call which file descriptors need 2020This is done by examining in each prepare call which file descriptors
1838to 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
1839them 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
1840provide just this functionality). Then, in the check watcher you check for 2023libraries provide exactly this functionality). Then, in the check watcher,
1841any events that occured (by checking the pending status of all watchers 2024you check for any events that occurred (by checking the pending status
1842and 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
1843callbacks will never actually be called (but must be valid nevertheless, 2026I/O and timer callbacks will never actually be called (but must be valid
1844because you never know, you know?). 2027nevertheless, because you never know, you know?).
1845 2028
1846As another example, the Perl Coro module uses these hooks to integrate 2029As another example, the Perl Coro module uses these hooks to integrate
1847coroutines into libev programs, by yielding to other active coroutines 2030coroutines into libev programs, by yielding to other active coroutines
1848during each prepare and only letting the process block if no coroutines 2031during each prepare and only letting the process block if no coroutines
1849are 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
1852loop from blocking if lower-priority coroutines are active, thus mapping 2035loop from blocking if lower-priority coroutines are active, thus mapping
1853low-priority coroutines to idle/background tasks). 2036low-priority coroutines to idle/background tasks).
1854 2037
1855It 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>)
1856priority, 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
1857after 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
1858too) should not activate ("feed") events into libev. While libev fully 2043activate ("feed") events into libev. While libev fully supports this, they
1859supports this, they will be called before other C<ev_check> watchers 2044might get executed before other C<ev_check> watchers did their job. As
1860did their job. As C<ev_check> watchers are often used to embed other 2045C<ev_check> watchers are often used to embed other (non-libev) event
1861(non-libev) event loops those other event loops might be in an unusable 2046loops those other event loops might be in an unusable state until their
1862state until their C<ev_check> watcher ran (always remind yourself to 2047C<ev_check> watcher ran (always remind yourself to coexist peacefully with
1863coexist peacefully with others). 2048others).
1864 2049
1865=head3 Watcher-Specific Functions and Data Members 2050=head3 Watcher-Specific Functions and Data Members
1866 2051
1867=over 4 2052=over 4
1868 2053
1870 2055
1871=item ev_check_init (ev_check *, callback) 2056=item ev_check_init (ev_check *, callback)
1872 2057
1873Initialises and configures the prepare or check watcher - they have no 2058Initialises and configures the prepare or check watcher - they have no
1874parameters 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>
1875macros, but using them is utterly, utterly and completely pointless. 2060macros, but using them is utterly, utterly, utterly and completely
2061pointless.
1876 2062
1877=back 2063=back
1878 2064
1879=head3 Examples 2065=head3 Examples
1880 2066
1881There 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
1882into 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
1883(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
1884use 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
1885embeds 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
1886into the Glib event loop). 2072Glib event loop).
1887 2073
1888Method 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,
1889and 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
1890is 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
1891priority 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
1892the 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.
1893 2079
1894 static ev_io iow [nfd]; 2080 static ev_io iow [nfd];
1895 static ev_timer tw; 2081 static ev_timer tw;
1896 2082
1897 static void 2083 static void
1898 io_cb (ev_loop *loop, ev_io *w, int revents) 2084 io_cb (ev_loop *loop, ev_io *w, int revents)
1899 { 2085 {
1900 } 2086 }
1901 2087
1902 // create io watchers for each fd and a timer before blocking 2088 // create io watchers for each fd and a timer before blocking
1903 static void 2089 static void
1904 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2090 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1905 { 2091 {
1906 int timeout = 3600000; 2092 int timeout = 3600000;
1907 struct pollfd fds [nfd]; 2093 struct pollfd fds [nfd];
1908 // actual code will need to loop here and realloc etc. 2094 // actual code will need to loop here and realloc etc.
1909 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2095 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1910 2096
1911 /* 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 */
1912 ev_timer_init (&tw, 0, timeout * 1e-3); 2098 ev_timer_init (&tw, 0, timeout * 1e-3);
1913 ev_timer_start (loop, &tw); 2099 ev_timer_start (loop, &tw);
1914 2100
1915 // create one ev_io per pollfd 2101 // create one ev_io per pollfd
1916 for (int i = 0; i < nfd; ++i) 2102 for (int i = 0; i < nfd; ++i)
1917 { 2103 {
1918 ev_io_init (iow + i, io_cb, fds [i].fd, 2104 ev_io_init (iow + i, io_cb, fds [i].fd,
1919 ((fds [i].events & POLLIN ? EV_READ : 0) 2105 ((fds [i].events & POLLIN ? EV_READ : 0)
1920 | (fds [i].events & POLLOUT ? EV_WRITE : 0))); 2106 | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1921 2107
1922 fds [i].revents = 0; 2108 fds [i].revents = 0;
1923 ev_io_start (loop, iow + i); 2109 ev_io_start (loop, iow + i);
1924 } 2110 }
1925 } 2111 }
1926 2112
1927 // stop all watchers after blocking 2113 // stop all watchers after blocking
1928 static void 2114 static void
1929 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2115 adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1930 { 2116 {
1931 ev_timer_stop (loop, &tw); 2117 ev_timer_stop (loop, &tw);
1932 2118
1933 for (int i = 0; i < nfd; ++i) 2119 for (int i = 0; i < nfd; ++i)
1934 { 2120 {
1935 // set the relevant poll flags 2121 // set the relevant poll flags
1936 // could also call adns_processreadable etc. here 2122 // could also call adns_processreadable etc. here
1937 struct pollfd *fd = fds + i; 2123 struct pollfd *fd = fds + i;
1938 int revents = ev_clear_pending (iow + i); 2124 int revents = ev_clear_pending (iow + i);
1939 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN; 2125 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1940 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT; 2126 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1941 2127
1942 // now stop the watcher 2128 // now stop the watcher
1943 ev_io_stop (loop, iow + i); 2129 ev_io_stop (loop, iow + i);
1944 } 2130 }
1945 2131
1946 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); 2132 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1947 } 2133 }
1948 2134
1949Method 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>
1950in the prepare watcher and would dispose of the check watcher. 2136in the prepare watcher and would dispose of the check watcher.
1951 2137
1952Method 3: If the module to be embedded supports explicit event 2138Method 3: If the module to be embedded supports explicit event
1953notification (adns does), you can also make use of the actual watcher 2139notification (libadns does), you can also make use of the actual watcher
1954callbacks, and only destroy/create the watchers in the prepare watcher. 2140callbacks, and only destroy/create the watchers in the prepare watcher.
1955 2141
1956 static void 2142 static void
1957 timer_cb (EV_P_ ev_timer *w, int revents) 2143 timer_cb (EV_P_ ev_timer *w, int revents)
1958 { 2144 {
1959 adns_state ads = (adns_state)w->data; 2145 adns_state ads = (adns_state)w->data;
1960 update_now (EV_A); 2146 update_now (EV_A);
1961 2147
1962 adns_processtimeouts (ads, &tv_now); 2148 adns_processtimeouts (ads, &tv_now);
1963 } 2149 }
1964 2150
1965 static void 2151 static void
1966 io_cb (EV_P_ ev_io *w, int revents) 2152 io_cb (EV_P_ ev_io *w, int revents)
1967 { 2153 {
1968 adns_state ads = (adns_state)w->data; 2154 adns_state ads = (adns_state)w->data;
1969 update_now (EV_A); 2155 update_now (EV_A);
1970 2156
1971 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now); 2157 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
1972 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now); 2158 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
1973 } 2159 }
1974 2160
1975 // do not ever call adns_afterpoll 2161 // do not ever call adns_afterpoll
1976 2162
1977Method 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
1978want 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
1979their poll function. The drawback with this solution is that the main 2165override their poll function. The drawback with this solution is that the
1980loop 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
1981this. 2167this approach, effectively embedding EV as a client into the horrible
2168libglib event loop.
1982 2169
1983 static gint 2170 static gint
1984 event_poll_func (GPollFD *fds, guint nfds, gint timeout) 2171 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
1985 { 2172 {
1986 int got_events = 0; 2173 int got_events = 0;
1987 2174
1988 for (n = 0; n < nfds; ++n) 2175 for (n = 0; n < nfds; ++n)
1989 // 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
1990 2177
1991 if (timeout >= 0) 2178 if (timeout >= 0)
1992 // create/start timer 2179 // create/start timer
1993 2180
1994 // poll 2181 // poll
1995 ev_loop (EV_A_ 0); 2182 ev_loop (EV_A_ 0);
1996 2183
1997 // stop timer again 2184 // stop timer again
1998 if (timeout >= 0) 2185 if (timeout >= 0)
1999 ev_timer_stop (EV_A_ &to); 2186 ev_timer_stop (EV_A_ &to);
2000 2187
2001 // stop io watchers again - their callbacks should have set 2188 // stop io watchers again - their callbacks should have set
2002 for (n = 0; n < nfds; ++n) 2189 for (n = 0; n < nfds; ++n)
2003 ev_io_stop (EV_A_ iow [n]); 2190 ev_io_stop (EV_A_ iow [n]);
2004 2191
2005 return got_events; 2192 return got_events;
2006 } 2193 }
2007 2194
2008 2195
2009=head2 C<ev_embed> - when one backend isn't enough... 2196=head2 C<ev_embed> - when one backend isn't enough...
2010 2197
2011This 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
2017prioritise I/O. 2204prioritise I/O.
2018 2205
2019As 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
2020sockets 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
2021still 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
2022so 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
2023into 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
2024be 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
2025at 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 :)
2026 2214
2027As 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
2028to be watched and handled very quickly (with low latency), and even 2216some fds have to be watched and handled very quickly (with low latency),
2029priorities and idle watchers might have too much overhead. In this case 2217and even priorities and idle watchers might have too much overhead. In
2030you 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
2031a second one, and embed the second one in the first. 2219the rest in a second one, and embed the second one in the first.
2032 2220
2033As 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
2034there 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
2035call 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
2036their 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
2044interested in that. 2232interested in that.
2045 2233
2046Also, there have not currently been made special provisions for forking: 2234Also, there have not currently been made special provisions for forking:
2047when 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,
2048but 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
2049yourself. 2237yourself - but you can use a fork watcher to handle this automatically,
2238and future versions of libev might do just that.
2050 2239
2051Unfortunately, not all backends are embeddable, only the ones returned by 2240Unfortunately, not all backends are embeddable: only the ones returned by
2052C<ev_embeddable_backends> are, which, unfortunately, does not include any 2241C<ev_embeddable_backends> are, which, unfortunately, does not include any
2053portable one. 2242portable one.
2054 2243
2055So 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
2056that 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
2057this 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
2058create it, and if that fails, use the normal loop for everything. 2247create it, and if that fails, use the normal loop for everything.
2059 2248
2249=head3 C<ev_embed> and fork
2250
2251While the C<ev_embed> watcher is running, forks in the embedding loop will
2252automatically be applied to the embedded loop as well, so no special
2253fork handling is required in that case. When the watcher is not running,
2254however, it is still the task of the libev user to call C<ev_loop_fork ()>
2255as applicable.
2256
2060=head3 Watcher-Specific Functions and Data Members 2257=head3 Watcher-Specific Functions and Data Members
2061 2258
2062=over 4 2259=over 4
2063 2260
2064=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 2261=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
2067 2264
2068Configures the watcher to embed the given loop, which must be 2265Configures the watcher to embed the given loop, which must be
2069embeddable. 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
2070invoked automatically, otherwise it is the responsibility of the callback 2267invoked automatically, otherwise it is the responsibility of the callback
2071to 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,
2072if 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).
2073 2270
2074=item ev_embed_sweep (loop, ev_embed *) 2271=item ev_embed_sweep (loop, ev_embed *)
2075 2272
2076Make a single, non-blocking sweep over the embedded loop. This works 2273Make a single, non-blocking sweep over the embedded loop. This works
2077similarly 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
2078apropriate way for embedded loops. 2275appropriate way for embedded loops.
2079 2276
2080=item struct ev_loop *other [read-only] 2277=item struct ev_loop *other [read-only]
2081 2278
2082The embedded event loop. 2279The embedded event loop.
2083 2280
2085 2282
2086=head3 Examples 2283=head3 Examples
2087 2284
2088Example: Try to get an embeddable event loop and embed it into the default 2285Example: Try to get an embeddable event loop and embed it into the default
2089event loop. If that is not possible, use the default loop. The default 2286event loop. If that is not possible, use the default loop. The default
2090loop is stored in C<loop_hi>, while the mebeddable loop is stored in 2287loop is stored in C<loop_hi>, while the embeddable loop is stored in
2091C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be 2288C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
2092used). 2289used).
2093 2290
2094 struct ev_loop *loop_hi = ev_default_init (0); 2291 struct ev_loop *loop_hi = ev_default_init (0);
2095 struct ev_loop *loop_lo = 0; 2292 struct ev_loop *loop_lo = 0;
2096 struct ev_embed embed; 2293 struct ev_embed embed;
2097 2294
2098 // see if there is a chance of getting one that works 2295 // see if there is a chance of getting one that works
2099 // (remember that a flags value of 0 means autodetection) 2296 // (remember that a flags value of 0 means autodetection)
2100 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2297 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2101 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2298 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2102 : 0; 2299 : 0;
2103 2300
2104 // if we got one, then embed it, otherwise default to loop_hi 2301 // if we got one, then embed it, otherwise default to loop_hi
2105 if (loop_lo) 2302 if (loop_lo)
2106 { 2303 {
2107 ev_embed_init (&embed, 0, loop_lo); 2304 ev_embed_init (&embed, 0, loop_lo);
2108 ev_embed_start (loop_hi, &embed); 2305 ev_embed_start (loop_hi, &embed);
2109 } 2306 }
2110 else 2307 else
2111 loop_lo = loop_hi; 2308 loop_lo = loop_hi;
2112 2309
2113Example: Check if kqueue is available but not recommended and create 2310Example: Check if kqueue is available but not recommended and create
2114a kqueue backend for use with sockets (which usually work with any 2311a kqueue backend for use with sockets (which usually work with any
2115kqueue implementation). Store the kqueue/socket-only event loop in 2312kqueue implementation). Store the kqueue/socket-only event loop in
2116C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 2313C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2117 2314
2118 struct ev_loop *loop = ev_default_init (0); 2315 struct ev_loop *loop = ev_default_init (0);
2119 struct ev_loop *loop_socket = 0; 2316 struct ev_loop *loop_socket = 0;
2120 struct ev_embed embed; 2317 struct ev_embed embed;
2121 2318
2122 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2319 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2123 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2320 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2124 { 2321 {
2125 ev_embed_init (&embed, 0, loop_socket); 2322 ev_embed_init (&embed, 0, loop_socket);
2126 ev_embed_start (loop, &embed); 2323 ev_embed_start (loop, &embed);
2127 } 2324 }
2128 2325
2129 if (!loop_socket) 2326 if (!loop_socket)
2130 loop_socket = loop; 2327 loop_socket = loop;
2131 2328
2132 // now use loop_socket for all sockets, and loop for everything else 2329 // now use loop_socket for all sockets, and loop for everything else
2133 2330
2134 2331
2135=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
2136 2333
2137Fork watchers are called when a C<fork ()> was detected (usually because 2334Fork watchers are called when a C<fork ()> was detected (usually because
2181is that the author does not know of a simple (or any) algorithm for a 2378is that the author does not know of a simple (or any) algorithm for a
2182multiple-writer-single-reader queue that works in all cases and doesn't 2379multiple-writer-single-reader queue that works in all cases and doesn't
2183need elaborate support such as pthreads. 2380need elaborate support such as pthreads.
2184 2381
2185That means that if you want to queue data, you have to provide your own 2382That means that if you want to queue data, you have to provide your own
2186queue. But at least I can tell you would implement locking around your 2383queue. But at least I can tell you how to implement locking around your
2187queue: 2384queue:
2188 2385
2189=over 4 2386=over 4
2190 2387
2191=item queueing from a signal handler context 2388=item queueing from a signal handler context
2192 2389
2193To implement race-free queueing, you simply add to the queue in the signal 2390To implement race-free queueing, you simply add to the queue in the signal
2194handler but you block the signal handler in the watcher callback. Here is an example that does that for 2391handler but you block the signal handler in the watcher callback. Here is
2195some fictitiuous SIGUSR1 handler: 2392an example that does that for some fictitious SIGUSR1 handler:
2196 2393
2197 static ev_async mysig; 2394 static ev_async mysig;
2198 2395
2199 static void 2396 static void
2200 sigusr1_handler (void) 2397 sigusr1_handler (void)
2267 2464
2268=item ev_async_init (ev_async *, callback) 2465=item ev_async_init (ev_async *, callback)
2269 2466
2270Initialises and configures the async watcher - it has no parameters of any 2467Initialises and configures the async watcher - it has no parameters of any
2271kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 2468kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
2272believe me. 2469trust me.
2273 2470
2274=item ev_async_send (loop, ev_async *) 2471=item ev_async_send (loop, ev_async *)
2275 2472
2276Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2473Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2277an C<EV_ASYNC> event on the watcher into the event loop. Unlike 2474an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2278C<ev_feed_event>, this call is safe to do in other threads, signal or 2475C<ev_feed_event>, this call is safe to do from other threads, signal or
2279similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding 2476similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2280section below on what exactly this means). 2477section below on what exactly this means).
2281 2478
2282This call incurs the overhead of a syscall only once per loop iteration, 2479This call incurs the overhead of a system call only once per loop iteration,
2283so while the overhead might be noticable, it doesn't apply to repeated 2480so while the overhead might be noticeable, it doesn't apply to repeated
2284calls to C<ev_async_send>. 2481calls to C<ev_async_send>.
2285 2482
2286=item bool = ev_async_pending (ev_async *) 2483=item bool = ev_async_pending (ev_async *)
2287 2484
2288Returns a non-zero value when C<ev_async_send> has been called on the 2485Returns a non-zero value when C<ev_async_send> has been called on the
2290event loop. 2487event loop.
2291 2488
2292C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 2489C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2293the loop iterates next and checks for the watcher to have become active, 2490the loop iterates next and checks for the watcher to have become active,
2294it will reset the flag again. C<ev_async_pending> can be used to very 2491it will reset the flag again. C<ev_async_pending> can be used to very
2295quickly check wether invoking the loop might be a good idea. 2492quickly check whether invoking the loop might be a good idea.
2296 2493
2297Not that this does I<not> check wether the watcher itself is pending, only 2494Not that this does I<not> check whether the watcher itself is pending, only
2298wether it has been requested to make this watcher pending. 2495whether it has been requested to make this watcher pending.
2299 2496
2300=back 2497=back
2301 2498
2302 2499
2303=head1 OTHER FUNCTIONS 2500=head1 OTHER FUNCTIONS
2307=over 4 2504=over 4
2308 2505
2309=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)
2310 2507
2311This 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
2312callback on whichever event happens first and automatically stop both 2509callback on whichever event happens first and automatically stops both
2313watchers. 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
2314or timeout without having to allocate/configure/start/stop/free one or 2511or timeout without having to allocate/configure/start/stop/free one or
2315more watchers yourself. 2512more watchers yourself.
2316 2513
2317If 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
2318is 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
2319C<events> set will be craeted and started. 2516the given C<fd> and C<events> set will be created and started.
2320 2517
2321If 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
2322started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 2519started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2323repeat = 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.
2324dubious value.
2325 2521
2326The 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
2327passed an C<revents> set like normal event callbacks (a combination of 2523passed an C<revents> set like normal event callbacks (a combination of
2328C<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>
2329value 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.
2330 2528
2529Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2530
2331 static void stdin_ready (int revents, void *arg) 2531 static void stdin_ready (int revents, void *arg)
2332 { 2532 {
2333 if (revents & EV_TIMEOUT)
2334 /* doh, nothing entered */;
2335 else if (revents & EV_READ) 2533 if (revents & EV_READ)
2336 /* 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 */;
2337 } 2537 }
2338 2538
2339 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 2539 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2340 2540
2341=item ev_feed_event (ev_loop *, watcher *, int revents) 2541=item ev_feed_event (ev_loop *, watcher *, int revents)
2342 2542
2343Feeds 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
2344had 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
2349Feed 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
2350the given events it. 2550the given events it.
2351 2551
2352=item ev_feed_signal_event (ev_loop *loop, int signum) 2552=item ev_feed_signal_event (ev_loop *loop, int signum)
2353 2553
2354Feed 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
2355loop!). 2555loop!).
2356 2556
2357=back 2557=back
2358 2558
2359 2559
2375 2575
2376=item * Priorities are not currently supported. Initialising priorities 2576=item * Priorities are not currently supported. Initialising priorities
2377will 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
2378is an ev_pri field. 2578is an ev_pri field.
2379 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
2380=item * Other members are not supported. 2583=item * Other members are not supported.
2381 2584
2382=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
2383to use the libev header file and library. 2586to use the libev header file and library.
2384 2587
2385=back 2588=back
2386 2589
2387=head1 C++ SUPPORT 2590=head1 C++ SUPPORT
2388 2591
2389Libev comes with some simplistic wrapper classes for C++ that mainly allow 2592Libev comes with some simplistic wrapper classes for C++ that mainly allow
2390you 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
2391the callback model to a model using method callbacks on objects. 2594the callback model to a model using method callbacks on objects.
2392 2595
2393To use it, 2596To use it,
2394 2597
2395 #include <ev++.h> 2598 #include <ev++.h>
2396 2599
2397This 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
2398of them macros) into the global namespace. All C++ specific things are 2601of them macros) into the global namespace. All C++ specific things are
2399put 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
2400options as F<ev.h>, most notably C<EV_MULTIPLICITY>. 2603options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
2467your 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
2468thunking function, making it as fast as a direct C callback. 2671thunking function, making it as fast as a direct C callback.
2469 2672
2470Example: simple class declaration and watcher initialisation 2673Example: simple class declaration and watcher initialisation
2471 2674
2472 struct myclass 2675 struct myclass
2473 { 2676 {
2474 void io_cb (ev::io &w, int revents) { } 2677 void io_cb (ev::io &w, int revents) { }
2475 } 2678 }
2476 2679
2477 myclass obj; 2680 myclass obj;
2478 ev::io iow; 2681 ev::io iow;
2479 iow.set <myclass, &myclass::io_cb> (&obj); 2682 iow.set <myclass, &myclass::io_cb> (&obj);
2480 2683
2481=item w->set<function> (void *data = 0) 2684=item w->set<function> (void *data = 0)
2482 2685
2483Also 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
2484callback. 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
2486 2689
2487The 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)>.
2488 2691
2489See the method-C<set> above for more details. 2692See the method-C<set> above for more details.
2490 2693
2491Example: 2694Example: Use a plain function as callback.
2492 2695
2493 static void io_cb (ev::io &w, int revents) { } 2696 static void io_cb (ev::io &w, int revents) { }
2494 iow.set <io_cb> (); 2697 iow.set <io_cb> ();
2495 2698
2496=item w->set (struct ev_loop *) 2699=item w->set (struct ev_loop *)
2497 2700
2498Associates 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
2499do this when the watcher is inactive (and not pending either). 2702do this when the watcher is inactive (and not pending either).
2500 2703
2501=item w->set ([args]) 2704=item w->set ([arguments])
2502 2705
2503Basically 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
2504called at least once. Unlike the C counterpart, an active watcher gets 2707called at least once. Unlike the C counterpart, an active watcher gets
2505automatically stopped and restarted when reconfiguring it with this 2708automatically stopped and restarted when reconfiguring it with this
2506method. 2709method.
2507 2710
2508=item w->start () 2711=item w->start ()
2532=back 2735=back
2533 2736
2534Example: 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
2535the constructor. 2738the constructor.
2536 2739
2537 class myclass 2740 class myclass
2538 { 2741 {
2539 ev::io io; void io_cb (ev::io &w, int revents); 2742 ev::io io ; void io_cb (ev::io &w, int revents);
2540 ev:idle idle void idle_cb (ev::idle &w, int revents); 2743 ev::idle idle; void idle_cb (ev::idle &w, int revents);
2541 2744
2542 myclass (int fd) 2745 myclass (int fd)
2543 { 2746 {
2544 io .set <myclass, &myclass::io_cb > (this); 2747 io .set <myclass, &myclass::io_cb > (this);
2545 idle.set <myclass, &myclass::idle_cb> (this); 2748 idle.set <myclass, &myclass::idle_cb> (this);
2546 2749
2547 io.start (fd, ev::READ); 2750 io.start (fd, ev::READ);
2548 } 2751 }
2549 }; 2752 };
2550 2753
2551 2754
2552=head1 OTHER LANGUAGE BINDINGS 2755=head1 OTHER LANGUAGE BINDINGS
2553 2756
2554Libev does not offer other language bindings itself, but bindings for a 2757Libev does not offer other language bindings itself, but bindings for a
2555numbe rof languages exist in the form of third-party packages. If you know 2758number of languages exist in the form of third-party packages. If you know
2556any interesting language binding in addition to the ones listed here, drop 2759any interesting language binding in addition to the ones listed here, drop
2557me a note. 2760me a note.
2558 2761
2559=over 4 2762=over 4
2560 2763
2561=item Perl 2764=item Perl
2562 2765
2563The EV module implements the full libev API and is actually used to test 2766The EV module implements the full libev API and is actually used to test
2564libev. EV is developed together with libev. Apart from the EV core module, 2767libev. EV is developed together with libev. Apart from the EV core module,
2565there are additional modules that implement libev-compatible interfaces 2768there are additional modules that implement libev-compatible interfaces
2566to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the 2769to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays),
2567C<libglib> event core (C<Glib::EV> and C<EV::Glib>). 2770C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV>
2771and C<EV::Glib>).
2568 2772
2569It can be found and installed via CPAN, its homepage is found at 2773It can be found and installed via CPAN, its homepage is at
2570L<http://software.schmorp.de/pkg/EV>. 2774L<http://software.schmorp.de/pkg/EV>.
2571 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
2572=item Ruby 2785=item Ruby
2573 2786
2574Tony Arcieri has written a ruby extension that offers access to a subset 2787Tony Arcieri has written a ruby extension that offers access to a subset
2575of the libev API and adds filehandle abstractions, asynchronous DNS and 2788of the libev API and adds file handle abstractions, asynchronous DNS and
2576more on top of it. It can be found via gem servers. Its homepage is at 2789more on top of it. It can be found via gem servers. Its homepage is at
2577L<http://rev.rubyforge.org/>. 2790L<http://rev.rubyforge.org/>.
2578 2791
2579=item D 2792=item D
2580 2793
2581Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 2794Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2582be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>. 2795be found at L<http://proj.llucax.com.ar/wiki/evd>.
2583 2796
2584=back 2797=back
2585 2798
2586 2799
2587=head1 MACRO MAGIC 2800=head1 MACRO MAGIC
2588 2801
2589Libev can be compiled with a variety of options, the most fundamantal 2802Libev can be compiled with a variety of options, the most fundamental
2590of which is C<EV_MULTIPLICITY>. This option determines whether (most) 2803of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2591functions and callbacks have an initial C<struct ev_loop *> argument. 2804functions and callbacks have an initial C<struct ev_loop *> argument.
2592 2805
2593To 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
2594following macros are defined: 2807following macros are defined:
2599 2812
2600This 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
2601loop 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,
2602C<EV_A_> is used when other arguments are following. Example: 2815C<EV_A_> is used when other arguments are following. Example:
2603 2816
2604 ev_unref (EV_A); 2817 ev_unref (EV_A);
2605 ev_timer_add (EV_A_ watcher); 2818 ev_timer_add (EV_A_ watcher);
2606 ev_loop (EV_A_ 0); 2819 ev_loop (EV_A_ 0);
2607 2820
2608It 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,
2609which is often provided by the following macro. 2822which is often provided by the following macro.
2610 2823
2611=item C<EV_P>, C<EV_P_> 2824=item C<EV_P>, C<EV_P_>
2612 2825
2613This 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
2614loop 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,
2615C<EV_P_> is used when other parameters are following. Example: 2828C<EV_P_> is used when other parameters are following. Example:
2616 2829
2617 // this is how ev_unref is being declared 2830 // this is how ev_unref is being declared
2618 static void ev_unref (EV_P); 2831 static void ev_unref (EV_P);
2619 2832
2620 // this is how you can declare your typical callback 2833 // this is how you can declare your typical callback
2621 static void cb (EV_P_ ev_timer *w, int revents) 2834 static void cb (EV_P_ ev_timer *w, int revents)
2622 2835
2623It 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
2624suitable for use with C<EV_A>. 2837suitable for use with C<EV_A>.
2625 2838
2626=item C<EV_DEFAULT>, C<EV_DEFAULT_> 2839=item C<EV_DEFAULT>, C<EV_DEFAULT_>
2642 2855
2643Example: Declare and initialise a check watcher, utilising the above 2856Example: Declare and initialise a check watcher, utilising the above
2644macros so it will work regardless of whether multiple loops are supported 2857macros so it will work regardless of whether multiple loops are supported
2645or not. 2858or not.
2646 2859
2647 static void 2860 static void
2648 check_cb (EV_P_ ev_timer *w, int revents) 2861 check_cb (EV_P_ ev_timer *w, int revents)
2649 { 2862 {
2650 ev_check_stop (EV_A_ w); 2863 ev_check_stop (EV_A_ w);
2651 } 2864 }
2652 2865
2653 ev_check check; 2866 ev_check check;
2654 ev_check_init (&check, check_cb); 2867 ev_check_init (&check, check_cb);
2655 ev_check_start (EV_DEFAULT_ &check); 2868 ev_check_start (EV_DEFAULT_ &check);
2656 ev_loop (EV_DEFAULT_ 0); 2869 ev_loop (EV_DEFAULT_ 0);
2657 2870
2658=head1 EMBEDDING 2871=head1 EMBEDDING
2659 2872
2660Libev can (and often is) directly embedded into host 2873Libev can (and often is) directly embedded into host
2661applications. Examples of applications that embed it include the Deliantra 2874applications. Examples of applications that embed it include the Deliantra
2668libev somewhere in your source tree). 2881libev somewhere in your source tree).
2669 2882
2670=head2 FILESETS 2883=head2 FILESETS
2671 2884
2672Depending 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
2673in your app. 2886in your application.
2674 2887
2675=head3 CORE EVENT LOOP 2888=head3 CORE EVENT LOOP
2676 2889
2677To 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
2678configuration (no autoconf): 2891configuration (no autoconf):
2679 2892
2680 #define EV_STANDALONE 1 2893 #define EV_STANDALONE 1
2681 #include "ev.c" 2894 #include "ev.c"
2682 2895
2683This 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
2684single C source file only to provide the function implementations. To use 2897single C source file only to provide the function implementations. To use
2685it, 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
2686done 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
2687where you can put other configuration options): 2900where you can put other configuration options):
2688 2901
2689 #define EV_STANDALONE 1 2902 #define EV_STANDALONE 1
2690 #include "ev.h" 2903 #include "ev.h"
2691 2904
2692Both header files and implementation files can be compiled with a C++ 2905Both header files and implementation files can be compiled with a C++
2693compiler (at least, thats a stated goal, and breakage will be treated 2906compiler (at least, thats a stated goal, and breakage will be treated
2694as a bug). 2907as a bug).
2695 2908
2696You 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
2697in your include path (e.g. in libev/ when using -Ilibev): 2910in your include path (e.g. in libev/ when using -Ilibev):
2698 2911
2699 ev.h 2912 ev.h
2700 ev.c 2913 ev.c
2701 ev_vars.h 2914 ev_vars.h
2702 ev_wrap.h 2915 ev_wrap.h
2703 2916
2704 ev_win32.c required on win32 platforms only 2917 ev_win32.c required on win32 platforms only
2705 2918
2706 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)
2707 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)
2708 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)
2709 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)
2710 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)
2711 2924
2712F<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
2713to compile this single file. 2926to compile this single file.
2714 2927
2715=head3 LIBEVENT COMPATIBILITY API 2928=head3 LIBEVENT COMPATIBILITY API
2716 2929
2717To include the libevent compatibility API, also include: 2930To include the libevent compatibility API, also include:
2718 2931
2719 #include "event.c" 2932 #include "event.c"
2720 2933
2721in the file including F<ev.c>, and: 2934in the file including F<ev.c>, and:
2722 2935
2723 #include "event.h" 2936 #include "event.h"
2724 2937
2725in 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>.
2726 2939
2727You need the following additional files for this: 2940You need the following additional files for this:
2728 2941
2729 event.h 2942 event.h
2730 event.c 2943 event.c
2731 2944
2732=head3 AUTOCONF SUPPORT 2945=head3 AUTOCONF SUPPORT
2733 2946
2734Instead of using C<EV_STANDALONE=1> and providing your config in 2947Instead of using C<EV_STANDALONE=1> and providing your configuration in
2735whatever 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
2736F<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
2737include F<config.h> and configure itself accordingly. 2950include F<config.h> and configure itself accordingly.
2738 2951
2739For this of course you need the m4 file: 2952For this of course you need the m4 file:
2740 2953
2741 libev.m4 2954 libev.m4
2742 2955
2743=head2 PREPROCESSOR SYMBOLS/MACROS 2956=head2 PREPROCESSOR SYMBOLS/MACROS
2744 2957
2745Libev can be configured via a variety of preprocessor symbols you have to 2958Libev can be configured via a variety of preprocessor symbols you have to
2746define before including any of its files. The default in the absense of 2959define before including any of its files. The default in the absence of
2747autoconf is noted for every option. 2960autoconf is documented for every option.
2748 2961
2749=over 4 2962=over 4
2750 2963
2751=item EV_STANDALONE 2964=item EV_STANDALONE
2752 2965
2757F<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.
2758 2971
2759=item EV_USE_MONOTONIC 2972=item EV_USE_MONOTONIC
2760 2973
2761If 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
2762monotonic clock option at both compiletime and runtime. Otherwise no use 2975monotonic clock option at both compile time and runtime. Otherwise no use
2763of 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
2764usually have to link against librt or something similar. Enabling it when 2977usually have to link against librt or something similar. Enabling it when
2765the functionality isn't available is safe, though, although you have 2978the functionality isn't available is safe, though, although you have
2766to 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>
2767function is hiding in (often F<-lrt>). 2980function is hiding in (often F<-lrt>).
2768 2981
2769=item EV_USE_REALTIME 2982=item EV_USE_REALTIME
2770 2983
2771If 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
2772realtime clock option at compiletime (and assume its availability at 2985real-time clock option at compile time (and assume its availability at
2773runtime if successful). Otherwise no use of the realtime clock option will 2986runtime if successful). Otherwise no use of the real-time clock option will
2774be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2987be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2775(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 2988(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2776note about libraries in the description of C<EV_USE_MONOTONIC>, though. 2989note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2777 2990
2778=item EV_USE_NANOSLEEP 2991=item EV_USE_NANOSLEEP
27892.7 or newer, otherwise disabled. 30022.7 or newer, otherwise disabled.
2790 3003
2791=item EV_USE_SELECT 3004=item EV_USE_SELECT
2792 3005
2793If 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
2794C<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
2795other method takes over, select will be it. Otherwise the select backend 3008other method takes over, select will be it. Otherwise the select backend
2796will not be compiled in. 3009will not be compiled in.
2797 3010
2798=item EV_SELECT_USE_FD_SET 3011=item EV_SELECT_USE_FD_SET
2799 3012
2800If 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>
2801structure. 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
2802C<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
2803exotic systems. This usually limits the range of file descriptors to some 3016exotic systems. This usually limits the range of file descriptors to some
2804low limit such as 1024 or might have other limitations (winsocket only 3017low limit such as 1024 or might have other limitations (winsocket only
2805allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3018allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
2806influence the size of the C<fd_set> used. 3019influence the size of the C<fd_set> used.
2807 3020
2856otherwise another method will be used as fallback. This is the preferred 3069otherwise another method will be used as fallback. This is the preferred
2857backend for Solaris 10 systems. 3070backend for Solaris 10 systems.
2858 3071
2859=item EV_USE_DEVPOLL 3072=item EV_USE_DEVPOLL
2860 3073
2861reserved for future expansion, works like the USE symbols above. 3074Reserved for future expansion, works like the USE symbols above.
2862 3075
2863=item EV_USE_INOTIFY 3076=item EV_USE_INOTIFY
2864 3077
2865If 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
2866interface to speed up C<ev_stat> watchers. Its actual availability will 3079interface to speed up C<ev_stat> watchers. Its actual availability will
2873access is atomic with respect to other threads or signal contexts. No such 3086access is atomic with respect to other threads or signal contexts. No such
2874type is easily found in the C language, so you can provide your own type 3087type is easily found in the C language, so you can provide your own type
2875that you know is safe for your purposes. It is used both for signal handler "locking" 3088that you know is safe for your purposes. It is used both for signal handler "locking"
2876as well as for signal and thread safety in C<ev_async> watchers. 3089as well as for signal and thread safety in C<ev_async> watchers.
2877 3090
2878In the absense of this define, libev will use C<sig_atomic_t volatile> 3091In the absence of this define, libev will use C<sig_atomic_t volatile>
2879(from F<signal.h>), which is usually good enough on most platforms. 3092(from F<signal.h>), which is usually good enough on most platforms.
2880 3093
2881=item EV_H 3094=item EV_H
2882 3095
2883The 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
2922When doing priority-based operations, libev usually has to linearly search 3135When doing priority-based operations, libev usually has to linearly search
2923all 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
2924and 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
2925fine. 3138fine.
2926 3139
2927If your embedding app does not need any priorities, defining these both to 3140If your embedding application does not need any priorities, defining these
2928C<0> will save some memory and cpu. 3141both to C<0> will save some memory and CPU.
2929 3142
2930=item EV_PERIODIC_ENABLE 3143=item EV_PERIODIC_ENABLE
2931 3144
2932If 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
2933defined 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
2940code. 3153code.
2941 3154
2942=item EV_EMBED_ENABLE 3155=item EV_EMBED_ENABLE
2943 3156
2944If 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
2945defined 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.
2946 3160
2947=item EV_STAT_ENABLE 3161=item EV_STAT_ENABLE
2948 3162
2949If 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
2950defined to be C<0>, then they are not. 3164defined to be C<0>, then they are not.
2960defined to be C<0>, then they are not. 3174defined to be C<0>, then they are not.
2961 3175
2962=item EV_MINIMAL 3176=item EV_MINIMAL
2963 3177
2964If 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
2965speed, 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
2966some 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.
2967 3182
2968=item EV_PID_HASHSIZE 3183=item EV_PID_HASHSIZE
2969 3184
2970C<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
2971pid. 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
2978inotify 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>),
2979usually 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>
2980watchers 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
2981two). 3196two).
2982 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
2983=item EV_COMMON 3233=item EV_COMMON
2984 3234
2985By default, all watchers have a C<void *data> member. By redefining 3235By default, all watchers have a C<void *data> member. By redefining
2986this 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
2987members. 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,
2988though, and it must be identical each time. 3238though, and it must be identical each time.
2989 3239
2990For example, the perl EV module uses something like this: 3240For example, the perl EV module uses something like this:
2991 3241
2992 #define EV_COMMON \ 3242 #define EV_COMMON \
2993 SV *self; /* contains this struct */ \ 3243 SV *self; /* contains this struct */ \
2994 SV *cb_sv, *fh /* note no trailing ";" */ 3244 SV *cb_sv, *fh /* note no trailing ";" */
2995 3245
2996=item EV_CB_DECLARE (type) 3246=item EV_CB_DECLARE (type)
2997 3247
2998=item EV_CB_INVOKE (watcher, revents) 3248=item EV_CB_INVOKE (watcher, revents)
2999 3249
3004definition and a statement, respectively. See the F<ev.h> header file for 3254definition and a statement, respectively. See the F<ev.h> header file for
3005their default definitions. One possible use for overriding these is to 3255their default definitions. One possible use for overriding these is to
3006avoid 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
3007method calls instead of plain function calls in C++. 3257method calls instead of plain function calls in C++.
3008 3258
3259=back
3260
3009=head2 EXPORTED API SYMBOLS 3261=head2 EXPORTED API SYMBOLS
3010 3262
3011If you need to re-export the API (e.g. via a dll) and you need a list of 3263If you need to re-export the API (e.g. via a DLL) and you need a list of
3012exported symbols, you can use the provided F<Symbol.*> files which list 3264exported symbols, you can use the provided F<Symbol.*> files which list
3013all public symbols, one per line: 3265all public symbols, one per line:
3014 3266
3015 Symbols.ev for libev proper 3267 Symbols.ev for libev proper
3016 Symbols.event for the libevent emulation 3268 Symbols.event for the libevent emulation
3017 3269
3018This can also be used to rename all public symbols to avoid clashes with 3270This can also be used to rename all public symbols to avoid clashes with
3019multiple versions of libev linked together (which is obviously bad in 3271multiple versions of libev linked together (which is obviously bad in
3020itself, but sometimes it is inconvinient to avoid this). 3272itself, but sometimes it is inconvenient to avoid this).
3021 3273
3022A sed command like this will create wrapper C<#define>'s that you need to 3274A sed command like this will create wrapper C<#define>'s that you need to
3023include before including F<ev.h>: 3275include before including F<ev.h>:
3024 3276
3025 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h 3277 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
3042file. 3294file.
3043 3295
3044The 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
3045that everybody includes and which overrides some configure choices: 3297that everybody includes and which overrides some configure choices:
3046 3298
3047 #define EV_MINIMAL 1 3299 #define EV_MINIMAL 1
3048 #define EV_USE_POLL 0 3300 #define EV_USE_POLL 0
3049 #define EV_MULTIPLICITY 0 3301 #define EV_MULTIPLICITY 0
3050 #define EV_PERIODIC_ENABLE 0 3302 #define EV_PERIODIC_ENABLE 0
3051 #define EV_STAT_ENABLE 0 3303 #define EV_STAT_ENABLE 0
3052 #define EV_FORK_ENABLE 0 3304 #define EV_FORK_ENABLE 0
3053 #define EV_CONFIG_H <config.h> 3305 #define EV_CONFIG_H <config.h>
3054 #define EV_MINPRI 0 3306 #define EV_MINPRI 0
3055 #define EV_MAXPRI 0 3307 #define EV_MAXPRI 0
3056 3308
3057 #include "ev++.h" 3309 #include "ev++.h"
3058 3310
3059And 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:
3060 3312
3061 #include "ev_cpp.h" 3313 #include "ev_cpp.h"
3062 #include "ev.c" 3314 #include "ev.c"
3063 3315
3316=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
3064 3317
3065=head1 THREADS AND COROUTINES 3318=head2 THREADS AND COROUTINES
3066 3319
3067=head2 THREADS 3320=head3 THREADS
3068 3321
3069Libev itself is completely threadsafe, but it uses no locking. This 3322All libev functions are reentrant and thread-safe unless explicitly
3323documented otherwise, but libev implements no locking itself. This means
3070means that you can use as many loops as you want in parallel, as long as 3324that you can use as many loops as you want in parallel, as long as there
3071only one thread ever calls into one libev function with the same loop 3325are no concurrent calls into any libev function with the same loop
3072parameter. 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.
3073 3329
3074Or put differently: calls with different loop parameters can be done in 3330Or to put it differently: calls with different loop parameters can be done
3075parallel from multiple threads, calls with the same loop parameter must be 3331concurrently from multiple threads, calls with the same loop parameter
3076done serially (but can be done from different threads, as long as only one 3332must be done serially (but can be done from different threads, as long as
3077thread ever is inside a call at any point in time, e.g. by using a mutex 3333only one thread ever is inside a call at any point in time, e.g. by using
3078per loop). 3334a mutex per loop).
3079 3335
3080If you want to know which design is best for your problem, then I cannot 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
3081help you but by giving some generic advice: 3343help you, but here is some generic advice:
3082 3344
3083=over 4 3345=over 4
3084 3346
3085=item * most applications have a main thread: use the default libev loop 3347=item * most applications have a main thread: use the default libev loop
3086in that thread, or create a seperate thread running only the default loop. 3348in that thread, or create a separate thread running only the default loop.
3087 3349
3088This helps integrating other libraries or software modules that use libev 3350This helps integrating other libraries or software modules that use libev
3089themselves and don't care/know about threading. 3351themselves and don't care/know about threading.
3090 3352
3091=item * one loop per thread is usually a good model. 3353=item * one loop per thread is usually a good model.
3092 3354
3093Doing this is almost never wrong, sometimes a better-performance model 3355Doing this is almost never wrong, sometimes a better-performance model
3094exists, but it is always a good start. 3356exists, but it is always a good start.
3095 3357
3096=item * other models exist, such as the leader/follower pattern, where one 3358=item * other models exist, such as the leader/follower pattern, where one
3097loop is handed through multiple threads in a kind of round-robbin fashion. 3359loop is handed through multiple threads in a kind of round-robin fashion.
3098 3360
3099Chosing a model is hard - look around, learn, know that usually you cna do 3361Choosing a model is hard - look around, learn, know that usually you can do
3100better than you currently do :-) 3362better than you currently do :-)
3101 3363
3102=item * often you need to talk to some other thread which blocks in the 3364=item * often you need to talk to some other thread which blocks in the
3365event loop.
3366
3103event loop - C<ev_async> watchers can be used to wake them up from other 3367C<ev_async> watchers can be used to wake them up from other threads safely
3104threads safely (or from signal contexts...). 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.
3105 3374
3106=back 3375=back
3107 3376
3108=head2 COROUTINES 3377=head3 COROUTINES
3109 3378
3110Libev is much more accomodating to coroutines ("cooperative threads"): 3379Libev is very accommodating to coroutines ("cooperative threads"):
3111libev fully supports nesting calls to it's functions from different 3380libev fully supports nesting calls to its functions from different
3112coroutines (e.g. you can call C<ev_loop> on the same loop from two 3381coroutines (e.g. you can call C<ev_loop> on the same loop from two
3113different coroutines and switch freely between both coroutines running the 3382different coroutines, and switch freely between both coroutines running the
3114loop, as long as you don't confuse yourself). The only exception is that 3383loop, as long as you don't confuse yourself). The only exception is that
3115you must not do this from C<ev_periodic> reschedule callbacks. 3384you must not do this from C<ev_periodic> reschedule callbacks.
3116 3385
3117Care has been invested into making sure that libev does not keep local 3386Care has been taken to ensure that libev does not keep local state inside
3118state inside C<ev_loop>, and other calls do not usually allow coroutine 3387C<ev_loop>, and other calls do not usually allow for coroutine switches as
3119switches. 3388they do not clal any callbacks.
3120 3389
3390=head2 COMPILER WARNINGS
3121 3391
3122=head1 COMPLEXITIES 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.
3123 3395
3124In this section the complexities of (many of) the algorithms used inside 3396However, these are unavoidable for many reasons. For one, each compiler
3125libev will be explained. For complexity discussions about backends see the 3397has different warnings, and each user has different tastes regarding
3126documentation for C<ev_default_init>. 3398warning options. "Warn-free" code therefore cannot be a goal except when
3399targeting a specific compiler and compiler-version.
3127 3400
3128All of the following are about amortised time: If an array needs to be 3401Another reason is that some compiler warnings require elaborate
3129extended, libev needs to realloc and move the whole array, but this 3402workarounds, or other changes to the code that make it less clear and less
3130happens asymptotically never with higher number of elements, so O(1) might 3403maintainable.
3131mean it might do a lengthy realloc operation in rare cases, but on average
3132it is much faster and asymptotically approaches constant time.
3133 3404
3134=over 4 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.
3135 3411
3136=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 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.
3137 3417
3138This means that, when you have a watcher that triggers in one hour and
3139there are 100 watchers that would trigger before that then inserting will
3140have to skip roughly seven (C<ld 100>) of these watchers.
3141 3418
3142=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) 3419=head2 VALGRIND
3143 3420
3144That means that changing a timer costs less than removing/adding them 3421Valgrind has a special section here because it is a popular tool that is
3145as only the relative motion in the event queue has to be paid for. 3422highly useful. Unfortunately, valgrind reports are very hard to interpret.
3146 3423
3147=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) 3424If you think you found a bug (memory leak, uninitialised data access etc.)
3425in libev, then check twice: If valgrind reports something like:
3148 3426
3149These just add the watcher into an array or at the head of a list. 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.
3150 3430
3151=item Stopping check/prepare/idle/fork/async watchers: O(1) 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.
3152 3433
3153=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 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.
3154 3438
3155These watchers are stored in lists then need to be walked to find the 3439Keep in mind that valgrind is a very good tool, but only a tool. Don't
3156correct watcher to remove. The lists are usually short (you don't usually 3440make it into some kind of religion.
3157have many watchers waiting for the same fd or signal).
3158 3441
3159=item Finding the next timer in each loop iteration: O(1) 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.
3160 3447
3161By virtue of using a binary heap, the next timer is always found at the 3448If you need, for some reason, empty reports from valgrind for your project
3162beginning of the storage array. 3449I suggest using suppression lists.
3163 3450
3164=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3165 3451
3166A change means an I/O watcher gets started or stopped, which requires 3452=head1 PORTABILITY NOTES
3167libev to recalculate its status (and possibly tell the kernel, depending
3168on backend and wether C<ev_io_set> was used).
3169 3453
3170=item Activating one watcher (putting it into the pending state): O(1) 3454=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
3171
3172=item Priority handling: O(number_of_priorities)
3173
3174Priorities are implemented by allocating some space for each
3175priority. When doing priority-based operations, libev usually has to
3176linearly search all the priorities, but starting/stopping and activating
3177watchers becomes O(1) w.r.t. priority handling.
3178
3179=item Sending an ev_async: O(1)
3180
3181=item Processing ev_async_send: O(number_of_async_watchers)
3182
3183=item Processing signals: O(max_signal_number)
3184
3185Sending involves a syscall I<iff> there were no other C<ev_async_send>
3186calls in the current loop iteration. Checking for async and signal events
3187involves iterating over all running async watchers or all signal numbers.
3188
3189=back
3190
3191
3192=head1 Win32 platform limitations and workarounds
3193 3455
3194Win32 doesn't support any of the standards (e.g. POSIX) that libev 3456Win32 doesn't support any of the standards (e.g. POSIX) that libev
3195requires, and its I/O model is fundamentally incompatible with the POSIX 3457requires, and its I/O model is fundamentally incompatible with the POSIX
3196model. Libev still offers limited functionality on this platform in 3458model. Libev still offers limited functionality on this platform in
3197the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3459the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3198descriptors. This only applies when using Win32 natively, not when using 3460descriptors. This only applies when using Win32 natively, not when using
3199e.g. cygwin. 3461e.g. cygwin.
3200 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
3201There is no supported compilation method available on windows except 3468There is no supported compilation method available on windows except
3202embedding it into other applications. 3469embedding it into other applications.
3203 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
3204Due to the many, low, and arbitrary limits on the win32 platform and the 3478Due to the many, low, and arbitrary limits on the win32 platform and
3205abysmal performance of winsockets, using a large number of sockets is not 3479the abysmal performance of winsockets, using a large number of sockets
3206recommended (and not reasonable). If your program needs to use more than 3480is not recommended (and not reasonable). If your program needs to use
3207a hundred or so sockets, then likely it needs to use a totally different 3481more than a hundred or so sockets, then likely it needs to use a totally
3208implementation for windows, as libev offers the POSIX model, which cannot 3482different implementation for windows, as libev offers the POSIX readiness
3209be implemented efficiently on windows (microsoft monopoly games). 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"
3210 3500
3211=over 4 3501=over 4
3212 3502
3213=item The winsocket select function 3503=item The winsocket select function
3214 3504
3215The winsocket C<select> function doesn't follow POSIX in that it requires 3505The winsocket C<select> function doesn't follow POSIX in that it
3216socket I<handles> and not socket I<file descriptors>. This makes select 3506requires socket I<handles> and not socket I<file descriptors> (it is
3217very inefficient, and also requires a mapping from file descriptors 3507also extremely buggy). This makes select very inefficient, and also
3218to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>, 3508requires a mapping from file descriptors to socket handles (the Microsoft
3219C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor 3509C runtime provides the function C<_open_osfhandle> for this). See the
3220symbols for more info. 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.
3221 3512
3222The configuration for a "naked" win32 using the microsoft runtime 3513The configuration for a "naked" win32 using the Microsoft runtime
3223libraries and raw winsocket select is: 3514libraries and raw winsocket select is:
3224 3515
3225 #define EV_USE_SELECT 1 3516 #define EV_USE_SELECT 1
3226 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 3517 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3227 3518
3228Note that winsockets handling of fd sets is O(n), so you can easily get a 3519Note that winsockets handling of fd sets is O(n), so you can easily get a
3229complexity in the O(n²) range when using win32. 3520complexity in the O(n²) range when using win32.
3230 3521
3231=item Limited number of file descriptors 3522=item Limited number of file descriptors
3232 3523
3233Windows has numerous arbitrary (and low) limits on things. Early versions 3524Windows has numerous arbitrary (and low) limits on things.
3234of winsocket's select only supported waiting for a max. of C<64> handles 3525
3526Early versions of winsocket's select only supported waiting for a maximum
3235(probably owning to the fact that all windows kernels can only wait for 3527of C<64> handles (probably owning to the fact that all windows kernels
3236C<64> things at the same time internally; microsoft recommends spawning a 3528can only wait for C<64> things at the same time internally; Microsoft
3237chain of threads and wait for 63 handles and the previous thread in each). 3529recommends spawning a chain of threads and wait for 63 handles and the
3530previous thread in each. Great).
3238 3531
3239Newer versions support more handles, but you need to define C<FD_SETSIZE> 3532Newer versions support more handles, but you need to define C<FD_SETSIZE>
3240to some high number (e.g. C<2048>) before compiling the winsocket select 3533to some high number (e.g. C<2048>) before compiling the winsocket select
3241call (which might be in libev or elsewhere, for example, perl does its own 3534call (which might be in libev or elsewhere, for example, perl does its own
3242select emulation on windows). 3535select emulation on windows).
3243 3536
3244Another limit is the number of file descriptors in the microsoft runtime 3537Another limit is the number of file descriptors in the Microsoft runtime
3245libraries, which by default is C<64> (there must be a hidden I<64> fetish 3538libraries, which by default is C<64> (there must be a hidden I<64> fetish
3246or something like this inside microsoft). You can increase this by calling 3539or something like this inside Microsoft). You can increase this by calling
3247C<_setmaxstdio>, which can increase this limit to C<2048> (another 3540C<_setmaxstdio>, which can increase this limit to C<2048> (another
3248arbitrary limit), but is broken in many versions of the microsoft runtime 3541arbitrary limit), but is broken in many versions of the Microsoft runtime
3249libraries. 3542libraries.
3250 3543
3251This might get you to about C<512> or C<2048> sockets (depending on 3544This might get you to about C<512> or C<2048> sockets (depending on
3252windows version and/or the phase of the moon). To get more, you need to 3545windows version and/or the phase of the moon). To get more, you need to
3253wrap all I/O functions and provide your own fd management, but the cost of 3546wrap all I/O functions and provide your own fd management, but the cost of
3254calling select (O(n²)) will likely make this unworkable. 3547calling select (O(n²)) will likely make this unworkable.
3255 3548
3256=back 3549=back
3257 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
3607=head1 ALGORITHMIC COMPLEXITIES
3608
3609In this section the complexities of (many of) the algorithms used inside
3610libev will be documented. For complexity discussions about backends see
3611the documentation for C<ev_default_init>.
3612
3613All of the following are about amortised time: If an array needs to be
3614extended, libev needs to realloc and move the whole array, but this
3615happens asymptotically rarer with higher number of elements, so O(1) might
3616mean that libev does a lengthy realloc operation in rare cases, but on
3617average it is much faster and asymptotically approaches constant time.
3618
3619=over 4
3620
3621=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
3622
3623This means that, when you have a watcher that triggers in one hour and
3624there are 100 watchers that would trigger before that, then inserting will
3625have to skip roughly seven (C<ld 100>) of these watchers.
3626
3627=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
3628
3629That means that changing a timer costs less than removing/adding them,
3630as only the relative motion in the event queue has to be paid for.
3631
3632=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
3633
3634These just add the watcher into an array or at the head of a list.
3635
3636=item Stopping check/prepare/idle/fork/async watchers: O(1)
3637
3638=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
3639
3640These watchers are stored in lists, so they need to be walked to find the
3641correct watcher to remove. The lists are usually short (you don't usually
3642have many watchers waiting for the same fd or signal: one is typical, two
3643is rare).
3644
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.
3649
3650=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3651
3652A change means an I/O watcher gets started or stopped, which requires
3653libev to recalculate its status (and possibly tell the kernel, depending
3654on backend and whether C<ev_io_set> was used).
3655
3656=item Activating one watcher (putting it into the pending state): O(1)
3657
3658=item Priority handling: O(number_of_priorities)
3659
3660Priorities are implemented by allocating some space for each
3661priority. When doing priority-based operations, libev usually has to
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.
3674
3675=back
3676
3258 3677
3259=head1 AUTHOR 3678=head1 AUTHOR
3260 3679
3261Marc Lehmann <libev@schmorp.de>. 3680Marc Lehmann <libev@schmorp.de>.
3262 3681

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines