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

Comparing libev/ev.pod (file contents):
Revision 1.158 by root, Wed May 21 12:51:38 2008 UTC vs.
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 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 #include <stdio.h> // for puts
15
14 // every watcher type has its own typedef'd struct 16 // every watcher type has its own typedef'd struct
15 // with the name ev_<type> 17 // with the name ev_TYPE
16 ev_io stdin_watcher; 18 ev_io stdin_watcher;
17 ev_timer timeout_watcher; 19 ev_timer timeout_watcher;
18 20
19 // all watcher callbacks have a similar signature 21 // all watcher callbacks have a similar signature
20 // this callback is called when data is readable on stdin 22 // this callback is called when data is readable on stdin
21 static void 23 static void
22 stdin_cb (EV_P_ struct ev_io *w, int revents) 24 stdin_cb (EV_P_ ev_io *w, int revents)
23 { 25 {
24 puts ("stdin ready"); 26 puts ("stdin ready");
25 // for one-shot events, one must manually stop the watcher 27 // for one-shot events, one must manually stop the watcher
26 // with its corresponding stop function. 28 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w); 29 ev_io_stop (EV_A_ w);
28 30
29 // this causes all nested ev_loop's to stop iterating 31 // this causes all nested ev_loop's to stop iterating
30 ev_unloop (EV_A_ EVUNLOOP_ALL); 32 ev_unloop (EV_A_ EVUNLOOP_ALL);
31 } 33 }
32 34
33 // another callback, this time for a time-out 35 // another callback, this time for a time-out
34 static void 36 static void
35 timeout_cb (EV_P_ struct ev_timer *w, int revents) 37 timeout_cb (EV_P_ ev_timer *w, int revents)
36 { 38 {
37 puts ("timeout"); 39 puts ("timeout");
38 // this causes the innermost ev_loop to stop iterating 40 // this causes the innermost ev_loop to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE); 41 ev_unloop (EV_A_ EVUNLOOP_ONE);
40 } 42 }
41 43
42 int 44 int
43 main (void) 45 main (void)
44 { 46 {
45 // use the default event loop unless you have special needs 47 // use the default event loop unless you have special needs
46 struct ev_loop *loop = ev_default_loop (0); 48 struct ev_loop *loop = ev_default_loop (0);
47 49
48 // initialise an io watcher, then start it 50 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable 51 // this one will watch for stdin to become readable
50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 52 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
51 ev_io_start (loop, &stdin_watcher); 53 ev_io_start (loop, &stdin_watcher);
52 54
53 // initialise a timer watcher, then start it 55 // initialise a timer watcher, then start it
54 // simple non-repeating 5.5 second timeout 56 // simple non-repeating 5.5 second timeout
55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 57 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
56 ev_timer_start (loop, &timeout_watcher); 58 ev_timer_start (loop, &timeout_watcher);
57 59
58 // now wait for events to arrive 60 // now wait for events to arrive
59 ev_loop (loop, 0); 61 ev_loop (loop, 0);
60 62
61 // unloop was called, so exit 63 // unloop was called, so exit
62 return 0; 64 return 0;
63 } 65 }
64 66
65=head1 DESCRIPTION 67=head1 ABOUT THIS DOCUMENT
68
69This document documents the libev software package.
66 70
67The newest version of this document is also available as an html-formatted 71The 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 72web page you might find easier to navigate when reading it for the first
69time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. 73time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
74
75While this document tries to be as complete as possible in documenting
76libev, its usage and the rationale behind its design, it is not a tutorial
77on event-based programming, nor will it introduce event-based programming
78with libev.
79
80Familarity with event based programming techniques in general is assumed
81throughout this document.
82
83=head1 ABOUT LIBEV
70 84
71Libev is an event loop: you register interest in certain events (such as a 85Libev 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 86file descriptor being readable or a timeout occurring), and it will manage
73these event sources and provide your program with events. 87these event sources and provide your program with events.
74 88
84=head2 FEATURES 98=head2 FEATURES
85 99
86Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
87BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
88for file descriptor events (C<ev_io>), the Linux C<inotify> interface 102for file descriptor events (C<ev_io>), the Linux C<inotify> interface
89(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 103(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
90with customised rescheduling (C<ev_periodic>), synchronous signals 104inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
91(C<ev_signal>), process status change events (C<ev_child>), and event 105timers (C<ev_timer>), absolute timers with customised rescheduling
92watchers dealing with the event loop mechanism itself (C<ev_idle>, 106(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
93C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 107change events (C<ev_child>), and event watchers dealing with the event
94file watchers (C<ev_stat>) and even limited support for fork events 108loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
95(C<ev_fork>). 109C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
110limited support for fork events (C<ev_fork>).
96 111
97It also is quite fast (see this 112It also is quite fast (see this
98L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 113L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
99for example). 114for example).
100 115
108name C<loop> (which is always of type C<struct ev_loop *>) will not have 123name C<loop> (which is always of type C<struct ev_loop *>) will not have
109this argument. 124this argument.
110 125
111=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
112 127
113Libev represents time as a single floating point number, representing the 128Libev represents time as a single floating point number, representing
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 129the (fractional) number of seconds since the (POSIX) epoch (somewhere
115the beginning of 1970, details are complicated, don't ask). This type is 130near the beginning of 1970, details are complicated, don't ask). This
116called C<ev_tstamp>, which is what you should use too. It usually aliases 131type is called C<ev_tstamp>, which is what you should use too. It usually
117to the C<double> type in C, and when you need to do any calculations on 132aliases to the C<double> type in C. When you need to do any calculations
118it, you should treat it as some floatingpoint value. Unlike the name 133on it, you should treat it as some floating point value. Unlike the name
119component C<stamp> might indicate, it is also used for time differences 134component C<stamp> might indicate, it is also used for time differences
120throughout libev. 135throughout libev.
136
137=head1 ERROR HANDLING
138
139Libev knows three classes of errors: operating system errors, usage errors
140and internal errors (bugs).
141
142When libev catches an operating system error it cannot handle (for example
143a system call indicating a condition libev cannot fix), it calls the callback
144set via C<ev_set_syserr_cb>, which is supposed to fix the problem or
145abort. The default is to print a diagnostic message and to call C<abort
146()>.
147
148When libev detects a usage error such as a negative timer interval, then
149it will print a diagnostic message and abort (via the C<assert> mechanism,
150so C<NDEBUG> will disable this checking): these are programming errors in
151the libev caller and need to be fixed there.
152
153Libev also has a few internal error-checking C<assert>ions, and also has
154extensive consistency checking code. These do not trigger under normal
155circumstances, as they indicate either a bug in libev or worse.
156
121 157
122=head1 GLOBAL FUNCTIONS 158=head1 GLOBAL FUNCTIONS
123 159
124These functions can be called anytime, even before initialising the 160These functions can be called anytime, even before initialising the
125library in any way. 161library in any way.
134 170
135=item ev_sleep (ev_tstamp interval) 171=item ev_sleep (ev_tstamp interval)
136 172
137Sleep for the given interval: The current thread will be blocked until 173Sleep for the given interval: The current thread will be blocked until
138either it is interrupted or the given time interval has passed. Basically 174either it is interrupted or the given time interval has passed. Basically
139this is a subsecond-resolution C<sleep ()>. 175this is a sub-second-resolution C<sleep ()>.
140 176
141=item int ev_version_major () 177=item int ev_version_major ()
142 178
143=item int ev_version_minor () 179=item int ev_version_minor ()
144 180
157not a problem. 193not a problem.
158 194
159Example: Make sure we haven't accidentally been linked against the wrong 195Example: Make sure we haven't accidentally been linked against the wrong
160version. 196version.
161 197
162 assert (("libev version mismatch", 198 assert (("libev version mismatch",
163 ev_version_major () == EV_VERSION_MAJOR 199 ev_version_major () == EV_VERSION_MAJOR
164 && ev_version_minor () >= EV_VERSION_MINOR)); 200 && ev_version_minor () >= EV_VERSION_MINOR));
165 201
166=item unsigned int ev_supported_backends () 202=item unsigned int ev_supported_backends ()
167 203
168Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*> 204Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
169value) compiled into this binary of libev (independent of their 205value) compiled into this binary of libev (independent of their
171a description of the set values. 207a description of the set values.
172 208
173Example: make sure we have the epoll method, because yeah this is cool and 209Example: 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 210a must have and can we have a torrent of it please!!!11
175 211
176 assert (("sorry, no epoll, no sex", 212 assert (("sorry, no epoll, no sex",
177 ev_supported_backends () & EVBACKEND_EPOLL)); 213 ev_supported_backends () & EVBACKEND_EPOLL));
178 214
179=item unsigned int ev_recommended_backends () 215=item unsigned int ev_recommended_backends ()
180 216
181Return the set of all backends compiled into this binary of libev and also 217Return 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 218recommended for this platform. This set is often smaller than the one
183returned by C<ev_supported_backends>, as for example kqueue is broken on 219returned by C<ev_supported_backends>, as for example kqueue is broken on
184most BSDs and will not be autodetected unless you explicitly request it 220most 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 221(assuming you know what you are doing). This is the set of backends that
186libev will probe for if you specify no backends explicitly. 222libev will probe for if you specify no backends explicitly.
187 223
188=item unsigned int ev_embeddable_backends () 224=item unsigned int ev_embeddable_backends ()
189 225
193C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 229C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
194recommended ones. 230recommended ones.
195 231
196See the description of C<ev_embed> watchers for more info. 232See the description of C<ev_embed> watchers for more info.
197 233
198=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 234=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
199 235
200Sets the allocation function to use (the prototype is similar - the 236Sets the allocation function to use (the prototype is similar - the
201semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 237semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
202used to allocate and free memory (no surprises here). If it returns zero 238used to allocate and free memory (no surprises here). If it returns zero
203when memory needs to be allocated (C<size != 0>), the library might abort 239when memory needs to be allocated (C<size != 0>), the library might abort
229 } 265 }
230 266
231 ... 267 ...
232 ev_set_allocator (persistent_realloc); 268 ev_set_allocator (persistent_realloc);
233 269
234=item ev_set_syserr_cb (void (*cb)(const char *msg)); 270=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
235 271
236Set the callback function to call on a retryable syscall error (such 272Set the callback function to call on a retryable system call error (such
237as failed select, poll, epoll_wait). The message is a printable string 273as failed select, poll, epoll_wait). The message is a printable string
238indicating the system call or subsystem causing the problem. If this 274indicating the system call or subsystem causing the problem. If this
239callback is set, then libev will expect it to remedy the sitution, no 275callback is set, then libev will expect it to remedy the situation, no
240matter what, when it returns. That is, libev will generally retry the 276matter what, when it returns. That is, libev will generally retry the
241requested operation, or, if the condition doesn't go away, do bad stuff 277requested operation, or, if the condition doesn't go away, do bad stuff
242(such as abort). 278(such as abort).
243 279
244Example: This is basically the same thing that libev does internally, too. 280Example: This is basically the same thing that libev does internally, too.
255 291
256=back 292=back
257 293
258=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 294=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
259 295
260An event loop is described by a C<struct ev_loop *>. The library knows two 296An event loop is described by a C<struct ev_loop *> (the C<struct>
261types of such loops, the I<default> loop, which supports signals and child 297is I<not> optional in this case, as there is also an C<ev_loop>
262events, and dynamically created loops which do not. 298I<function>).
299
300The library knows two types of such loops, the I<default> loop, which
301supports signals and child events, and dynamically created loops which do
302not.
263 303
264=over 4 304=over 4
265 305
266=item struct ev_loop *ev_default_loop (unsigned int flags) 306=item struct ev_loop *ev_default_loop (unsigned int flags)
267 307
273If you don't know what event loop to use, use the one returned from this 313If you don't know what event loop to use, use the one returned from this
274function. 314function.
275 315
276Note that this function is I<not> thread-safe, so if you want to use it 316Note that this function is I<not> thread-safe, so if you want to use it
277from multiple threads, you have to lock (note also that this is unlikely, 317from multiple threads, you have to lock (note also that this is unlikely,
278as loops cannot bes hared easily between threads anyway). 318as loops cannot be shared easily between threads anyway).
279 319
280The default loop is the only loop that can handle C<ev_signal> and 320The default loop is the only loop that can handle C<ev_signal> and
281C<ev_child> watchers, and to do this, it always registers a handler 321C<ev_child> watchers, and to do this, it always registers a handler
282for C<SIGCHLD>. If this is a problem for your app you can either 322for C<SIGCHLD>. If this is a problem for your application you can either
283create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 323create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
284can simply overwrite the C<SIGCHLD> signal handler I<after> calling 324can simply overwrite the C<SIGCHLD> signal handler I<after> calling
285C<ev_default_init>. 325C<ev_default_init>.
286 326
287The flags argument can be used to specify special behaviour or specific 327The flags argument can be used to specify special behaviour or specific
296The default flags value. Use this if you have no clue (it's the right 336The default flags value. Use this if you have no clue (it's the right
297thing, believe me). 337thing, believe me).
298 338
299=item C<EVFLAG_NOENV> 339=item C<EVFLAG_NOENV>
300 340
301If this flag bit is ored into the flag value (or the program runs setuid 341If this flag bit is or'ed into the flag value (or the program runs setuid
302or setgid) then libev will I<not> look at the environment variable 342or setgid) then libev will I<not> look at the environment variable
303C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 343C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
304override the flags completely if it is found in the environment. This is 344override the flags completely if it is found in the environment. This is
305useful to try out specific backends to test their performance, or to work 345useful to try out specific backends to test their performance, or to work
306around bugs. 346around bugs.
313 353
314This works by calling C<getpid ()> on every iteration of the loop, 354This works by calling C<getpid ()> on every iteration of the loop,
315and thus this might slow down your event loop if you do a lot of loop 355and thus this might slow down your event loop if you do a lot of loop
316iterations and little real work, but is usually not noticeable (on my 356iterations and little real work, but is usually not noticeable (on my
317GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 357GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
318without a syscall and thus I<very> fast, but my GNU/Linux system also has 358without a system call and thus I<very> fast, but my GNU/Linux system also has
319C<pthread_atfork> which is even faster). 359C<pthread_atfork> which is even faster).
320 360
321The big advantage of this flag is that you can forget about fork (and 361The big advantage of this flag is that you can forget about fork (and
322forget about forgetting to tell libev about forking) when you use this 362forget about forgetting to tell libev about forking) when you use this
323flag. 363flag.
324 364
325This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS> 365This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
326environment variable. 366environment variable.
367
368=item C<EVFLAG_NOINOTIFY>
369
370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374
375=item C<EVFLAG_SIGNALFD>
376
377When this flag is specified, then libev will attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379delivers signals synchronously, which makes is both faster and might make
380it possible to get the queued signal data.
381
382Signalfd will not be used by default as this changes your signal mask, and
383there are a lot of shoddy libraries and programs (glib's threadpool for
384example) that can't properly initialise their signal masks.
327 385
328=item C<EVBACKEND_SELECT> (value 1, portable select backend) 386=item C<EVBACKEND_SELECT> (value 1, portable select backend)
329 387
330This is your standard select(2) backend. Not I<completely> standard, as 388This is your standard select(2) backend. Not I<completely> standard, as
331libev tries to roll its own fd_set with no limits on the number of fds, 389libev tries to roll its own fd_set with no limits on the number of fds,
332but if that fails, expect a fairly low limit on the number of fds when 390but if that fails, expect a fairly low limit on the number of fds when
333using this backend. It doesn't scale too well (O(highest_fd)), but its 391using this backend. It doesn't scale too well (O(highest_fd)), but its
334usually the fastest backend for a low number of (low-numbered :) fds. 392usually the fastest backend for a low number of (low-numbered :) fds.
335 393
336To get good performance out of this backend you need a high amount of 394To get good performance out of this backend you need a high amount of
337parallelity (most of the file descriptors should be busy). If you are 395parallelism (most of the file descriptors should be busy). If you are
338writing a server, you should C<accept ()> in a loop to accept as many 396writing a server, you should C<accept ()> in a loop to accept as many
339connections as possible during one iteration. You might also want to have 397connections as possible during one iteration. You might also want to have
340a look at C<ev_set_io_collect_interval ()> to increase the amount of 398a look at C<ev_set_io_collect_interval ()> to increase the amount of
341readiness notifications you get per iteration. 399readiness notifications you get per iteration.
400
401This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the
402C<writefds> set (and to work around Microsoft Windows bugs, also onto the
403C<exceptfds> set on that platform).
342 404
343=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 405=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
344 406
345And this is your standard poll(2) backend. It's more complicated 407And this is your standard poll(2) backend. It's more complicated
346than select, but handles sparse fds better and has no artificial 408than select, but handles sparse fds better and has no artificial
347limit on the number of fds you can use (except it will slow down 409limit on the number of fds you can use (except it will slow down
348considerably with a lot of inactive fds). It scales similarly to select, 410considerably with a lot of inactive fds). It scales similarly to select,
349i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for 411i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
350performance tips. 412performance tips.
351 413
414This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
415C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
416
352=item C<EVBACKEND_EPOLL> (value 4, Linux) 417=item C<EVBACKEND_EPOLL> (value 4, Linux)
418
419Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
420kernels).
353 421
354For few fds, this backend is a bit little slower than poll and select, 422For few fds, this backend is a bit little slower than poll and select,
355but it scales phenomenally better. While poll and select usually scale 423but it scales phenomenally better. While poll and select usually scale
356like O(total_fds) where n is the total number of fds (or the highest fd), 424like O(total_fds) where n is the total number of fds (or the highest fd),
357epoll scales either O(1) or O(active_fds). The epoll design has a number 425epoll scales either O(1) or O(active_fds).
358of shortcomings, such as silently dropping events in some hard-to-detect 426
359cases and requiring a syscall per fd change, no fork support and bad 427The epoll mechanism deserves honorable mention as the most misdesigned
360support for dup. 428of the more advanced event mechanisms: mere annoyances include silently
429dropping file descriptors, requiring a system call per change per file
430descriptor (and unnecessary guessing of parameters), problems with dup and
431so on. The biggest issue is fork races, however - if a program forks then
432I<both> parent and child process have to recreate the epoll set, which can
433take considerable time (one syscall per file descriptor) and is of course
434hard to detect.
435
436Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
437of course I<doesn't>, and epoll just loves to report events for totally
438I<different> file descriptors (even already closed ones, so one cannot
439even remove them from the set) than registered in the set (especially
440on SMP systems). Libev tries to counter these spurious notifications by
441employing an additional generation counter and comparing that against the
442events to filter out spurious ones, recreating the set when required.
361 443
362While stopping, setting and starting an I/O watcher in the same iteration 444While stopping, setting and starting an I/O watcher in the same iteration
363will result in some caching, there is still a syscall per such incident 445will result in some caching, there is still a system call per such
364(because the fd could point to a different file description now), so its 446incident (because the same I<file descriptor> could point to a different
365best to avoid that. Also, C<dup ()>'ed file descriptors might not work 447I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
366very well if you register events for both fds. 448file descriptors might not work very well if you register events for both
367 449file descriptors.
368Please note that epoll sometimes generates spurious notifications, so you
369need to use non-blocking I/O or other means to avoid blocking when no data
370(or space) is available.
371 450
372Best performance from this backend is achieved by not unregistering all 451Best performance from this backend is achieved by not unregistering all
373watchers for a file descriptor until it has been closed, if possible, i.e. 452watchers for a file descriptor until it has been closed, if possible,
374keep at least one watcher active per fd at all times. 453i.e. keep at least one watcher active per fd at all times. Stopping and
454starting a watcher (without re-setting it) also usually doesn't cause
455extra overhead. A fork can both result in spurious notifications as well
456as in libev having to destroy and recreate the epoll object, which can
457take considerable time and thus should be avoided.
375 458
459All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
460faster than epoll for maybe up to a hundred file descriptors, depending on
461the usage. So sad.
462
376While nominally embeddeble in other event loops, this feature is broken in 463While nominally embeddable in other event loops, this feature is broken in
377all kernel versions tested so far. 464all kernel versions tested so far.
465
466This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
467C<EVBACKEND_POLL>.
378 468
379=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 469=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
380 470
381Kqueue deserves special mention, as at the time of this writing, it 471Kqueue deserves special mention, as at the time of this writing, it
382was broken on all BSDs except NetBSD (usually it doesn't work reliably 472was broken on all BSDs except NetBSD (usually it doesn't work reliably
383with anything but sockets and pipes, except on Darwin, where of course 473with anything but sockets and pipes, except on Darwin, where of course
384it's completely useless). For this reason it's not being "autodetected" 474it's completely useless). Unlike epoll, however, whose brokenness
475is by design, these kqueue bugs can (and eventually will) be fixed
476without API changes to existing programs. For this reason it's not being
385unless you explicitly specify it explicitly in the flags (i.e. using 477"auto-detected" unless you explicitly specify it in the flags (i.e. using
386C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 478C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
387system like NetBSD. 479system like NetBSD.
388 480
389You still can embed kqueue into a normal poll or select backend and use it 481You still can embed kqueue into a normal poll or select backend and use it
390only for sockets (after having made sure that sockets work with kqueue on 482only for sockets (after having made sure that sockets work with kqueue on
391the target platform). See C<ev_embed> watchers for more info. 483the target platform). See C<ev_embed> watchers for more info.
392 484
393It scales in the same way as the epoll backend, but the interface to the 485It scales in the same way as the epoll backend, but the interface to the
394kernel is more efficient (which says nothing about its actual speed, of 486kernel is more efficient (which says nothing about its actual speed, of
395course). While stopping, setting and starting an I/O watcher does never 487course). While stopping, setting and starting an I/O watcher does never
396cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to 488cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
397two event changes per incident, support for C<fork ()> is very bad and it 489two event changes per incident. Support for C<fork ()> is very bad (but
398drops fds silently in similarly hard-to-detect cases. 490sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
491cases
399 492
400This backend usually performs well under most conditions. 493This backend usually performs well under most conditions.
401 494
402While nominally embeddable in other event loops, this doesn't work 495While nominally embeddable in other event loops, this doesn't work
403everywhere, so you might need to test for this. And since it is broken 496everywhere, so you might need to test for this. And since it is broken
404almost everywhere, you should only use it when you have a lot of sockets 497almost everywhere, you should only use it when you have a lot of sockets
405(for which it usually works), by embedding it into another event loop 498(for which it usually works), by embedding it into another event loop
406(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for 499(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
407sockets. 500also broken on OS X)) and, did I mention it, using it only for sockets.
501
502This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
503C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
504C<NOTE_EOF>.
408 505
409=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 506=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
410 507
411This is not implemented yet (and might never be, unless you send me an 508This is not implemented yet (and might never be, unless you send me an
412implementation). According to reports, C</dev/poll> only supports sockets 509implementation). According to reports, C</dev/poll> only supports sockets
416=item C<EVBACKEND_PORT> (value 32, Solaris 10) 513=item C<EVBACKEND_PORT> (value 32, Solaris 10)
417 514
418This uses the Solaris 10 event port mechanism. As with everything on Solaris, 515This uses the Solaris 10 event port mechanism. As with everything on Solaris,
419it's really slow, but it still scales very well (O(active_fds)). 516it's really slow, but it still scales very well (O(active_fds)).
420 517
421Please note that solaris event ports can deliver a lot of spurious 518Please note that Solaris event ports can deliver a lot of spurious
422notifications, so you need to use non-blocking I/O or other means to avoid 519notifications, so you need to use non-blocking I/O or other means to avoid
423blocking when no data (or space) is available. 520blocking when no data (or space) is available.
424 521
425While this backend scales well, it requires one system call per active 522While this backend scales well, it requires one system call per active
426file descriptor per loop iteration. For small and medium numbers of file 523file descriptor per loop iteration. For small and medium numbers of file
427descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 524descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
428might perform better. 525might perform better.
429 526
430On the positive side, ignoring the spurious readiness notifications, this 527On the positive side, with the exception of the spurious readiness
431backend actually performed to specification in all tests and is fully 528notifications, this backend actually performed fully to specification
432embeddable, which is a rare feat among the OS-specific backends. 529in all tests and is fully embeddable, which is a rare feat among the
530OS-specific backends (I vastly prefer correctness over speed hacks).
531
532This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
533C<EVBACKEND_POLL>.
433 534
434=item C<EVBACKEND_ALL> 535=item C<EVBACKEND_ALL>
435 536
436Try all backends (even potentially broken ones that wouldn't be tried 537Try all backends (even potentially broken ones that wouldn't be tried
437with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 538with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
439 540
440It is definitely not recommended to use this flag. 541It is definitely not recommended to use this flag.
441 542
442=back 543=back
443 544
444If one or more of these are ored into the flags value, then only these 545If one or more of the backend flags are or'ed into the flags value,
445backends will be tried (in the reverse order as listed here). If none are 546then only these backends will be tried (in the reverse order as listed
446specified, all backends in C<ev_recommended_backends ()> will be tried. 547here). If none are specified, all backends in C<ev_recommended_backends
548()> will be tried.
447 549
448The most typical usage is like this: 550Example: This is the most typical usage.
449 551
450 if (!ev_default_loop (0)) 552 if (!ev_default_loop (0))
451 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 553 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
452 554
453Restrict libev to the select and poll backends, and do not allow 555Example: Restrict libev to the select and poll backends, and do not allow
454environment settings to be taken into account: 556environment settings to be taken into account:
455 557
456 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); 558 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
457 559
458Use whatever libev has to offer, but make sure that kqueue is used if 560Example: Use whatever libev has to offer, but make sure that kqueue is
459available (warning, breaks stuff, best use only with your own private 561used if available (warning, breaks stuff, best use only with your own
460event loop and only if you know the OS supports your types of fds): 562private event loop and only if you know the OS supports your types of
563fds):
461 564
462 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 565 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
463 566
464=item struct ev_loop *ev_loop_new (unsigned int flags) 567=item struct ev_loop *ev_loop_new (unsigned int flags)
465 568
466Similar to C<ev_default_loop>, but always creates a new event loop that is 569Similar to C<ev_default_loop>, but always creates a new event loop that is
467always distinct from the default loop. Unlike the default loop, it cannot 570always distinct from the default loop. Unlike the default loop, it cannot
472libev with threads is indeed to create one loop per thread, and using the 575libev with threads is indeed to create one loop per thread, and using the
473default loop in the "main" or "initial" thread. 576default loop in the "main" or "initial" thread.
474 577
475Example: Try to create a event loop that uses epoll and nothing else. 578Example: Try to create a event loop that uses epoll and nothing else.
476 579
477 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 580 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
478 if (!epoller) 581 if (!epoller)
479 fatal ("no epoll found here, maybe it hides under your chair"); 582 fatal ("no epoll found here, maybe it hides under your chair");
480 583
481=item ev_default_destroy () 584=item ev_default_destroy ()
482 585
483Destroys the default loop again (frees all memory and kernel state 586Destroys the default loop again (frees all memory and kernel state
484etc.). None of the active event watchers will be stopped in the normal 587etc.). None of the active event watchers will be stopped in the normal
485sense, so e.g. C<ev_is_active> might still return true. It is your 588sense, so e.g. C<ev_is_active> might still return true. It is your
486responsibility to either stop all watchers cleanly yoursef I<before> 589responsibility to either stop all watchers cleanly yourself I<before>
487calling this function, or cope with the fact afterwards (which is usually 590calling this function, or cope with the fact afterwards (which is usually
488the easiest thing, you can just ignore the watchers and/or C<free ()> them 591the easiest thing, you can just ignore the watchers and/or C<free ()> them
489for example). 592for example).
490 593
491Note that certain global state, such as signal state, will not be freed by 594Note that certain global state, such as signal state (and installed signal
492this function, and related watchers (such as signal and child watchers) 595handlers), will not be freed by this function, and related watchers (such
493would need to be stopped manually. 596as signal and child watchers) would need to be stopped manually.
494 597
495In general it is not advisable to call this function except in the 598In general it is not advisable to call this function except in the
496rare occasion where you really need to free e.g. the signal handling 599rare occasion where you really need to free e.g. the signal handling
497pipe fds. If you need dynamically allocated loops it is better to use 600pipe fds. If you need dynamically allocated loops it is better to use
498C<ev_loop_new> and C<ev_loop_destroy>). 601C<ev_loop_new> and C<ev_loop_destroy>.
499 602
500=item ev_loop_destroy (loop) 603=item ev_loop_destroy (loop)
501 604
502Like C<ev_default_destroy>, but destroys an event loop created by an 605Like C<ev_default_destroy>, but destroys an event loop created by an
503earlier call to C<ev_loop_new>. 606earlier call to C<ev_loop_new>.
523 626
524=item ev_loop_fork (loop) 627=item ev_loop_fork (loop)
525 628
526Like C<ev_default_fork>, but acts on an event loop created by 629Like C<ev_default_fork>, but acts on an event loop created by
527C<ev_loop_new>. Yes, you have to call this on every allocated event loop 630C<ev_loop_new>. Yes, you have to call this on every allocated event loop
528after fork, and how you do this is entirely your own problem. 631after fork that you want to re-use in the child, and how you do this is
632entirely your own problem.
529 633
530=item int ev_is_default_loop (loop) 634=item int ev_is_default_loop (loop)
531 635
532Returns true when the given loop actually is the default loop, false otherwise. 636Returns true when the given loop is, in fact, the default loop, and false
637otherwise.
533 638
534=item unsigned int ev_loop_count (loop) 639=item unsigned int ev_loop_count (loop)
535 640
536Returns the count of loop iterations for the loop, which is identical to 641Returns the count of loop iterations for the loop, which is identical to
537the number of times libev did poll for new events. It starts at C<0> and 642the number of times libev did poll for new events. It starts at C<0> and
538happily wraps around with enough iterations. 643happily wraps around with enough iterations.
539 644
540This value can sometimes be useful as a generation counter of sorts (it 645This value can sometimes be useful as a generation counter of sorts (it
541"ticks" the number of loop iterations), as it roughly corresponds with 646"ticks" the number of loop iterations), as it roughly corresponds with
542C<ev_prepare> and C<ev_check> calls. 647C<ev_prepare> and C<ev_check> calls.
648
649=item unsigned int ev_loop_depth (loop)
650
651Returns the number of times C<ev_loop> was entered minus the number of
652times C<ev_loop> was exited, in other words, the recursion depth.
653
654Outside C<ev_loop>, this number is zero. In a callback, this number is
655C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
656in which case it is higher.
657
658Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
659etc.), doesn't count as exit.
543 660
544=item unsigned int ev_backend (loop) 661=item unsigned int ev_backend (loop)
545 662
546Returns one of the C<EVBACKEND_*> flags indicating the event backend in 663Returns one of the C<EVBACKEND_*> flags indicating the event backend in
547use. 664use.
552received events and started processing them. This timestamp does not 669received events and started processing them. This timestamp does not
553change as long as callbacks are being processed, and this is also the base 670change as long as callbacks are being processed, and this is also the base
554time used for relative timers. You can treat it as the timestamp of the 671time used for relative timers. You can treat it as the timestamp of the
555event occurring (or more correctly, libev finding out about it). 672event occurring (or more correctly, libev finding out about it).
556 673
674=item ev_now_update (loop)
675
676Establishes the current time by querying the kernel, updating the time
677returned by C<ev_now ()> in the progress. This is a costly operation and
678is usually done automatically within C<ev_loop ()>.
679
680This function is rarely useful, but when some event callback runs for a
681very long time without entering the event loop, updating libev's idea of
682the current time is a good idea.
683
684See also L<The special problem of time updates> in the C<ev_timer> section.
685
686=item ev_suspend (loop)
687
688=item ev_resume (loop)
689
690These two functions suspend and resume a loop, for use when the loop is
691not used for a while and timeouts should not be processed.
692
693A typical use case would be an interactive program such as a game: When
694the user presses C<^Z> to suspend the game and resumes it an hour later it
695would be best to handle timeouts as if no time had actually passed while
696the program was suspended. This can be achieved by calling C<ev_suspend>
697in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
698C<ev_resume> directly afterwards to resume timer processing.
699
700Effectively, all C<ev_timer> watchers will be delayed by the time spend
701between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
702will be rescheduled (that is, they will lose any events that would have
703occured while suspended).
704
705After calling C<ev_suspend> you B<must not> call I<any> function on the
706given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
707without a previous call to C<ev_suspend>.
708
709Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
710event loop time (see C<ev_now_update>).
711
557=item ev_loop (loop, int flags) 712=item ev_loop (loop, int flags)
558 713
559Finally, this is it, the event handler. This function usually is called 714Finally, this is it, the event handler. This function usually is called
560after you initialised all your watchers and you want to start handling 715after you have initialised all your watchers and you want to start
561events. 716handling events.
562 717
563If the flags argument is specified as C<0>, it will not return until 718If the flags argument is specified as C<0>, it will not return until
564either no event watchers are active anymore or C<ev_unloop> was called. 719either no event watchers are active anymore or C<ev_unloop> was called.
565 720
566Please note that an explicit C<ev_unloop> is usually better than 721Please note that an explicit C<ev_unloop> is usually better than
567relying on all watchers to be stopped when deciding when a program has 722relying on all watchers to be stopped when deciding when a program has
568finished (especially in interactive programs), but having a program that 723finished (especially in interactive programs), but having a program
569automatically loops as long as it has to and no longer by virtue of 724that automatically loops as long as it has to and no longer by virtue
570relying on its watchers stopping correctly is a thing of beauty. 725of relying on its watchers stopping correctly, that is truly a thing of
726beauty.
571 727
572A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 728A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
573those events and any outstanding ones, but will not block your process in 729those events and any already outstanding ones, but will not block your
574case there are no events and will return after one iteration of the loop. 730process in case there are no events and will return after one iteration of
731the loop.
575 732
576A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 733A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
577neccessary) and will handle those and any outstanding ones. It will block 734necessary) and will handle those and any already outstanding ones. It
578your process until at least one new event arrives, and will return after 735will block your process until at least one new event arrives (which could
579one iteration of the loop. This is useful if you are waiting for some 736be an event internal to libev itself, so there is no guarantee that a
580external event in conjunction with something not expressible using other 737user-registered callback will be called), and will return after one
738iteration of the loop.
739
740This is useful if you are waiting for some external event in conjunction
741with something not expressible using other libev watchers (i.e. "roll your
581libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 742own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
582usually a better approach for this kind of thing. 743usually a better approach for this kind of thing.
583 744
584Here are the gory details of what C<ev_loop> does: 745Here are the gory details of what C<ev_loop> does:
585 746
586 - Before the first iteration, call any pending watchers. 747 - Before the first iteration, call any pending watchers.
587 * If EVFLAG_FORKCHECK was used, check for a fork. 748 * If EVFLAG_FORKCHECK was used, check for a fork.
588 - If a fork was detected, queue and call all fork watchers. 749 - If a fork was detected (by any means), queue and call all fork watchers.
589 - Queue and call all prepare watchers. 750 - Queue and call all prepare watchers.
590 - If we have been forked, recreate the kernel state. 751 - If we have been forked, detach and recreate the kernel state
752 as to not disturb the other process.
591 - Update the kernel state with all outstanding changes. 753 - Update the kernel state with all outstanding changes.
592 - Update the "event loop time". 754 - Update the "event loop time" (ev_now ()).
593 - Calculate for how long to sleep or block, if at all 755 - Calculate for how long to sleep or block, if at all
594 (active idle watchers, EVLOOP_NONBLOCK or not having 756 (active idle watchers, EVLOOP_NONBLOCK or not having
595 any active watchers at all will result in not sleeping). 757 any active watchers at all will result in not sleeping).
596 - Sleep if the I/O and timer collect interval say so. 758 - Sleep if the I/O and timer collect interval say so.
597 - Block the process, waiting for any events. 759 - Block the process, waiting for any events.
598 - Queue all outstanding I/O (fd) events. 760 - Queue all outstanding I/O (fd) events.
599 - Update the "event loop time" and do time jump handling. 761 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
600 - Queue all outstanding timers. 762 - Queue all expired timers.
601 - Queue all outstanding periodics. 763 - Queue all expired periodics.
602 - If no events are pending now, queue all idle watchers. 764 - Unless any events are pending now, queue all idle watchers.
603 - Queue all check watchers. 765 - Queue all check watchers.
604 - Call all queued watchers in reverse order (i.e. check watchers first). 766 - Call all queued watchers in reverse order (i.e. check watchers first).
605 Signals and child watchers are implemented as I/O watchers, and will 767 Signals and child watchers are implemented as I/O watchers, and will
606 be handled here by queueing them when their watcher gets executed. 768 be handled here by queueing them when their watcher gets executed.
607 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 769 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
612anymore. 774anymore.
613 775
614 ... queue jobs here, make sure they register event watchers as long 776 ... queue jobs here, make sure they register event watchers as long
615 ... as they still have work to do (even an idle watcher will do..) 777 ... as they still have work to do (even an idle watcher will do..)
616 ev_loop (my_loop, 0); 778 ev_loop (my_loop, 0);
617 ... jobs done. yeah! 779 ... jobs done or somebody called unloop. yeah!
618 780
619=item ev_unloop (loop, how) 781=item ev_unloop (loop, how)
620 782
621Can be used to make a call to C<ev_loop> return early (but only after it 783Can be used to make a call to C<ev_loop> return early (but only after it
622has processed all outstanding events). The C<how> argument must be either 784has processed all outstanding events). The C<how> argument must be either
623C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 785C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
624C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 786C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
625 787
626This "unloop state" will be cleared when entering C<ev_loop> again. 788This "unloop state" will be cleared when entering C<ev_loop> again.
627 789
790It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls.
791
628=item ev_ref (loop) 792=item ev_ref (loop)
629 793
630=item ev_unref (loop) 794=item ev_unref (loop)
631 795
632Ref/unref can be used to add or remove a reference count on the event 796Ref/unref can be used to add or remove a reference count on the event
633loop: Every watcher keeps one reference, and as long as the reference 797loop: Every watcher keeps one reference, and as long as the reference
634count is nonzero, C<ev_loop> will not return on its own. If you have 798count is nonzero, C<ev_loop> will not return on its own.
635a watcher you never unregister that should not keep C<ev_loop> from 799
636returning, ev_unref() after starting, and ev_ref() before stopping it. For 800This is useful when you have a watcher that you never intend to
801unregister, but that nevertheless should not keep C<ev_loop> from
802returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
803before stopping it.
804
637example, libev itself uses this for its internal signal pipe: It is not 805As an example, libev itself uses this for its internal signal pipe: It
638visible to the libev user and should not keep C<ev_loop> from exiting if 806is not visible to the libev user and should not keep C<ev_loop> from
639no event watchers registered by it are active. It is also an excellent 807exiting if no event watchers registered by it are active. It is also an
640way to do this for generic recurring timers or from within third-party 808excellent way to do this for generic recurring timers or from within
641libraries. Just remember to I<unref after start> and I<ref before stop> 809third-party libraries. Just remember to I<unref after start> and I<ref
642(but only if the watcher wasn't active before, or was active before, 810before stop> (but only if the watcher wasn't active before, or was active
643respectively). 811before, respectively. Note also that libev might stop watchers itself
812(e.g. non-repeating timers) in which case you have to C<ev_ref>
813in the callback).
644 814
645Example: Create a signal watcher, but keep it from keeping C<ev_loop> 815Example: Create a signal watcher, but keep it from keeping C<ev_loop>
646running when nothing else is active. 816running when nothing else is active.
647 817
648 struct ev_signal exitsig; 818 ev_signal exitsig;
649 ev_signal_init (&exitsig, sig_cb, SIGINT); 819 ev_signal_init (&exitsig, sig_cb, SIGINT);
650 ev_signal_start (loop, &exitsig); 820 ev_signal_start (loop, &exitsig);
651 evf_unref (loop); 821 evf_unref (loop);
652 822
653Example: For some weird reason, unregister the above signal handler again. 823Example: For some weird reason, unregister the above signal handler again.
654 824
655 ev_ref (loop); 825 ev_ref (loop);
656 ev_signal_stop (loop, &exitsig); 826 ev_signal_stop (loop, &exitsig);
657 827
658=item ev_set_io_collect_interval (loop, ev_tstamp interval) 828=item ev_set_io_collect_interval (loop, ev_tstamp interval)
659 829
660=item ev_set_timeout_collect_interval (loop, ev_tstamp interval) 830=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
661 831
662These advanced functions influence the time that libev will spend waiting 832These advanced functions influence the time that libev will spend waiting
663for events. Both are by default C<0>, meaning that libev will try to 833for events. Both time intervals are by default C<0>, meaning that libev
664invoke timer/periodic callbacks and I/O callbacks with minimum latency. 834will try to invoke timer/periodic callbacks and I/O callbacks with minimum
835latency.
665 836
666Setting these to a higher value (the C<interval> I<must> be >= C<0>) 837Setting these to a higher value (the C<interval> I<must> be >= C<0>)
667allows libev to delay invocation of I/O and timer/periodic callbacks to 838allows libev to delay invocation of I/O and timer/periodic callbacks
668increase efficiency of loop iterations. 839to increase efficiency of loop iterations (or to increase power-saving
840opportunities).
669 841
670The background is that sometimes your program runs just fast enough to 842The idea is that sometimes your program runs just fast enough to handle
671handle one (or very few) event(s) per loop iteration. While this makes 843one (or very few) event(s) per loop iteration. While this makes the
672the program responsive, it also wastes a lot of CPU time to poll for new 844program responsive, it also wastes a lot of CPU time to poll for new
673events, especially with backends like C<select ()> which have a high 845events, especially with backends like C<select ()> which have a high
674overhead for the actual polling but can deliver many events at once. 846overhead for the actual polling but can deliver many events at once.
675 847
676By setting a higher I<io collect interval> you allow libev to spend more 848By setting a higher I<io collect interval> you allow libev to spend more
677time collecting I/O events, so you can handle more events per iteration, 849time collecting I/O events, so you can handle more events per iteration,
678at the cost of increasing latency. Timeouts (both C<ev_periodic> and 850at the cost of increasing latency. Timeouts (both C<ev_periodic> and
679C<ev_timer>) will be not affected. Setting this to a non-null value will 851C<ev_timer>) will be not affected. Setting this to a non-null value will
680introduce an additional C<ev_sleep ()> call into most loop iterations. 852introduce an additional C<ev_sleep ()> call into most loop iterations. The
853sleep time ensures that libev will not poll for I/O events more often then
854once per this interval, on average.
681 855
682Likewise, by setting a higher I<timeout collect interval> you allow libev 856Likewise, by setting a higher I<timeout collect interval> you allow libev
683to spend more time collecting timeouts, at the expense of increased 857to spend more time collecting timeouts, at the expense of increased
684latency (the watcher callback will be called later). C<ev_io> watchers 858latency/jitter/inexactness (the watcher callback will be called
685will not be affected. Setting this to a non-null value will not introduce 859later). C<ev_io> watchers will not be affected. Setting this to a non-null
686any overhead in libev. 860value will not introduce any overhead in libev.
687 861
688Many (busy) programs can usually benefit by setting the io collect 862Many (busy) programs can usually benefit by setting the I/O collect
689interval to a value near C<0.1> or so, which is often enough for 863interval to a value near C<0.1> or so, which is often enough for
690interactive servers (of course not for games), likewise for timeouts. It 864interactive servers (of course not for games), likewise for timeouts. It
691usually doesn't make much sense to set it to a lower value than C<0.01>, 865usually doesn't make much sense to set it to a lower value than C<0.01>,
692as this approsaches the timing granularity of most systems. 866as this approaches the timing granularity of most systems. Note that if
867you do transactions with the outside world and you can't increase the
868parallelity, then this setting will limit your transaction rate (if you
869need to poll once per transaction and the I/O collect interval is 0.01,
870then you can't do more than 100 transations per second).
871
872Setting the I<timeout collect interval> can improve the opportunity for
873saving power, as the program will "bundle" timer callback invocations that
874are "near" in time together, by delaying some, thus reducing the number of
875times the process sleeps and wakes up again. Another useful technique to
876reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
877they fire on, say, one-second boundaries only.
878
879Example: we only need 0.1s timeout granularity, and we wish not to poll
880more often than 100 times per second:
881
882 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
883 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
884
885=item ev_invoke_pending (loop)
886
887This call will simply invoke all pending watchers while resetting their
888pending state. Normally, C<ev_loop> does this automatically when required,
889but when overriding the invoke callback this call comes handy.
890
891=item int ev_pending_count (loop)
892
893Returns the number of pending watchers - zero indicates that no watchers
894are pending.
895
896=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
897
898This overrides the invoke pending functionality of the loop: Instead of
899invoking all pending watchers when there are any, C<ev_loop> will call
900this callback instead. This is useful, for example, when you want to
901invoke the actual watchers inside another context (another thread etc.).
902
903If you want to reset the callback, use C<ev_invoke_pending> as new
904callback.
905
906=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
907
908Sometimes you want to share the same loop between multiple threads. This
909can be done relatively simply by putting mutex_lock/unlock calls around
910each call to a libev function.
911
912However, C<ev_loop> can run an indefinite time, so it is not feasible to
913wait for it to return. One way around this is to wake up the loop via
914C<ev_unloop> and C<av_async_send>, another way is to set these I<release>
915and I<acquire> callbacks on the loop.
916
917When set, then C<release> will be called just before the thread is
918suspended waiting for new events, and C<acquire> is called just
919afterwards.
920
921Ideally, C<release> will just call your mutex_unlock function, and
922C<acquire> will just call the mutex_lock function again.
923
924While event loop modifications are allowed between invocations of
925C<release> and C<acquire> (that's their only purpose after all), no
926modifications done will affect the event loop, i.e. adding watchers will
927have no effect on the set of file descriptors being watched, or the time
928waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
929to take note of any changes you made.
930
931In theory, threads executing C<ev_loop> will be async-cancel safe between
932invocations of C<release> and C<acquire>.
933
934See also the locking example in the C<THREADS> section later in this
935document.
936
937=item ev_set_userdata (loop, void *data)
938
939=item ev_userdata (loop)
940
941Set and retrieve a single C<void *> associated with a loop. When
942C<ev_set_userdata> has never been called, then C<ev_userdata> returns
943C<0.>
944
945These two functions can be used to associate arbitrary data with a loop,
946and are intended solely for the C<invoke_pending_cb>, C<release> and
947C<acquire> callbacks described above, but of course can be (ab-)used for
948any other purpose as well.
949
950=item ev_loop_verify (loop)
951
952This function only does something when C<EV_VERIFY> support has been
953compiled in, which is the default for non-minimal builds. It tries to go
954through all internal structures and checks them for validity. If anything
955is found to be inconsistent, it will print an error message to standard
956error and call C<abort ()>.
957
958This can be used to catch bugs inside libev itself: under normal
959circumstances, this function will never abort as of course libev keeps its
960data structures consistent.
693 961
694=back 962=back
695 963
696 964
697=head1 ANATOMY OF A WATCHER 965=head1 ANATOMY OF A WATCHER
966
967In the following description, uppercase C<TYPE> in names stands for the
968watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
969watchers and C<ev_io_start> for I/O watchers.
698 970
699A watcher is a structure that you create and register to record your 971A watcher is a structure that you create and register to record your
700interest in some event. For instance, if you want to wait for STDIN to 972interest in some event. For instance, if you want to wait for STDIN to
701become readable, you would create an C<ev_io> watcher for that: 973become readable, you would create an C<ev_io> watcher for that:
702 974
703 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 975 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
704 { 976 {
705 ev_io_stop (w); 977 ev_io_stop (w);
706 ev_unloop (loop, EVUNLOOP_ALL); 978 ev_unloop (loop, EVUNLOOP_ALL);
707 } 979 }
708 980
709 struct ev_loop *loop = ev_default_loop (0); 981 struct ev_loop *loop = ev_default_loop (0);
982
710 struct ev_io stdin_watcher; 983 ev_io stdin_watcher;
984
711 ev_init (&stdin_watcher, my_cb); 985 ev_init (&stdin_watcher, my_cb);
712 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 986 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
713 ev_io_start (loop, &stdin_watcher); 987 ev_io_start (loop, &stdin_watcher);
988
714 ev_loop (loop, 0); 989 ev_loop (loop, 0);
715 990
716As you can see, you are responsible for allocating the memory for your 991As you can see, you are responsible for allocating the memory for your
717watcher structures (and it is usually a bad idea to do this on the stack, 992watcher structures (and it is I<usually> a bad idea to do this on the
718although this can sometimes be quite valid). 993stack).
994
995Each watcher has an associated watcher structure (called C<struct ev_TYPE>
996or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
719 997
720Each watcher structure must be initialised by a call to C<ev_init 998Each watcher structure must be initialised by a call to C<ev_init
721(watcher *, callback)>, which expects a callback to be provided. This 999(watcher *, callback)>, which expects a callback to be provided. This
722callback gets invoked each time the event occurs (or, in the case of io 1000callback gets invoked each time the event occurs (or, in the case of I/O
723watchers, each time the event loop detects that the file descriptor given 1001watchers, each time the event loop detects that the file descriptor given
724is readable and/or writable). 1002is readable and/or writable).
725 1003
726Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 1004Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
727with arguments specific to this watcher type. There is also a macro 1005macro to configure it, with arguments specific to the watcher type. There
728to combine initialisation and setting in one call: C<< ev_<type>_init 1006is also a macro to combine initialisation and setting in one call: C<<
729(watcher *, callback, ...) >>. 1007ev_TYPE_init (watcher *, callback, ...) >>.
730 1008
731To make the watcher actually watch out for events, you have to start it 1009To make the watcher actually watch out for events, you have to start it
732with a watcher-specific start function (C<< ev_<type>_start (loop, watcher 1010with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
733*) >>), and you can stop watching for events at any time by calling the 1011*) >>), and you can stop watching for events at any time by calling the
734corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 1012corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
735 1013
736As long as your watcher is active (has been started but not stopped) you 1014As long as your watcher is active (has been started but not stopped) you
737must not touch the values stored in it. Most specifically you must never 1015must not touch the values stored in it. Most specifically you must never
738reinitialise it or call its C<set> macro. 1016reinitialise it or call its C<ev_TYPE_set> macro.
739 1017
740Each and every callback receives the event loop pointer as first, the 1018Each and every callback receives the event loop pointer as first, the
741registered watcher structure as second, and a bitset of received events as 1019registered watcher structure as second, and a bitset of received events as
742third argument. 1020third argument.
743 1021
801 1079
802=item C<EV_ASYNC> 1080=item C<EV_ASYNC>
803 1081
804The given async watcher has been asynchronously notified (see C<ev_async>). 1082The given async watcher has been asynchronously notified (see C<ev_async>).
805 1083
1084=item C<EV_CUSTOM>
1085
1086Not ever sent (or otherwise used) by libev itself, but can be freely used
1087by libev users to signal watchers (e.g. via C<ev_feed_event>).
1088
806=item C<EV_ERROR> 1089=item C<EV_ERROR>
807 1090
808An unspecified error has occured, the watcher has been stopped. This might 1091An unspecified error has occurred, the watcher has been stopped. This might
809happen because the watcher could not be properly started because libev 1092happen because the watcher could not be properly started because libev
810ran out of memory, a file descriptor was found to be closed or any other 1093ran out of memory, a file descriptor was found to be closed or any other
1094problem. Libev considers these application bugs.
1095
811problem. You best act on it by reporting the problem and somehow coping 1096You best act on it by reporting the problem and somehow coping with the
812with the watcher being stopped. 1097watcher being stopped. Note that well-written programs should not receive
1098an error ever, so when your watcher receives it, this usually indicates a
1099bug in your program.
813 1100
814Libev will usually signal a few "dummy" events together with an error, 1101Libev will usually signal a few "dummy" events together with an error, for
815for example it might indicate that a fd is readable or writable, and if 1102example it might indicate that a fd is readable or writable, and if your
816your callbacks is well-written it can just attempt the operation and cope 1103callbacks is well-written it can just attempt the operation and cope with
817with the error from read() or write(). This will not work in multithreaded 1104the error from read() or write(). This will not work in multi-threaded
818programs, though, so beware. 1105programs, though, as the fd could already be closed and reused for another
1106thing, so beware.
819 1107
820=back 1108=back
821 1109
822=head2 GENERIC WATCHER FUNCTIONS 1110=head2 GENERIC WATCHER FUNCTIONS
823
824In the following description, C<TYPE> stands for the watcher type,
825e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
826 1111
827=over 4 1112=over 4
828 1113
829=item C<ev_init> (ev_TYPE *watcher, callback) 1114=item C<ev_init> (ev_TYPE *watcher, callback)
830 1115
836which rolls both calls into one. 1121which rolls both calls into one.
837 1122
838You can reinitialise a watcher at any time as long as it has been stopped 1123You can reinitialise a watcher at any time as long as it has been stopped
839(or never started) and there are no pending events outstanding. 1124(or never started) and there are no pending events outstanding.
840 1125
841The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher, 1126The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
842int revents)>. 1127int revents)>.
843 1128
1129Example: Initialise an C<ev_io> watcher in two steps.
1130
1131 ev_io w;
1132 ev_init (&w, my_cb);
1133 ev_io_set (&w, STDIN_FILENO, EV_READ);
1134
844=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1135=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
845 1136
846This macro initialises the type-specific parts of a watcher. You need to 1137This macro initialises the type-specific parts of a watcher. You need to
847call C<ev_init> at least once before you call this macro, but you can 1138call C<ev_init> at least once before you call this macro, but you can
848call C<ev_TYPE_set> any number of times. You must not, however, call this 1139call C<ev_TYPE_set> any number of times. You must not, however, call this
849macro on a watcher that is active (it can be pending, however, which is a 1140macro on a watcher that is active (it can be pending, however, which is a
850difference to the C<ev_init> macro). 1141difference to the C<ev_init> macro).
851 1142
852Although some watcher types do not have type-specific arguments 1143Although some watcher types do not have type-specific arguments
853(e.g. C<ev_prepare>) you still need to call its C<set> macro. 1144(e.g. C<ev_prepare>) you still need to call its C<set> macro.
854 1145
1146See C<ev_init>, above, for an example.
1147
855=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 1148=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
856 1149
857This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro 1150This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
858calls into a single call. This is the most convinient method to initialise 1151calls into a single call. This is the most convenient method to initialise
859a watcher. The same limitations apply, of course. 1152a watcher. The same limitations apply, of course.
860 1153
1154Example: Initialise and set an C<ev_io> watcher in one step.
1155
1156 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1157
861=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1158=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
862 1159
863Starts (activates) the given watcher. Only active watchers will receive 1160Starts (activates) the given watcher. Only active watchers will receive
864events. If the watcher is already active nothing will happen. 1161events. If the watcher is already active nothing will happen.
865 1162
1163Example: Start the C<ev_io> watcher that is being abused as example in this
1164whole section.
1165
1166 ev_io_start (EV_DEFAULT_UC, &w);
1167
866=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1168=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
867 1169
868Stops the given watcher again (if active) and clears the pending 1170Stops the given watcher if active, and clears the pending status (whether
1171the watcher was active or not).
1172
869status. It is possible that stopped watchers are pending (for example, 1173It is possible that stopped watchers are pending - for example,
870non-repeating timers are being stopped when they become pending), but 1174non-repeating timers are being stopped when they become pending - but
871C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If 1175calling C<ev_TYPE_stop> ensures that the watcher is neither active nor
872you want to free or reuse the memory used by the watcher it is therefore a 1176pending. If you want to free or reuse the memory used by the watcher it is
873good idea to always call its C<ev_TYPE_stop> function. 1177therefore a good idea to always call its C<ev_TYPE_stop> function.
874 1178
875=item bool ev_is_active (ev_TYPE *watcher) 1179=item bool ev_is_active (ev_TYPE *watcher)
876 1180
877Returns a true value iff the watcher is active (i.e. it has been started 1181Returns a true value iff the watcher is active (i.e. it has been started
878and not yet been stopped). As long as a watcher is active you must not modify 1182and not yet been stopped). As long as a watcher is active you must not modify
894=item ev_cb_set (ev_TYPE *watcher, callback) 1198=item ev_cb_set (ev_TYPE *watcher, callback)
895 1199
896Change the callback. You can change the callback at virtually any time 1200Change the callback. You can change the callback at virtually any time
897(modulo threads). 1201(modulo threads).
898 1202
899=item ev_set_priority (ev_TYPE *watcher, priority) 1203=item ev_set_priority (ev_TYPE *watcher, int priority)
900 1204
901=item int ev_priority (ev_TYPE *watcher) 1205=item int ev_priority (ev_TYPE *watcher)
902 1206
903Set and query the priority of the watcher. The priority is a small 1207Set and query the priority of the watcher. The priority is a small
904integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1208integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
905(default: C<-2>). Pending watchers with higher priority will be invoked 1209(default: C<-2>). Pending watchers with higher priority will be invoked
906before watchers with lower priority, but priority will not keep watchers 1210before watchers with lower priority, but priority will not keep watchers
907from being executed (except for C<ev_idle> watchers). 1211from being executed (except for C<ev_idle> watchers).
908 1212
909This means that priorities are I<only> used for ordering callback
910invocation after new events have been received. This is useful, for
911example, to reduce latency after idling, or more often, to bind two
912watchers on the same event and make sure one is called first.
913
914If you need to suppress invocation when higher priority events are pending 1213If you need to suppress invocation when higher priority events are pending
915you need to look at C<ev_idle> watchers, which provide this functionality. 1214you need to look at C<ev_idle> watchers, which provide this functionality.
916 1215
917You I<must not> change the priority of a watcher as long as it is active or 1216You I<must not> change the priority of a watcher as long as it is active or
918pending. 1217pending.
919 1218
1219Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1220fine, as long as you do not mind that the priority value you query might
1221or might not have been clamped to the valid range.
1222
920The default priority used by watchers when no priority has been set is 1223The default priority used by watchers when no priority has been set is
921always C<0>, which is supposed to not be too high and not be too low :). 1224always C<0>, which is supposed to not be too high and not be too low :).
922 1225
923Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1226See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
924fine, as long as you do not mind that the priority value you query might 1227priorities.
925or might not have been adjusted to be within valid range.
926 1228
927=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1229=item ev_invoke (loop, ev_TYPE *watcher, int revents)
928 1230
929Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1231Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
930C<loop> nor C<revents> need to be valid as long as the watcher callback 1232C<loop> nor C<revents> need to be valid as long as the watcher callback
931can deal with that fact. 1233can deal with that fact, as both are simply passed through to the
1234callback.
932 1235
933=item int ev_clear_pending (loop, ev_TYPE *watcher) 1236=item int ev_clear_pending (loop, ev_TYPE *watcher)
934 1237
935If the watcher is pending, this function returns clears its pending status 1238If the watcher is pending, this function clears its pending status and
936and returns its C<revents> bitset (as if its callback was invoked). If the 1239returns its C<revents> bitset (as if its callback was invoked). If the
937watcher isn't pending it does nothing and returns C<0>. 1240watcher isn't pending it does nothing and returns C<0>.
938 1241
1242Sometimes it can be useful to "poll" a watcher instead of waiting for its
1243callback to be invoked, which can be accomplished with this function.
1244
1245=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1246
1247Feeds the given event set into the event loop, as if the specified event
1248had happened for the specified watcher (which must be a pointer to an
1249initialised but not necessarily started event watcher). Obviously you must
1250not free the watcher as long as it has pending events.
1251
1252Stopping the watcher, letting libev invoke it, or calling
1253C<ev_clear_pending> will clear the pending event, even if the watcher was
1254not started in the first place.
1255
1256See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1257functions that do not need a watcher.
1258
939=back 1259=back
940 1260
941 1261
942=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1262=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
943 1263
944Each watcher has, by default, a member C<void *data> that you can change 1264Each watcher has, by default, a member C<void *data> that you can change
945and read at any time, libev will completely ignore it. This can be used 1265and read at any time: libev will completely ignore it. This can be used
946to associate arbitrary data with your watcher. If you need more data and 1266to associate arbitrary data with your watcher. If you need more data and
947don't want to allocate memory and store a pointer to it in that data 1267don't want to allocate memory and store a pointer to it in that data
948member, you can also "subclass" the watcher type and provide your own 1268member, you can also "subclass" the watcher type and provide your own
949data: 1269data:
950 1270
951 struct my_io 1271 struct my_io
952 { 1272 {
953 struct ev_io io; 1273 ev_io io;
954 int otherfd; 1274 int otherfd;
955 void *somedata; 1275 void *somedata;
956 struct whatever *mostinteresting; 1276 struct whatever *mostinteresting;
957 } 1277 };
1278
1279 ...
1280 struct my_io w;
1281 ev_io_init (&w.io, my_cb, fd, EV_READ);
958 1282
959And since your callback will be called with a pointer to the watcher, you 1283And since your callback will be called with a pointer to the watcher, you
960can cast it back to your own type: 1284can cast it back to your own type:
961 1285
962 static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) 1286 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
963 { 1287 {
964 struct my_io *w = (struct my_io *)w_; 1288 struct my_io *w = (struct my_io *)w_;
965 ... 1289 ...
966 } 1290 }
967 1291
968More interesting and less C-conformant ways of casting your callback type 1292More interesting and less C-conformant ways of casting your callback type
969instead have been omitted. 1293instead have been omitted.
970 1294
971Another common scenario is having some data structure with multiple 1295Another common scenario is to use some data structure with multiple
972watchers: 1296embedded watchers:
973 1297
974 struct my_biggy 1298 struct my_biggy
975 { 1299 {
976 int some_data; 1300 int some_data;
977 ev_timer t1; 1301 ev_timer t1;
978 ev_timer t2; 1302 ev_timer t2;
979 } 1303 }
980 1304
981In this case getting the pointer to C<my_biggy> is a bit more complicated, 1305In this case getting the pointer to C<my_biggy> is a bit more
982you need to use C<offsetof>: 1306complicated: Either you store the address of your C<my_biggy> struct
1307in the C<data> member of the watcher (for woozies), or you need to use
1308some pointer arithmetic using C<offsetof> inside your watchers (for real
1309programmers):
983 1310
984 #include <stddef.h> 1311 #include <stddef.h>
985 1312
986 static void 1313 static void
987 t1_cb (EV_P_ struct ev_timer *w, int revents) 1314 t1_cb (EV_P_ ev_timer *w, int revents)
988 { 1315 {
989 struct my_biggy big = (struct my_biggy * 1316 struct my_biggy big = (struct my_biggy *)
990 (((char *)w) - offsetof (struct my_biggy, t1)); 1317 (((char *)w) - offsetof (struct my_biggy, t1));
991 } 1318 }
992 1319
993 static void 1320 static void
994 t2_cb (EV_P_ struct ev_timer *w, int revents) 1321 t2_cb (EV_P_ ev_timer *w, int revents)
995 { 1322 {
996 struct my_biggy big = (struct my_biggy * 1323 struct my_biggy big = (struct my_biggy *)
997 (((char *)w) - offsetof (struct my_biggy, t2)); 1324 (((char *)w) - offsetof (struct my_biggy, t2));
998 } 1325 }
1326
1327=head2 WATCHER PRIORITY MODELS
1328
1329Many event loops support I<watcher priorities>, which are usually small
1330integers that influence the ordering of event callback invocation
1331between watchers in some way, all else being equal.
1332
1333In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1334description for the more technical details such as the actual priority
1335range.
1336
1337There are two common ways how these these priorities are being interpreted
1338by event loops:
1339
1340In the more common lock-out model, higher priorities "lock out" invocation
1341of lower priority watchers, which means as long as higher priority
1342watchers receive events, lower priority watchers are not being invoked.
1343
1344The less common only-for-ordering model uses priorities solely to order
1345callback invocation within a single event loop iteration: Higher priority
1346watchers are invoked before lower priority ones, but they all get invoked
1347before polling for new events.
1348
1349Libev uses the second (only-for-ordering) model for all its watchers
1350except for idle watchers (which use the lock-out model).
1351
1352The rationale behind this is that implementing the lock-out model for
1353watchers is not well supported by most kernel interfaces, and most event
1354libraries will just poll for the same events again and again as long as
1355their callbacks have not been executed, which is very inefficient in the
1356common case of one high-priority watcher locking out a mass of lower
1357priority ones.
1358
1359Static (ordering) priorities are most useful when you have two or more
1360watchers handling the same resource: a typical usage example is having an
1361C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1362timeouts. Under load, data might be received while the program handles
1363other jobs, but since timers normally get invoked first, the timeout
1364handler will be executed before checking for data. In that case, giving
1365the timer a lower priority than the I/O watcher ensures that I/O will be
1366handled first even under adverse conditions (which is usually, but not
1367always, what you want).
1368
1369Since idle watchers use the "lock-out" model, meaning that idle watchers
1370will only be executed when no same or higher priority watchers have
1371received events, they can be used to implement the "lock-out" model when
1372required.
1373
1374For example, to emulate how many other event libraries handle priorities,
1375you can associate an C<ev_idle> watcher to each such watcher, and in
1376the normal watcher callback, you just start the idle watcher. The real
1377processing is done in the idle watcher callback. This causes libev to
1378continously poll and process kernel event data for the watcher, but when
1379the lock-out case is known to be rare (which in turn is rare :), this is
1380workable.
1381
1382Usually, however, the lock-out model implemented that way will perform
1383miserably under the type of load it was designed to handle. In that case,
1384it might be preferable to stop the real watcher before starting the
1385idle watcher, so the kernel will not have to process the event in case
1386the actual processing will be delayed for considerable time.
1387
1388Here is an example of an I/O watcher that should run at a strictly lower
1389priority than the default, and which should only process data when no
1390other events are pending:
1391
1392 ev_idle idle; // actual processing watcher
1393 ev_io io; // actual event watcher
1394
1395 static void
1396 io_cb (EV_P_ ev_io *w, int revents)
1397 {
1398 // stop the I/O watcher, we received the event, but
1399 // are not yet ready to handle it.
1400 ev_io_stop (EV_A_ w);
1401
1402 // start the idle watcher to ahndle the actual event.
1403 // it will not be executed as long as other watchers
1404 // with the default priority are receiving events.
1405 ev_idle_start (EV_A_ &idle);
1406 }
1407
1408 static void
1409 idle_cb (EV_P_ ev_idle *w, int revents)
1410 {
1411 // actual processing
1412 read (STDIN_FILENO, ...);
1413
1414 // have to start the I/O watcher again, as
1415 // we have handled the event
1416 ev_io_start (EV_P_ &io);
1417 }
1418
1419 // initialisation
1420 ev_idle_init (&idle, idle_cb);
1421 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1422 ev_io_start (EV_DEFAULT_ &io);
1423
1424In the "real" world, it might also be beneficial to start a timer, so that
1425low-priority connections can not be locked out forever under load. This
1426enables your program to keep a lower latency for important connections
1427during short periods of high load, while not completely locking out less
1428important ones.
999 1429
1000 1430
1001=head1 WATCHER TYPES 1431=head1 WATCHER TYPES
1002 1432
1003This section describes each watcher in detail, but will not repeat 1433This section describes each watcher in detail, but will not repeat
1027In general you can register as many read and/or write event watchers per 1457In general you can register as many read and/or write event watchers per
1028fd as you want (as long as you don't confuse yourself). Setting all file 1458fd as you want (as long as you don't confuse yourself). Setting all file
1029descriptors to non-blocking mode is also usually a good idea (but not 1459descriptors to non-blocking mode is also usually a good idea (but not
1030required if you know what you are doing). 1460required if you know what you are doing).
1031 1461
1032If you must do this, then force the use of a known-to-be-good backend 1462If you cannot use non-blocking mode, then force the use of a
1033(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 1463known-to-be-good backend (at the time of this writing, this includes only
1034C<EVBACKEND_POLL>). 1464C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1465descriptors for which non-blocking operation makes no sense (such as
1466files) - libev doesn't guarentee any specific behaviour in that case.
1035 1467
1036Another thing you have to watch out for is that it is quite easy to 1468Another thing you have to watch out for is that it is quite easy to
1037receive "spurious" readiness notifications, that is your callback might 1469receive "spurious" readiness notifications, that is your callback might
1038be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1470be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1039because there is no data. Not only are some backends known to create a 1471because there is no data. Not only are some backends known to create a
1040lot of those (for example solaris ports), it is very easy to get into 1472lot of those (for example Solaris ports), it is very easy to get into
1041this situation even with a relatively standard program structure. Thus 1473this situation even with a relatively standard program structure. Thus
1042it is best to always use non-blocking I/O: An extra C<read>(2) returning 1474it is best to always use non-blocking I/O: An extra C<read>(2) returning
1043C<EAGAIN> is far preferable to a program hanging until some data arrives. 1475C<EAGAIN> is far preferable to a program hanging until some data arrives.
1044 1476
1045If you cannot run the fd in non-blocking mode (for example you should not 1477If you cannot run the fd in non-blocking mode (for example you should
1046play around with an Xlib connection), then you have to seperately re-test 1478not play around with an Xlib connection), then you have to separately
1047whether a file descriptor is really ready with a known-to-be good interface 1479re-test whether a file descriptor is really ready with a known-to-be good
1048such as poll (fortunately in our Xlib example, Xlib already does this on 1480interface such as poll (fortunately in our Xlib example, Xlib already
1049its own, so its quite safe to use). 1481does this on its own, so its quite safe to use). Some people additionally
1482use C<SIGALRM> and an interval timer, just to be sure you won't block
1483indefinitely.
1484
1485But really, best use non-blocking mode.
1050 1486
1051=head3 The special problem of disappearing file descriptors 1487=head3 The special problem of disappearing file descriptors
1052 1488
1053Some backends (e.g. kqueue, epoll) need to be told about closing a file 1489Some backends (e.g. kqueue, epoll) need to be told about closing a file
1054descriptor (either by calling C<close> explicitly or by any other means, 1490descriptor (either due to calling C<close> explicitly or any other means,
1055such as C<dup>). The reason is that you register interest in some file 1491such as C<dup2>). The reason is that you register interest in some file
1056descriptor, but when it goes away, the operating system will silently drop 1492descriptor, but when it goes away, the operating system will silently drop
1057this interest. If another file descriptor with the same number then is 1493this interest. If another file descriptor with the same number then is
1058registered with libev, there is no efficient way to see that this is, in 1494registered with libev, there is no efficient way to see that this is, in
1059fact, a different file descriptor. 1495fact, a different file descriptor.
1060 1496
1091enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1527enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1092C<EVBACKEND_POLL>. 1528C<EVBACKEND_POLL>.
1093 1529
1094=head3 The special problem of SIGPIPE 1530=head3 The special problem of SIGPIPE
1095 1531
1096While not really specific to libev, it is easy to forget about SIGPIPE: 1532While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1097when reading from a pipe whose other end has been closed, your program 1533when writing to a pipe whose other end has been closed, your program gets
1098gets send a SIGPIPE, which, by default, aborts your program. For most 1534sent a SIGPIPE, which, by default, aborts your program. For most programs
1099programs this is sensible behaviour, for daemons, this is usually 1535this is sensible behaviour, for daemons, this is usually undesirable.
1100undesirable.
1101 1536
1102So when you encounter spurious, unexplained daemon exits, make sure you 1537So when you encounter spurious, unexplained daemon exits, make sure you
1103ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1538ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1104somewhere, as that would have given you a big clue). 1539somewhere, as that would have given you a big clue).
1105 1540
1111=item ev_io_init (ev_io *, callback, int fd, int events) 1546=item ev_io_init (ev_io *, callback, int fd, int events)
1112 1547
1113=item ev_io_set (ev_io *, int fd, int events) 1548=item ev_io_set (ev_io *, int fd, int events)
1114 1549
1115Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1550Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1116rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or 1551receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or
1117C<EV_READ | EV_WRITE> to receive the given events. 1552C<EV_READ | EV_WRITE>, to express the desire to receive the given events.
1118 1553
1119=item int fd [read-only] 1554=item int fd [read-only]
1120 1555
1121The file descriptor being watched. 1556The file descriptor being watched.
1122 1557
1130 1565
1131Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well 1566Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1132readable, but only once. Since it is likely line-buffered, you could 1567readable, but only once. Since it is likely line-buffered, you could
1133attempt to read a whole line in the callback. 1568attempt to read a whole line in the callback.
1134 1569
1135 static void 1570 static void
1136 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1571 stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents)
1137 { 1572 {
1138 ev_io_stop (loop, w); 1573 ev_io_stop (loop, w);
1139 .. read from stdin here (or from w->fd) and haqndle any I/O errors 1574 .. read from stdin here (or from w->fd) and handle any I/O errors
1140 } 1575 }
1141 1576
1142 ... 1577 ...
1143 struct ev_loop *loop = ev_default_init (0); 1578 struct ev_loop *loop = ev_default_init (0);
1144 struct ev_io stdin_readable; 1579 ev_io stdin_readable;
1145 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1580 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1146 ev_io_start (loop, &stdin_readable); 1581 ev_io_start (loop, &stdin_readable);
1147 ev_loop (loop, 0); 1582 ev_loop (loop, 0);
1148 1583
1149 1584
1150=head2 C<ev_timer> - relative and optionally repeating timeouts 1585=head2 C<ev_timer> - relative and optionally repeating timeouts
1151 1586
1152Timer watchers are simple relative timers that generate an event after a 1587Timer watchers are simple relative timers that generate an event after a
1153given time, and optionally repeating in regular intervals after that. 1588given time, and optionally repeating in regular intervals after that.
1154 1589
1155The timers are based on real time, that is, if you register an event that 1590The timers are based on real time, that is, if you register an event that
1156times out after an hour and you reset your system clock to january last 1591times out after an hour and you reset your system clock to January last
1157year, it will still time out after (roughly) and hour. "Roughly" because 1592year, it will still time out after (roughly) one hour. "Roughly" because
1158detecting time jumps is hard, and some inaccuracies are unavoidable (the 1593detecting time jumps is hard, and some inaccuracies are unavoidable (the
1159monotonic clock option helps a lot here). 1594monotonic clock option helps a lot here).
1595
1596The callback is guaranteed to be invoked only I<after> its timeout has
1597passed (not I<at>, so on systems with very low-resolution clocks this
1598might introduce a small delay). If multiple timers become ready during the
1599same loop iteration then the ones with earlier time-out values are invoked
1600before ones of the same priority with later time-out values (but this is
1601no longer true when a callback calls C<ev_loop> recursively).
1602
1603=head3 Be smart about timeouts
1604
1605Many real-world problems involve some kind of timeout, usually for error
1606recovery. A typical example is an HTTP request - if the other side hangs,
1607you want to raise some error after a while.
1608
1609What follows are some ways to handle this problem, from obvious and
1610inefficient to smart and efficient.
1611
1612In the following, a 60 second activity timeout is assumed - a timeout that
1613gets reset to 60 seconds each time there is activity (e.g. each time some
1614data or other life sign was received).
1615
1616=over 4
1617
1618=item 1. Use a timer and stop, reinitialise and start it on activity.
1619
1620This is the most obvious, but not the most simple way: In the beginning,
1621start the watcher:
1622
1623 ev_timer_init (timer, callback, 60., 0.);
1624 ev_timer_start (loop, timer);
1625
1626Then, each time there is some activity, C<ev_timer_stop> it, initialise it
1627and start it again:
1628
1629 ev_timer_stop (loop, timer);
1630 ev_timer_set (timer, 60., 0.);
1631 ev_timer_start (loop, timer);
1632
1633This is relatively simple to implement, but means that each time there is
1634some activity, libev will first have to remove the timer from its internal
1635data structure and then add it again. Libev tries to be fast, but it's
1636still not a constant-time operation.
1637
1638=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1639
1640This is the easiest way, and involves using C<ev_timer_again> instead of
1641C<ev_timer_start>.
1642
1643To implement this, configure an C<ev_timer> with a C<repeat> value
1644of C<60> and then call C<ev_timer_again> at start and each time you
1645successfully read or write some data. If you go into an idle state where
1646you do not expect data to travel on the socket, you can C<ev_timer_stop>
1647the timer, and C<ev_timer_again> will automatically restart it if need be.
1648
1649That means you can ignore both the C<ev_timer_start> function and the
1650C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1651member and C<ev_timer_again>.
1652
1653At start:
1654
1655 ev_init (timer, callback);
1656 timer->repeat = 60.;
1657 ev_timer_again (loop, timer);
1658
1659Each time there is some activity:
1660
1661 ev_timer_again (loop, timer);
1662
1663It is even possible to change the time-out on the fly, regardless of
1664whether the watcher is active or not:
1665
1666 timer->repeat = 30.;
1667 ev_timer_again (loop, timer);
1668
1669This is slightly more efficient then stopping/starting the timer each time
1670you want to modify its timeout value, as libev does not have to completely
1671remove and re-insert the timer from/into its internal data structure.
1672
1673It is, however, even simpler than the "obvious" way to do it.
1674
1675=item 3. Let the timer time out, but then re-arm it as required.
1676
1677This method is more tricky, but usually most efficient: Most timeouts are
1678relatively long compared to the intervals between other activity - in
1679our example, within 60 seconds, there are usually many I/O events with
1680associated activity resets.
1681
1682In this case, it would be more efficient to leave the C<ev_timer> alone,
1683but remember the time of last activity, and check for a real timeout only
1684within the callback:
1685
1686 ev_tstamp last_activity; // time of last activity
1687
1688 static void
1689 callback (EV_P_ ev_timer *w, int revents)
1690 {
1691 ev_tstamp now = ev_now (EV_A);
1692 ev_tstamp timeout = last_activity + 60.;
1693
1694 // if last_activity + 60. is older than now, we did time out
1695 if (timeout < now)
1696 {
1697 // timeout occured, take action
1698 }
1699 else
1700 {
1701 // callback was invoked, but there was some activity, re-arm
1702 // the watcher to fire in last_activity + 60, which is
1703 // guaranteed to be in the future, so "again" is positive:
1704 w->repeat = timeout - now;
1705 ev_timer_again (EV_A_ w);
1706 }
1707 }
1708
1709To summarise the callback: first calculate the real timeout (defined
1710as "60 seconds after the last activity"), then check if that time has
1711been reached, which means something I<did>, in fact, time out. Otherwise
1712the callback was invoked too early (C<timeout> is in the future), so
1713re-schedule the timer to fire at that future time, to see if maybe we have
1714a timeout then.
1715
1716Note how C<ev_timer_again> is used, taking advantage of the
1717C<ev_timer_again> optimisation when the timer is already running.
1718
1719This scheme causes more callback invocations (about one every 60 seconds
1720minus half the average time between activity), but virtually no calls to
1721libev to change the timeout.
1722
1723To start the timer, simply initialise the watcher and set C<last_activity>
1724to the current time (meaning we just have some activity :), then call the
1725callback, which will "do the right thing" and start the timer:
1726
1727 ev_init (timer, callback);
1728 last_activity = ev_now (loop);
1729 callback (loop, timer, EV_TIMEOUT);
1730
1731And when there is some activity, simply store the current time in
1732C<last_activity>, no libev calls at all:
1733
1734 last_actiivty = ev_now (loop);
1735
1736This technique is slightly more complex, but in most cases where the
1737time-out is unlikely to be triggered, much more efficient.
1738
1739Changing the timeout is trivial as well (if it isn't hard-coded in the
1740callback :) - just change the timeout and invoke the callback, which will
1741fix things for you.
1742
1743=item 4. Wee, just use a double-linked list for your timeouts.
1744
1745If there is not one request, but many thousands (millions...), all
1746employing some kind of timeout with the same timeout value, then one can
1747do even better:
1748
1749When starting the timeout, calculate the timeout value and put the timeout
1750at the I<end> of the list.
1751
1752Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
1753the list is expected to fire (for example, using the technique #3).
1754
1755When there is some activity, remove the timer from the list, recalculate
1756the timeout, append it to the end of the list again, and make sure to
1757update the C<ev_timer> if it was taken from the beginning of the list.
1758
1759This way, one can manage an unlimited number of timeouts in O(1) time for
1760starting, stopping and updating the timers, at the expense of a major
1761complication, and having to use a constant timeout. The constant timeout
1762ensures that the list stays sorted.
1763
1764=back
1765
1766So which method the best?
1767
1768Method #2 is a simple no-brain-required solution that is adequate in most
1769situations. Method #3 requires a bit more thinking, but handles many cases
1770better, and isn't very complicated either. In most case, choosing either
1771one is fine, with #3 being better in typical situations.
1772
1773Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1774rather complicated, but extremely efficient, something that really pays
1775off after the first million or so of active timers, i.e. it's usually
1776overkill :)
1777
1778=head3 The special problem of time updates
1779
1780Establishing the current time is a costly operation (it usually takes at
1781least two system calls): EV therefore updates its idea of the current
1782time only before and after C<ev_loop> collects new events, which causes a
1783growing difference between C<ev_now ()> and C<ev_time ()> when handling
1784lots of events in one iteration.
1160 1785
1161The relative timeouts are calculated relative to the C<ev_now ()> 1786The relative timeouts are calculated relative to the C<ev_now ()>
1162time. This is usually the right thing as this timestamp refers to the time 1787time. This is usually the right thing as this timestamp refers to the time
1163of the event triggering whatever timeout you are modifying/starting. If 1788of the event triggering whatever timeout you are modifying/starting. If
1164you suspect event processing to be delayed and you I<need> to base the timeout 1789you suspect event processing to be delayed and you I<need> to base the
1165on the current time, use something like this to adjust for this: 1790timeout on the current time, use something like this to adjust for this:
1166 1791
1167 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1792 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1168 1793
1169The callback is guarenteed to be invoked only after its timeout has passed, 1794If the event loop is suspended for a long time, you can also force an
1170but if multiple timers become ready during the same loop iteration then 1795update of the time returned by C<ev_now ()> by calling C<ev_now_update
1171order of execution is undefined. 1796()>.
1797
1798=head3 The special problems of suspended animation
1799
1800When you leave the server world it is quite customary to hit machines that
1801can suspend/hibernate - what happens to the clocks during such a suspend?
1802
1803Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1804all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1805to run until the system is suspended, but they will not advance while the
1806system is suspended. That means, on resume, it will be as if the program
1807was frozen for a few seconds, but the suspend time will not be counted
1808towards C<ev_timer> when a monotonic clock source is used. The real time
1809clock advanced as expected, but if it is used as sole clocksource, then a
1810long suspend would be detected as a time jump by libev, and timers would
1811be adjusted accordingly.
1812
1813I would not be surprised to see different behaviour in different between
1814operating systems, OS versions or even different hardware.
1815
1816The other form of suspend (job control, or sending a SIGSTOP) will see a
1817time jump in the monotonic clocks and the realtime clock. If the program
1818is suspended for a very long time, and monotonic clock sources are in use,
1819then you can expect C<ev_timer>s to expire as the full suspension time
1820will be counted towards the timers. When no monotonic clock source is in
1821use, then libev will again assume a timejump and adjust accordingly.
1822
1823It might be beneficial for this latter case to call C<ev_suspend>
1824and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1825deterministic behaviour in this case (you can do nothing against
1826C<SIGSTOP>).
1172 1827
1173=head3 Watcher-Specific Functions and Data Members 1828=head3 Watcher-Specific Functions and Data Members
1174 1829
1175=over 4 1830=over 4
1176 1831
1195This will act as if the timer timed out and restart it again if it is 1850This will act as if the timer timed out and restart it again if it is
1196repeating. The exact semantics are: 1851repeating. The exact semantics are:
1197 1852
1198If the timer is pending, its pending status is cleared. 1853If the timer is pending, its pending status is cleared.
1199 1854
1200If the timer is started but nonrepeating, stop it (as if it timed out). 1855If the timer is started but non-repeating, stop it (as if it timed out).
1201 1856
1202If the timer is repeating, either start it if necessary (with the 1857If the timer is repeating, either start it if necessary (with the
1203C<repeat> value), or reset the running timer to the C<repeat> value. 1858C<repeat> value), or reset the running timer to the C<repeat> value.
1204 1859
1205This sounds a bit complicated, but here is a useful and typical 1860This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1206example: Imagine you have a tcp connection and you want a so-called idle 1861usage example.
1207timeout, that is, you want to be called when there have been, say, 60
1208seconds of inactivity on the socket. The easiest way to do this is to
1209configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1210C<ev_timer_again> each time you successfully read or write some data. If
1211you go into an idle state where you do not expect data to travel on the
1212socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
1213automatically restart it if need be.
1214 1862
1215That means you can ignore the C<after> value and C<ev_timer_start> 1863=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1216altogether and only ever use the C<repeat> value and C<ev_timer_again>:
1217 1864
1218 ev_timer_init (timer, callback, 0., 5.); 1865Returns the remaining time until a timer fires. If the timer is active,
1219 ev_timer_again (loop, timer); 1866then this time is relative to the current event loop time, otherwise it's
1220 ... 1867the timeout value currently configured.
1221 timer->again = 17.;
1222 ev_timer_again (loop, timer);
1223 ...
1224 timer->again = 10.;
1225 ev_timer_again (loop, timer);
1226 1868
1227This is more slightly efficient then stopping/starting the timer each time 1869That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1228you want to modify its timeout value. 1870C<5>. When the timer is started and one second passes, C<ev_timer_remain>
1871will return C<4>. When the timer expires and is restarted, it will return
1872roughly C<7> (likely slightly less as callback invocation takes some time,
1873too), and so on.
1229 1874
1230=item ev_tstamp repeat [read-write] 1875=item ev_tstamp repeat [read-write]
1231 1876
1232The current C<repeat> value. Will be used each time the watcher times out 1877The current C<repeat> value. Will be used each time the watcher times out
1233or C<ev_timer_again> is called and determines the next timeout (if any), 1878or C<ev_timer_again> is called, and determines the next timeout (if any),
1234which is also when any modifications are taken into account. 1879which is also when any modifications are taken into account.
1235 1880
1236=back 1881=back
1237 1882
1238=head3 Examples 1883=head3 Examples
1239 1884
1240Example: Create a timer that fires after 60 seconds. 1885Example: Create a timer that fires after 60 seconds.
1241 1886
1242 static void 1887 static void
1243 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1888 one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents)
1244 { 1889 {
1245 .. one minute over, w is actually stopped right here 1890 .. one minute over, w is actually stopped right here
1246 } 1891 }
1247 1892
1248 struct ev_timer mytimer; 1893 ev_timer mytimer;
1249 ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1894 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1250 ev_timer_start (loop, &mytimer); 1895 ev_timer_start (loop, &mytimer);
1251 1896
1252Example: Create a timeout timer that times out after 10 seconds of 1897Example: Create a timeout timer that times out after 10 seconds of
1253inactivity. 1898inactivity.
1254 1899
1255 static void 1900 static void
1256 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1901 timeout_cb (struct ev_loop *loop, ev_timer *w, int revents)
1257 { 1902 {
1258 .. ten seconds without any activity 1903 .. ten seconds without any activity
1259 } 1904 }
1260 1905
1261 struct ev_timer mytimer; 1906 ev_timer mytimer;
1262 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1907 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1263 ev_timer_again (&mytimer); /* start timer */ 1908 ev_timer_again (&mytimer); /* start timer */
1264 ev_loop (loop, 0); 1909 ev_loop (loop, 0);
1265 1910
1266 // and in some piece of code that gets executed on any "activity": 1911 // and in some piece of code that gets executed on any "activity":
1267 // reset the timeout to start ticking again at 10 seconds 1912 // reset the timeout to start ticking again at 10 seconds
1268 ev_timer_again (&mytimer); 1913 ev_timer_again (&mytimer);
1269 1914
1270 1915
1271=head2 C<ev_periodic> - to cron or not to cron? 1916=head2 C<ev_periodic> - to cron or not to cron?
1272 1917
1273Periodic watchers are also timers of a kind, but they are very versatile 1918Periodic watchers are also timers of a kind, but they are very versatile
1274(and unfortunately a bit complex). 1919(and unfortunately a bit complex).
1275 1920
1276Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1921Unlike C<ev_timer>, periodic watchers are not based on real time (or
1277but on wallclock time (absolute time). You can tell a periodic watcher 1922relative time, the physical time that passes) but on wall clock time
1278to trigger after some specific point in time. For example, if you tell a 1923(absolute time, the thing you can read on your calender or clock). The
1279periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now () 1924difference is that wall clock time can run faster or slower than real
1280+ 10.>, that is, an absolute time not a delay) and then reset your system 1925time, and time jumps are not uncommon (e.g. when you adjust your
1281clock to january of the previous year, then it will take more than year 1926wrist-watch).
1282to trigger the event (unlike an C<ev_timer>, which would still trigger
1283roughly 10 seconds later as it uses a relative timeout).
1284 1927
1928You can tell a periodic watcher to trigger after some specific point
1929in time: for example, if you tell a periodic watcher to trigger "in 10
1930seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1931not a delay) and then reset your system clock to January of the previous
1932year, then it will take a year or more to trigger the event (unlike an
1933C<ev_timer>, which would still trigger roughly 10 seconds after starting
1934it, as it uses a relative timeout).
1935
1285C<ev_periodic>s can also be used to implement vastly more complex timers, 1936C<ev_periodic> watchers can also be used to implement vastly more complex
1286such as triggering an event on each "midnight, local time", or other 1937timers, such as triggering an event on each "midnight, local time", or
1287complicated, rules. 1938other complicated rules. This cannot be done with C<ev_timer> watchers, as
1939those cannot react to time jumps.
1288 1940
1289As with timers, the callback is guarenteed to be invoked only when the 1941As with timers, the callback is guaranteed to be invoked only when the
1290time (C<at>) has passed, but if multiple periodic timers become ready 1942point in time where it is supposed to trigger has passed. If multiple
1291during the same loop iteration then order of execution is undefined. 1943timers become ready during the same loop iteration then the ones with
1944earlier time-out values are invoked before ones with later time-out values
1945(but this is no longer true when a callback calls C<ev_loop> recursively).
1292 1946
1293=head3 Watcher-Specific Functions and Data Members 1947=head3 Watcher-Specific Functions and Data Members
1294 1948
1295=over 4 1949=over 4
1296 1950
1297=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1951=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1298 1952
1299=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1953=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1300 1954
1301Lots of arguments, lets sort it out... There are basically three modes of 1955Lots of arguments, let's sort it out... There are basically three modes of
1302operation, and we will explain them from simplest to complex: 1956operation, and we will explain them from simplest to most complex:
1303 1957
1304=over 4 1958=over 4
1305 1959
1306=item * absolute timer (at = time, interval = reschedule_cb = 0) 1960=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1307 1961
1308In this configuration the watcher triggers an event after the wallclock 1962In this configuration the watcher triggers an event after the wall clock
1309time C<at> has passed and doesn't repeat. It will not adjust when a time 1963time C<offset> has passed. It will not repeat and will not adjust when a
1310jump occurs, that is, if it is to be run at January 1st 2011 then it will 1964time jump occurs, that is, if it is to be run at January 1st 2011 then it
1311run when the system time reaches or surpasses this time. 1965will be stopped and invoked when the system clock reaches or surpasses
1966this point in time.
1312 1967
1313=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1968=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1314 1969
1315In this mode the watcher will always be scheduled to time out at the next 1970In this mode the watcher will always be scheduled to time out at the next
1316C<at + N * interval> time (for some integer N, which can also be negative) 1971C<offset + N * interval> time (for some integer N, which can also be
1317and then repeat, regardless of any time jumps. 1972negative) and then repeat, regardless of any time jumps. The C<offset>
1973argument is merely an offset into the C<interval> periods.
1318 1974
1319This can be used to create timers that do not drift with respect to system 1975This can be used to create timers that do not drift with respect to the
1320time, for example, here is a C<ev_periodic> that triggers each hour, on 1976system clock, for example, here is an C<ev_periodic> that triggers each
1321the hour: 1977hour, on the hour (with respect to UTC):
1322 1978
1323 ev_periodic_set (&periodic, 0., 3600., 0); 1979 ev_periodic_set (&periodic, 0., 3600., 0);
1324 1980
1325This doesn't mean there will always be 3600 seconds in between triggers, 1981This doesn't mean there will always be 3600 seconds in between triggers,
1326but only that the the callback will be called when the system time shows a 1982but only that the callback will be called when the system time shows a
1327full hour (UTC), or more correctly, when the system time is evenly divisible 1983full hour (UTC), or more correctly, when the system time is evenly divisible
1328by 3600. 1984by 3600.
1329 1985
1330Another way to think about it (for the mathematically inclined) is that 1986Another way to think about it (for the mathematically inclined) is that
1331C<ev_periodic> will try to run the callback in this mode at the next possible 1987C<ev_periodic> will try to run the callback in this mode at the next possible
1332time where C<time = at (mod interval)>, regardless of any time jumps. 1988time where C<time = offset (mod interval)>, regardless of any time jumps.
1333 1989
1334For numerical stability it is preferable that the C<at> value is near 1990For numerical stability it is preferable that the C<offset> value is near
1335C<ev_now ()> (the current time), but there is no range requirement for 1991C<ev_now ()> (the current time), but there is no range requirement for
1336this value, and in fact is often specified as zero. 1992this value, and in fact is often specified as zero.
1337 1993
1338Note also that there is an upper limit to how often a timer can fire (cpu 1994Note also that there is an upper limit to how often a timer can fire (CPU
1339speed for example), so if C<interval> is very small then timing stability 1995speed for example), so if C<interval> is very small then timing stability
1340will of course detoriate. Libev itself tries to be exact to be about one 1996will of course deteriorate. Libev itself tries to be exact to be about one
1341millisecond (if the OS supports it and the machine is fast enough). 1997millisecond (if the OS supports it and the machine is fast enough).
1342 1998
1343=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1999=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1344 2000
1345In this mode the values for C<interval> and C<at> are both being 2001In this mode the values for C<interval> and C<offset> are both being
1346ignored. Instead, each time the periodic watcher gets scheduled, the 2002ignored. Instead, each time the periodic watcher gets scheduled, the
1347reschedule callback will be called with the watcher as first, and the 2003reschedule callback will be called with the watcher as first, and the
1348current time as second argument. 2004current time as second argument.
1349 2005
1350NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 2006NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1351ever, or make ANY event loop modifications whatsoever>. 2007or make ANY other event loop modifications whatsoever, unless explicitly
2008allowed by documentation here>.
1352 2009
1353If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 2010If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1354it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 2011it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1355only event loop modification you are allowed to do). 2012only event loop modification you are allowed to do).
1356 2013
1357The callback prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic 2014The callback prototype is C<ev_tstamp (*reschedule_cb)(ev_periodic
1358*w, ev_tstamp now)>, e.g.: 2015*w, ev_tstamp now)>, e.g.:
1359 2016
2017 static ev_tstamp
1360 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 2018 my_rescheduler (ev_periodic *w, ev_tstamp now)
1361 { 2019 {
1362 return now + 60.; 2020 return now + 60.;
1363 } 2021 }
1364 2022
1365It must return the next time to trigger, based on the passed time value 2023It must return the next time to trigger, based on the passed time value
1385a different time than the last time it was called (e.g. in a crond like 2043a different time than the last time it was called (e.g. in a crond like
1386program when the crontabs have changed). 2044program when the crontabs have changed).
1387 2045
1388=item ev_tstamp ev_periodic_at (ev_periodic *) 2046=item ev_tstamp ev_periodic_at (ev_periodic *)
1389 2047
1390When active, returns the absolute time that the watcher is supposed to 2048When active, returns the absolute time that the watcher is supposed
1391trigger next. 2049to trigger next. This is not the same as the C<offset> argument to
2050C<ev_periodic_set>, but indeed works even in interval and manual
2051rescheduling modes.
1392 2052
1393=item ev_tstamp offset [read-write] 2053=item ev_tstamp offset [read-write]
1394 2054
1395When repeating, this contains the offset value, otherwise this is the 2055When repeating, this contains the offset value, otherwise this is the
1396absolute point in time (the C<at> value passed to C<ev_periodic_set>). 2056absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
2057although libev might modify this value for better numerical stability).
1397 2058
1398Can be modified any time, but changes only take effect when the periodic 2059Can be modified any time, but changes only take effect when the periodic
1399timer fires or C<ev_periodic_again> is being called. 2060timer fires or C<ev_periodic_again> is being called.
1400 2061
1401=item ev_tstamp interval [read-write] 2062=item ev_tstamp interval [read-write]
1402 2063
1403The current interval value. Can be modified any time, but changes only 2064The current interval value. Can be modified any time, but changes only
1404take effect when the periodic timer fires or C<ev_periodic_again> is being 2065take effect when the periodic timer fires or C<ev_periodic_again> is being
1405called. 2066called.
1406 2067
1407=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 2068=item ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]
1408 2069
1409The current reschedule callback, or C<0>, if this functionality is 2070The current reschedule callback, or C<0>, if this functionality is
1410switched off. Can be changed any time, but changes only take effect when 2071switched off. Can be changed any time, but changes only take effect when
1411the periodic timer fires or C<ev_periodic_again> is being called. 2072the periodic timer fires or C<ev_periodic_again> is being called.
1412 2073
1413=back 2074=back
1414 2075
1415=head3 Examples 2076=head3 Examples
1416 2077
1417Example: Call a callback every hour, or, more precisely, whenever the 2078Example: Call a callback every hour, or, more precisely, whenever the
1418system clock is divisible by 3600. The callback invocation times have 2079system time is divisible by 3600. The callback invocation times have
1419potentially a lot of jittering, but good long-term stability. 2080potentially a lot of jitter, but good long-term stability.
1420 2081
1421 static void 2082 static void
1422 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 2083 clock_cb (struct ev_loop *loop, ev_io *w, int revents)
1423 { 2084 {
1424 ... its now a full hour (UTC, or TAI or whatever your clock follows) 2085 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1425 } 2086 }
1426 2087
1427 struct ev_periodic hourly_tick; 2088 ev_periodic hourly_tick;
1428 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 2089 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1429 ev_periodic_start (loop, &hourly_tick); 2090 ev_periodic_start (loop, &hourly_tick);
1430 2091
1431Example: The same as above, but use a reschedule callback to do it: 2092Example: The same as above, but use a reschedule callback to do it:
1432 2093
1433 #include <math.h> 2094 #include <math.h>
1434 2095
1435 static ev_tstamp 2096 static ev_tstamp
1436 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 2097 my_scheduler_cb (ev_periodic *w, ev_tstamp now)
1437 { 2098 {
1438 return fmod (now, 3600.) + 3600.; 2099 return now + (3600. - fmod (now, 3600.));
1439 } 2100 }
1440 2101
1441 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 2102 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1442 2103
1443Example: Call a callback every hour, starting now: 2104Example: Call a callback every hour, starting now:
1444 2105
1445 struct ev_periodic hourly_tick; 2106 ev_periodic hourly_tick;
1446 ev_periodic_init (&hourly_tick, clock_cb, 2107 ev_periodic_init (&hourly_tick, clock_cb,
1447 fmod (ev_now (loop), 3600.), 3600., 0); 2108 fmod (ev_now (loop), 3600.), 3600., 0);
1448 ev_periodic_start (loop, &hourly_tick); 2109 ev_periodic_start (loop, &hourly_tick);
1449 2110
1450 2111
1451=head2 C<ev_signal> - signal me when a signal gets signalled! 2112=head2 C<ev_signal> - signal me when a signal gets signalled!
1452 2113
1453Signal watchers will trigger an event when the process receives a specific 2114Signal watchers will trigger an event when the process receives a specific
1454signal one or more times. Even though signals are very asynchronous, libev 2115signal one or more times. Even though signals are very asynchronous, libev
1455will try it's best to deliver signals synchronously, i.e. as part of the 2116will try it's best to deliver signals synchronously, i.e. as part of the
1456normal event processing, like any other event. 2117normal event processing, like any other event.
1457 2118
2119If you want signals to be delivered truly asynchronously, just use
2120C<sigaction> as you would do without libev and forget about sharing
2121the signal. You can even use C<ev_async> from a signal handler to
2122synchronously wake up an event loop.
2123
1458You can configure as many watchers as you like per signal. Only when the 2124You can configure as many watchers as you like for the same signal, but
2125only within the same loop, i.e. you can watch for C<SIGINT> in your
2126default loop and for C<SIGIO> in another loop, but you cannot watch for
2127C<SIGINT> in both the default loop and another loop at the same time. At
2128the moment, C<SIGCHLD> is permanently tied to the default loop.
2129
1459first watcher gets started will libev actually register a signal watcher 2130When the first watcher gets started will libev actually register something
1460with the kernel (thus it coexists with your own signal handlers as long 2131with the kernel (thus it coexists with your own signal handlers as long as
1461as you don't register any with libev). Similarly, when the last signal 2132you don't register any with libev for the same signal).
1462watcher for a signal is stopped libev will reset the signal handler to
1463SIG_DFL (regardless of what it was set to before).
1464 2133
1465If possible and supported, libev will install its handlers with 2134If possible and supported, libev will install its handlers with
1466C<SA_RESTART> behaviour enabled, so syscalls should not be unduly 2135C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1467interrupted. If you have a problem with syscalls getting interrupted by 2136not be unduly interrupted. If you have a problem with system calls getting
1468signals you can block all signals in an C<ev_check> watcher and unblock 2137interrupted by signals you can block all signals in an C<ev_check> watcher
1469them in an C<ev_prepare> watcher. 2138and unblock them in an C<ev_prepare> watcher.
2139
2140=head3 The special problem of inheritance over fork/execve/pthread_create
2141
2142Both the signal mask (C<sigprocmask>) and the signal disposition
2143(C<sigaction>) are unspecified after starting a signal watcher (and after
2144stopping it again), that is, libev might or might not block the signal,
2145and might or might not set or restore the installed signal handler.
2146
2147While this does not matter for the signal disposition (libev never
2148sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2149C<execve>), this matters for the signal mask: many programs do not expect
2150certain signals to be blocked.
2151
2152This means that before calling C<exec> (from the child) you should reset
2153the signal mask to whatever "default" you expect (all clear is a good
2154choice usually).
2155
2156The simplest way to ensure that the signal mask is reset in the child is
2157to install a fork handler with C<pthread_atfork> that resets it. That will
2158catch fork calls done by libraries (such as the libc) as well.
2159
2160In current versions of libev, the signal will not be blocked indefinitely
2161unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2162the window of opportunity for problems, it will not go away, as libev
2163I<has> to modify the signal mask, at least temporarily.
2164
2165So I can't stress this enough I<if you do not reset your signal mask
2166when you expect it to be empty, you have a race condition in your
2167program>. This is not a libev-specific thing, this is true for most event
2168libraries.
1470 2169
1471=head3 Watcher-Specific Functions and Data Members 2170=head3 Watcher-Specific Functions and Data Members
1472 2171
1473=over 4 2172=over 4
1474 2173
1485 2184
1486=back 2185=back
1487 2186
1488=head3 Examples 2187=head3 Examples
1489 2188
1490Example: Try to exit cleanly on SIGINT and SIGTERM. 2189Example: Try to exit cleanly on SIGINT.
1491 2190
1492 static void 2191 static void
1493 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 2192 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1494 { 2193 {
1495 ev_unloop (loop, EVUNLOOP_ALL); 2194 ev_unloop (loop, EVUNLOOP_ALL);
1496 } 2195 }
1497 2196
1498 struct ev_signal signal_watcher; 2197 ev_signal signal_watcher;
1499 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 2198 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1500 ev_signal_start (loop, &sigint_cb); 2199 ev_signal_start (loop, &signal_watcher);
1501 2200
1502 2201
1503=head2 C<ev_child> - watch out for process status changes 2202=head2 C<ev_child> - watch out for process status changes
1504 2203
1505Child watchers trigger when your process receives a SIGCHLD in response to 2204Child watchers trigger when your process receives a SIGCHLD in response to
1506some child status changes (most typically when a child of yours dies). It 2205some child status changes (most typically when a child of yours dies or
1507is permissible to install a child watcher I<after> the child has been 2206exits). It is permissible to install a child watcher I<after> the child
1508forked (which implies it might have already exited), as long as the event 2207has been forked (which implies it might have already exited), as long
1509loop isn't entered (or is continued from a watcher). 2208as the event loop isn't entered (or is continued from a watcher), i.e.,
2209forking and then immediately registering a watcher for the child is fine,
2210but forking and registering a watcher a few event loop iterations later or
2211in the next callback invocation is not.
1510 2212
1511Only the default event loop is capable of handling signals, and therefore 2213Only the default event loop is capable of handling signals, and therefore
1512you can only rgeister child watchers in the default event loop. 2214you can only register child watchers in the default event loop.
2215
2216Due to some design glitches inside libev, child watchers will always be
2217handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2218libev)
1513 2219
1514=head3 Process Interaction 2220=head3 Process Interaction
1515 2221
1516Libev grabs C<SIGCHLD> as soon as the default event loop is 2222Libev grabs C<SIGCHLD> as soon as the default event loop is
1517initialised. This is necessary to guarantee proper behaviour even if 2223initialised. This is necessary to guarantee proper behaviour even if the
1518the first child watcher is started after the child exits. The occurance 2224first child watcher is started after the child exits. The occurrence
1519of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2225of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1520synchronously as part of the event loop processing. Libev always reaps all 2226synchronously as part of the event loop processing. Libev always reaps all
1521children, even ones not watched. 2227children, even ones not watched.
1522 2228
1523=head3 Overriding the Built-In Processing 2229=head3 Overriding the Built-In Processing
1527handler, you can override it easily by installing your own handler for 2233handler, you can override it easily by installing your own handler for
1528C<SIGCHLD> after initialising the default loop, and making sure the 2234C<SIGCHLD> after initialising the default loop, and making sure the
1529default loop never gets destroyed. You are encouraged, however, to use an 2235default loop never gets destroyed. You are encouraged, however, to use an
1530event-based approach to child reaping and thus use libev's support for 2236event-based approach to child reaping and thus use libev's support for
1531that, so other libev users can use C<ev_child> watchers freely. 2237that, so other libev users can use C<ev_child> watchers freely.
2238
2239=head3 Stopping the Child Watcher
2240
2241Currently, the child watcher never gets stopped, even when the
2242child terminates, so normally one needs to stop the watcher in the
2243callback. Future versions of libev might stop the watcher automatically
2244when a child exit is detected (calling C<ev_child_stop> twice is not a
2245problem).
1532 2246
1533=head3 Watcher-Specific Functions and Data Members 2247=head3 Watcher-Specific Functions and Data Members
1534 2248
1535=over 4 2249=over 4
1536 2250
1565=head3 Examples 2279=head3 Examples
1566 2280
1567Example: C<fork()> a new process and install a child handler to wait for 2281Example: C<fork()> a new process and install a child handler to wait for
1568its completion. 2282its completion.
1569 2283
1570 ev_child cw; 2284 ev_child cw;
1571 2285
1572 static void 2286 static void
1573 child_cb (EV_P_ struct ev_child *w, int revents) 2287 child_cb (EV_P_ ev_child *w, int revents)
1574 { 2288 {
1575 ev_child_stop (EV_A_ w); 2289 ev_child_stop (EV_A_ w);
1576 printf ("process %d exited with status %x\n", w->rpid, w->rstatus); 2290 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1577 } 2291 }
1578 2292
1579 pid_t pid = fork (); 2293 pid_t pid = fork ();
1580 2294
1581 if (pid < 0) 2295 if (pid < 0)
1582 // error 2296 // error
1583 else if (pid == 0) 2297 else if (pid == 0)
1584 { 2298 {
1585 // the forked child executes here 2299 // the forked child executes here
1586 exit (1); 2300 exit (1);
1587 } 2301 }
1588 else 2302 else
1589 { 2303 {
1590 ev_child_init (&cw, child_cb, pid, 0); 2304 ev_child_init (&cw, child_cb, pid, 0);
1591 ev_child_start (EV_DEFAULT_ &cw); 2305 ev_child_start (EV_DEFAULT_ &cw);
1592 } 2306 }
1593 2307
1594 2308
1595=head2 C<ev_stat> - did the file attributes just change? 2309=head2 C<ev_stat> - did the file attributes just change?
1596 2310
1597This watches a filesystem path for attribute changes. That is, it calls 2311This watches a file system path for attribute changes. That is, it calls
1598C<stat> regularly (or when the OS says it changed) and sees if it changed 2312C<stat> on that path in regular intervals (or when the OS says it changed)
1599compared to the last time, invoking the callback if it did. 2313and sees if it changed compared to the last time, invoking the callback if
2314it did.
1600 2315
1601The path does not need to exist: changing from "path exists" to "path does 2316The path does not need to exist: changing from "path exists" to "path does
1602not exist" is a status change like any other. The condition "path does 2317not exist" is a status change like any other. The condition "path does not
1603not exist" is signified by the C<st_nlink> field being zero (which is 2318exist" (or more correctly "path cannot be stat'ed") is signified by the
1604otherwise always forced to be at least one) and all the other fields of 2319C<st_nlink> field being zero (which is otherwise always forced to be at
1605the stat buffer having unspecified contents. 2320least one) and all the other fields of the stat buffer having unspecified
2321contents.
1606 2322
1607The path I<should> be absolute and I<must not> end in a slash. If it is 2323The path I<must not> end in a slash or contain special components such as
2324C<.> or C<..>. The path I<should> be absolute: If it is relative and
1608relative and your working directory changes, the behaviour is undefined. 2325your working directory changes, then the behaviour is undefined.
1609 2326
1610Since there is no standard to do this, the portable implementation simply 2327Since there is no portable change notification interface available, the
1611calls C<stat (2)> regularly on the path to see if it changed somehow. You 2328portable implementation simply calls C<stat(2)> regularly on the path
1612can specify a recommended polling interval for this case. If you specify 2329to see if it changed somehow. You can specify a recommended polling
1613a polling interval of C<0> (highly recommended!) then a I<suitable, 2330interval for this case. If you specify a polling interval of C<0> (highly
1614unspecified default> value will be used (which you can expect to be around 2331recommended!) then a I<suitable, unspecified default> value will be used
1615five seconds, although this might change dynamically). Libev will also 2332(which you can expect to be around five seconds, although this might
1616impose a minimum interval which is currently around C<0.1>, but thats 2333change dynamically). Libev will also impose a minimum interval which is
1617usually overkill. 2334currently around C<0.1>, but that's usually overkill.
1618 2335
1619This watcher type is not meant for massive numbers of stat watchers, 2336This watcher type is not meant for massive numbers of stat watchers,
1620as even with OS-supported change notifications, this can be 2337as even with OS-supported change notifications, this can be
1621resource-intensive. 2338resource-intensive.
1622 2339
1623At the time of this writing, only the Linux inotify interface is 2340At the time of this writing, the only OS-specific interface implemented
1624implemented (implementing kqueue support is left as an exercise for the 2341is the Linux inotify interface (implementing kqueue support is left as an
1625reader, note, however, that the author sees no way of implementing ev_stat 2342exercise for the reader. Note, however, that the author sees no way of
1626semantics with kqueue). Inotify will be used to give hints only and should 2343implementing C<ev_stat> semantics with kqueue, except as a hint).
1627not change the semantics of C<ev_stat> watchers, which means that libev
1628sometimes needs to fall back to regular polling again even with inotify,
1629but changes are usually detected immediately, and if the file exists there
1630will be no polling.
1631 2344
1632=head3 ABI Issues (Largefile Support) 2345=head3 ABI Issues (Largefile Support)
1633 2346
1634Libev by default (unless the user overrides this) uses the default 2347Libev by default (unless the user overrides this) uses the default
1635compilation environment, which means that on systems with optionally 2348compilation environment, which means that on systems with large file
1636disabled large file support, you get the 32 bit version of the stat 2349support disabled by default, you get the 32 bit version of the stat
1637structure. When using the library from programs that change the ABI to 2350structure. When using the library from programs that change the ABI to
1638use 64 bit file offsets the programs will fail. In that case you have to 2351use 64 bit file offsets the programs will fail. In that case you have to
1639compile libev with the same flags to get binary compatibility. This is 2352compile libev with the same flags to get binary compatibility. This is
1640obviously the case with any flags that change the ABI, but the problem is 2353obviously the case with any flags that change the ABI, but the problem is
1641most noticably with ev_stat and largefile support. 2354most noticeably displayed with ev_stat and large file support.
1642 2355
1643=head3 Inotify 2356The solution for this is to lobby your distribution maker to make large
2357file interfaces available by default (as e.g. FreeBSD does) and not
2358optional. Libev cannot simply switch on large file support because it has
2359to exchange stat structures with application programs compiled using the
2360default compilation environment.
1644 2361
2362=head3 Inotify and Kqueue
2363
1645When C<inotify (7)> support has been compiled into libev (generally only 2364When C<inotify (7)> support has been compiled into libev and present at
1646available on Linux) and present at runtime, it will be used to speed up 2365runtime, it will be used to speed up change detection where possible. The
1647change detection where possible. The inotify descriptor will be created lazily 2366inotify descriptor will be created lazily when the first C<ev_stat>
1648when the first C<ev_stat> watcher is being started. 2367watcher is being started.
1649 2368
1650Inotify presence does not change the semantics of C<ev_stat> watchers 2369Inotify presence does not change the semantics of C<ev_stat> watchers
1651except that changes might be detected earlier, and in some cases, to avoid 2370except that changes might be detected earlier, and in some cases, to avoid
1652making regular C<stat> calls. Even in the presence of inotify support 2371making regular C<stat> calls. Even in the presence of inotify support
1653there are many cases where libev has to resort to regular C<stat> polling. 2372there are many cases where libev has to resort to regular C<stat> polling,
2373but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
2374many bugs), the path exists (i.e. stat succeeds), and the path resides on
2375a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2376xfs are fully working) libev usually gets away without polling.
1654 2377
1655(There is no support for kqueue, as apparently it cannot be used to 2378There is no support for kqueue, as apparently it cannot be used to
1656implement this functionality, due to the requirement of having a file 2379implement this functionality, due to the requirement of having a file
1657descriptor open on the object at all times). 2380descriptor open on the object at all times, and detecting renames, unlinks
2381etc. is difficult.
2382
2383=head3 C<stat ()> is a synchronous operation
2384
2385Libev doesn't normally do any kind of I/O itself, and so is not blocking
2386the process. The exception are C<ev_stat> watchers - those call C<stat
2387()>, which is a synchronous operation.
2388
2389For local paths, this usually doesn't matter: unless the system is very
2390busy or the intervals between stat's are large, a stat call will be fast,
2391as the path data is usually in memory already (except when starting the
2392watcher).
2393
2394For networked file systems, calling C<stat ()> can block an indefinite
2395time due to network issues, and even under good conditions, a stat call
2396often takes multiple milliseconds.
2397
2398Therefore, it is best to avoid using C<ev_stat> watchers on networked
2399paths, although this is fully supported by libev.
1658 2400
1659=head3 The special problem of stat time resolution 2401=head3 The special problem of stat time resolution
1660 2402
1661The C<stat ()> syscall only supports full-second resolution portably, and 2403The C<stat ()> system call only supports full-second resolution portably,
1662even on systems where the resolution is higher, many filesystems still 2404and even on systems where the resolution is higher, most file systems
1663only support whole seconds. 2405still only support whole seconds.
1664 2406
1665That means that, if the time is the only thing that changes, you can 2407That means that, if the time is the only thing that changes, you can
1666easily miss updates: on the first update, C<ev_stat> detects a change and 2408easily miss updates: on the first update, C<ev_stat> detects a change and
1667calls your callback, which does something. When there is another update 2409calls your callback, which does something. When there is another update
1668within the same second, C<ev_stat> will be unable to detect it as the stat 2410within the same second, C<ev_stat> will be unable to detect unless the
1669data does not change. 2411stat data does change in other ways (e.g. file size).
1670 2412
1671The solution to this is to delay acting on a change for slightly more 2413The solution to this is to delay acting on a change for slightly more
1672than a second (or till slightly after the next full second boundary), using 2414than a second (or till slightly after the next full second boundary), using
1673a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02); 2415a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
1674ev_timer_again (loop, w)>). 2416ev_timer_again (loop, w)>).
1694C<path>. The C<interval> is a hint on how quickly a change is expected to 2436C<path>. The C<interval> is a hint on how quickly a change is expected to
1695be detected and should normally be specified as C<0> to let libev choose 2437be detected and should normally be specified as C<0> to let libev choose
1696a suitable value. The memory pointed to by C<path> must point to the same 2438a suitable value. The memory pointed to by C<path> must point to the same
1697path for as long as the watcher is active. 2439path for as long as the watcher is active.
1698 2440
1699The callback will receive C<EV_STAT> when a change was detected, relative 2441The callback will receive an C<EV_STAT> event when a change was detected,
1700to the attributes at the time the watcher was started (or the last change 2442relative to the attributes at the time the watcher was started (or the
1701was detected). 2443last change was detected).
1702 2444
1703=item ev_stat_stat (loop, ev_stat *) 2445=item ev_stat_stat (loop, ev_stat *)
1704 2446
1705Updates the stat buffer immediately with new values. If you change the 2447Updates the stat buffer immediately with new values. If you change the
1706watched path in your callback, you could call this function to avoid 2448watched path in your callback, you could call this function to avoid
1727 2469
1728The specified interval. 2470The specified interval.
1729 2471
1730=item const char *path [read-only] 2472=item const char *path [read-only]
1731 2473
1732The filesystem path that is being watched. 2474The file system path that is being watched.
1733 2475
1734=back 2476=back
1735 2477
1736=head3 Examples 2478=head3 Examples
1737 2479
1738Example: Watch C</etc/passwd> for attribute changes. 2480Example: Watch C</etc/passwd> for attribute changes.
1739 2481
1740 static void 2482 static void
1741 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 2483 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1742 { 2484 {
1743 /* /etc/passwd changed in some way */ 2485 /* /etc/passwd changed in some way */
1744 if (w->attr.st_nlink) 2486 if (w->attr.st_nlink)
1745 { 2487 {
1746 printf ("passwd current size %ld\n", (long)w->attr.st_size); 2488 printf ("passwd current size %ld\n", (long)w->attr.st_size);
1747 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime); 2489 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
1748 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime); 2490 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
1749 } 2491 }
1750 else 2492 else
1751 /* you shalt not abuse printf for puts */ 2493 /* you shalt not abuse printf for puts */
1752 puts ("wow, /etc/passwd is not there, expect problems. " 2494 puts ("wow, /etc/passwd is not there, expect problems. "
1753 "if this is windows, they already arrived\n"); 2495 "if this is windows, they already arrived\n");
1754 } 2496 }
1755 2497
1756 ... 2498 ...
1757 ev_stat passwd; 2499 ev_stat passwd;
1758 2500
1759 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); 2501 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1760 ev_stat_start (loop, &passwd); 2502 ev_stat_start (loop, &passwd);
1761 2503
1762Example: Like above, but additionally use a one-second delay so we do not 2504Example: Like above, but additionally use a one-second delay so we do not
1763miss updates (however, frequent updates will delay processing, too, so 2505miss updates (however, frequent updates will delay processing, too, so
1764one might do the work both on C<ev_stat> callback invocation I<and> on 2506one might do the work both on C<ev_stat> callback invocation I<and> on
1765C<ev_timer> callback invocation). 2507C<ev_timer> callback invocation).
1766 2508
1767 static ev_stat passwd; 2509 static ev_stat passwd;
1768 static ev_timer timer; 2510 static ev_timer timer;
1769 2511
1770 static void 2512 static void
1771 timer_cb (EV_P_ ev_timer *w, int revents) 2513 timer_cb (EV_P_ ev_timer *w, int revents)
1772 { 2514 {
1773 ev_timer_stop (EV_A_ w); 2515 ev_timer_stop (EV_A_ w);
1774 2516
1775 /* now it's one second after the most recent passwd change */ 2517 /* now it's one second after the most recent passwd change */
1776 } 2518 }
1777 2519
1778 static void 2520 static void
1779 stat_cb (EV_P_ ev_stat *w, int revents) 2521 stat_cb (EV_P_ ev_stat *w, int revents)
1780 { 2522 {
1781 /* reset the one-second timer */ 2523 /* reset the one-second timer */
1782 ev_timer_again (EV_A_ &timer); 2524 ev_timer_again (EV_A_ &timer);
1783 } 2525 }
1784 2526
1785 ... 2527 ...
1786 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 2528 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1787 ev_stat_start (loop, &passwd); 2529 ev_stat_start (loop, &passwd);
1788 ev_timer_init (&timer, timer_cb, 0., 1.02); 2530 ev_timer_init (&timer, timer_cb, 0., 1.02);
1789 2531
1790 2532
1791=head2 C<ev_idle> - when you've got nothing better to do... 2533=head2 C<ev_idle> - when you've got nothing better to do...
1792 2534
1793Idle watchers trigger events when no other events of the same or higher 2535Idle watchers trigger events when no other events of the same or higher
1794priority are pending (prepare, check and other idle watchers do not 2536priority are pending (prepare, check and other idle watchers do not count
1795count). 2537as receiving "events").
1796 2538
1797That is, as long as your process is busy handling sockets or timeouts 2539That is, as long as your process is busy handling sockets or timeouts
1798(or even signals, imagine) of the same or higher priority it will not be 2540(or even signals, imagine) of the same or higher priority it will not be
1799triggered. But when your process is idle (or only lower-priority watchers 2541triggered. But when your process is idle (or only lower-priority watchers
1800are pending), the idle watchers are being called once per event loop 2542are pending), the idle watchers are being called once per event loop
1811 2553
1812=head3 Watcher-Specific Functions and Data Members 2554=head3 Watcher-Specific Functions and Data Members
1813 2555
1814=over 4 2556=over 4
1815 2557
1816=item ev_idle_init (ev_signal *, callback) 2558=item ev_idle_init (ev_idle *, callback)
1817 2559
1818Initialises and configures the idle watcher - it has no parameters of any 2560Initialises and configures the idle watcher - it has no parameters of any
1819kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2561kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
1820believe me. 2562believe me.
1821 2563
1824=head3 Examples 2566=head3 Examples
1825 2567
1826Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the 2568Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1827callback, free it. Also, use no error checking, as usual. 2569callback, free it. Also, use no error checking, as usual.
1828 2570
1829 static void 2571 static void
1830 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 2572 idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
1831 { 2573 {
1832 free (w); 2574 free (w);
1833 // now do something you wanted to do when the program has 2575 // now do something you wanted to do when the program has
1834 // no longer anything immediate to do. 2576 // no longer anything immediate to do.
1835 } 2577 }
1836 2578
1837 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 2579 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
1838 ev_idle_init (idle_watcher, idle_cb); 2580 ev_idle_init (idle_watcher, idle_cb);
1839 ev_idle_start (loop, idle_cb); 2581 ev_idle_start (loop, idle_watcher);
1840 2582
1841 2583
1842=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2584=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1843 2585
1844Prepare and check watchers are usually (but not always) used in tandem: 2586Prepare and check watchers are usually (but not always) used in pairs:
1845prepare watchers get invoked before the process blocks and check watchers 2587prepare watchers get invoked before the process blocks and check watchers
1846afterwards. 2588afterwards.
1847 2589
1848You I<must not> call C<ev_loop> or similar functions that enter 2590You I<must not> call C<ev_loop> or similar functions that enter
1849the current event loop from either C<ev_prepare> or C<ev_check> 2591the current event loop from either C<ev_prepare> or C<ev_check>
1852those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2594those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1853C<ev_check> so if you have one watcher of each kind they will always be 2595C<ev_check> so if you have one watcher of each kind they will always be
1854called in pairs bracketing the blocking call. 2596called in pairs bracketing the blocking call.
1855 2597
1856Their main purpose is to integrate other event mechanisms into libev and 2598Their main purpose is to integrate other event mechanisms into libev and
1857their use is somewhat advanced. This could be used, for example, to track 2599their use is somewhat advanced. They could be used, for example, to track
1858variable changes, implement your own watchers, integrate net-snmp or a 2600variable changes, implement your own watchers, integrate net-snmp or a
1859coroutine library and lots more. They are also occasionally useful if 2601coroutine library and lots more. They are also occasionally useful if
1860you cache some data and want to flush it before blocking (for example, 2602you cache some data and want to flush it before blocking (for example,
1861in X programs you might want to do an C<XFlush ()> in an C<ev_prepare> 2603in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1862watcher). 2604watcher).
1863 2605
1864This is done by examining in each prepare call which file descriptors need 2606This is done by examining in each prepare call which file descriptors
1865to be watched by the other library, registering C<ev_io> watchers for 2607need to be watched by the other library, registering C<ev_io> watchers
1866them and starting an C<ev_timer> watcher for any timeouts (many libraries 2608for them and starting an C<ev_timer> watcher for any timeouts (many
1867provide just this functionality). Then, in the check watcher you check for 2609libraries provide exactly this functionality). Then, in the check watcher,
1868any events that occured (by checking the pending status of all watchers 2610you check for any events that occurred (by checking the pending status
1869and stopping them) and call back into the library. The I/O and timer 2611of all watchers and stopping them) and call back into the library. The
1870callbacks will never actually be called (but must be valid nevertheless, 2612I/O and timer callbacks will never actually be called (but must be valid
1871because you never know, you know?). 2613nevertheless, because you never know, you know?).
1872 2614
1873As another example, the Perl Coro module uses these hooks to integrate 2615As another example, the Perl Coro module uses these hooks to integrate
1874coroutines into libev programs, by yielding to other active coroutines 2616coroutines into libev programs, by yielding to other active coroutines
1875during each prepare and only letting the process block if no coroutines 2617during each prepare and only letting the process block if no coroutines
1876are ready to run (it's actually more complicated: it only runs coroutines 2618are ready to run (it's actually more complicated: it only runs coroutines
1879loop from blocking if lower-priority coroutines are active, thus mapping 2621loop from blocking if lower-priority coroutines are active, thus mapping
1880low-priority coroutines to idle/background tasks). 2622low-priority coroutines to idle/background tasks).
1881 2623
1882It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 2624It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1883priority, to ensure that they are being run before any other watchers 2625priority, to ensure that they are being run before any other watchers
2626after the poll (this doesn't matter for C<ev_prepare> watchers).
2627
1884after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers, 2628Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
1885too) should not activate ("feed") events into libev. While libev fully 2629activate ("feed") events into libev. While libev fully supports this, they
1886supports this, they might get executed before other C<ev_check> watchers 2630might get executed before other C<ev_check> watchers did their job. As
1887did their job. As C<ev_check> watchers are often used to embed other 2631C<ev_check> watchers are often used to embed other (non-libev) event
1888(non-libev) event loops those other event loops might be in an unusable 2632loops those other event loops might be in an unusable state until their
1889state until their C<ev_check> watcher ran (always remind yourself to 2633C<ev_check> watcher ran (always remind yourself to coexist peacefully with
1890coexist peacefully with others). 2634others).
1891 2635
1892=head3 Watcher-Specific Functions and Data Members 2636=head3 Watcher-Specific Functions and Data Members
1893 2637
1894=over 4 2638=over 4
1895 2639
1897 2641
1898=item ev_check_init (ev_check *, callback) 2642=item ev_check_init (ev_check *, callback)
1899 2643
1900Initialises and configures the prepare or check watcher - they have no 2644Initialises and configures the prepare or check watcher - they have no
1901parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 2645parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1902macros, but using them is utterly, utterly and completely pointless. 2646macros, but using them is utterly, utterly, utterly and completely
2647pointless.
1903 2648
1904=back 2649=back
1905 2650
1906=head3 Examples 2651=head3 Examples
1907 2652
1916and in a check watcher, destroy them and call into libadns. What follows 2661and in a check watcher, destroy them and call into libadns. What follows
1917is pseudo-code only of course. This requires you to either use a low 2662is pseudo-code only of course. This requires you to either use a low
1918priority for the check watcher or use C<ev_clear_pending> explicitly, as 2663priority for the check watcher or use C<ev_clear_pending> explicitly, as
1919the callbacks for the IO/timeout watchers might not have been called yet. 2664the callbacks for the IO/timeout watchers might not have been called yet.
1920 2665
1921 static ev_io iow [nfd]; 2666 static ev_io iow [nfd];
1922 static ev_timer tw; 2667 static ev_timer tw;
1923 2668
1924 static void 2669 static void
1925 io_cb (ev_loop *loop, ev_io *w, int revents) 2670 io_cb (struct ev_loop *loop, ev_io *w, int revents)
1926 { 2671 {
1927 } 2672 }
1928 2673
1929 // create io watchers for each fd and a timer before blocking 2674 // create io watchers for each fd and a timer before blocking
1930 static void 2675 static void
1931 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2676 adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents)
1932 { 2677 {
1933 int timeout = 3600000; 2678 int timeout = 3600000;
1934 struct pollfd fds [nfd]; 2679 struct pollfd fds [nfd];
1935 // actual code will need to loop here and realloc etc. 2680 // actual code will need to loop here and realloc etc.
1936 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2681 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1937 2682
1938 /* the callback is illegal, but won't be called as we stop during check */ 2683 /* the callback is illegal, but won't be called as we stop during check */
1939 ev_timer_init (&tw, 0, timeout * 1e-3); 2684 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
1940 ev_timer_start (loop, &tw); 2685 ev_timer_start (loop, &tw);
1941 2686
1942 // create one ev_io per pollfd 2687 // create one ev_io per pollfd
1943 for (int i = 0; i < nfd; ++i) 2688 for (int i = 0; i < nfd; ++i)
1944 { 2689 {
1945 ev_io_init (iow + i, io_cb, fds [i].fd, 2690 ev_io_init (iow + i, io_cb, fds [i].fd,
1946 ((fds [i].events & POLLIN ? EV_READ : 0) 2691 ((fds [i].events & POLLIN ? EV_READ : 0)
1947 | (fds [i].events & POLLOUT ? EV_WRITE : 0))); 2692 | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1948 2693
1949 fds [i].revents = 0; 2694 fds [i].revents = 0;
1950 ev_io_start (loop, iow + i); 2695 ev_io_start (loop, iow + i);
1951 } 2696 }
1952 } 2697 }
1953 2698
1954 // stop all watchers after blocking 2699 // stop all watchers after blocking
1955 static void 2700 static void
1956 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2701 adns_check_cb (struct ev_loop *loop, ev_check *w, int revents)
1957 { 2702 {
1958 ev_timer_stop (loop, &tw); 2703 ev_timer_stop (loop, &tw);
1959 2704
1960 for (int i = 0; i < nfd; ++i) 2705 for (int i = 0; i < nfd; ++i)
1961 { 2706 {
1962 // set the relevant poll flags 2707 // set the relevant poll flags
1963 // could also call adns_processreadable etc. here 2708 // could also call adns_processreadable etc. here
1964 struct pollfd *fd = fds + i; 2709 struct pollfd *fd = fds + i;
1965 int revents = ev_clear_pending (iow + i); 2710 int revents = ev_clear_pending (iow + i);
1966 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN; 2711 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1967 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT; 2712 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1968 2713
1969 // now stop the watcher 2714 // now stop the watcher
1970 ev_io_stop (loop, iow + i); 2715 ev_io_stop (loop, iow + i);
1971 } 2716 }
1972 2717
1973 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); 2718 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1974 } 2719 }
1975 2720
1976Method 2: This would be just like method 1, but you run C<adns_afterpoll> 2721Method 2: This would be just like method 1, but you run C<adns_afterpoll>
1977in the prepare watcher and would dispose of the check watcher. 2722in the prepare watcher and would dispose of the check watcher.
1978 2723
1979Method 3: If the module to be embedded supports explicit event 2724Method 3: If the module to be embedded supports explicit event
1980notification (adns does), you can also make use of the actual watcher 2725notification (libadns does), you can also make use of the actual watcher
1981callbacks, and only destroy/create the watchers in the prepare watcher. 2726callbacks, and only destroy/create the watchers in the prepare watcher.
1982 2727
1983 static void 2728 static void
1984 timer_cb (EV_P_ ev_timer *w, int revents) 2729 timer_cb (EV_P_ ev_timer *w, int revents)
1985 { 2730 {
1986 adns_state ads = (adns_state)w->data; 2731 adns_state ads = (adns_state)w->data;
1987 update_now (EV_A); 2732 update_now (EV_A);
1988 2733
1989 adns_processtimeouts (ads, &tv_now); 2734 adns_processtimeouts (ads, &tv_now);
1990 } 2735 }
1991 2736
1992 static void 2737 static void
1993 io_cb (EV_P_ ev_io *w, int revents) 2738 io_cb (EV_P_ ev_io *w, int revents)
1994 { 2739 {
1995 adns_state ads = (adns_state)w->data; 2740 adns_state ads = (adns_state)w->data;
1996 update_now (EV_A); 2741 update_now (EV_A);
1997 2742
1998 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now); 2743 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
1999 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now); 2744 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
2000 } 2745 }
2001 2746
2002 // do not ever call adns_afterpoll 2747 // do not ever call adns_afterpoll
2003 2748
2004Method 4: Do not use a prepare or check watcher because the module you 2749Method 4: Do not use a prepare or check watcher because the module you
2005want to embed is too inflexible to support it. Instead, youc na override 2750want to embed is not flexible enough to support it. Instead, you can
2006their poll function. The drawback with this solution is that the main 2751override their poll function. The drawback with this solution is that the
2007loop is now no longer controllable by EV. The C<Glib::EV> module does 2752main loop is now no longer controllable by EV. The C<Glib::EV> module uses
2008this. 2753this approach, effectively embedding EV as a client into the horrible
2754libglib event loop.
2009 2755
2010 static gint 2756 static gint
2011 event_poll_func (GPollFD *fds, guint nfds, gint timeout) 2757 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
2012 { 2758 {
2013 int got_events = 0; 2759 int got_events = 0;
2014 2760
2015 for (n = 0; n < nfds; ++n) 2761 for (n = 0; n < nfds; ++n)
2016 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events 2762 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
2017 2763
2018 if (timeout >= 0) 2764 if (timeout >= 0)
2019 // create/start timer 2765 // create/start timer
2020 2766
2021 // poll 2767 // poll
2022 ev_loop (EV_A_ 0); 2768 ev_loop (EV_A_ 0);
2023 2769
2024 // stop timer again 2770 // stop timer again
2025 if (timeout >= 0) 2771 if (timeout >= 0)
2026 ev_timer_stop (EV_A_ &to); 2772 ev_timer_stop (EV_A_ &to);
2027 2773
2028 // stop io watchers again - their callbacks should have set 2774 // stop io watchers again - their callbacks should have set
2029 for (n = 0; n < nfds; ++n) 2775 for (n = 0; n < nfds; ++n)
2030 ev_io_stop (EV_A_ iow [n]); 2776 ev_io_stop (EV_A_ iow [n]);
2031 2777
2032 return got_events; 2778 return got_events;
2033 } 2779 }
2034 2780
2035 2781
2036=head2 C<ev_embed> - when one backend isn't enough... 2782=head2 C<ev_embed> - when one backend isn't enough...
2037 2783
2038This is a rather advanced watcher type that lets you embed one event loop 2784This is a rather advanced watcher type that lets you embed one event loop
2044prioritise I/O. 2790prioritise I/O.
2045 2791
2046As an example for a bug workaround, the kqueue backend might only support 2792As an example for a bug workaround, the kqueue backend might only support
2047sockets on some platform, so it is unusable as generic backend, but you 2793sockets on some platform, so it is unusable as generic backend, but you
2048still want to make use of it because you have many sockets and it scales 2794still want to make use of it because you have many sockets and it scales
2049so nicely. In this case, you would create a kqueue-based loop and embed it 2795so nicely. In this case, you would create a kqueue-based loop and embed
2050into your default loop (which might use e.g. poll). Overall operation will 2796it into your default loop (which might use e.g. poll). Overall operation
2051be a bit slower because first libev has to poll and then call kevent, but 2797will be a bit slower because first libev has to call C<poll> and then
2052at least you can use both at what they are best. 2798C<kevent>, but at least you can use both mechanisms for what they are
2799best: C<kqueue> for scalable sockets and C<poll> if you want it to work :)
2053 2800
2054As for prioritising I/O: rarely you have the case where some fds have 2801As for prioritising I/O: under rare circumstances you have the case where
2055to be watched and handled very quickly (with low latency), and even 2802some fds have to be watched and handled very quickly (with low latency),
2056priorities and idle watchers might have too much overhead. In this case 2803and even priorities and idle watchers might have too much overhead. In
2057you would put all the high priority stuff in one loop and all the rest in 2804this case you would put all the high priority stuff in one loop and all
2058a second one, and embed the second one in the first. 2805the rest in a second one, and embed the second one in the first.
2059 2806
2060As long as the watcher is active, the callback will be invoked every time 2807As long as the watcher is active, the callback will be invoked every
2061there might be events pending in the embedded loop. The callback must then 2808time there might be events pending in the embedded loop. The callback
2062call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2809must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2063their callbacks (you could also start an idle watcher to give the embedded 2810sweep and invoke their callbacks (the callback doesn't need to invoke the
2064loop strictly lower priority for example). You can also set the callback 2811C<ev_embed_sweep> function directly, it could also start an idle watcher
2065to C<0>, in which case the embed watcher will automatically execute the 2812to give the embedded loop strictly lower priority for example).
2066embedded loop sweep.
2067 2813
2068As long as the watcher is started it will automatically handle events. The 2814You can also set the callback to C<0>, in which case the embed watcher
2069callback will be invoked whenever some events have been handled. You can 2815will automatically execute the embedded loop sweep whenever necessary.
2070set the callback to C<0> to avoid having to specify one if you are not
2071interested in that.
2072 2816
2073Also, there have not currently been made special provisions for forking: 2817Fork detection will be handled transparently while the C<ev_embed> watcher
2074when you fork, you not only have to call C<ev_loop_fork> on both loops, 2818is active, i.e., the embedded loop will automatically be forked when the
2075but you will also have to stop and restart any C<ev_embed> watchers 2819embedding loop forks. In other cases, the user is responsible for calling
2076yourself. 2820C<ev_loop_fork> on the embedded loop.
2077 2821
2078Unfortunately, not all backends are embeddable, only the ones returned by 2822Unfortunately, not all backends are embeddable: only the ones returned by
2079C<ev_embeddable_backends> are, which, unfortunately, does not include any 2823C<ev_embeddable_backends> are, which, unfortunately, does not include any
2080portable one. 2824portable one.
2081 2825
2082So when you want to use this feature you will always have to be prepared 2826So when you want to use this feature you will always have to be prepared
2083that you cannot get an embeddable loop. The recommended way to get around 2827that you cannot get an embeddable loop. The recommended way to get around
2084this is to have a separate variables for your embeddable loop, try to 2828this is to have a separate variables for your embeddable loop, try to
2085create it, and if that fails, use the normal loop for everything. 2829create it, and if that fails, use the normal loop for everything.
2086 2830
2831=head3 C<ev_embed> and fork
2832
2833While the C<ev_embed> watcher is running, forks in the embedding loop will
2834automatically be applied to the embedded loop as well, so no special
2835fork handling is required in that case. When the watcher is not running,
2836however, it is still the task of the libev user to call C<ev_loop_fork ()>
2837as applicable.
2838
2087=head3 Watcher-Specific Functions and Data Members 2839=head3 Watcher-Specific Functions and Data Members
2088 2840
2089=over 4 2841=over 4
2090 2842
2091=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 2843=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
2094 2846
2095Configures the watcher to embed the given loop, which must be 2847Configures the watcher to embed the given loop, which must be
2096embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 2848embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
2097invoked automatically, otherwise it is the responsibility of the callback 2849invoked automatically, otherwise it is the responsibility of the callback
2098to invoke it (it will continue to be called until the sweep has been done, 2850to invoke it (it will continue to be called until the sweep has been done,
2099if you do not want thta, you need to temporarily stop the embed watcher). 2851if you do not want that, you need to temporarily stop the embed watcher).
2100 2852
2101=item ev_embed_sweep (loop, ev_embed *) 2853=item ev_embed_sweep (loop, ev_embed *)
2102 2854
2103Make a single, non-blocking sweep over the embedded loop. This works 2855Make a single, non-blocking sweep over the embedded loop. This works
2104similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 2856similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
2105apropriate way for embedded loops. 2857appropriate way for embedded loops.
2106 2858
2107=item struct ev_loop *other [read-only] 2859=item struct ev_loop *other [read-only]
2108 2860
2109The embedded event loop. 2861The embedded event loop.
2110 2862
2112 2864
2113=head3 Examples 2865=head3 Examples
2114 2866
2115Example: Try to get an embeddable event loop and embed it into the default 2867Example: Try to get an embeddable event loop and embed it into the default
2116event loop. If that is not possible, use the default loop. The default 2868event loop. If that is not possible, use the default loop. The default
2117loop is stored in C<loop_hi>, while the mebeddable loop is stored in 2869loop is stored in C<loop_hi>, while the embeddable loop is stored in
2118C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be 2870C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
2119used). 2871used).
2120 2872
2121 struct ev_loop *loop_hi = ev_default_init (0); 2873 struct ev_loop *loop_hi = ev_default_init (0);
2122 struct ev_loop *loop_lo = 0; 2874 struct ev_loop *loop_lo = 0;
2123 struct ev_embed embed; 2875 ev_embed embed;
2124 2876
2125 // see if there is a chance of getting one that works 2877 // see if there is a chance of getting one that works
2126 // (remember that a flags value of 0 means autodetection) 2878 // (remember that a flags value of 0 means autodetection)
2127 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2879 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2128 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2880 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2129 : 0; 2881 : 0;
2130 2882
2131 // if we got one, then embed it, otherwise default to loop_hi 2883 // if we got one, then embed it, otherwise default to loop_hi
2132 if (loop_lo) 2884 if (loop_lo)
2133 { 2885 {
2134 ev_embed_init (&embed, 0, loop_lo); 2886 ev_embed_init (&embed, 0, loop_lo);
2135 ev_embed_start (loop_hi, &embed); 2887 ev_embed_start (loop_hi, &embed);
2136 } 2888 }
2137 else 2889 else
2138 loop_lo = loop_hi; 2890 loop_lo = loop_hi;
2139 2891
2140Example: Check if kqueue is available but not recommended and create 2892Example: Check if kqueue is available but not recommended and create
2141a kqueue backend for use with sockets (which usually work with any 2893a kqueue backend for use with sockets (which usually work with any
2142kqueue implementation). Store the kqueue/socket-only event loop in 2894kqueue implementation). Store the kqueue/socket-only event loop in
2143C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 2895C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2144 2896
2145 struct ev_loop *loop = ev_default_init (0); 2897 struct ev_loop *loop = ev_default_init (0);
2146 struct ev_loop *loop_socket = 0; 2898 struct ev_loop *loop_socket = 0;
2147 struct ev_embed embed; 2899 ev_embed embed;
2148 2900
2149 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2901 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2150 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2902 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2151 { 2903 {
2152 ev_embed_init (&embed, 0, loop_socket); 2904 ev_embed_init (&embed, 0, loop_socket);
2153 ev_embed_start (loop, &embed); 2905 ev_embed_start (loop, &embed);
2154 } 2906 }
2155 2907
2156 if (!loop_socket) 2908 if (!loop_socket)
2157 loop_socket = loop; 2909 loop_socket = loop;
2158 2910
2159 // now use loop_socket for all sockets, and loop for everything else 2911 // now use loop_socket for all sockets, and loop for everything else
2160 2912
2161 2913
2162=head2 C<ev_fork> - the audacity to resume the event loop after a fork 2914=head2 C<ev_fork> - the audacity to resume the event loop after a fork
2163 2915
2164Fork watchers are called when a C<fork ()> was detected (usually because 2916Fork watchers are called when a C<fork ()> was detected (usually because
2167event loop blocks next and before C<ev_check> watchers are being called, 2919event loop blocks next and before C<ev_check> watchers are being called,
2168and only in the child after the fork. If whoever good citizen calling 2920and only in the child after the fork. If whoever good citizen calling
2169C<ev_default_fork> cheats and calls it in the wrong process, the fork 2921C<ev_default_fork> cheats and calls it in the wrong process, the fork
2170handlers will be invoked, too, of course. 2922handlers will be invoked, too, of course.
2171 2923
2924=head3 The special problem of life after fork - how is it possible?
2925
2926Most uses of C<fork()> consist of forking, then some simple calls to ste
2927up/change the process environment, followed by a call to C<exec()>. This
2928sequence should be handled by libev without any problems.
2929
2930This changes when the application actually wants to do event handling
2931in the child, or both parent in child, in effect "continuing" after the
2932fork.
2933
2934The default mode of operation (for libev, with application help to detect
2935forks) is to duplicate all the state in the child, as would be expected
2936when I<either> the parent I<or> the child process continues.
2937
2938When both processes want to continue using libev, then this is usually the
2939wrong result. In that case, usually one process (typically the parent) is
2940supposed to continue with all watchers in place as before, while the other
2941process typically wants to start fresh, i.e. without any active watchers.
2942
2943The cleanest and most efficient way to achieve that with libev is to
2944simply create a new event loop, which of course will be "empty", and
2945use that for new watchers. This has the advantage of not touching more
2946memory than necessary, and thus avoiding the copy-on-write, and the
2947disadvantage of having to use multiple event loops (which do not support
2948signal watchers).
2949
2950When this is not possible, or you want to use the default loop for
2951other reasons, then in the process that wants to start "fresh", call
2952C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
2953the default loop will "orphan" (not stop) all registered watchers, so you
2954have to be careful not to execute code that modifies those watchers. Note
2955also that in that case, you have to re-register any signal watchers.
2956
2172=head3 Watcher-Specific Functions and Data Members 2957=head3 Watcher-Specific Functions and Data Members
2173 2958
2174=over 4 2959=over 4
2175 2960
2176=item ev_fork_init (ev_signal *, callback) 2961=item ev_fork_init (ev_signal *, callback)
2205=head3 Queueing 2990=head3 Queueing
2206 2991
2207C<ev_async> does not support queueing of data in any way. The reason 2992C<ev_async> does not support queueing of data in any way. The reason
2208is that the author does not know of a simple (or any) algorithm for a 2993is that the author does not know of a simple (or any) algorithm for a
2209multiple-writer-single-reader queue that works in all cases and doesn't 2994multiple-writer-single-reader queue that works in all cases and doesn't
2210need elaborate support such as pthreads. 2995need elaborate support such as pthreads or unportable memory access
2996semantics.
2211 2997
2212That means that if you want to queue data, you have to provide your own 2998That means that if you want to queue data, you have to provide your own
2213queue. But at least I can tell you would implement locking around your 2999queue. But at least I can tell you how to implement locking around your
2214queue: 3000queue:
2215 3001
2216=over 4 3002=over 4
2217 3003
2218=item queueing from a signal handler context 3004=item queueing from a signal handler context
2219 3005
2220To implement race-free queueing, you simply add to the queue in the signal 3006To implement race-free queueing, you simply add to the queue in the signal
2221handler but you block the signal handler in the watcher callback. Here is an example that does that for 3007handler but you block the signal handler in the watcher callback. Here is
2222some fictitiuous SIGUSR1 handler: 3008an example that does that for some fictitious SIGUSR1 handler:
2223 3009
2224 static ev_async mysig; 3010 static ev_async mysig;
2225 3011
2226 static void 3012 static void
2227 sigusr1_handler (void) 3013 sigusr1_handler (void)
2293=over 4 3079=over 4
2294 3080
2295=item ev_async_init (ev_async *, callback) 3081=item ev_async_init (ev_async *, callback)
2296 3082
2297Initialises and configures the async watcher - it has no parameters of any 3083Initialises and configures the async watcher - it has no parameters of any
2298kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 3084kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2299believe me. 3085trust me.
2300 3086
2301=item ev_async_send (loop, ev_async *) 3087=item ev_async_send (loop, ev_async *)
2302 3088
2303Sends/signals/activates the given C<ev_async> watcher, that is, feeds 3089Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2304an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3090an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2305C<ev_feed_event>, this call is safe to do in other threads, signal or 3091C<ev_feed_event>, this call is safe to do from other threads, signal or
2306similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding 3092similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2307section below on what exactly this means). 3093section below on what exactly this means).
2308 3094
3095Note that, as with other watchers in libev, multiple events might get
3096compressed into a single callback invocation (another way to look at this
3097is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
3098reset when the event loop detects that).
3099
2309This call incurs the overhead of a syscall only once per loop iteration, 3100This call incurs the overhead of a system call only once per event loop
2310so while the overhead might be noticable, it doesn't apply to repeated 3101iteration, so while the overhead might be noticeable, it doesn't apply to
2311calls to C<ev_async_send>. 3102repeated calls to C<ev_async_send> for the same event loop.
2312 3103
2313=item bool = ev_async_pending (ev_async *) 3104=item bool = ev_async_pending (ev_async *)
2314 3105
2315Returns a non-zero value when C<ev_async_send> has been called on the 3106Returns a non-zero value when C<ev_async_send> has been called on the
2316watcher but the event has not yet been processed (or even noted) by the 3107watcher but the event has not yet been processed (or even noted) by the
2317event loop. 3108event loop.
2318 3109
2319C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 3110C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2320the loop iterates next and checks for the watcher to have become active, 3111the loop iterates next and checks for the watcher to have become active,
2321it will reset the flag again. C<ev_async_pending> can be used to very 3112it will reset the flag again. C<ev_async_pending> can be used to very
2322quickly check wether invoking the loop might be a good idea. 3113quickly check whether invoking the loop might be a good idea.
2323 3114
2324Not that this does I<not> check wether the watcher itself is pending, only 3115Not that this does I<not> check whether the watcher itself is pending,
2325wether it has been requested to make this watcher pending. 3116only whether it has been requested to make this watcher pending: there
3117is a time window between the event loop checking and resetting the async
3118notification, and the callback being invoked.
2326 3119
2327=back 3120=back
2328 3121
2329 3122
2330=head1 OTHER FUNCTIONS 3123=head1 OTHER FUNCTIONS
2334=over 4 3127=over 4
2335 3128
2336=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 3129=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
2337 3130
2338This function combines a simple timer and an I/O watcher, calls your 3131This function combines a simple timer and an I/O watcher, calls your
2339callback on whichever event happens first and automatically stop both 3132callback on whichever event happens first and automatically stops both
2340watchers. This is useful if you want to wait for a single event on an fd 3133watchers. This is useful if you want to wait for a single event on an fd
2341or timeout without having to allocate/configure/start/stop/free one or 3134or timeout without having to allocate/configure/start/stop/free one or
2342more watchers yourself. 3135more watchers yourself.
2343 3136
2344If C<fd> is less than 0, then no I/O watcher will be started and events 3137If C<fd> is less than 0, then no I/O watcher will be started and the
2345is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and 3138C<events> argument is being ignored. Otherwise, an C<ev_io> watcher for
2346C<events> set will be craeted and started. 3139the given C<fd> and C<events> set will be created and started.
2347 3140
2348If C<timeout> is less than 0, then no timeout watcher will be 3141If C<timeout> is less than 0, then no timeout watcher will be
2349started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3142started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2350repeat = 0) will be started. While C<0> is a valid timeout, it is of 3143repeat = 0) will be started. C<0> is a valid timeout.
2351dubious value.
2352 3144
2353The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3145The callback has the type C<void (*cb)(int revents, void *arg)> and gets
2354passed an C<revents> set like normal event callbacks (a combination of 3146passed an C<revents> set like normal event callbacks (a combination of
2355C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3147C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
2356value passed to C<ev_once>: 3148value passed to C<ev_once>. Note that it is possible to receive I<both>
3149a timeout and an io event at the same time - you probably should give io
3150events precedence.
2357 3151
3152Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3153
2358 static void stdin_ready (int revents, void *arg) 3154 static void stdin_ready (int revents, void *arg)
2359 { 3155 {
2360 if (revents & EV_TIMEOUT)
2361 /* doh, nothing entered */;
2362 else if (revents & EV_READ) 3156 if (revents & EV_READ)
2363 /* stdin might have data for us, joy! */; 3157 /* stdin might have data for us, joy! */;
3158 else if (revents & EV_TIMEOUT)
3159 /* doh, nothing entered */;
2364 } 3160 }
2365 3161
2366 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3162 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2367 3163
2368=item ev_feed_event (ev_loop *, watcher *, int revents)
2369
2370Feeds the given event set into the event loop, as if the specified event
2371had happened for the specified watcher (which must be a pointer to an
2372initialised but not necessarily started event watcher).
2373
2374=item ev_feed_fd_event (ev_loop *, int fd, int revents) 3164=item ev_feed_fd_event (loop, int fd, int revents)
2375 3165
2376Feed an event on the given fd, as if a file descriptor backend detected 3166Feed an event on the given fd, as if a file descriptor backend detected
2377the given events it. 3167the given events it.
2378 3168
2379=item ev_feed_signal_event (ev_loop *loop, int signum) 3169=item ev_feed_signal_event (loop, int signum)
2380 3170
2381Feed an event as if the given signal occured (C<loop> must be the default 3171Feed an event as if the given signal occurred (C<loop> must be the default
2382loop!). 3172loop!).
2383 3173
2384=back 3174=back
2385 3175
2386 3176
2415=back 3205=back
2416 3206
2417=head1 C++ SUPPORT 3207=head1 C++ SUPPORT
2418 3208
2419Libev comes with some simplistic wrapper classes for C++ that mainly allow 3209Libev comes with some simplistic wrapper classes for C++ that mainly allow
2420you to use some convinience methods to start/stop watchers and also change 3210you to use some convenience methods to start/stop watchers and also change
2421the callback model to a model using method callbacks on objects. 3211the callback model to a model using method callbacks on objects.
2422 3212
2423To use it, 3213To use it,
2424 3214
2425 #include <ev++.h> 3215 #include <ev++.h>
2426 3216
2427This automatically includes F<ev.h> and puts all of its definitions (many 3217This automatically includes F<ev.h> and puts all of its definitions (many
2428of them macros) into the global namespace. All C++ specific things are 3218of them macros) into the global namespace. All C++ specific things are
2429put into the C<ev> namespace. It should support all the same embedding 3219put into the C<ev> namespace. It should support all the same embedding
2430options as F<ev.h>, most notably C<EV_MULTIPLICITY>. 3220options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
2464 3254
2465=over 4 3255=over 4
2466 3256
2467=item ev::TYPE::TYPE () 3257=item ev::TYPE::TYPE ()
2468 3258
2469=item ev::TYPE::TYPE (struct ev_loop *) 3259=item ev::TYPE::TYPE (loop)
2470 3260
2471=item ev::TYPE::~TYPE 3261=item ev::TYPE::~TYPE
2472 3262
2473The constructor (optionally) takes an event loop to associate the watcher 3263The constructor (optionally) takes an event loop to associate the watcher
2474with. If it is omitted, it will use C<EV_DEFAULT>. 3264with. If it is omitted, it will use C<EV_DEFAULT>.
2497your compiler is good :), then the method will be fully inlined into the 3287your compiler is good :), then the method will be fully inlined into the
2498thunking function, making it as fast as a direct C callback. 3288thunking function, making it as fast as a direct C callback.
2499 3289
2500Example: simple class declaration and watcher initialisation 3290Example: simple class declaration and watcher initialisation
2501 3291
2502 struct myclass 3292 struct myclass
2503 { 3293 {
2504 void io_cb (ev::io &w, int revents) { } 3294 void io_cb (ev::io &w, int revents) { }
2505 } 3295 }
2506 3296
2507 myclass obj; 3297 myclass obj;
2508 ev::io iow; 3298 ev::io iow;
2509 iow.set <myclass, &myclass::io_cb> (&obj); 3299 iow.set <myclass, &myclass::io_cb> (&obj);
3300
3301=item w->set (object *)
3302
3303This is an B<experimental> feature that might go away in a future version.
3304
3305This is a variation of a method callback - leaving out the method to call
3306will default the method to C<operator ()>, which makes it possible to use
3307functor objects without having to manually specify the C<operator ()> all
3308the time. Incidentally, you can then also leave out the template argument
3309list.
3310
3311The C<operator ()> method prototype must be C<void operator ()(watcher &w,
3312int revents)>.
3313
3314See the method-C<set> above for more details.
3315
3316Example: use a functor object as callback.
3317
3318 struct myfunctor
3319 {
3320 void operator() (ev::io &w, int revents)
3321 {
3322 ...
3323 }
3324 }
3325
3326 myfunctor f;
3327
3328 ev::io w;
3329 w.set (&f);
2510 3330
2511=item w->set<function> (void *data = 0) 3331=item w->set<function> (void *data = 0)
2512 3332
2513Also sets a callback, but uses a static method or plain function as 3333Also sets a callback, but uses a static method or plain function as
2514callback. The optional C<data> argument will be stored in the watcher's 3334callback. The optional C<data> argument will be stored in the watcher's
2516 3336
2517The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. 3337The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
2518 3338
2519See the method-C<set> above for more details. 3339See the method-C<set> above for more details.
2520 3340
2521Example: 3341Example: Use a plain function as callback.
2522 3342
2523 static void io_cb (ev::io &w, int revents) { } 3343 static void io_cb (ev::io &w, int revents) { }
2524 iow.set <io_cb> (); 3344 iow.set <io_cb> ();
2525 3345
2526=item w->set (struct ev_loop *) 3346=item w->set (loop)
2527 3347
2528Associates a different C<struct ev_loop> with this watcher. You can only 3348Associates a different C<struct ev_loop> with this watcher. You can only
2529do this when the watcher is inactive (and not pending either). 3349do this when the watcher is inactive (and not pending either).
2530 3350
2531=item w->set ([args]) 3351=item w->set ([arguments])
2532 3352
2533Basically the same as C<ev_TYPE_set>, with the same args. Must be 3353Basically the same as C<ev_TYPE_set>, with the same arguments. Must be
2534called at least once. Unlike the C counterpart, an active watcher gets 3354called at least once. Unlike the C counterpart, an active watcher gets
2535automatically stopped and restarted when reconfiguring it with this 3355automatically stopped and restarted when reconfiguring it with this
2536method. 3356method.
2537 3357
2538=item w->start () 3358=item w->start ()
2562=back 3382=back
2563 3383
2564Example: Define a class with an IO and idle watcher, start one of them in 3384Example: Define a class with an IO and idle watcher, start one of them in
2565the constructor. 3385the constructor.
2566 3386
2567 class myclass 3387 class myclass
2568 { 3388 {
2569 ev::io io; void io_cb (ev::io &w, int revents); 3389 ev::io io ; void io_cb (ev::io &w, int revents);
2570 ev:idle idle void idle_cb (ev::idle &w, int revents); 3390 ev::idle idle; void idle_cb (ev::idle &w, int revents);
2571 3391
2572 myclass (int fd) 3392 myclass (int fd)
2573 { 3393 {
2574 io .set <myclass, &myclass::io_cb > (this); 3394 io .set <myclass, &myclass::io_cb > (this);
2575 idle.set <myclass, &myclass::idle_cb> (this); 3395 idle.set <myclass, &myclass::idle_cb> (this);
2576 3396
2577 io.start (fd, ev::READ); 3397 io.start (fd, ev::READ);
2578 } 3398 }
2579 }; 3399 };
2580 3400
2581 3401
2582=head1 OTHER LANGUAGE BINDINGS 3402=head1 OTHER LANGUAGE BINDINGS
2583 3403
2584Libev does not offer other language bindings itself, but bindings for a 3404Libev does not offer other language bindings itself, but bindings for a
2585numbe rof languages exist in the form of third-party packages. If you know 3405number of languages exist in the form of third-party packages. If you know
2586any interesting language binding in addition to the ones listed here, drop 3406any interesting language binding in addition to the ones listed here, drop
2587me a note. 3407me a note.
2588 3408
2589=over 4 3409=over 4
2590 3410
2591=item Perl 3411=item Perl
2592 3412
2593The EV module implements the full libev API and is actually used to test 3413The EV module implements the full libev API and is actually used to test
2594libev. EV is developed together with libev. Apart from the EV core module, 3414libev. EV is developed together with libev. Apart from the EV core module,
2595there are additional modules that implement libev-compatible interfaces 3415there are additional modules that implement libev-compatible interfaces
2596to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the 3416to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays),
2597C<libglib> event core (C<Glib::EV> and C<EV::Glib>). 3417C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV>
3418and C<EV::Glib>).
2598 3419
2599It can be found and installed via CPAN, its homepage is found at 3420It can be found and installed via CPAN, its homepage is at
2600L<http://software.schmorp.de/pkg/EV>. 3421L<http://software.schmorp.de/pkg/EV>.
2601 3422
3423=item Python
3424
3425Python bindings can be found at L<http://code.google.com/p/pyev/>. It
3426seems to be quite complete and well-documented.
3427
2602=item Ruby 3428=item Ruby
2603 3429
2604Tony Arcieri has written a ruby extension that offers access to a subset 3430Tony Arcieri has written a ruby extension that offers access to a subset
2605of the libev API and adds filehandle abstractions, asynchronous DNS and 3431of the libev API and adds file handle abstractions, asynchronous DNS and
2606more on top of it. It can be found via gem servers. Its homepage is at 3432more on top of it. It can be found via gem servers. Its homepage is at
2607L<http://rev.rubyforge.org/>. 3433L<http://rev.rubyforge.org/>.
2608 3434
3435Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3436makes rev work even on mingw.
3437
3438=item Haskell
3439
3440A haskell binding to libev is available at
3441L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3442
2609=item D 3443=item D
2610 3444
2611Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3445Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2612be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>. 3446be found at L<http://proj.llucax.com.ar/wiki/evd>.
3447
3448=item Ocaml
3449
3450Erkki Seppala has written Ocaml bindings for libev, to be found at
3451L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3452
3453=item Lua
3454
3455Brian Maher has written a partial interface to libev
3456for lua (only C<ev_io> and C<ev_timer>), to be found at
3457L<http://github.com/brimworks/lua-ev>.
2613 3458
2614=back 3459=back
2615 3460
2616 3461
2617=head1 MACRO MAGIC 3462=head1 MACRO MAGIC
2618 3463
2619Libev can be compiled with a variety of options, the most fundamantal 3464Libev can be compiled with a variety of options, the most fundamental
2620of which is C<EV_MULTIPLICITY>. This option determines whether (most) 3465of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2621functions and callbacks have an initial C<struct ev_loop *> argument. 3466functions and callbacks have an initial C<struct ev_loop *> argument.
2622 3467
2623To make it easier to write programs that cope with either variant, the 3468To make it easier to write programs that cope with either variant, the
2624following macros are defined: 3469following macros are defined:
2629 3474
2630This provides the loop I<argument> for functions, if one is required ("ev 3475This provides the loop I<argument> for functions, if one is required ("ev
2631loop argument"). The C<EV_A> form is used when this is the sole argument, 3476loop argument"). The C<EV_A> form is used when this is the sole argument,
2632C<EV_A_> is used when other arguments are following. Example: 3477C<EV_A_> is used when other arguments are following. Example:
2633 3478
2634 ev_unref (EV_A); 3479 ev_unref (EV_A);
2635 ev_timer_add (EV_A_ watcher); 3480 ev_timer_add (EV_A_ watcher);
2636 ev_loop (EV_A_ 0); 3481 ev_loop (EV_A_ 0);
2637 3482
2638It assumes the variable C<loop> of type C<struct ev_loop *> is in scope, 3483It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
2639which is often provided by the following macro. 3484which is often provided by the following macro.
2640 3485
2641=item C<EV_P>, C<EV_P_> 3486=item C<EV_P>, C<EV_P_>
2642 3487
2643This provides the loop I<parameter> for functions, if one is required ("ev 3488This provides the loop I<parameter> for functions, if one is required ("ev
2644loop parameter"). The C<EV_P> form is used when this is the sole parameter, 3489loop parameter"). The C<EV_P> form is used when this is the sole parameter,
2645C<EV_P_> is used when other parameters are following. Example: 3490C<EV_P_> is used when other parameters are following. Example:
2646 3491
2647 // this is how ev_unref is being declared 3492 // this is how ev_unref is being declared
2648 static void ev_unref (EV_P); 3493 static void ev_unref (EV_P);
2649 3494
2650 // this is how you can declare your typical callback 3495 // this is how you can declare your typical callback
2651 static void cb (EV_P_ ev_timer *w, int revents) 3496 static void cb (EV_P_ ev_timer *w, int revents)
2652 3497
2653It declares a parameter C<loop> of type C<struct ev_loop *>, quite 3498It declares a parameter C<loop> of type C<struct ev_loop *>, quite
2654suitable for use with C<EV_A>. 3499suitable for use with C<EV_A>.
2655 3500
2656=item C<EV_DEFAULT>, C<EV_DEFAULT_> 3501=item C<EV_DEFAULT>, C<EV_DEFAULT_>
2672 3517
2673Example: Declare and initialise a check watcher, utilising the above 3518Example: Declare and initialise a check watcher, utilising the above
2674macros so it will work regardless of whether multiple loops are supported 3519macros so it will work regardless of whether multiple loops are supported
2675or not. 3520or not.
2676 3521
2677 static void 3522 static void
2678 check_cb (EV_P_ ev_timer *w, int revents) 3523 check_cb (EV_P_ ev_timer *w, int revents)
2679 { 3524 {
2680 ev_check_stop (EV_A_ w); 3525 ev_check_stop (EV_A_ w);
2681 } 3526 }
2682 3527
2683 ev_check check; 3528 ev_check check;
2684 ev_check_init (&check, check_cb); 3529 ev_check_init (&check, check_cb);
2685 ev_check_start (EV_DEFAULT_ &check); 3530 ev_check_start (EV_DEFAULT_ &check);
2686 ev_loop (EV_DEFAULT_ 0); 3531 ev_loop (EV_DEFAULT_ 0);
2687 3532
2688=head1 EMBEDDING 3533=head1 EMBEDDING
2689 3534
2690Libev can (and often is) directly embedded into host 3535Libev can (and often is) directly embedded into host
2691applications. Examples of applications that embed it include the Deliantra 3536applications. Examples of applications that embed it include the Deliantra
2698libev somewhere in your source tree). 3543libev somewhere in your source tree).
2699 3544
2700=head2 FILESETS 3545=head2 FILESETS
2701 3546
2702Depending on what features you need you need to include one or more sets of files 3547Depending on what features you need you need to include one or more sets of files
2703in your app. 3548in your application.
2704 3549
2705=head3 CORE EVENT LOOP 3550=head3 CORE EVENT LOOP
2706 3551
2707To include only the libev core (all the C<ev_*> functions), with manual 3552To include only the libev core (all the C<ev_*> functions), with manual
2708configuration (no autoconf): 3553configuration (no autoconf):
2709 3554
2710 #define EV_STANDALONE 1 3555 #define EV_STANDALONE 1
2711 #include "ev.c" 3556 #include "ev.c"
2712 3557
2713This will automatically include F<ev.h>, too, and should be done in a 3558This will automatically include F<ev.h>, too, and should be done in a
2714single C source file only to provide the function implementations. To use 3559single C source file only to provide the function implementations. To use
2715it, do the same for F<ev.h> in all files wishing to use this API (best 3560it, do the same for F<ev.h> in all files wishing to use this API (best
2716done by writing a wrapper around F<ev.h> that you can include instead and 3561done by writing a wrapper around F<ev.h> that you can include instead and
2717where you can put other configuration options): 3562where you can put other configuration options):
2718 3563
2719 #define EV_STANDALONE 1 3564 #define EV_STANDALONE 1
2720 #include "ev.h" 3565 #include "ev.h"
2721 3566
2722Both header files and implementation files can be compiled with a C++ 3567Both header files and implementation files can be compiled with a C++
2723compiler (at least, thats a stated goal, and breakage will be treated 3568compiler (at least, that's a stated goal, and breakage will be treated
2724as a bug). 3569as a bug).
2725 3570
2726You need the following files in your source tree, or in a directory 3571You need the following files in your source tree, or in a directory
2727in your include path (e.g. in libev/ when using -Ilibev): 3572in your include path (e.g. in libev/ when using -Ilibev):
2728 3573
2729 ev.h 3574 ev.h
2730 ev.c 3575 ev.c
2731 ev_vars.h 3576 ev_vars.h
2732 ev_wrap.h 3577 ev_wrap.h
2733 3578
2734 ev_win32.c required on win32 platforms only 3579 ev_win32.c required on win32 platforms only
2735 3580
2736 ev_select.c only when select backend is enabled (which is enabled by default) 3581 ev_select.c only when select backend is enabled (which is enabled by default)
2737 ev_poll.c only when poll backend is enabled (disabled by default) 3582 ev_poll.c only when poll backend is enabled (disabled by default)
2738 ev_epoll.c only when the epoll backend is enabled (disabled by default) 3583 ev_epoll.c only when the epoll backend is enabled (disabled by default)
2739 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 3584 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
2740 ev_port.c only when the solaris port backend is enabled (disabled by default) 3585 ev_port.c only when the solaris port backend is enabled (disabled by default)
2741 3586
2742F<ev.c> includes the backend files directly when enabled, so you only need 3587F<ev.c> includes the backend files directly when enabled, so you only need
2743to compile this single file. 3588to compile this single file.
2744 3589
2745=head3 LIBEVENT COMPATIBILITY API 3590=head3 LIBEVENT COMPATIBILITY API
2746 3591
2747To include the libevent compatibility API, also include: 3592To include the libevent compatibility API, also include:
2748 3593
2749 #include "event.c" 3594 #include "event.c"
2750 3595
2751in the file including F<ev.c>, and: 3596in the file including F<ev.c>, and:
2752 3597
2753 #include "event.h" 3598 #include "event.h"
2754 3599
2755in the files that want to use the libevent API. This also includes F<ev.h>. 3600in the files that want to use the libevent API. This also includes F<ev.h>.
2756 3601
2757You need the following additional files for this: 3602You need the following additional files for this:
2758 3603
2759 event.h 3604 event.h
2760 event.c 3605 event.c
2761 3606
2762=head3 AUTOCONF SUPPORT 3607=head3 AUTOCONF SUPPORT
2763 3608
2764Instead of using C<EV_STANDALONE=1> and providing your config in 3609Instead of using C<EV_STANDALONE=1> and providing your configuration in
2765whatever way you want, you can also C<m4_include([libev.m4])> in your 3610whatever way you want, you can also C<m4_include([libev.m4])> in your
2766F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then 3611F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
2767include F<config.h> and configure itself accordingly. 3612include F<config.h> and configure itself accordingly.
2768 3613
2769For this of course you need the m4 file: 3614For this of course you need the m4 file:
2770 3615
2771 libev.m4 3616 libev.m4
2772 3617
2773=head2 PREPROCESSOR SYMBOLS/MACROS 3618=head2 PREPROCESSOR SYMBOLS/MACROS
2774 3619
2775Libev can be configured via a variety of preprocessor symbols you have to 3620Libev can be configured via a variety of preprocessor symbols you have to
2776define before including any of its files. The default in the absense of 3621define before including any of its files. The default in the absence of
2777autoconf is noted for every option. 3622autoconf is documented for every option.
2778 3623
2779=over 4 3624=over 4
2780 3625
2781=item EV_STANDALONE 3626=item EV_STANDALONE
2782 3627
2784keeps libev from including F<config.h>, and it also defines dummy 3629keeps libev from including F<config.h>, and it also defines dummy
2785implementations for some libevent functions (such as logging, which is not 3630implementations for some libevent functions (such as logging, which is not
2786supported). It will also not define any of the structs usually found in 3631supported). It will also not define any of the structs usually found in
2787F<event.h> that are not directly supported by the libev core alone. 3632F<event.h> that are not directly supported by the libev core alone.
2788 3633
3634In standalone mode, libev will still try to automatically deduce the
3635configuration, but has to be more conservative.
3636
2789=item EV_USE_MONOTONIC 3637=item EV_USE_MONOTONIC
2790 3638
2791If defined to be C<1>, libev will try to detect the availability of the 3639If defined to be C<1>, libev will try to detect the availability of the
2792monotonic clock option at both compiletime and runtime. Otherwise no use 3640monotonic clock option at both compile time and runtime. Otherwise no
2793of the monotonic clock option will be attempted. If you enable this, you 3641use of the monotonic clock option will be attempted. If you enable this,
2794usually have to link against librt or something similar. Enabling it when 3642you usually have to link against librt or something similar. Enabling it
2795the functionality isn't available is safe, though, although you have 3643when the functionality isn't available is safe, though, although you have
2796to make sure you link against any libraries where the C<clock_gettime> 3644to make sure you link against any libraries where the C<clock_gettime>
2797function is hiding in (often F<-lrt>). 3645function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
2798 3646
2799=item EV_USE_REALTIME 3647=item EV_USE_REALTIME
2800 3648
2801If defined to be C<1>, libev will try to detect the availability of the 3649If defined to be C<1>, libev will try to detect the availability of the
2802realtime clock option at compiletime (and assume its availability at 3650real-time clock option at compile time (and assume its availability
2803runtime if successful). Otherwise no use of the realtime clock option will 3651at runtime if successful). Otherwise no use of the real-time clock
2804be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3652option will be attempted. This effectively replaces C<gettimeofday>
2805(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3653by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
2806note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3654correctness. See the note about libraries in the description of
3655C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3656C<EV_USE_CLOCK_SYSCALL>.
3657
3658=item EV_USE_CLOCK_SYSCALL
3659
3660If defined to be C<1>, libev will try to use a direct syscall instead
3661of calling the system-provided C<clock_gettime> function. This option
3662exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3663unconditionally pulls in C<libpthread>, slowing down single-threaded
3664programs needlessly. Using a direct syscall is slightly slower (in
3665theory), because no optimised vdso implementation can be used, but avoids
3666the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3667higher, as it simplifies linking (no need for C<-lrt>).
2807 3668
2808=item EV_USE_NANOSLEEP 3669=item EV_USE_NANOSLEEP
2809 3670
2810If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3671If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2811and will use it for delays. Otherwise it will use C<select ()>. 3672and will use it for delays. Otherwise it will use C<select ()>.
28192.7 or newer, otherwise disabled. 36802.7 or newer, otherwise disabled.
2820 3681
2821=item EV_USE_SELECT 3682=item EV_USE_SELECT
2822 3683
2823If undefined or defined to be C<1>, libev will compile in support for the 3684If undefined or defined to be C<1>, libev will compile in support for the
2824C<select>(2) backend. No attempt at autodetection will be done: if no 3685C<select>(2) backend. No attempt at auto-detection will be done: if no
2825other method takes over, select will be it. Otherwise the select backend 3686other method takes over, select will be it. Otherwise the select backend
2826will not be compiled in. 3687will not be compiled in.
2827 3688
2828=item EV_SELECT_USE_FD_SET 3689=item EV_SELECT_USE_FD_SET
2829 3690
2830If defined to C<1>, then the select backend will use the system C<fd_set> 3691If defined to C<1>, then the select backend will use the system C<fd_set>
2831structure. This is useful if libev doesn't compile due to a missing 3692structure. This is useful if libev doesn't compile due to a missing
2832C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on 3693C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
2833exotic systems. This usually limits the range of file descriptors to some 3694on exotic systems. This usually limits the range of file descriptors to
2834low limit such as 1024 or might have other limitations (winsocket only 3695some low limit such as 1024 or might have other limitations (winsocket
2835allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3696only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
2836influence the size of the C<fd_set> used. 3697configures the maximum size of the C<fd_set>.
2837 3698
2838=item EV_SELECT_IS_WINSOCKET 3699=item EV_SELECT_IS_WINSOCKET
2839 3700
2840When defined to C<1>, the select backend will assume that 3701When defined to C<1>, the select backend will assume that
2841select/socket/connect etc. don't understand file descriptors but 3702select/socket/connect etc. don't understand file descriptors but
2843be used is the winsock select). This means that it will call 3704be used is the winsock select). This means that it will call
2844C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3705C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
2845it is assumed that all these functions actually work on fds, even 3706it is assumed that all these functions actually work on fds, even
2846on win32. Should not be defined on non-win32 platforms. 3707on win32. Should not be defined on non-win32 platforms.
2847 3708
2848=item EV_FD_TO_WIN32_HANDLE 3709=item EV_FD_TO_WIN32_HANDLE(fd)
2849 3710
2850If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3711If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
2851file descriptors to socket handles. When not defining this symbol (the 3712file descriptors to socket handles. When not defining this symbol (the
2852default), then libev will call C<_get_osfhandle>, which is usually 3713default), then libev will call C<_get_osfhandle>, which is usually
2853correct. In some cases, programs use their own file descriptor management, 3714correct. In some cases, programs use their own file descriptor management,
2854in which case they can provide this function to map fds to socket handles. 3715in which case they can provide this function to map fds to socket handles.
3716
3717=item EV_WIN32_HANDLE_TO_FD(handle)
3718
3719If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3720using the standard C<_open_osfhandle> function. For programs implementing
3721their own fd to handle mapping, overwriting this function makes it easier
3722to do so. This can be done by defining this macro to an appropriate value.
3723
3724=item EV_WIN32_CLOSE_FD(fd)
3725
3726If programs implement their own fd to handle mapping on win32, then this
3727macro can be used to override the C<close> function, useful to unregister
3728file descriptors again. Note that the replacement function has to close
3729the underlying OS handle.
2855 3730
2856=item EV_USE_POLL 3731=item EV_USE_POLL
2857 3732
2858If defined to be C<1>, libev will compile in support for the C<poll>(2) 3733If defined to be C<1>, libev will compile in support for the C<poll>(2)
2859backend. Otherwise it will be enabled on non-win32 platforms. It 3734backend. Otherwise it will be enabled on non-win32 platforms. It
2886otherwise another method will be used as fallback. This is the preferred 3761otherwise another method will be used as fallback. This is the preferred
2887backend for Solaris 10 systems. 3762backend for Solaris 10 systems.
2888 3763
2889=item EV_USE_DEVPOLL 3764=item EV_USE_DEVPOLL
2890 3765
2891reserved for future expansion, works like the USE symbols above. 3766Reserved for future expansion, works like the USE symbols above.
2892 3767
2893=item EV_USE_INOTIFY 3768=item EV_USE_INOTIFY
2894 3769
2895If defined to be C<1>, libev will compile in support for the Linux inotify 3770If defined to be C<1>, libev will compile in support for the Linux inotify
2896interface to speed up C<ev_stat> watchers. Its actual availability will 3771interface to speed up C<ev_stat> watchers. Its actual availability will
2903access is atomic with respect to other threads or signal contexts. No such 3778access is atomic with respect to other threads or signal contexts. No such
2904type is easily found in the C language, so you can provide your own type 3779type is easily found in the C language, so you can provide your own type
2905that you know is safe for your purposes. It is used both for signal handler "locking" 3780that you know is safe for your purposes. It is used both for signal handler "locking"
2906as well as for signal and thread safety in C<ev_async> watchers. 3781as well as for signal and thread safety in C<ev_async> watchers.
2907 3782
2908In the absense of this define, libev will use C<sig_atomic_t volatile> 3783In the absence of this define, libev will use C<sig_atomic_t volatile>
2909(from F<signal.h>), which is usually good enough on most platforms. 3784(from F<signal.h>), which is usually good enough on most platforms.
2910 3785
2911=item EV_H 3786=item EV_H
2912 3787
2913The name of the F<ev.h> header file used to include it. The default if 3788The name of the F<ev.h> header file used to include it. The default if
2952When doing priority-based operations, libev usually has to linearly search 3827When doing priority-based operations, libev usually has to linearly search
2953all the priorities, so having many of them (hundreds) uses a lot of space 3828all the priorities, so having many of them (hundreds) uses a lot of space
2954and time, so using the defaults of five priorities (-2 .. +2) is usually 3829and time, so using the defaults of five priorities (-2 .. +2) is usually
2955fine. 3830fine.
2956 3831
2957If your embedding app does not need any priorities, defining these both to 3832If your embedding application does not need any priorities, defining these
2958C<0> will save some memory and cpu. 3833both to C<0> will save some memory and CPU.
2959 3834
2960=item EV_PERIODIC_ENABLE 3835=item EV_PERIODIC_ENABLE
2961 3836
2962If undefined or defined to be C<1>, then periodic timers are supported. If 3837If undefined or defined to be C<1>, then periodic timers are supported. If
2963defined to be C<0>, then they are not. Disabling them saves a few kB of 3838defined to be C<0>, then they are not. Disabling them saves a few kB of
2970code. 3845code.
2971 3846
2972=item EV_EMBED_ENABLE 3847=item EV_EMBED_ENABLE
2973 3848
2974If undefined or defined to be C<1>, then embed watchers are supported. If 3849If undefined or defined to be C<1>, then embed watchers are supported. If
2975defined to be C<0>, then they are not. 3850defined to be C<0>, then they are not. Embed watchers rely on most other
3851watcher types, which therefore must not be disabled.
2976 3852
2977=item EV_STAT_ENABLE 3853=item EV_STAT_ENABLE
2978 3854
2979If undefined or defined to be C<1>, then stat watchers are supported. If 3855If undefined or defined to be C<1>, then stat watchers are supported. If
2980defined to be C<0>, then they are not. 3856defined to be C<0>, then they are not.
2990defined to be C<0>, then they are not. 3866defined to be C<0>, then they are not.
2991 3867
2992=item EV_MINIMAL 3868=item EV_MINIMAL
2993 3869
2994If you need to shave off some kilobytes of code at the expense of some 3870If you need to shave off some kilobytes of code at the expense of some
2995speed, define this symbol to C<1>. Currently this is used to override some 3871speed (but with the full API), define this symbol to C<1>. Currently this
2996inlining decisions, saves roughly 30% codesize of amd64. It also selects a 3872is used to override some inlining decisions, saves roughly 30% code size
2997much smaller 2-heap for timer management over the default 4-heap. 3873on amd64. It also selects a much smaller 2-heap for timer management over
3874the default 4-heap.
3875
3876You can save even more by disabling watcher types you do not need
3877and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
3878(C<-DNDEBUG>) will usually reduce code size a lot.
3879
3880Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3881provide a bare-bones event library. See C<ev.h> for details on what parts
3882of the API are still available, and do not complain if this subset changes
3883over time.
3884
3885=item EV_NSIG
3886
3887The highest supported signal number, +1 (or, the number of
3888signals): Normally, libev tries to deduce the maximum number of signals
3889automatically, but sometimes this fails, in which case it can be
3890specified. Also, using a lower number than detected (C<32> should be
3891good for about any system in existance) can save some memory, as libev
3892statically allocates some 12-24 bytes per signal number.
2998 3893
2999=item EV_PID_HASHSIZE 3894=item EV_PID_HASHSIZE
3000 3895
3001C<ev_child> watchers use a small hash table to distribute workload by 3896C<ev_child> watchers use a small hash table to distribute workload by
3002pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3897pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
3012two). 3907two).
3013 3908
3014=item EV_USE_4HEAP 3909=item EV_USE_4HEAP
3015 3910
3016Heaps are not very cache-efficient. To improve the cache-efficiency of the 3911Heaps are not very cache-efficient. To improve the cache-efficiency of the
3017timer and periodics heap, libev uses a 4-heap when this symbol is defined 3912timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3018to C<1>. The 4-heap uses more complicated (longer) code but has 3913to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3019noticably faster performance with many (thousands) of watchers. 3914faster performance with many (thousands) of watchers.
3020 3915
3021The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3916The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3022(disabled). 3917(disabled).
3023 3918
3024=item EV_HEAP_CACHE_AT 3919=item EV_HEAP_CACHE_AT
3025 3920
3026Heaps are not very cache-efficient. To improve the cache-efficiency of the 3921Heaps are not very cache-efficient. To improve the cache-efficiency of the
3027timer and periodics heap, libev can cache the timestamp (I<at>) within 3922timer and periodics heaps, libev can cache the timestamp (I<at>) within
3028the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 3923the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3029which uses 8-12 bytes more per watcher and a few hundred bytes more code, 3924which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3030but avoids random read accesses on heap changes. This improves performance 3925but avoids random read accesses on heap changes. This improves performance
3031noticably with with many (hundreds) of watchers. 3926noticeably with many (hundreds) of watchers.
3032 3927
3033The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3928The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3034(disabled). 3929(disabled).
3930
3931=item EV_VERIFY
3932
3933Controls how much internal verification (see C<ev_loop_verify ()>) will
3934be done: If set to C<0>, no internal verification code will be compiled
3935in. If set to C<1>, then verification code will be compiled in, but not
3936called. If set to C<2>, then the internal verification code will be
3937called once per loop, which can slow down libev. If set to C<3>, then the
3938verification code will be called very frequently, which will slow down
3939libev considerably.
3940
3941The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
3942C<0>.
3035 3943
3036=item EV_COMMON 3944=item EV_COMMON
3037 3945
3038By default, all watchers have a C<void *data> member. By redefining 3946By default, all watchers have a C<void *data> member. By redefining
3039this macro to a something else you can include more and other types of 3947this macro to a something else you can include more and other types of
3040members. You have to define it each time you include one of the files, 3948members. You have to define it each time you include one of the files,
3041though, and it must be identical each time. 3949though, and it must be identical each time.
3042 3950
3043For example, the perl EV module uses something like this: 3951For example, the perl EV module uses something like this:
3044 3952
3045 #define EV_COMMON \ 3953 #define EV_COMMON \
3046 SV *self; /* contains this struct */ \ 3954 SV *self; /* contains this struct */ \
3047 SV *cb_sv, *fh /* note no trailing ";" */ 3955 SV *cb_sv, *fh /* note no trailing ";" */
3048 3956
3049=item EV_CB_DECLARE (type) 3957=item EV_CB_DECLARE (type)
3050 3958
3051=item EV_CB_INVOKE (watcher, revents) 3959=item EV_CB_INVOKE (watcher, revents)
3052 3960
3057definition and a statement, respectively. See the F<ev.h> header file for 3965definition and a statement, respectively. See the F<ev.h> header file for
3058their default definitions. One possible use for overriding these is to 3966their default definitions. One possible use for overriding these is to
3059avoid the C<struct ev_loop *> as first argument in all cases, or to use 3967avoid the C<struct ev_loop *> as first argument in all cases, or to use
3060method calls instead of plain function calls in C++. 3968method calls instead of plain function calls in C++.
3061 3969
3970=back
3971
3062=head2 EXPORTED API SYMBOLS 3972=head2 EXPORTED API SYMBOLS
3063 3973
3064If you need to re-export the API (e.g. via a dll) and you need a list of 3974If you need to re-export the API (e.g. via a DLL) and you need a list of
3065exported symbols, you can use the provided F<Symbol.*> files which list 3975exported symbols, you can use the provided F<Symbol.*> files which list
3066all public symbols, one per line: 3976all public symbols, one per line:
3067 3977
3068 Symbols.ev for libev proper 3978 Symbols.ev for libev proper
3069 Symbols.event for the libevent emulation 3979 Symbols.event for the libevent emulation
3070 3980
3071This can also be used to rename all public symbols to avoid clashes with 3981This can also be used to rename all public symbols to avoid clashes with
3072multiple versions of libev linked together (which is obviously bad in 3982multiple versions of libev linked together (which is obviously bad in
3073itself, but sometimes it is inconvinient to avoid this). 3983itself, but sometimes it is inconvenient to avoid this).
3074 3984
3075A sed command like this will create wrapper C<#define>'s that you need to 3985A sed command like this will create wrapper C<#define>'s that you need to
3076include before including F<ev.h>: 3986include before including F<ev.h>:
3077 3987
3078 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h 3988 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
3095file. 4005file.
3096 4006
3097The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4007The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3098that everybody includes and which overrides some configure choices: 4008that everybody includes and which overrides some configure choices:
3099 4009
3100 #define EV_MINIMAL 1 4010 #define EV_MINIMAL 1
3101 #define EV_USE_POLL 0 4011 #define EV_USE_POLL 0
3102 #define EV_MULTIPLICITY 0 4012 #define EV_MULTIPLICITY 0
3103 #define EV_PERIODIC_ENABLE 0 4013 #define EV_PERIODIC_ENABLE 0
3104 #define EV_STAT_ENABLE 0 4014 #define EV_STAT_ENABLE 0
3105 #define EV_FORK_ENABLE 0 4015 #define EV_FORK_ENABLE 0
3106 #define EV_CONFIG_H <config.h> 4016 #define EV_CONFIG_H <config.h>
3107 #define EV_MINPRI 0 4017 #define EV_MINPRI 0
3108 #define EV_MAXPRI 0 4018 #define EV_MAXPRI 0
3109 4019
3110 #include "ev++.h" 4020 #include "ev++.h"
3111 4021
3112And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4022And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3113 4023
3114 #include "ev_cpp.h" 4024 #include "ev_cpp.h"
3115 #include "ev.c" 4025 #include "ev.c"
3116 4026
4027=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
3117 4028
3118=head1 THREADS AND COROUTINES 4029=head2 THREADS AND COROUTINES
3119 4030
3120=head2 THREADS 4031=head3 THREADS
3121 4032
3122Libev itself is completely threadsafe, but it uses no locking. This 4033All libev functions are reentrant and thread-safe unless explicitly
4034documented otherwise, but libev implements no locking itself. This means
3123means that you can use as many loops as you want in parallel, as long as 4035that you can use as many loops as you want in parallel, as long as there
3124only one thread ever calls into one libev function with the same loop 4036are no concurrent calls into any libev function with the same loop
3125parameter. 4037parameter (C<ev_default_*> calls have an implicit default loop parameter,
4038of course): libev guarantees that different event loops share no data
4039structures that need any locking.
3126 4040
3127Or put differently: calls with different loop parameters can be done in 4041Or to put it differently: calls with different loop parameters can be done
3128parallel from multiple threads, calls with the same loop parameter must be 4042concurrently from multiple threads, calls with the same loop parameter
3129done serially (but can be done from different threads, as long as only one 4043must be done serially (but can be done from different threads, as long as
3130thread ever is inside a call at any point in time, e.g. by using a mutex 4044only one thread ever is inside a call at any point in time, e.g. by using
3131per loop). 4045a mutex per loop).
3132 4046
3133If you want to know which design is best for your problem, then I cannot 4047Specifically to support threads (and signal handlers), libev implements
4048so-called C<ev_async> watchers, which allow some limited form of
4049concurrency on the same event loop, namely waking it up "from the
4050outside".
4051
4052If you want to know which design (one loop, locking, or multiple loops
4053without or something else still) is best for your problem, then I cannot
3134help you but by giving some generic advice: 4054help you, but here is some generic advice:
3135 4055
3136=over 4 4056=over 4
3137 4057
3138=item * most applications have a main thread: use the default libev loop 4058=item * most applications have a main thread: use the default libev loop
3139in that thread, or create a seperate thread running only the default loop. 4059in that thread, or create a separate thread running only the default loop.
3140 4060
3141This helps integrating other libraries or software modules that use libev 4061This helps integrating other libraries or software modules that use libev
3142themselves and don't care/know about threading. 4062themselves and don't care/know about threading.
3143 4063
3144=item * one loop per thread is usually a good model. 4064=item * one loop per thread is usually a good model.
3145 4065
3146Doing this is almost never wrong, sometimes a better-performance model 4066Doing this is almost never wrong, sometimes a better-performance model
3147exists, but it is always a good start. 4067exists, but it is always a good start.
3148 4068
3149=item * other models exist, such as the leader/follower pattern, where one 4069=item * other models exist, such as the leader/follower pattern, where one
3150loop is handed through multiple threads in a kind of round-robbin fashion. 4070loop is handed through multiple threads in a kind of round-robin fashion.
3151 4071
3152Chosing a model is hard - look around, learn, know that usually you cna do 4072Choosing a model is hard - look around, learn, know that usually you can do
3153better than you currently do :-) 4073better than you currently do :-)
3154 4074
3155=item * often you need to talk to some other thread which blocks in the 4075=item * often you need to talk to some other thread which blocks in the
4076event loop.
4077
3156event loop - C<ev_async> watchers can be used to wake them up from other 4078C<ev_async> watchers can be used to wake them up from other threads safely
3157threads safely (or from signal contexts...). 4079(or from signal contexts...).
4080
4081An example use would be to communicate signals or other events that only
4082work in the default loop by registering the signal watcher with the
4083default loop and triggering an C<ev_async> watcher from the default loop
4084watcher callback into the event loop interested in the signal.
3158 4085
3159=back 4086=back
3160 4087
4088=head4 THREAD LOCKING EXAMPLE
4089
4090Here is a fictitious example of how to run an event loop in a different
4091thread than where callbacks are being invoked and watchers are
4092created/added/removed.
4093
4094For a real-world example, see the C<EV::Loop::Async> perl module,
4095which uses exactly this technique (which is suited for many high-level
4096languages).
4097
4098The example uses a pthread mutex to protect the loop data, a condition
4099variable to wait for callback invocations, an async watcher to notify the
4100event loop thread and an unspecified mechanism to wake up the main thread.
4101
4102First, you need to associate some data with the event loop:
4103
4104 typedef struct {
4105 mutex_t lock; /* global loop lock */
4106 ev_async async_w;
4107 thread_t tid;
4108 cond_t invoke_cv;
4109 } userdata;
4110
4111 void prepare_loop (EV_P)
4112 {
4113 // for simplicity, we use a static userdata struct.
4114 static userdata u;
4115
4116 ev_async_init (&u->async_w, async_cb);
4117 ev_async_start (EV_A_ &u->async_w);
4118
4119 pthread_mutex_init (&u->lock, 0);
4120 pthread_cond_init (&u->invoke_cv, 0);
4121
4122 // now associate this with the loop
4123 ev_set_userdata (EV_A_ u);
4124 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4125 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4126
4127 // then create the thread running ev_loop
4128 pthread_create (&u->tid, 0, l_run, EV_A);
4129 }
4130
4131The callback for the C<ev_async> watcher does nothing: the watcher is used
4132solely to wake up the event loop so it takes notice of any new watchers
4133that might have been added:
4134
4135 static void
4136 async_cb (EV_P_ ev_async *w, int revents)
4137 {
4138 // just used for the side effects
4139 }
4140
4141The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4142protecting the loop data, respectively.
4143
4144 static void
4145 l_release (EV_P)
4146 {
4147 userdata *u = ev_userdata (EV_A);
4148 pthread_mutex_unlock (&u->lock);
4149 }
4150
4151 static void
4152 l_acquire (EV_P)
4153 {
4154 userdata *u = ev_userdata (EV_A);
4155 pthread_mutex_lock (&u->lock);
4156 }
4157
4158The event loop thread first acquires the mutex, and then jumps straight
4159into C<ev_loop>:
4160
4161 void *
4162 l_run (void *thr_arg)
4163 {
4164 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4165
4166 l_acquire (EV_A);
4167 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4168 ev_loop (EV_A_ 0);
4169 l_release (EV_A);
4170
4171 return 0;
4172 }
4173
4174Instead of invoking all pending watchers, the C<l_invoke> callback will
4175signal the main thread via some unspecified mechanism (signals? pipe
4176writes? C<Async::Interrupt>?) and then waits until all pending watchers
4177have been called (in a while loop because a) spurious wakeups are possible
4178and b) skipping inter-thread-communication when there are no pending
4179watchers is very beneficial):
4180
4181 static void
4182 l_invoke (EV_P)
4183 {
4184 userdata *u = ev_userdata (EV_A);
4185
4186 while (ev_pending_count (EV_A))
4187 {
4188 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4189 pthread_cond_wait (&u->invoke_cv, &u->lock);
4190 }
4191 }
4192
4193Now, whenever the main thread gets told to invoke pending watchers, it
4194will grab the lock, call C<ev_invoke_pending> and then signal the loop
4195thread to continue:
4196
4197 static void
4198 real_invoke_pending (EV_P)
4199 {
4200 userdata *u = ev_userdata (EV_A);
4201
4202 pthread_mutex_lock (&u->lock);
4203 ev_invoke_pending (EV_A);
4204 pthread_cond_signal (&u->invoke_cv);
4205 pthread_mutex_unlock (&u->lock);
4206 }
4207
4208Whenever you want to start/stop a watcher or do other modifications to an
4209event loop, you will now have to lock:
4210
4211 ev_timer timeout_watcher;
4212 userdata *u = ev_userdata (EV_A);
4213
4214 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4215
4216 pthread_mutex_lock (&u->lock);
4217 ev_timer_start (EV_A_ &timeout_watcher);
4218 ev_async_send (EV_A_ &u->async_w);
4219 pthread_mutex_unlock (&u->lock);
4220
4221Note that sending the C<ev_async> watcher is required because otherwise
4222an event loop currently blocking in the kernel will have no knowledge
4223about the newly added timer. By waking up the loop it will pick up any new
4224watchers in the next event loop iteration.
4225
3161=head2 COROUTINES 4226=head3 COROUTINES
3162 4227
3163Libev is much more accomodating to coroutines ("cooperative threads"): 4228Libev is very accommodating to coroutines ("cooperative threads"):
3164libev fully supports nesting calls to it's functions from different 4229libev fully supports nesting calls to its functions from different
3165coroutines (e.g. you can call C<ev_loop> on the same loop from two 4230coroutines (e.g. you can call C<ev_loop> on the same loop from two
3166different coroutines and switch freely between both coroutines running the 4231different coroutines, and switch freely between both coroutines running
3167loop, as long as you don't confuse yourself). The only exception is that 4232the loop, as long as you don't confuse yourself). The only exception is
3168you must not do this from C<ev_periodic> reschedule callbacks. 4233that you must not do this from C<ev_periodic> reschedule callbacks.
3169 4234
3170Care has been invested into making sure that libev does not keep local 4235Care has been taken to ensure that libev does not keep local state inside
3171state inside C<ev_loop>, and other calls do not usually allow coroutine 4236C<ev_loop>, and other calls do not usually allow for coroutine switches as
3172switches. 4237they do not call any callbacks.
3173 4238
4239=head2 COMPILER WARNINGS
3174 4240
3175=head1 COMPLEXITIES 4241Depending on your compiler and compiler settings, you might get no or a
4242lot of warnings when compiling libev code. Some people are apparently
4243scared by this.
3176 4244
3177In this section the complexities of (many of) the algorithms used inside 4245However, these are unavoidable for many reasons. For one, each compiler
3178libev will be explained. For complexity discussions about backends see the 4246has different warnings, and each user has different tastes regarding
3179documentation for C<ev_default_init>. 4247warning options. "Warn-free" code therefore cannot be a goal except when
4248targeting a specific compiler and compiler-version.
3180 4249
3181All of the following are about amortised time: If an array needs to be 4250Another reason is that some compiler warnings require elaborate
3182extended, libev needs to realloc and move the whole array, but this 4251workarounds, or other changes to the code that make it less clear and less
3183happens asymptotically never with higher number of elements, so O(1) might 4252maintainable.
3184mean it might do a lengthy realloc operation in rare cases, but on average
3185it is much faster and asymptotically approaches constant time.
3186 4253
3187=over 4 4254And of course, some compiler warnings are just plain stupid, or simply
4255wrong (because they don't actually warn about the condition their message
4256seems to warn about). For example, certain older gcc versions had some
4257warnings that resulted an extreme number of false positives. These have
4258been fixed, but some people still insist on making code warn-free with
4259such buggy versions.
3188 4260
3189=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 4261While libev is written to generate as few warnings as possible,
4262"warn-free" code is not a goal, and it is recommended not to build libev
4263with any compiler warnings enabled unless you are prepared to cope with
4264them (e.g. by ignoring them). Remember that warnings are just that:
4265warnings, not errors, or proof of bugs.
3190 4266
3191This means that, when you have a watcher that triggers in one hour and
3192there are 100 watchers that would trigger before that then inserting will
3193have to skip roughly seven (C<ld 100>) of these watchers.
3194 4267
3195=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) 4268=head2 VALGRIND
3196 4269
3197That means that changing a timer costs less than removing/adding them 4270Valgrind has a special section here because it is a popular tool that is
3198as only the relative motion in the event queue has to be paid for. 4271highly useful. Unfortunately, valgrind reports are very hard to interpret.
3199 4272
3200=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) 4273If you think you found a bug (memory leak, uninitialised data access etc.)
4274in libev, then check twice: If valgrind reports something like:
3201 4275
3202These just add the watcher into an array or at the head of a list. 4276 ==2274== definitely lost: 0 bytes in 0 blocks.
4277 ==2274== possibly lost: 0 bytes in 0 blocks.
4278 ==2274== still reachable: 256 bytes in 1 blocks.
3203 4279
3204=item Stopping check/prepare/idle/fork/async watchers: O(1) 4280Then there is no memory leak, just as memory accounted to global variables
4281is not a memleak - the memory is still being referenced, and didn't leak.
3205 4282
3206=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 4283Similarly, under some circumstances, valgrind might report kernel bugs
4284as if it were a bug in libev (e.g. in realloc or in the poll backend,
4285although an acceptable workaround has been found here), or it might be
4286confused.
3207 4287
3208These watchers are stored in lists then need to be walked to find the 4288Keep in mind that valgrind is a very good tool, but only a tool. Don't
3209correct watcher to remove. The lists are usually short (you don't usually 4289make it into some kind of religion.
3210have many watchers waiting for the same fd or signal).
3211 4290
3212=item Finding the next timer in each loop iteration: O(1) 4291If you are unsure about something, feel free to contact the mailing list
4292with the full valgrind report and an explanation on why you think this
4293is a bug in libev (best check the archives, too :). However, don't be
4294annoyed when you get a brisk "this is no bug" answer and take the chance
4295of learning how to interpret valgrind properly.
3213 4296
3214By virtue of using a binary or 4-heap, the next timer is always found at a 4297If you need, for some reason, empty reports from valgrind for your project
3215fixed position in the storage array. 4298I suggest using suppression lists.
3216 4299
3217=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3218 4300
3219A change means an I/O watcher gets started or stopped, which requires 4301=head1 PORTABILITY NOTES
3220libev to recalculate its status (and possibly tell the kernel, depending
3221on backend and wether C<ev_io_set> was used).
3222 4302
3223=item Activating one watcher (putting it into the pending state): O(1) 4303=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
3224
3225=item Priority handling: O(number_of_priorities)
3226
3227Priorities are implemented by allocating some space for each
3228priority. When doing priority-based operations, libev usually has to
3229linearly search all the priorities, but starting/stopping and activating
3230watchers becomes O(1) w.r.t. priority handling.
3231
3232=item Sending an ev_async: O(1)
3233
3234=item Processing ev_async_send: O(number_of_async_watchers)
3235
3236=item Processing signals: O(max_signal_number)
3237
3238Sending involves a syscall I<iff> there were no other C<ev_async_send>
3239calls in the current loop iteration. Checking for async and signal events
3240involves iterating over all running async watchers or all signal numbers.
3241
3242=back
3243
3244
3245=head1 Win32 platform limitations and workarounds
3246 4304
3247Win32 doesn't support any of the standards (e.g. POSIX) that libev 4305Win32 doesn't support any of the standards (e.g. POSIX) that libev
3248requires, and its I/O model is fundamentally incompatible with the POSIX 4306requires, and its I/O model is fundamentally incompatible with the POSIX
3249model. Libev still offers limited functionality on this platform in 4307model. Libev still offers limited functionality on this platform in
3250the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4308the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3257way (note also that glib is the slowest event library known to man). 4315way (note also that glib is the slowest event library known to man).
3258 4316
3259There is no supported compilation method available on windows except 4317There is no supported compilation method available on windows except
3260embedding it into other applications. 4318embedding it into other applications.
3261 4319
4320Sensible signal handling is officially unsupported by Microsoft - libev
4321tries its best, but under most conditions, signals will simply not work.
4322
4323Not a libev limitation but worth mentioning: windows apparently doesn't
4324accept large writes: instead of resulting in a partial write, windows will
4325either accept everything or return C<ENOBUFS> if the buffer is too large,
4326so make sure you only write small amounts into your sockets (less than a
4327megabyte seems safe, but this apparently depends on the amount of memory
4328available).
4329
3262Due to the many, low, and arbitrary limits on the win32 platform and 4330Due to the many, low, and arbitrary limits on the win32 platform and
3263the abysmal performance of winsockets, using a large number of sockets 4331the abysmal performance of winsockets, using a large number of sockets
3264is not recommended (and not reasonable). If your program needs to use 4332is not recommended (and not reasonable). If your program needs to use
3265more than a hundred or so sockets, then likely it needs to use a totally 4333more than a hundred or so sockets, then likely it needs to use a totally
3266different implementation for windows, as libev offers the POSIX readiness 4334different implementation for windows, as libev offers the POSIX readiness
3267notification model, which cannot be implemented efficiently on windows 4335notification model, which cannot be implemented efficiently on windows
3268(microsoft monopoly games). 4336(due to Microsoft monopoly games).
4337
4338A typical way to use libev under windows is to embed it (see the embedding
4339section for details) and use the following F<evwrap.h> header file instead
4340of F<ev.h>:
4341
4342 #define EV_STANDALONE /* keeps ev from requiring config.h */
4343 #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */
4344
4345 #include "ev.h"
4346
4347And compile the following F<evwrap.c> file into your project (make sure
4348you do I<not> compile the F<ev.c> or any other embedded source files!):
4349
4350 #include "evwrap.h"
4351 #include "ev.c"
3269 4352
3270=over 4 4353=over 4
3271 4354
3272=item The winsocket select function 4355=item The winsocket select function
3273 4356
3274The winsocket C<select> function doesn't follow POSIX in that it requires 4357The winsocket C<select> function doesn't follow POSIX in that it
3275socket I<handles> and not socket I<file descriptors>. This makes select 4358requires socket I<handles> and not socket I<file descriptors> (it is
3276very inefficient, and also requires a mapping from file descriptors 4359also extremely buggy). This makes select very inefficient, and also
3277to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>, 4360requires a mapping from file descriptors to socket handles (the Microsoft
3278C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor 4361C runtime provides the function C<_open_osfhandle> for this). See the
3279symbols for more info. 4362discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
4363C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
3280 4364
3281The configuration for a "naked" win32 using the microsoft runtime 4365The configuration for a "naked" win32 using the Microsoft runtime
3282libraries and raw winsocket select is: 4366libraries and raw winsocket select is:
3283 4367
3284 #define EV_USE_SELECT 1 4368 #define EV_USE_SELECT 1
3285 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 4369 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3286 4370
3287Note that winsockets handling of fd sets is O(n), so you can easily get a 4371Note that winsockets handling of fd sets is O(n), so you can easily get a
3288complexity in the O(n²) range when using win32. 4372complexity in the O(n²) range when using win32.
3289 4373
3290=item Limited number of file descriptors 4374=item Limited number of file descriptors
3291 4375
3292Windows has numerous arbitrary (and low) limits on things. 4376Windows has numerous arbitrary (and low) limits on things.
3293 4377
3294Early versions of winsocket's select only supported waiting for a maximum 4378Early versions of winsocket's select only supported waiting for a maximum
3295of C<64> handles (probably owning to the fact that all windows kernels 4379of C<64> handles (probably owning to the fact that all windows kernels
3296can only wait for C<64> things at the same time internally; microsoft 4380can only wait for C<64> things at the same time internally; Microsoft
3297recommends spawning a chain of threads and wait for 63 handles and the 4381recommends spawning a chain of threads and wait for 63 handles and the
3298previous thread in each. Great). 4382previous thread in each. Sounds great!).
3299 4383
3300Newer versions support more handles, but you need to define C<FD_SETSIZE> 4384Newer versions support more handles, but you need to define C<FD_SETSIZE>
3301to some high number (e.g. C<2048>) before compiling the winsocket select 4385to some high number (e.g. C<2048>) before compiling the winsocket select
3302call (which might be in libev or elsewhere, for example, perl does its own 4386call (which might be in libev or elsewhere, for example, perl and many
3303select emulation on windows). 4387other interpreters do their own select emulation on windows).
3304 4388
3305Another limit is the number of file descriptors in the microsoft runtime 4389Another limit is the number of file descriptors in the Microsoft runtime
3306libraries, which by default is C<64> (there must be a hidden I<64> fetish 4390libraries, which by default is C<64> (there must be a hidden I<64>
3307or something like this inside microsoft). You can increase this by calling 4391fetish or something like this inside Microsoft). You can increase this
3308C<_setmaxstdio>, which can increase this limit to C<2048> (another 4392by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3309arbitrary limit), but is broken in many versions of the microsoft runtime 4393(another arbitrary limit), but is broken in many versions of the Microsoft
3310libraries.
3311
3312This might get you to about C<512> or C<2048> sockets (depending on 4394runtime libraries. This might get you to about C<512> or C<2048> sockets
3313windows version and/or the phase of the moon). To get more, you need to 4395(depending on windows version and/or the phase of the moon). To get more,
3314wrap all I/O functions and provide your own fd management, but the cost of 4396you need to wrap all I/O functions and provide your own fd management, but
3315calling select (O(n²)) will likely make this unworkable. 4397the cost of calling select (O(n²)) will likely make this unworkable.
3316 4398
3317=back 4399=back
3318 4400
3319
3320=head1 PORTABILITY REQUIREMENTS 4401=head2 PORTABILITY REQUIREMENTS
3321 4402
3322In addition to a working ISO-C implementation, libev relies on a few 4403In addition to a working ISO-C implementation and of course the
3323additional extensions: 4404backend-specific APIs, libev relies on a few additional extensions:
3324 4405
3325=over 4 4406=over 4
3326 4407
4408=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
4409calling conventions regardless of C<ev_watcher_type *>.
4410
4411Libev assumes not only that all watcher pointers have the same internal
4412structure (guaranteed by POSIX but not by ISO C for example), but it also
4413assumes that the same (machine) code can be used to call any watcher
4414callback: The watcher callbacks have different type signatures, but libev
4415calls them using an C<ev_watcher *> internally.
4416
3327=item C<sig_atomic_t volatile> must be thread-atomic as well 4417=item C<sig_atomic_t volatile> must be thread-atomic as well
3328 4418
3329The type C<sig_atomic_t volatile> (or whatever is defined as 4419The type C<sig_atomic_t volatile> (or whatever is defined as
3330C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different 4420C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
3331threads. This is not part of the specification for C<sig_atomic_t>, but is 4421threads. This is not part of the specification for C<sig_atomic_t>, but is
3332believed to be sufficiently portable. 4422believed to be sufficiently portable.
3333 4423
3334=item C<sigprocmask> must work in a threaded environment 4424=item C<sigprocmask> must work in a threaded environment
3335 4425
3344except the initial one, and run the default loop in the initial thread as 4434except the initial one, and run the default loop in the initial thread as
3345well. 4435well.
3346 4436
3347=item C<long> must be large enough for common memory allocation sizes 4437=item C<long> must be large enough for common memory allocation sizes
3348 4438
3349To improve portability and simplify using libev, libev uses C<long> 4439To improve portability and simplify its API, libev uses C<long> internally
3350internally instead of C<size_t> when allocating its data structures. On 4440instead of C<size_t> when allocating its data structures. On non-POSIX
3351non-POSIX systems (Microsoft...) this might be unexpectedly low, but 4441systems (Microsoft...) this might be unexpectedly low, but is still at
3352is still at least 31 bits everywhere, which is enough for hundreds of 4442least 31 bits everywhere, which is enough for hundreds of millions of
3353millions of watchers. 4443watchers.
3354 4444
3355=item C<double> must hold a time value in seconds with enough accuracy 4445=item C<double> must hold a time value in seconds with enough accuracy
3356 4446
3357The type C<double> is used to represent timestamps. It is required to 4447The type C<double> is used to represent timestamps. It is required to
3358have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4448have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3359enough for at least into the year 4000. This requirement is fulfilled by 4449enough for at least into the year 4000. This requirement is fulfilled by
3360implementations implementing IEEE 754 (basically all existing ones). 4450implementations implementing IEEE 754, which is basically all existing
4451ones. With IEEE 754 doubles, you get microsecond accuracy until at least
44522200.
3361 4453
3362=back 4454=back
3363 4455
3364If you know of other additional requirements drop me a note. 4456If you know of other additional requirements drop me a note.
3365 4457
3366 4458
3367=head1 VALGRIND 4459=head1 ALGORITHMIC COMPLEXITIES
3368 4460
3369Valgrind has a special section here because it is a popular tool that is 4461In this section the complexities of (many of) the algorithms used inside
3370highly useful, but valgrind reports are very hard to interpret. 4462libev will be documented. For complexity discussions about backends see
4463the documentation for C<ev_default_init>.
3371 4464
3372If you think you found a bug (memory leak, uninitialised data access etc.) 4465All of the following are about amortised time: If an array needs to be
3373in libev, then check twice: If valgrind reports something like: 4466extended, libev needs to realloc and move the whole array, but this
4467happens asymptotically rarer with higher number of elements, so O(1) might
4468mean that libev does a lengthy realloc operation in rare cases, but on
4469average it is much faster and asymptotically approaches constant time.
3374 4470
3375 ==2274== definitely lost: 0 bytes in 0 blocks. 4471=over 4
3376 ==2274== possibly lost: 0 bytes in 0 blocks.
3377 ==2274== still reachable: 256 bytes in 1 blocks.
3378 4472
3379then there is no memory leak. Similarly, under some circumstances, 4473=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
3380valgrind might report kernel bugs as if it were a bug in libev, or it
3381might be confused (it is a very good tool, but only a tool).
3382 4474
3383If you are unsure about something, feel free to contact the mailing list 4475This means that, when you have a watcher that triggers in one hour and
3384with the full valgrind report and an explanation on why you think this is 4476there are 100 watchers that would trigger before that, then inserting will
3385a bug in libev. However, don't be annoyed when you get a brisk "this is 4477have to skip roughly seven (C<ld 100>) of these watchers.
3386no bug" answer and take the chance of learning how to interpret valgrind
3387properly.
3388 4478
3389If you need, for some reason, empty reports from valgrind for your project 4479=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
3390I suggest using suppression lists.
3391 4480
4481That means that changing a timer costs less than removing/adding them,
4482as only the relative motion in the event queue has to be paid for.
4483
4484=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
4485
4486These just add the watcher into an array or at the head of a list.
4487
4488=item Stopping check/prepare/idle/fork/async watchers: O(1)
4489
4490=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
4491
4492These watchers are stored in lists, so they need to be walked to find the
4493correct watcher to remove. The lists are usually short (you don't usually
4494have many watchers waiting for the same fd or signal: one is typical, two
4495is rare).
4496
4497=item Finding the next timer in each loop iteration: O(1)
4498
4499By virtue of using a binary or 4-heap, the next timer is always found at a
4500fixed position in the storage array.
4501
4502=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
4503
4504A change means an I/O watcher gets started or stopped, which requires
4505libev to recalculate its status (and possibly tell the kernel, depending
4506on backend and whether C<ev_io_set> was used).
4507
4508=item Activating one watcher (putting it into the pending state): O(1)
4509
4510=item Priority handling: O(number_of_priorities)
4511
4512Priorities are implemented by allocating some space for each
4513priority. When doing priority-based operations, libev usually has to
4514linearly search all the priorities, but starting/stopping and activating
4515watchers becomes O(1) with respect to priority handling.
4516
4517=item Sending an ev_async: O(1)
4518
4519=item Processing ev_async_send: O(number_of_async_watchers)
4520
4521=item Processing signals: O(max_signal_number)
4522
4523Sending involves a system call I<iff> there were no other C<ev_async_send>
4524calls in the current loop iteration. Checking for async and signal events
4525involves iterating over all running async watchers or all signal numbers.
4526
4527=back
4528
4529
4530=head1 GLOSSARY
4531
4532=over 4
4533
4534=item active
4535
4536A watcher is active as long as it has been started (has been attached to
4537an event loop) but not yet stopped (disassociated from the event loop).
4538
4539=item application
4540
4541In this document, an application is whatever is using libev.
4542
4543=item callback
4544
4545The address of a function that is called when some event has been
4546detected. Callbacks are being passed the event loop, the watcher that
4547received the event, and the actual event bitset.
4548
4549=item callback invocation
4550
4551The act of calling the callback associated with a watcher.
4552
4553=item event
4554
4555A change of state of some external event, such as data now being available
4556for reading on a file descriptor, time having passed or simply not having
4557any other events happening anymore.
4558
4559In libev, events are represented as single bits (such as C<EV_READ> or
4560C<EV_TIMEOUT>).
4561
4562=item event library
4563
4564A software package implementing an event model and loop.
4565
4566=item event loop
4567
4568An entity that handles and processes external events and converts them
4569into callback invocations.
4570
4571=item event model
4572
4573The model used to describe how an event loop handles and processes
4574watchers and events.
4575
4576=item pending
4577
4578A watcher is pending as soon as the corresponding event has been detected,
4579and stops being pending as soon as the watcher will be invoked or its
4580pending status is explicitly cleared by the application.
4581
4582A watcher can be pending, but not active. Stopping a watcher also clears
4583its pending status.
4584
4585=item real time
4586
4587The physical time that is observed. It is apparently strictly monotonic :)
4588
4589=item wall-clock time
4590
4591The time and date as shown on clocks. Unlike real time, it can actually
4592be wrong and jump forwards and backwards, e.g. when the you adjust your
4593clock.
4594
4595=item watcher
4596
4597A data structure that describes interest in certain events. Watchers need
4598to be started (attached to an event loop) before they can receive events.
4599
4600=item watcher invocation
4601
4602The act of calling the callback associated with a watcher.
4603
4604=back
3392 4605
3393=head1 AUTHOR 4606=head1 AUTHOR
3394 4607
3395Marc Lehmann <libev@schmorp.de>. 4608Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3396 4609

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines