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

Comparing libev/ev.pod (file contents):
Revision 1.114 by root, Mon Dec 31 01:31:30 2007 UTC vs.
Revision 1.177 by root, Mon Sep 8 17:27:42 2008 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines