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

Comparing libev/ev.pod (file contents):
Revision 1.213 by root, Wed Nov 5 02:48:45 2008 UTC vs.
Revision 1.455 by root, Wed Jun 26 00:01:46 2019 UTC

1=encoding utf-8
2
1=head1 NAME 3=head1 NAME
2 4
3libev - a high performance full-featured event loop written in C 5libev - a high performance full-featured event loop written in C
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
8 10
9=head2 EXAMPLE PROGRAM 11=head2 EXAMPLE PROGRAM
10 12
11 // a single header file is required 13 // a single header file is required
12 #include <ev.h> 14 #include <ev.h>
15
16 #include <stdio.h> // for puts
13 17
14 // every watcher type has its own typedef'd struct 18 // every watcher type has its own typedef'd struct
15 // with the name ev_TYPE 19 // with the name ev_TYPE
16 ev_io stdin_watcher; 20 ev_io stdin_watcher;
17 ev_timer timeout_watcher; 21 ev_timer timeout_watcher;
24 puts ("stdin ready"); 28 puts ("stdin ready");
25 // for one-shot events, one must manually stop the watcher 29 // for one-shot events, one must manually stop the watcher
26 // with its corresponding stop function. 30 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w); 31 ev_io_stop (EV_A_ w);
28 32
29 // this causes all nested ev_loop's to stop iterating 33 // this causes all nested ev_run's to stop iterating
30 ev_unloop (EV_A_ EVUNLOOP_ALL); 34 ev_break (EV_A_ EVBREAK_ALL);
31 } 35 }
32 36
33 // another callback, this time for a time-out 37 // another callback, this time for a time-out
34 static void 38 static void
35 timeout_cb (EV_P_ ev_timer *w, int revents) 39 timeout_cb (EV_P_ ev_timer *w, int revents)
36 { 40 {
37 puts ("timeout"); 41 puts ("timeout");
38 // this causes the innermost ev_loop to stop iterating 42 // this causes the innermost ev_run to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE); 43 ev_break (EV_A_ EVBREAK_ONE);
40 } 44 }
41 45
42 int 46 int
43 main (void) 47 main (void)
44 { 48 {
45 // use the default event loop unless you have special needs 49 // use the default event loop unless you have special needs
46 ev_loop *loop = ev_default_loop (0); 50 struct ev_loop *loop = EV_DEFAULT;
47 51
48 // initialise an io watcher, then start it 52 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable 53 // this one will watch for stdin to become readable
50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 54 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
51 ev_io_start (loop, &stdin_watcher); 55 ev_io_start (loop, &stdin_watcher);
54 // simple non-repeating 5.5 second timeout 58 // simple non-repeating 5.5 second timeout
55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 59 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
56 ev_timer_start (loop, &timeout_watcher); 60 ev_timer_start (loop, &timeout_watcher);
57 61
58 // now wait for events to arrive 62 // now wait for events to arrive
59 ev_loop (loop, 0); 63 ev_run (loop, 0);
60 64
61 // unloop was called, so exit 65 // break was called, so exit
62 return 0; 66 return 0;
63 } 67 }
64 68
65=head1 DESCRIPTION 69=head1 ABOUT THIS DOCUMENT
70
71This document documents the libev software package.
66 72
67The newest version of this document is also available as an html-formatted 73The newest version of this document is also available as an html-formatted
68web page you might find easier to navigate when reading it for the first 74web page you might find easier to navigate when reading it for the first
69time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. 75time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
76
77While this document tries to be as complete as possible in documenting
78libev, its usage and the rationale behind its design, it is not a tutorial
79on event-based programming, nor will it introduce event-based programming
80with libev.
81
82Familiarity with event based programming techniques in general is assumed
83throughout this document.
84
85=head1 WHAT TO READ WHEN IN A HURRY
86
87This manual tries to be very detailed, but unfortunately, this also makes
88it very long. If you just want to know the basics of libev, I suggest
89reading L</ANATOMY OF A WATCHER>, then the L</EXAMPLE PROGRAM> above and
90look up the missing functions in L</GLOBAL FUNCTIONS> and the C<ev_io> and
91C<ev_timer> sections in L</WATCHER TYPES>.
92
93=head1 ABOUT LIBEV
70 94
71Libev is an event loop: you register interest in certain events (such as a 95Libev is an event loop: you register interest in certain events (such as a
72file descriptor being readable or a timeout occurring), and it will manage 96file descriptor being readable or a timeout occurring), and it will manage
73these event sources and provide your program with events. 97these event sources and provide your program with events.
74 98
81details of the event, and then hand it over to libev by I<starting> the 105details of the event, and then hand it over to libev by I<starting> the
82watcher. 106watcher.
83 107
84=head2 FEATURES 108=head2 FEATURES
85 109
86Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 110Libev supports C<select>, C<poll>, the Linux-specific aio and C<epoll>
87BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 111interfaces, the BSD-specific C<kqueue> and the Solaris-specific event port
88for file descriptor events (C<ev_io>), the Linux C<inotify> interface 112mechanisms for file descriptor events (C<ev_io>), the Linux C<inotify>
89(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 113interface (for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
90with customised rescheduling (C<ev_periodic>), synchronous signals 114inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
91(C<ev_signal>), process status change events (C<ev_child>), and event 115timers (C<ev_timer>), absolute timers with customised rescheduling
92watchers dealing with the event loop mechanism itself (C<ev_idle>, 116(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
93C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 117change events (C<ev_child>), and event watchers dealing with the event
94file watchers (C<ev_stat>) and even limited support for fork events 118loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
95(C<ev_fork>). 119C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
120limited support for fork events (C<ev_fork>).
96 121
97It also is quite fast (see this 122It also is quite fast (see this
98L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 123L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
99for example). 124for example).
100 125
103Libev is very configurable. In this manual the default (and most common) 128Libev is very configurable. In this manual the default (and most common)
104configuration will be described, which supports multiple event loops. For 129configuration will be described, which supports multiple event loops. For
105more info about various configuration options please have a look at 130more info about various configuration options please have a look at
106B<EMBED> section in this manual. If libev was configured without support 131B<EMBED> section in this manual. If libev was configured without support
107for multiple event loops, then all functions taking an initial argument of 132for multiple event loops, then all functions taking an initial argument of
108name C<loop> (which is always of type C<ev_loop *>) will not have 133name C<loop> (which is always of type C<struct ev_loop *>) will not have
109this argument. 134this argument.
110 135
111=head2 TIME REPRESENTATION 136=head2 TIME REPRESENTATION
112 137
113Libev represents time as a single floating point number, representing the 138Libev represents time as a single floating point number, representing
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 139the (fractional) number of seconds since the (POSIX) epoch (in practice
115the beginning of 1970, details are complicated, don't ask). This type is 140somewhere near the beginning of 1970, details are complicated, don't
116called C<ev_tstamp>, which is what you should use too. It usually aliases 141ask). This type is called C<ev_tstamp>, which is what you should use
117to the C<double> type in C, and when you need to do any calculations on 142too. It usually aliases to the C<double> type in C. When you need to do
118it, you should treat it as some floating point value. Unlike the name 143any calculations on it, you should treat it as some floating point value.
144
119component C<stamp> might indicate, it is also used for time differences 145Unlike the name component C<stamp> might indicate, it is also used for
120throughout libev. 146time differences (e.g. delays) throughout libev.
121 147
122=head1 ERROR HANDLING 148=head1 ERROR HANDLING
123 149
124Libev knows three classes of errors: operating system errors, usage errors 150Libev knows three classes of errors: operating system errors, usage errors
125and internal errors (bugs). 151and internal errors (bugs).
133When libev detects a usage error such as a negative timer interval, then 159When 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, 160it will print a diagnostic message and abort (via the C<assert> mechanism,
135so C<NDEBUG> will disable this checking): these are programming errors in 161so C<NDEBUG> will disable this checking): these are programming errors in
136the libev caller and need to be fixed there. 162the libev caller and need to be fixed there.
137 163
164Via the C<EV_FREQUENT> macro you can compile in and/or enable extensive
165consistency checking code inside libev that can be used to check for
166internal inconsistencies, suually caused by application bugs.
167
138Libev also has a few internal error-checking C<assert>ions, and also has 168Libev also has a few internal error-checking C<assert>ions. These do not
139extensive consistency checking code. These do not trigger under normal
140circumstances, as they indicate either a bug in libev or worse. 169trigger under normal circumstances, as they indicate either a bug in libev
170or worse.
141 171
142 172
143=head1 GLOBAL FUNCTIONS 173=head1 GLOBAL FUNCTIONS
144 174
145These functions can be called anytime, even before initialising the 175These functions can be called anytime, even before initialising the
149 179
150=item ev_tstamp ev_time () 180=item ev_tstamp ev_time ()
151 181
152Returns the current time as libev would use it. Please note that the 182Returns the current time as libev would use it. Please note that the
153C<ev_now> function is usually faster and also often returns the timestamp 183C<ev_now> function is usually faster and also often returns the timestamp
154you actually want to know. 184you actually want to know. Also interesting is the combination of
185C<ev_now_update> and C<ev_now>.
155 186
156=item ev_sleep (ev_tstamp interval) 187=item ev_sleep (ev_tstamp interval)
157 188
158Sleep for the given interval: The current thread will be blocked until 189Sleep for the given interval: The current thread will be blocked
159either it is interrupted or the given time interval has passed. Basically 190until either it is interrupted or the given time interval has
191passed (approximately - it might return a bit earlier even if not
192interrupted). Returns immediately if C<< interval <= 0 >>.
193
160this is a sub-second-resolution C<sleep ()>. 194Basically this is a sub-second-resolution C<sleep ()>.
195
196The range of the C<interval> is limited - libev only guarantees to work
197with sleep times of up to one day (C<< interval <= 86400 >>).
161 198
162=item int ev_version_major () 199=item int ev_version_major ()
163 200
164=item int ev_version_minor () 201=item int ev_version_minor ()
165 202
176as this indicates an incompatible change. Minor versions are usually 213as this indicates an incompatible change. Minor versions are usually
177compatible to older versions, so a larger minor version alone is usually 214compatible to older versions, so a larger minor version alone is usually
178not a problem. 215not a problem.
179 216
180Example: Make sure we haven't accidentally been linked against the wrong 217Example: Make sure we haven't accidentally been linked against the wrong
181version. 218version (note, however, that this will not detect other ABI mismatches,
219such as LFS or reentrancy).
182 220
183 assert (("libev version mismatch", 221 assert (("libev version mismatch",
184 ev_version_major () == EV_VERSION_MAJOR 222 ev_version_major () == EV_VERSION_MAJOR
185 && ev_version_minor () >= EV_VERSION_MINOR)); 223 && ev_version_minor () >= EV_VERSION_MINOR));
186 224
197 assert (("sorry, no epoll, no sex", 235 assert (("sorry, no epoll, no sex",
198 ev_supported_backends () & EVBACKEND_EPOLL)); 236 ev_supported_backends () & EVBACKEND_EPOLL));
199 237
200=item unsigned int ev_recommended_backends () 238=item unsigned int ev_recommended_backends ()
201 239
202Return the set of all backends compiled into this binary of libev and also 240Return the set of all backends compiled into this binary of libev and
203recommended for this platform. This set is often smaller than the one 241also recommended for this platform, meaning it will work for most file
242descriptor types. This set is often smaller than the one returned by
204returned by C<ev_supported_backends>, as for example kqueue is broken on 243C<ev_supported_backends>, as for example kqueue is broken on most BSDs
205most BSDs and will not be auto-detected unless you explicitly request it 244and will not be auto-detected unless you explicitly request it (assuming
206(assuming you know what you are doing). This is the set of backends that 245you know what you are doing). This is the set of backends that libev will
207libev will probe for if you specify no backends explicitly. 246probe for if you specify no backends explicitly.
208 247
209=item unsigned int ev_embeddable_backends () 248=item unsigned int ev_embeddable_backends ()
210 249
211Returns the set of backends that are embeddable in other event loops. This 250Returns the set of backends that are embeddable in other event loops. This
212is the theoretical, all-platform, value. To find which backends 251value is platform-specific but can include backends not available on the
213might be supported on the current system, you would need to look at 252current system. To find which embeddable backends might be supported on
214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 253the current system, you would need to look at C<ev_embeddable_backends ()
215recommended ones. 254& ev_supported_backends ()>, likewise for recommended ones.
216 255
217See the description of C<ev_embed> watchers for more info. 256See the description of C<ev_embed> watchers for more info.
218 257
219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] 258=item ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())
220 259
221Sets the allocation function to use (the prototype is similar - the 260Sets the allocation function to use (the prototype is similar - the
222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 261semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
223used to allocate and free memory (no surprises here). If it returns zero 262used to allocate and free memory (no surprises here). If it returns zero
224when memory needs to be allocated (C<size != 0>), the library might abort 263when memory needs to be allocated (C<size != 0>), the library might abort
230 269
231You could override this function in high-availability programs to, say, 270You could override this function in high-availability programs to, say,
232free some memory if it cannot allocate memory, to use a special allocator, 271free some memory if it cannot allocate memory, to use a special allocator,
233or even to sleep a while and retry until some memory is available. 272or even to sleep a while and retry until some memory is available.
234 273
274Example: The following is the C<realloc> function that libev itself uses
275which should work with C<realloc> and C<free> functions of all kinds and
276is probably a good basis for your own implementation.
277
278 static void *
279 ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
280 {
281 if (size)
282 return realloc (ptr, size);
283
284 free (ptr);
285 return 0;
286 }
287
235Example: Replace the libev allocator with one that waits a bit and then 288Example: Replace the libev allocator with one that waits a bit and then
236retries (example requires a standards-compliant C<realloc>). 289retries.
237 290
238 static void * 291 static void *
239 persistent_realloc (void *ptr, size_t size) 292 persistent_realloc (void *ptr, size_t size)
240 { 293 {
294 if (!size)
295 {
296 free (ptr);
297 return 0;
298 }
299
241 for (;;) 300 for (;;)
242 { 301 {
243 void *newptr = realloc (ptr, size); 302 void *newptr = realloc (ptr, size);
244 303
245 if (newptr) 304 if (newptr)
250 } 309 }
251 310
252 ... 311 ...
253 ev_set_allocator (persistent_realloc); 312 ev_set_allocator (persistent_realloc);
254 313
255=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT] 314=item ev_set_syserr_cb (void (*cb)(const char *msg) throw ())
256 315
257Set the callback function to call on a retryable system call error (such 316Set the callback function to call on a retryable system call error (such
258as failed select, poll, epoll_wait). The message is a printable string 317as failed select, poll, epoll_wait). The message is a printable string
259indicating the system call or subsystem causing the problem. If this 318indicating the system call or subsystem causing the problem. If this
260callback is set, then libev will expect it to remedy the situation, no 319callback is set, then libev will expect it to remedy the situation, no
272 } 331 }
273 332
274 ... 333 ...
275 ev_set_syserr_cb (fatal_error); 334 ev_set_syserr_cb (fatal_error);
276 335
336=item ev_feed_signal (int signum)
337
338This function can be used to "simulate" a signal receive. It is completely
339safe to call this function at any time, from any context, including signal
340handlers or random threads.
341
342Its main use is to customise signal handling in your process, especially
343in the presence of threads. For example, you could block signals
344by default in all threads (and specifying C<EVFLAG_NOSIGMASK> when
345creating any loops), and in one thread, use C<sigwait> or any other
346mechanism to wait for signals, then "deliver" them to libev by calling
347C<ev_feed_signal>.
348
277=back 349=back
278 350
279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 351=head1 FUNCTIONS CONTROLLING EVENT LOOPS
280 352
281An event loop is described by a C<struct ev_loop *> (the C<struct> 353An event loop is described by a C<struct ev_loop *> (the C<struct> is
282is I<not> optional in this case, as there is also an C<ev_loop> 354I<not> optional in this case unless libev 3 compatibility is disabled, as
283I<function>). 355libev 3 had an C<ev_loop> function colliding with the struct name).
284 356
285The library knows two types of such loops, the I<default> loop, which 357The library knows two types of such loops, the I<default> loop, which
286supports signals and child events, and dynamically created loops which do 358supports child process events, and dynamically created event loops which
287not. 359do not.
288 360
289=over 4 361=over 4
290 362
291=item struct ev_loop *ev_default_loop (unsigned int flags) 363=item struct ev_loop *ev_default_loop (unsigned int flags)
292 364
293This will initialise the default event loop if it hasn't been initialised 365This returns the "default" event loop object, which is what you should
294yet and return it. If the default loop could not be initialised, returns 366normally use when you just need "the event loop". Event loop objects and
295false. If it already was initialised it simply returns it (and ignores the 367the C<flags> parameter are described in more detail in the entry for
296flags. If that is troubling you, check C<ev_backend ()> afterwards). 368C<ev_loop_new>.
369
370If the default loop is already initialised then this function simply
371returns it (and ignores the flags. If that is troubling you, check
372C<ev_backend ()> afterwards). Otherwise it will create it with the given
373flags, which should almost always be C<0>, unless the caller is also the
374one calling C<ev_run> or otherwise qualifies as "the main program".
297 375
298If you don't know what event loop to use, use the one returned from this 376If you don't know what event loop to use, use the one returned from this
299function. 377function (or via the C<EV_DEFAULT> macro).
300 378
301Note that this function is I<not> thread-safe, so if you want to use it 379Note that this function is I<not> thread-safe, so if you want to use it
302from multiple threads, you have to lock (note also that this is unlikely, 380from multiple threads, you have to employ some kind of mutex (note also
303as loops cannot be shared easily between threads anyway). 381that this case is unlikely, as loops cannot be shared easily between
382threads anyway).
304 383
305The default loop is the only loop that can handle C<ev_signal> and 384The default loop is the only loop that can handle C<ev_child> watchers,
306C<ev_child> watchers, and to do this, it always registers a handler 385and to do this, it always registers a handler for C<SIGCHLD>. If this is
307for C<SIGCHLD>. If this is a problem for your application you can either 386a problem for your application you can either create a dynamic loop with
308create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 387C<ev_loop_new> which doesn't do that, or you can simply overwrite the
309can simply overwrite the C<SIGCHLD> signal handler I<after> calling 388C<SIGCHLD> signal handler I<after> calling C<ev_default_init>.
310C<ev_default_init>. 389
390Example: This is the most typical usage.
391
392 if (!ev_default_loop (0))
393 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
394
395Example: Restrict libev to the select and poll backends, and do not allow
396environment settings to be taken into account:
397
398 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
399
400=item struct ev_loop *ev_loop_new (unsigned int flags)
401
402This will create and initialise a new event loop object. If the loop
403could not be initialised, returns false.
404
405This function is thread-safe, and one common way to use libev with
406threads is indeed to create one loop per thread, and using the default
407loop in the "main" or "initial" thread.
311 408
312The flags argument can be used to specify special behaviour or specific 409The flags argument can be used to specify special behaviour or specific
313backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>). 410backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
314 411
315The following flags are supported: 412The following flags are supported:
325 422
326If this flag bit is or'ed into the flag value (or the program runs setuid 423If this flag bit is or'ed into the flag value (or the program runs setuid
327or setgid) then libev will I<not> look at the environment variable 424or setgid) then libev will I<not> look at the environment variable
328C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 425C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
329override the flags completely if it is found in the environment. This is 426override the flags completely if it is found in the environment. This is
330useful to try out specific backends to test their performance, or to work 427useful to try out specific backends to test their performance, to work
331around bugs. 428around bugs, or to make libev threadsafe (accessing environment variables
429cannot be done in a threadsafe way, but usually it works if no other
430thread modifies them).
332 431
333=item C<EVFLAG_FORKCHECK> 432=item C<EVFLAG_FORKCHECK>
334 433
335Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 434Instead of calling C<ev_loop_fork> manually after a fork, you can also
336a fork, you can also make libev check for a fork in each iteration by 435make libev check for a fork in each iteration by enabling this flag.
337enabling this flag.
338 436
339This works by calling C<getpid ()> on every iteration of the loop, 437This works by calling C<getpid ()> on every iteration of the loop,
340and thus this might slow down your event loop if you do a lot of loop 438and thus this might slow down your event loop if you do a lot of loop
341iterations and little real work, but is usually not noticeable (on my 439iterations and little real work, but is usually not noticeable (on my
342GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 440GNU/Linux system for example, C<getpid> is actually a simple 5-insn
343without a system call and thus I<very> fast, but my GNU/Linux system also has 441sequence without a system call and thus I<very> fast, but my GNU/Linux
344C<pthread_atfork> which is even faster). 442system also has C<pthread_atfork> which is even faster). (Update: glibc
443versions 2.25 apparently removed the C<getpid> optimisation again).
345 444
346The big advantage of this flag is that you can forget about fork (and 445The big advantage of this flag is that you can forget about fork (and
347forget about forgetting to tell libev about forking) when you use this 446forget about forgetting to tell libev about forking, although you still
348flag. 447have to ignore C<SIGPIPE>) when you use this flag.
349 448
350This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 449This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
351environment variable. 450environment variable.
451
452=item C<EVFLAG_NOINOTIFY>
453
454When this flag is specified, then libev will not attempt to use the
455I<inotify> API for its C<ev_stat> watchers. Apart from debugging and
456testing, this flag can be useful to conserve inotify file descriptors, as
457otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
458
459=item C<EVFLAG_SIGNALFD>
460
461When this flag is specified, then libev will attempt to use the
462I<signalfd> API for its C<ev_signal> (and C<ev_child>) watchers. This API
463delivers signals synchronously, which makes it both faster and might make
464it possible to get the queued signal data. It can also simplify signal
465handling with threads, as long as you properly block signals in your
466threads that are not interested in handling them.
467
468Signalfd will not be used by default as this changes your signal mask, and
469there are a lot of shoddy libraries and programs (glib's threadpool for
470example) that can't properly initialise their signal masks.
471
472=item C<EVFLAG_NOSIGMASK>
473
474When this flag is specified, then libev will avoid to modify the signal
475mask. Specifically, this means you have to make sure signals are unblocked
476when you want to receive them.
477
478This behaviour is useful when you want to do your own signal handling, or
479want to handle signals only in specific threads and want to avoid libev
480unblocking the signals.
481
482It's also required by POSIX in a threaded program, as libev calls
483C<sigprocmask>, whose behaviour is officially unspecified.
484
485This flag's behaviour will become the default in future versions of libev.
352 486
353=item C<EVBACKEND_SELECT> (value 1, portable select backend) 487=item C<EVBACKEND_SELECT> (value 1, portable select backend)
354 488
355This is your standard select(2) backend. Not I<completely> standard, as 489This is your standard select(2) backend. Not I<completely> standard, as
356libev tries to roll its own fd_set with no limits on the number of fds, 490libev tries to roll its own fd_set with no limits on the number of fds,
381This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 515This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
382C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 516C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
383 517
384=item C<EVBACKEND_EPOLL> (value 4, Linux) 518=item C<EVBACKEND_EPOLL> (value 4, Linux)
385 519
520Use the Linux-specific epoll(7) interface (for both pre- and post-2.6.9
521kernels).
522
386For few fds, this backend is a bit little slower than poll and select, 523For few fds, this backend is a bit little slower than poll and select, but
387but it scales phenomenally better. While poll and select usually scale 524it scales phenomenally better. While poll and select usually scale like
388like O(total_fds) where n is the total number of fds (or the highest fd), 525O(total_fds) where total_fds is the total number of fds (or the highest
389epoll scales either O(1) or O(active_fds). 526fd), epoll scales either O(1) or O(active_fds).
390 527
391The epoll mechanism deserves honorable mention as the most misdesigned 528The epoll mechanism deserves honorable mention as the most misdesigned
392of the more advanced event mechanisms: mere annoyances include silently 529of the more advanced event mechanisms: mere annoyances include silently
393dropping file descriptors, requiring a system call per change per file 530dropping file descriptors, requiring a system call per change per file
394descriptor (and unnecessary guessing of parameters), problems with dup and 531descriptor (and unnecessary guessing of parameters), problems with dup,
532returning before the timeout value, resulting in additional iterations
533(and only giving 5ms accuracy while select on the same platform gives
395so on. The biggest issue is fork races, however - if a program forks then 5340.1ms) and so on. The biggest issue is fork races, however - if a program
396I<both> parent and child process have to recreate the epoll set, which can 535forks then I<both> parent and child process have to recreate the epoll
397take considerable time (one syscall per file descriptor) and is of course 536set, which can take considerable time (one syscall per file descriptor)
398hard to detect. 537and is of course hard to detect.
399 538
400Epoll is also notoriously buggy - embedding epoll fds I<should> work, but 539Epoll is also notoriously buggy - embedding epoll fds I<should> work,
401of course I<doesn't>, and epoll just loves to report events for totally 540but of course I<doesn't>, and epoll just loves to report events for
402I<different> file descriptors (even already closed ones, so one cannot 541totally I<different> file descriptors (even already closed ones, so
403even remove them from the set) than registered in the set (especially 542one cannot even remove them from the set) than registered in the set
404on SMP systems). Libev tries to counter these spurious notifications by 543(especially on SMP systems). Libev tries to counter these spurious
405employing an additional generation counter and comparing that against the 544notifications by employing an additional generation counter and comparing
406events to filter out spurious ones, recreating the set when required. 545that against the events to filter out spurious ones, recreating the set
546when required. Epoll also erroneously rounds down timeouts, but gives you
547no way to know when and by how much, so sometimes you have to busy-wait
548because epoll returns immediately despite a nonzero timeout. And last
549not least, it also refuses to work with some file descriptors which work
550perfectly fine with C<select> (files, many character devices...).
551
552Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
553cobbled together in a hurry, no thought to design or interaction with
554others. Oh, the pain, will it ever stop...
407 555
408While stopping, setting and starting an I/O watcher in the same iteration 556While stopping, setting and starting an I/O watcher in the same iteration
409will result in some caching, there is still a system call per such 557will result in some caching, there is still a system call per such
410incident (because the same I<file descriptor> could point to a different 558incident (because the same I<file descriptor> could point to a different
411I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 559I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
418starting a watcher (without re-setting it) also usually doesn't cause 566starting a watcher (without re-setting it) also usually doesn't cause
419extra overhead. A fork can both result in spurious notifications as well 567extra overhead. A fork can both result in spurious notifications as well
420as in libev having to destroy and recreate the epoll object, which can 568as in libev having to destroy and recreate the epoll object, which can
421take considerable time and thus should be avoided. 569take considerable time and thus should be avoided.
422 570
423All this means that, in practise, C<EVBACKEND_SELECT> is as fast or faster 571All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
424then epoll for maybe up to a hundred file descriptors. So sad. 572faster than epoll for maybe up to a hundred file descriptors, depending on
573the usage. So sad.
425 574
426While nominally embeddable in other event loops, this feature is broken in 575While nominally embeddable in other event loops, this feature is broken in
427all kernel versions tested so far. 576a lot of kernel revisions, but probably(!) works in current versions.
428 577
429This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 578This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
430C<EVBACKEND_POLL>. 579C<EVBACKEND_POLL>.
431 580
581=item C<EVBACKEND_LINUXAIO> (value 64, Linux)
582
583Use the Linux-specific Linux AIO (I<not> C<< aio(7) >> but C<<
584io_submit(2) >>) event interface available in post-4.18 kernels (but libev
585only tries to use it in 4.19+).
586
587This is another Linux train wreck of an event interface.
588
589If this backend works for you (as of this writing, it was very
590experimental), it is the best event interface available on Linux and might
591be well worth enabling it - if it isn't available in your kernel this will
592be detected and this backend will be skipped.
593
594This backend can batch oneshot requests and supports a user-space ring
595buffer to receive events. It also doesn't suffer from most of the design
596problems of epoll (such as not being able to remove event sources from
597the epoll set), and generally sounds too good to be true. Because, this
598being the Linux kernel, of course it suffers from a whole new set of
599limitations, forcing you to fall back to epoll, inheriting all its design
600issues.
601
602For one, it is not easily embeddable (but probably could be done using
603an event fd at some extra overhead). It also is subject to a system wide
604limit that can be configured in F</proc/sys/fs/aio-max-nr>. If no AIO
605requests are left, this backend will be skipped during initialisation, and
606will switch to epoll when the loop is active.
607
608Most problematic in practice, however, is that not all file descriptors
609work with it. For example, in Linux 5.1, TCP sockets, pipes, event fds,
610files, F</dev/null> and many others are supported, but ttys do not work
611properly (a known bug that the kernel developers don't care about, see
612L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
613(yet?) a generic event polling interface.
614
615Overall, it seems the Linux developers just don't want it to have a
616generic event handling mechanism other than C<select> or C<poll>.
617
618To work around all these problem, the current version of libev uses its
619epoll backend as a fallback for file descriptor types that do not work. Or
620falls back completely to epoll if the kernel acts up.
621
622This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
623C<EVBACKEND_POLL>.
624
432=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 625=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
433 626
434Kqueue deserves special mention, as at the time of this writing, it 627Kqueue deserves special mention, as at the time this backend was
435was broken on all BSDs except NetBSD (usually it doesn't work reliably 628implemented, it was broken on all BSDs except NetBSD (usually it doesn't
436with anything but sockets and pipes, except on Darwin, where of course 629work reliably with anything but sockets and pipes, except on Darwin,
437it's completely useless). Unlike epoll, however, whose brokenness 630where of course it's completely useless). Unlike epoll, however, whose
438is by design, these kqueue bugs can (and eventually will) be fixed 631brokenness is by design, these kqueue bugs can be (and mostly have been)
439without API changes to existing programs. For this reason it's not being 632fixed without API changes to existing programs. For this reason it's not
440"auto-detected" unless you explicitly specify it in the flags (i.e. using 633being "auto-detected" on all platforms unless you explicitly specify it
441C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 634in the flags (i.e. using C<EVBACKEND_KQUEUE>) or libev was compiled on a
442system like NetBSD. 635known-to-be-good (-enough) system like NetBSD.
443 636
444You still can embed kqueue into a normal poll or select backend and use it 637You still can embed kqueue into a normal poll or select backend and use it
445only for sockets (after having made sure that sockets work with kqueue on 638only for sockets (after having made sure that sockets work with kqueue on
446the target platform). See C<ev_embed> watchers for more info. 639the target platform). See C<ev_embed> watchers for more info.
447 640
448It scales in the same way as the epoll backend, but the interface to the 641It scales in the same way as the epoll backend, but the interface to the
449kernel is more efficient (which says nothing about its actual speed, of 642kernel is more efficient (which says nothing about its actual speed, of
450course). While stopping, setting and starting an I/O watcher does never 643course). While stopping, setting and starting an I/O watcher does never
451cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 644cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
452two event changes per incident. Support for C<fork ()> is very bad (but 645two event changes per incident. Support for C<fork ()> is very bad (you
453sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 646might have to leak fds on fork, but it's more sane than epoll) and it
454cases 647drops fds silently in similarly hard-to-detect cases.
455 648
456This backend usually performs well under most conditions. 649This backend usually performs well under most conditions.
457 650
458While nominally embeddable in other event loops, this doesn't work 651While nominally embeddable in other event loops, this doesn't work
459everywhere, so you might need to test for this. And since it is broken 652everywhere, so you might need to test for this. And since it is broken
460almost everywhere, you should only use it when you have a lot of sockets 653almost everywhere, you should only use it when you have a lot of sockets
461(for which it usually works), by embedding it into another event loop 654(for which it usually works), by embedding it into another event loop
462(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it, 655(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
463using it only for sockets. 656also broken on OS X)) and, did I mention it, using it only for sockets.
464 657
465This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 658This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
466C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with 659C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
467C<NOTE_EOF>. 660C<NOTE_EOF>.
468 661
476=item C<EVBACKEND_PORT> (value 32, Solaris 10) 669=item C<EVBACKEND_PORT> (value 32, Solaris 10)
477 670
478This uses the Solaris 10 event port mechanism. As with everything on Solaris, 671This uses the Solaris 10 event port mechanism. As with everything on Solaris,
479it's really slow, but it still scales very well (O(active_fds)). 672it's really slow, but it still scales very well (O(active_fds)).
480 673
481Please note that Solaris event ports can deliver a lot of spurious
482notifications, so you need to use non-blocking I/O or other means to avoid
483blocking when no data (or space) is available.
484
485While this backend scales well, it requires one system call per active 674While this backend scales well, it requires one system call per active
486file descriptor per loop iteration. For small and medium numbers of file 675file descriptor per loop iteration. For small and medium numbers of file
487descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 676descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
488might perform better. 677might perform better.
489 678
490On the positive side, with the exception of the spurious readiness 679On the positive side, this backend actually performed fully to
491notifications, this backend actually performed fully to specification
492in all tests and is fully embeddable, which is a rare feat among the 680specification in all tests and is fully embeddable, which is a rare feat
493OS-specific backends (I vastly prefer correctness over speed hacks). 681among the OS-specific backends (I vastly prefer correctness over speed
682hacks).
683
684On the negative side, the interface is I<bizarre> - so bizarre that
685even sun itself gets it wrong in their code examples: The event polling
686function sometimes returns events to the caller even though an error
687occurred, but with no indication whether it has done so or not (yes, it's
688even documented that way) - deadly for edge-triggered interfaces where you
689absolutely have to know whether an event occurred or not because you have
690to re-arm the watcher.
691
692Fortunately libev seems to be able to work around these idiocies.
494 693
495This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 694This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
496C<EVBACKEND_POLL>. 695C<EVBACKEND_POLL>.
497 696
498=item C<EVBACKEND_ALL> 697=item C<EVBACKEND_ALL>
499 698
500Try all backends (even potentially broken ones that wouldn't be tried 699Try all backends (even potentially broken ones that wouldn't be tried
501with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 700with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
502C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 701C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
503 702
504It is definitely not recommended to use this flag. 703It is definitely not recommended to use this flag, use whatever
704C<ev_recommended_backends ()> returns, or simply do not specify a backend
705at all.
706
707=item C<EVBACKEND_MASK>
708
709Not a backend at all, but a mask to select all backend bits from a
710C<flags> value, in case you want to mask out any backends from a flags
711value (e.g. when modifying the C<LIBEV_FLAGS> environment variable).
505 712
506=back 713=back
507 714
508If one or more of these are or'ed into the flags value, then only these 715If one or more of the backend flags are or'ed into the flags value,
509backends will be tried (in the reverse order as listed here). If none are 716then only these backends will be tried (in the reverse order as listed
510specified, all backends in C<ev_recommended_backends ()> will be tried. 717here). If none are specified, all backends in C<ev_recommended_backends
511 718()> will be tried.
512Example: This is the most typical usage.
513
514 if (!ev_default_loop (0))
515 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
516
517Example: Restrict libev to the select and poll backends, and do not allow
518environment settings to be taken into account:
519
520 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
521
522Example: Use whatever libev has to offer, but make sure that kqueue is
523used if available (warning, breaks stuff, best use only with your own
524private event loop and only if you know the OS supports your types of
525fds):
526
527 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
528
529=item struct ev_loop *ev_loop_new (unsigned int flags)
530
531Similar to C<ev_default_loop>, but always creates a new event loop that is
532always distinct from the default loop. Unlike the default loop, it cannot
533handle signal and child watchers, and attempts to do so will be greeted by
534undefined behaviour (or a failed assertion if assertions are enabled).
535
536Note that this function I<is> thread-safe, and the recommended way to use
537libev with threads is indeed to create one loop per thread, and using the
538default loop in the "main" or "initial" thread.
539 719
540Example: Try to create a event loop that uses epoll and nothing else. 720Example: Try to create a event loop that uses epoll and nothing else.
541 721
542 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 722 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
543 if (!epoller) 723 if (!epoller)
544 fatal ("no epoll found here, maybe it hides under your chair"); 724 fatal ("no epoll found here, maybe it hides under your chair");
545 725
726Example: Use whatever libev has to offer, but make sure that kqueue is
727used if available.
728
729 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
730
731Example: Similarly, on linux, you mgiht want to take advantage of the
732linux aio backend if possible, but fall back to something else if that
733isn't available.
734
735 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
736
546=item ev_default_destroy () 737=item ev_loop_destroy (loop)
547 738
548Destroys the default loop again (frees all memory and kernel state 739Destroys an event loop object (frees all memory and kernel state
549etc.). None of the active event watchers will be stopped in the normal 740etc.). None of the active event watchers will be stopped in the normal
550sense, so e.g. C<ev_is_active> might still return true. It is your 741sense, so e.g. C<ev_is_active> might still return true. It is your
551responsibility to either stop all watchers cleanly yourself I<before> 742responsibility to either stop all watchers cleanly yourself I<before>
552calling this function, or cope with the fact afterwards (which is usually 743calling this function, or cope with the fact afterwards (which is usually
553the easiest thing, you can just ignore the watchers and/or C<free ()> them 744the easiest thing, you can just ignore the watchers and/or C<free ()> them
555 746
556Note that certain global state, such as signal state (and installed signal 747Note that certain global state, such as signal state (and installed signal
557handlers), will not be freed by this function, and related watchers (such 748handlers), will not be freed by this function, and related watchers (such
558as signal and child watchers) would need to be stopped manually. 749as signal and child watchers) would need to be stopped manually.
559 750
560In general it is not advisable to call this function except in the 751This function is normally used on loop objects allocated by
561rare occasion where you really need to free e.g. the signal handling 752C<ev_loop_new>, but it can also be used on the default loop returned by
753C<ev_default_loop>, in which case it is not thread-safe.
754
755Note that it is not advisable to call this function on the default loop
756except in the rare occasion where you really need to free its resources.
562pipe fds. If you need dynamically allocated loops it is better to use 757If you need dynamically allocated loops it is better to use C<ev_loop_new>
563C<ev_loop_new> and C<ev_loop_destroy>). 758and C<ev_loop_destroy>.
564 759
565=item ev_loop_destroy (loop) 760=item ev_loop_fork (loop)
566 761
567Like C<ev_default_destroy>, but destroys an event loop created by an
568earlier call to C<ev_loop_new>.
569
570=item ev_default_fork ()
571
572This function sets a flag that causes subsequent C<ev_loop> iterations 762This function sets a flag that causes subsequent C<ev_run> iterations
573to reinitialise the kernel state for backends that have one. Despite the 763to reinitialise the kernel state for backends that have one. Despite
574name, you can call it anytime, but it makes most sense after forking, in 764the name, you can call it anytime you are allowed to start or stop
575the child process (or both child and parent, but that again makes little 765watchers (except inside an C<ev_prepare> callback), but it makes most
576sense). You I<must> call it in the child before using any of the libev 766sense after forking, in the child process. You I<must> call it (or use
577functions, and it will only take effect at the next C<ev_loop> iteration. 767C<EVFLAG_FORKCHECK>) in the child before resuming or calling C<ev_run>.
768
769In addition, if you want to reuse a loop (via this function or
770C<EVFLAG_FORKCHECK>), you I<also> have to ignore C<SIGPIPE>.
771
772Again, you I<have> to call it on I<any> loop that you want to re-use after
773a fork, I<even if you do not plan to use the loop in the parent>. This is
774because some kernel interfaces *cough* I<kqueue> *cough* do funny things
775during fork.
578 776
579On the other hand, you only need to call this function in the child 777On the other hand, you only need to call this function in the child
580process if and only if you want to use the event library in the child. If 778process if and only if you want to use the event loop in the child. If
581you just fork+exec, you don't have to call it at all. 779you just fork+exec or create a new loop in the child, you don't have to
780call it at all (in fact, C<epoll> is so badly broken that it makes a
781difference, but libev will usually detect this case on its own and do a
782costly reset of the backend).
582 783
583The function itself is quite fast and it's usually not a problem to call 784The function itself is quite fast and it's usually not a problem to call
584it just in case after a fork. To make this easy, the function will fit in 785it just in case after a fork.
585quite nicely into a call to C<pthread_atfork>:
586 786
787Example: Automate calling C<ev_loop_fork> on the default loop when
788using pthreads.
789
790 static void
791 post_fork_child (void)
792 {
793 ev_loop_fork (EV_DEFAULT);
794 }
795
796 ...
587 pthread_atfork (0, 0, ev_default_fork); 797 pthread_atfork (0, 0, post_fork_child);
588
589=item ev_loop_fork (loop)
590
591Like C<ev_default_fork>, but acts on an event loop created by
592C<ev_loop_new>. Yes, you have to call this on every allocated event loop
593after fork that you want to re-use in the child, and how you do this is
594entirely your own problem.
595 798
596=item int ev_is_default_loop (loop) 799=item int ev_is_default_loop (loop)
597 800
598Returns true when the given loop is, in fact, the default loop, and false 801Returns true when the given loop is, in fact, the default loop, and false
599otherwise. 802otherwise.
600 803
601=item unsigned int ev_loop_count (loop) 804=item unsigned int ev_iteration (loop)
602 805
603Returns the count of loop iterations for the loop, which is identical to 806Returns the current iteration count for the event loop, which is identical
604the number of times libev did poll for new events. It starts at C<0> and 807to the number of times libev did poll for new events. It starts at C<0>
605happily wraps around with enough iterations. 808and happily wraps around with enough iterations.
606 809
607This value can sometimes be useful as a generation counter of sorts (it 810This value can sometimes be useful as a generation counter of sorts (it
608"ticks" the number of loop iterations), as it roughly corresponds with 811"ticks" the number of loop iterations), as it roughly corresponds with
609C<ev_prepare> and C<ev_check> calls. 812C<ev_prepare> and C<ev_check> calls - and is incremented between the
813prepare and check phases.
814
815=item unsigned int ev_depth (loop)
816
817Returns the number of times C<ev_run> was entered minus the number of
818times C<ev_run> was exited normally, in other words, the recursion depth.
819
820Outside C<ev_run>, this number is zero. In a callback, this number is
821C<1>, unless C<ev_run> was invoked recursively (or from another thread),
822in which case it is higher.
823
824Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread,
825throwing an exception etc.), doesn't count as "exit" - consider this
826as a hint to avoid such ungentleman-like behaviour unless it's really
827convenient, in which case it is fully supported.
610 828
611=item unsigned int ev_backend (loop) 829=item unsigned int ev_backend (loop)
612 830
613Returns one of the C<EVBACKEND_*> flags indicating the event backend in 831Returns one of the C<EVBACKEND_*> flags indicating the event backend in
614use. 832use.
623 841
624=item ev_now_update (loop) 842=item ev_now_update (loop)
625 843
626Establishes the current time by querying the kernel, updating the time 844Establishes the current time by querying the kernel, updating the time
627returned by C<ev_now ()> in the progress. This is a costly operation and 845returned by C<ev_now ()> in the progress. This is a costly operation and
628is usually done automatically within C<ev_loop ()>. 846is usually done automatically within C<ev_run ()>.
629 847
630This function is rarely useful, but when some event callback runs for a 848This function is rarely useful, but when some event callback runs for a
631very long time without entering the event loop, updating libev's idea of 849very long time without entering the event loop, updating libev's idea of
632the current time is a good idea. 850the current time is a good idea.
633 851
634See also "The special problem of time updates" in the C<ev_timer> section. 852See also L</The special problem of time updates> in the C<ev_timer> section.
635 853
854=item ev_suspend (loop)
855
856=item ev_resume (loop)
857
858These two functions suspend and resume an event loop, for use when the
859loop is not used for a while and timeouts should not be processed.
860
861A typical use case would be an interactive program such as a game: When
862the user presses C<^Z> to suspend the game and resumes it an hour later it
863would be best to handle timeouts as if no time had actually passed while
864the program was suspended. This can be achieved by calling C<ev_suspend>
865in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
866C<ev_resume> directly afterwards to resume timer processing.
867
868Effectively, all C<ev_timer> watchers will be delayed by the time spend
869between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
870will be rescheduled (that is, they will lose any events that would have
871occurred while suspended).
872
873After calling C<ev_suspend> you B<must not> call I<any> function on the
874given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
875without a previous call to C<ev_suspend>.
876
877Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
878event loop time (see C<ev_now_update>).
879
636=item ev_loop (loop, int flags) 880=item bool ev_run (loop, int flags)
637 881
638Finally, this is it, the event handler. This function usually is called 882Finally, this is it, the event handler. This function usually is called
639after you initialised all your watchers and you want to start handling 883after you have initialised all your watchers and you want to start
640events. 884handling events. It will ask the operating system for any new events, call
885the watcher callbacks, and then repeat the whole process indefinitely: This
886is why event loops are called I<loops>.
641 887
642If the flags argument is specified as C<0>, it will not return until 888If the flags argument is specified as C<0>, it will keep handling events
643either no event watchers are active anymore or C<ev_unloop> was called. 889until either no event watchers are active anymore or C<ev_break> was
890called.
644 891
892The return value is false if there are no more active watchers (which
893usually means "all jobs done" or "deadlock"), and true in all other cases
894(which usually means " you should call C<ev_run> again").
895
645Please note that an explicit C<ev_unloop> is usually better than 896Please note that an explicit C<ev_break> is usually better than
646relying on all watchers to be stopped when deciding when a program has 897relying on all watchers to be stopped when deciding when a program has
647finished (especially in interactive programs), but having a program 898finished (especially in interactive programs), but having a program
648that automatically loops as long as it has to and no longer by virtue 899that automatically loops as long as it has to and no longer by virtue
649of relying on its watchers stopping correctly, that is truly a thing of 900of relying on its watchers stopping correctly, that is truly a thing of
650beauty. 901beauty.
651 902
903This function is I<mostly> exception-safe - you can break out of a
904C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
905exception and so on. This does not decrement the C<ev_depth> value, nor
906will it clear any outstanding C<EVBREAK_ONE> breaks.
907
652A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 908A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
653those events and any already outstanding ones, but will not block your 909those events and any already outstanding ones, but will not wait and
654process in case there are no events and will return after one iteration of 910block your process in case there are no events and will return after one
655the loop. 911iteration of the loop. This is sometimes useful to poll and handle new
912events while doing lengthy calculations, to keep the program responsive.
656 913
657A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 914A flags value of C<EVRUN_ONCE> will look for new events (waiting if
658necessary) and will handle those and any already outstanding ones. It 915necessary) and will handle those and any already outstanding ones. It
659will block your process until at least one new event arrives (which could 916will block your process until at least one new event arrives (which could
660be an event internal to libev itself, so there is no guarantee that a 917be an event internal to libev itself, so there is no guarantee that a
661user-registered callback will be called), and will return after one 918user-registered callback will be called), and will return after one
662iteration of the loop. 919iteration of the loop.
663 920
664This is useful if you are waiting for some external event in conjunction 921This is useful if you are waiting for some external event in conjunction
665with something not expressible using other libev watchers (i.e. "roll your 922with something not expressible using other libev watchers (i.e. "roll your
666own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is 923own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
667usually a better approach for this kind of thing. 924usually a better approach for this kind of thing.
668 925
669Here are the gory details of what C<ev_loop> does: 926Here are the gory details of what C<ev_run> does (this is for your
927understanding, not a guarantee that things will work exactly like this in
928future versions):
670 929
930 - Increment loop depth.
931 - Reset the ev_break status.
671 - Before the first iteration, call any pending watchers. 932 - Before the first iteration, call any pending watchers.
933 LOOP:
672 * If EVFLAG_FORKCHECK was used, check for a fork. 934 - If EVFLAG_FORKCHECK was used, check for a fork.
673 - If a fork was detected (by any means), queue and call all fork watchers. 935 - If a fork was detected (by any means), queue and call all fork watchers.
674 - Queue and call all prepare watchers. 936 - Queue and call all prepare watchers.
937 - If ev_break was called, goto FINISH.
675 - If we have been forked, detach and recreate the kernel state 938 - If we have been forked, detach and recreate the kernel state
676 as to not disturb the other process. 939 as to not disturb the other process.
677 - Update the kernel state with all outstanding changes. 940 - Update the kernel state with all outstanding changes.
678 - Update the "event loop time" (ev_now ()). 941 - Update the "event loop time" (ev_now ()).
679 - Calculate for how long to sleep or block, if at all 942 - Calculate for how long to sleep or block, if at all
680 (active idle watchers, EVLOOP_NONBLOCK or not having 943 (active idle watchers, EVRUN_NOWAIT or not having
681 any active watchers at all will result in not sleeping). 944 any active watchers at all will result in not sleeping).
682 - Sleep if the I/O and timer collect interval say so. 945 - Sleep if the I/O and timer collect interval say so.
946 - Increment loop iteration counter.
683 - Block the process, waiting for any events. 947 - Block the process, waiting for any events.
684 - Queue all outstanding I/O (fd) events. 948 - Queue all outstanding I/O (fd) events.
685 - Update the "event loop time" (ev_now ()), and do time jump adjustments. 949 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
686 - Queue all expired timers. 950 - Queue all expired timers.
687 - Queue all expired periodics. 951 - Queue all expired periodics.
688 - Unless any events are pending now, queue all idle watchers. 952 - Queue all idle watchers with priority higher than that of pending events.
689 - Queue all check watchers. 953 - Queue all check watchers.
690 - Call all queued watchers in reverse order (i.e. check watchers first). 954 - Call all queued watchers in reverse order (i.e. check watchers first).
691 Signals and child watchers are implemented as I/O watchers, and will 955 Signals and child watchers are implemented as I/O watchers, and will
692 be handled here by queueing them when their watcher gets executed. 956 be handled here by queueing them when their watcher gets executed.
693 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 957 - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT
694 were used, or there are no active watchers, return, otherwise 958 were used, or there are no active watchers, goto FINISH, otherwise
695 continue with step *. 959 continue with step LOOP.
960 FINISH:
961 - Reset the ev_break status iff it was EVBREAK_ONE.
962 - Decrement the loop depth.
963 - Return.
696 964
697Example: Queue some jobs and then loop until no events are outstanding 965Example: Queue some jobs and then loop until no events are outstanding
698anymore. 966anymore.
699 967
700 ... queue jobs here, make sure they register event watchers as long 968 ... queue jobs here, make sure they register event watchers as long
701 ... as they still have work to do (even an idle watcher will do..) 969 ... as they still have work to do (even an idle watcher will do..)
702 ev_loop (my_loop, 0); 970 ev_run (my_loop, 0);
703 ... jobs done or somebody called unloop. yeah! 971 ... jobs done or somebody called break. yeah!
704 972
705=item ev_unloop (loop, how) 973=item ev_break (loop, how)
706 974
707Can be used to make a call to C<ev_loop> return early (but only after it 975Can be used to make a call to C<ev_run> return early (but only after it
708has processed all outstanding events). The C<how> argument must be either 976has processed all outstanding events). The C<how> argument must be either
709C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 977C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
710C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 978C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
711 979
712This "unloop state" will be cleared when entering C<ev_loop> again. 980This "break state" will be cleared on the next call to C<ev_run>.
713 981
714It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. 982It is safe to call C<ev_break> from outside any C<ev_run> calls, too, in
983which case it will have no effect.
715 984
716=item ev_ref (loop) 985=item ev_ref (loop)
717 986
718=item ev_unref (loop) 987=item ev_unref (loop)
719 988
720Ref/unref can be used to add or remove a reference count on the event 989Ref/unref can be used to add or remove a reference count on the event
721loop: Every watcher keeps one reference, and as long as the reference 990loop: Every watcher keeps one reference, and as long as the reference
722count is nonzero, C<ev_loop> will not return on its own. 991count is nonzero, C<ev_run> will not return on its own.
723 992
724If you have a watcher you never unregister that should not keep C<ev_loop> 993This is useful when you have a watcher that you never intend to
725from returning, call ev_unref() after starting, and ev_ref() before 994unregister, but that nevertheless should not keep C<ev_run> from
995returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
726stopping it. 996before stopping it.
727 997
728As an example, libev itself uses this for its internal signal pipe: It is 998As an example, libev itself uses this for its internal signal pipe: It
729not visible to the libev user and should not keep C<ev_loop> from exiting 999is not visible to the libev user and should not keep C<ev_run> from
730if no event watchers registered by it are active. It is also an excellent 1000exiting if no event watchers registered by it are active. It is also an
731way to do this for generic recurring timers or from within third-party 1001excellent way to do this for generic recurring timers or from within
732libraries. Just remember to I<unref after start> and I<ref before stop> 1002third-party libraries. Just remember to I<unref after start> and I<ref
733(but only if the watcher wasn't active before, or was active before, 1003before stop> (but only if the watcher wasn't active before, or was active
734respectively). 1004before, respectively. Note also that libev might stop watchers itself
1005(e.g. non-repeating timers) in which case you have to C<ev_ref>
1006in the callback).
735 1007
736Example: Create a signal watcher, but keep it from keeping C<ev_loop> 1008Example: Create a signal watcher, but keep it from keeping C<ev_run>
737running when nothing else is active. 1009running when nothing else is active.
738 1010
739 ev_signal exitsig; 1011 ev_signal exitsig;
740 ev_signal_init (&exitsig, sig_cb, SIGINT); 1012 ev_signal_init (&exitsig, sig_cb, SIGINT);
741 ev_signal_start (loop, &exitsig); 1013 ev_signal_start (loop, &exitsig);
742 evf_unref (loop); 1014 ev_unref (loop);
743 1015
744Example: For some weird reason, unregister the above signal handler again. 1016Example: For some weird reason, unregister the above signal handler again.
745 1017
746 ev_ref (loop); 1018 ev_ref (loop);
747 ev_signal_stop (loop, &exitsig); 1019 ev_signal_stop (loop, &exitsig);
767overhead for the actual polling but can deliver many events at once. 1039overhead for the actual polling but can deliver many events at once.
768 1040
769By setting a higher I<io collect interval> you allow libev to spend more 1041By setting a higher I<io collect interval> you allow libev to spend more
770time collecting I/O events, so you can handle more events per iteration, 1042time collecting I/O events, so you can handle more events per iteration,
771at the cost of increasing latency. Timeouts (both C<ev_periodic> and 1043at the cost of increasing latency. Timeouts (both C<ev_periodic> and
772C<ev_timer>) will be not affected. Setting this to a non-null value will 1044C<ev_timer>) will not be affected. Setting this to a non-null value will
773introduce an additional C<ev_sleep ()> call into most loop iterations. 1045introduce an additional C<ev_sleep ()> call into most loop iterations. The
1046sleep time ensures that libev will not poll for I/O events more often then
1047once per this interval, on average (as long as the host time resolution is
1048good enough).
774 1049
775Likewise, by setting a higher I<timeout collect interval> you allow libev 1050Likewise, by setting a higher I<timeout collect interval> you allow libev
776to spend more time collecting timeouts, at the expense of increased 1051to spend more time collecting timeouts, at the expense of increased
777latency/jitter/inexactness (the watcher callback will be called 1052latency/jitter/inexactness (the watcher callback will be called
778later). C<ev_io> watchers will not be affected. Setting this to a non-null 1053later). C<ev_io> watchers will not be affected. Setting this to a non-null
780 1055
781Many (busy) programs can usually benefit by setting the I/O collect 1056Many (busy) programs can usually benefit by setting the I/O collect
782interval to a value near C<0.1> or so, which is often enough for 1057interval to a value near C<0.1> or so, which is often enough for
783interactive servers (of course not for games), likewise for timeouts. It 1058interactive servers (of course not for games), likewise for timeouts. It
784usually doesn't make much sense to set it to a lower value than C<0.01>, 1059usually doesn't make much sense to set it to a lower value than C<0.01>,
785as this approaches the timing granularity of most systems. 1060as this approaches the timing granularity of most systems. Note that if
1061you do transactions with the outside world and you can't increase the
1062parallelity, then this setting will limit your transaction rate (if you
1063need to poll once per transaction and the I/O collect interval is 0.01,
1064then you can't do more than 100 transactions per second).
786 1065
787Setting the I<timeout collect interval> can improve the opportunity for 1066Setting the I<timeout collect interval> can improve the opportunity for
788saving power, as the program will "bundle" timer callback invocations that 1067saving power, as the program will "bundle" timer callback invocations that
789are "near" in time together, by delaying some, thus reducing the number of 1068are "near" in time together, by delaying some, thus reducing the number of
790times the process sleeps and wakes up again. Another useful technique to 1069times the process sleeps and wakes up again. Another useful technique to
791reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure 1070reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
792they fire on, say, one-second boundaries only. 1071they fire on, say, one-second boundaries only.
793 1072
1073Example: we only need 0.1s timeout granularity, and we wish not to poll
1074more often than 100 times per second:
1075
1076 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
1077 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
1078
1079=item ev_invoke_pending (loop)
1080
1081This call will simply invoke all pending watchers while resetting their
1082pending state. Normally, C<ev_run> does this automatically when required,
1083but when overriding the invoke callback this call comes handy. This
1084function can be invoked from a watcher - this can be useful for example
1085when you want to do some lengthy calculation and want to pass further
1086event handling to another thread (you still have to make sure only one
1087thread executes within C<ev_invoke_pending> or C<ev_run> of course).
1088
1089=item int ev_pending_count (loop)
1090
1091Returns the number of pending watchers - zero indicates that no watchers
1092are pending.
1093
1094=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
1095
1096This overrides the invoke pending functionality of the loop: Instead of
1097invoking all pending watchers when there are any, C<ev_run> will call
1098this callback instead. This is useful, for example, when you want to
1099invoke the actual watchers inside another context (another thread etc.).
1100
1101If you want to reset the callback, use C<ev_invoke_pending> as new
1102callback.
1103
1104=item ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())
1105
1106Sometimes you want to share the same loop between multiple threads. This
1107can be done relatively simply by putting mutex_lock/unlock calls around
1108each call to a libev function.
1109
1110However, C<ev_run> can run an indefinite time, so it is not feasible
1111to wait for it to return. One way around this is to wake up the event
1112loop via C<ev_break> and C<ev_async_send>, another way is to set these
1113I<release> and I<acquire> callbacks on the loop.
1114
1115When set, then C<release> will be called just before the thread is
1116suspended waiting for new events, and C<acquire> is called just
1117afterwards.
1118
1119Ideally, C<release> will just call your mutex_unlock function, and
1120C<acquire> will just call the mutex_lock function again.
1121
1122While event loop modifications are allowed between invocations of
1123C<release> and C<acquire> (that's their only purpose after all), no
1124modifications done will affect the event loop, i.e. adding watchers will
1125have no effect on the set of file descriptors being watched, or the time
1126waited. Use an C<ev_async> watcher to wake up C<ev_run> when you want it
1127to take note of any changes you made.
1128
1129In theory, threads executing C<ev_run> will be async-cancel safe between
1130invocations of C<release> and C<acquire>.
1131
1132See also the locking example in the C<THREADS> section later in this
1133document.
1134
1135=item ev_set_userdata (loop, void *data)
1136
1137=item void *ev_userdata (loop)
1138
1139Set and retrieve a single C<void *> associated with a loop. When
1140C<ev_set_userdata> has never been called, then C<ev_userdata> returns
1141C<0>.
1142
1143These two functions can be used to associate arbitrary data with a loop,
1144and are intended solely for the C<invoke_pending_cb>, C<release> and
1145C<acquire> callbacks described above, but of course can be (ab-)used for
1146any other purpose as well.
1147
794=item ev_loop_verify (loop) 1148=item ev_verify (loop)
795 1149
796This function only does something when C<EV_VERIFY> support has been 1150This function only does something when C<EV_VERIFY> support has been
797compiled in, which is the default for non-minimal builds. It tries to go 1151compiled in, which is the default for non-minimal builds. It tries to go
798through all internal structures and checks them for validity. If anything 1152through all internal structures and checks them for validity. If anything
799is found to be inconsistent, it will print an error message to standard 1153is found to be inconsistent, it will print an error message to standard
810 1164
811In the following description, uppercase C<TYPE> in names stands for the 1165In the following description, uppercase C<TYPE> in names stands for the
812watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer 1166watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
813watchers and C<ev_io_start> for I/O watchers. 1167watchers and C<ev_io_start> for I/O watchers.
814 1168
815A watcher is a structure that you create and register to record your 1169A watcher is an opaque structure that you allocate and register to record
816interest in some event. For instance, if you want to wait for STDIN to 1170your interest in some event. To make a concrete example, imagine you want
817become readable, you would create an C<ev_io> watcher for that: 1171to wait for STDIN to become readable, you would create an C<ev_io> watcher
1172for that:
818 1173
819 static void my_cb (struct ev_loop *loop, ev_io *w, int revents) 1174 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
820 { 1175 {
821 ev_io_stop (w); 1176 ev_io_stop (w);
822 ev_unloop (loop, EVUNLOOP_ALL); 1177 ev_break (loop, EVBREAK_ALL);
823 } 1178 }
824 1179
825 struct ev_loop *loop = ev_default_loop (0); 1180 struct ev_loop *loop = ev_default_loop (0);
826 1181
827 ev_io stdin_watcher; 1182 ev_io stdin_watcher;
828 1183
829 ev_init (&stdin_watcher, my_cb); 1184 ev_init (&stdin_watcher, my_cb);
830 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 1185 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
831 ev_io_start (loop, &stdin_watcher); 1186 ev_io_start (loop, &stdin_watcher);
832 1187
833 ev_loop (loop, 0); 1188 ev_run (loop, 0);
834 1189
835As you can see, you are responsible for allocating the memory for your 1190As you can see, you are responsible for allocating the memory for your
836watcher structures (and it is I<usually> a bad idea to do this on the 1191watcher structures (and it is I<usually> a bad idea to do this on the
837stack). 1192stack).
838 1193
839Each watcher has an associated watcher structure (called C<struct ev_TYPE> 1194Each watcher has an associated watcher structure (called C<struct ev_TYPE>
840or simply C<ev_TYPE>, as typedefs are provided for all watcher structs). 1195or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
841 1196
842Each watcher structure must be initialised by a call to C<ev_init 1197Each watcher structure must be initialised by a call to C<ev_init (watcher
843(watcher *, callback)>, which expects a callback to be provided. This 1198*, callback)>, which expects a callback to be provided. This callback is
844callback gets invoked each time the event occurs (or, in the case of I/O 1199invoked each time the event occurs (or, in the case of I/O watchers, each
845watchers, each time the event loop detects that the file descriptor given 1200time the event loop detects that the file descriptor given is readable
846is readable and/or writable). 1201and/or writable).
847 1202
848Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> 1203Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
849macro to configure it, with arguments specific to the watcher type. There 1204macro to configure it, with arguments specific to the watcher type. There
850is also a macro to combine initialisation and setting in one call: C<< 1205is also a macro to combine initialisation and setting in one call: C<<
851ev_TYPE_init (watcher *, callback, ...) >>. 1206ev_TYPE_init (watcher *, callback, ...) >>.
874=item C<EV_WRITE> 1229=item C<EV_WRITE>
875 1230
876The file descriptor in the C<ev_io> watcher has become readable and/or 1231The file descriptor in the C<ev_io> watcher has become readable and/or
877writable. 1232writable.
878 1233
879=item C<EV_TIMEOUT> 1234=item C<EV_TIMER>
880 1235
881The C<ev_timer> watcher has timed out. 1236The C<ev_timer> watcher has timed out.
882 1237
883=item C<EV_PERIODIC> 1238=item C<EV_PERIODIC>
884 1239
902 1257
903=item C<EV_PREPARE> 1258=item C<EV_PREPARE>
904 1259
905=item C<EV_CHECK> 1260=item C<EV_CHECK>
906 1261
907All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts 1262All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts to
908to gather new events, and all C<ev_check> watchers are invoked just after 1263gather new events, and all C<ev_check> watchers are queued (not invoked)
909C<ev_loop> has gathered them, but before it invokes any callbacks for any 1264just after C<ev_run> has gathered them, but before it queues any callbacks
1265for any received events. That means C<ev_prepare> watchers are the last
1266watchers invoked before the event loop sleeps or polls for new events, and
1267C<ev_check> watchers will be invoked before any other watchers of the same
1268or lower priority within an event loop iteration.
1269
910received events. Callbacks of both watcher types can start and stop as 1270Callbacks of both watcher types can start and stop as many watchers as
911many watchers as they want, and all of them will be taken into account 1271they want, and all of them will be taken into account (for example, a
912(for example, a C<ev_prepare> watcher might start an idle watcher to keep 1272C<ev_prepare> watcher might start an idle watcher to keep C<ev_run> from
913C<ev_loop> from blocking). 1273blocking).
914 1274
915=item C<EV_EMBED> 1275=item C<EV_EMBED>
916 1276
917The embedded event loop specified in the C<ev_embed> watcher needs attention. 1277The embedded event loop specified in the C<ev_embed> watcher needs attention.
918 1278
919=item C<EV_FORK> 1279=item C<EV_FORK>
920 1280
921The event loop has been resumed in the child process after fork (see 1281The event loop has been resumed in the child process after fork (see
922C<ev_fork>). 1282C<ev_fork>).
923 1283
1284=item C<EV_CLEANUP>
1285
1286The event loop is about to be destroyed (see C<ev_cleanup>).
1287
924=item C<EV_ASYNC> 1288=item C<EV_ASYNC>
925 1289
926The given async watcher has been asynchronously notified (see C<ev_async>). 1290The given async watcher has been asynchronously notified (see C<ev_async>).
1291
1292=item C<EV_CUSTOM>
1293
1294Not ever sent (or otherwise used) by libev itself, but can be freely used
1295by libev users to signal watchers (e.g. via C<ev_feed_event>).
927 1296
928=item C<EV_ERROR> 1297=item C<EV_ERROR>
929 1298
930An unspecified error has occurred, the watcher has been stopped. This might 1299An unspecified error has occurred, the watcher has been stopped. This might
931happen because the watcher could not be properly started because libev 1300happen because the watcher could not be properly started because libev
969 1338
970 ev_io w; 1339 ev_io w;
971 ev_init (&w, my_cb); 1340 ev_init (&w, my_cb);
972 ev_io_set (&w, STDIN_FILENO, EV_READ); 1341 ev_io_set (&w, STDIN_FILENO, EV_READ);
973 1342
974=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1343=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
975 1344
976This macro initialises the type-specific parts of a watcher. You need to 1345This macro initialises the type-specific parts of a watcher. You need to
977call C<ev_init> at least once before you call this macro, but you can 1346call C<ev_init> at least once before you call this macro, but you can
978call C<ev_TYPE_set> any number of times. You must not, however, call this 1347call C<ev_TYPE_set> any number of times. You must not, however, call this
979macro on a watcher that is active (it can be pending, however, which is a 1348macro on a watcher that is active (it can be pending, however, which is a
992 1361
993Example: Initialise and set an C<ev_io> watcher in one step. 1362Example: Initialise and set an C<ev_io> watcher in one step.
994 1363
995 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1364 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
996 1365
997=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1366=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
998 1367
999Starts (activates) the given watcher. Only active watchers will receive 1368Starts (activates) the given watcher. Only active watchers will receive
1000events. If the watcher is already active nothing will happen. 1369events. If the watcher is already active nothing will happen.
1001 1370
1002Example: Start the C<ev_io> watcher that is being abused as example in this 1371Example: Start the C<ev_io> watcher that is being abused as example in this
1003whole section. 1372whole section.
1004 1373
1005 ev_io_start (EV_DEFAULT_UC, &w); 1374 ev_io_start (EV_DEFAULT_UC, &w);
1006 1375
1007=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1376=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1008 1377
1009Stops the given watcher if active, and clears the pending status (whether 1378Stops the given watcher if active, and clears the pending status (whether
1010the watcher was active or not). 1379the watcher was active or not).
1011 1380
1012It is possible that stopped watchers are pending - for example, 1381It is possible that stopped watchers are pending - for example,
1032 1401
1033=item callback ev_cb (ev_TYPE *watcher) 1402=item callback ev_cb (ev_TYPE *watcher)
1034 1403
1035Returns the callback currently set on the watcher. 1404Returns the callback currently set on the watcher.
1036 1405
1037=item ev_cb_set (ev_TYPE *watcher, callback) 1406=item ev_set_cb (ev_TYPE *watcher, callback)
1038 1407
1039Change the callback. You can change the callback at virtually any time 1408Change the callback. You can change the callback at virtually any time
1040(modulo threads). 1409(modulo threads).
1041 1410
1042=item ev_set_priority (ev_TYPE *watcher, priority) 1411=item ev_set_priority (ev_TYPE *watcher, int priority)
1043 1412
1044=item int ev_priority (ev_TYPE *watcher) 1413=item int ev_priority (ev_TYPE *watcher)
1045 1414
1046Set and query the priority of the watcher. The priority is a small 1415Set and query the priority of the watcher. The priority is a small
1047integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1416integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1048(default: C<-2>). Pending watchers with higher priority will be invoked 1417(default: C<-2>). Pending watchers with higher priority will be invoked
1049before watchers with lower priority, but priority will not keep watchers 1418before watchers with lower priority, but priority will not keep watchers
1050from being executed (except for C<ev_idle> watchers). 1419from being executed (except for C<ev_idle> watchers).
1051 1420
1052This means that priorities are I<only> used for ordering callback
1053invocation after new events have been received. This is useful, for
1054example, to reduce latency after idling, or more often, to bind two
1055watchers on the same event and make sure one is called first.
1056
1057If you need to suppress invocation when higher priority events are pending 1421If you need to suppress invocation when higher priority events are pending
1058you need to look at C<ev_idle> watchers, which provide this functionality. 1422you need to look at C<ev_idle> watchers, which provide this functionality.
1059 1423
1060You I<must not> change the priority of a watcher as long as it is active or 1424You I<must not> change the priority of a watcher as long as it is active or
1061pending. 1425pending.
1062
1063The default priority used by watchers when no priority has been set is
1064always C<0>, which is supposed to not be too high and not be too low :).
1065 1426
1066Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1427Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1067fine, as long as you do not mind that the priority value you query might 1428fine, as long as you do not mind that the priority value you query might
1068or might not have been clamped to the valid range. 1429or might not have been clamped to the valid range.
1430
1431The default priority used by watchers when no priority has been set is
1432always C<0>, which is supposed to not be too high and not be too low :).
1433
1434See L</WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1435priorities.
1069 1436
1070=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1437=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1071 1438
1072Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1439Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1073C<loop> nor C<revents> need to be valid as long as the watcher callback 1440C<loop> nor C<revents> need to be valid as long as the watcher callback
1081watcher isn't pending it does nothing and returns C<0>. 1448watcher isn't pending it does nothing and returns C<0>.
1082 1449
1083Sometimes it can be useful to "poll" a watcher instead of waiting for its 1450Sometimes it can be useful to "poll" a watcher instead of waiting for its
1084callback to be invoked, which can be accomplished with this function. 1451callback to be invoked, which can be accomplished with this function.
1085 1452
1453=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1454
1455Feeds the given event set into the event loop, as if the specified event
1456had happened for the specified watcher (which must be a pointer to an
1457initialised but not necessarily started event watcher). Obviously you must
1458not free the watcher as long as it has pending events.
1459
1460Stopping the watcher, letting libev invoke it, or calling
1461C<ev_clear_pending> will clear the pending event, even if the watcher was
1462not started in the first place.
1463
1464See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1465functions that do not need a watcher.
1466
1086=back 1467=back
1087 1468
1469See also the L</ASSOCIATING CUSTOM DATA WITH A WATCHER> and L</BUILDING YOUR
1470OWN COMPOSITE WATCHERS> idioms.
1088 1471
1089=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1472=head2 WATCHER STATES
1090 1473
1091Each watcher has, by default, a member C<void *data> that you can change 1474There are various watcher states mentioned throughout this manual -
1092and read at any time: libev will completely ignore it. This can be used 1475active, pending and so on. In this section these states and the rules to
1093to associate arbitrary data with your watcher. If you need more data and 1476transition between them will be described in more detail - and while these
1094don't want to allocate memory and store a pointer to it in that data 1477rules might look complicated, they usually do "the right thing".
1095member, you can also "subclass" the watcher type and provide your own
1096data:
1097 1478
1098 struct my_io 1479=over 4
1480
1481=item initialised
1482
1483Before a watcher can be registered with the event loop it has to be
1484initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1485C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1486
1487In this state it is simply some block of memory that is suitable for
1488use in an event loop. It can be moved around, freed, reused etc. at
1489will - as long as you either keep the memory contents intact, or call
1490C<ev_TYPE_init> again.
1491
1492=item started/running/active
1493
1494Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1495property of the event loop, and is actively waiting for events. While in
1496this state it cannot be accessed (except in a few documented ways), moved,
1497freed or anything else - the only legal thing is to keep a pointer to it,
1498and call libev functions on it that are documented to work on active watchers.
1499
1500=item pending
1501
1502If a watcher is active and libev determines that an event it is interested
1503in has occurred (such as a timer expiring), it will become pending. It will
1504stay in this pending state until either it is stopped or its callback is
1505about to be invoked, so it is not normally pending inside the watcher
1506callback.
1507
1508The watcher might or might not be active while it is pending (for example,
1509an expired non-repeating timer can be pending but no longer active). If it
1510is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
1511but it is still property of the event loop at this time, so cannot be
1512moved, freed or reused. And if it is active the rules described in the
1513previous item still apply.
1514
1515It is also possible to feed an event on a watcher that is not active (e.g.
1516via C<ev_feed_event>), in which case it becomes pending without being
1517active.
1518
1519=item stopped
1520
1521A watcher can be stopped implicitly by libev (in which case it might still
1522be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
1523latter will clear any pending state the watcher might be in, regardless
1524of whether it was active or not, so stopping a watcher explicitly before
1525freeing it is often a good idea.
1526
1527While stopped (and not pending) the watcher is essentially in the
1528initialised state, that is, it can be reused, moved, modified in any way
1529you wish (but when you trash the memory block, you need to C<ev_TYPE_init>
1530it again).
1531
1532=back
1533
1534=head2 WATCHER PRIORITY MODELS
1535
1536Many event loops support I<watcher priorities>, which are usually small
1537integers that influence the ordering of event callback invocation
1538between watchers in some way, all else being equal.
1539
1540In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1541description for the more technical details such as the actual priority
1542range.
1543
1544There are two common ways how these these priorities are being interpreted
1545by event loops:
1546
1547In the more common lock-out model, higher priorities "lock out" invocation
1548of lower priority watchers, which means as long as higher priority
1549watchers receive events, lower priority watchers are not being invoked.
1550
1551The less common only-for-ordering model uses priorities solely to order
1552callback invocation within a single event loop iteration: Higher priority
1553watchers are invoked before lower priority ones, but they all get invoked
1554before polling for new events.
1555
1556Libev uses the second (only-for-ordering) model for all its watchers
1557except for idle watchers (which use the lock-out model).
1558
1559The rationale behind this is that implementing the lock-out model for
1560watchers is not well supported by most kernel interfaces, and most event
1561libraries will just poll for the same events again and again as long as
1562their callbacks have not been executed, which is very inefficient in the
1563common case of one high-priority watcher locking out a mass of lower
1564priority ones.
1565
1566Static (ordering) priorities are most useful when you have two or more
1567watchers handling the same resource: a typical usage example is having an
1568C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1569timeouts. Under load, data might be received while the program handles
1570other jobs, but since timers normally get invoked first, the timeout
1571handler will be executed before checking for data. In that case, giving
1572the timer a lower priority than the I/O watcher ensures that I/O will be
1573handled first even under adverse conditions (which is usually, but not
1574always, what you want).
1575
1576Since idle watchers use the "lock-out" model, meaning that idle watchers
1577will only be executed when no same or higher priority watchers have
1578received events, they can be used to implement the "lock-out" model when
1579required.
1580
1581For example, to emulate how many other event libraries handle priorities,
1582you can associate an C<ev_idle> watcher to each such watcher, and in
1583the normal watcher callback, you just start the idle watcher. The real
1584processing is done in the idle watcher callback. This causes libev to
1585continuously poll and process kernel event data for the watcher, but when
1586the lock-out case is known to be rare (which in turn is rare :), this is
1587workable.
1588
1589Usually, however, the lock-out model implemented that way will perform
1590miserably under the type of load it was designed to handle. In that case,
1591it might be preferable to stop the real watcher before starting the
1592idle watcher, so the kernel will not have to process the event in case
1593the actual processing will be delayed for considerable time.
1594
1595Here is an example of an I/O watcher that should run at a strictly lower
1596priority than the default, and which should only process data when no
1597other events are pending:
1598
1599 ev_idle idle; // actual processing watcher
1600 ev_io io; // actual event watcher
1601
1602 static void
1603 io_cb (EV_P_ ev_io *w, int revents)
1099 { 1604 {
1100 ev_io io; 1605 // stop the I/O watcher, we received the event, but
1101 int otherfd; 1606 // are not yet ready to handle it.
1102 void *somedata; 1607 ev_io_stop (EV_A_ w);
1103 struct whatever *mostinteresting; 1608
1609 // start the idle watcher to handle the actual event.
1610 // it will not be executed as long as other watchers
1611 // with the default priority are receiving events.
1612 ev_idle_start (EV_A_ &idle);
1104 }; 1613 }
1105 1614
1106 ... 1615 static void
1107 struct my_io w; 1616 idle_cb (EV_P_ ev_idle *w, int revents)
1108 ev_io_init (&w.io, my_cb, fd, EV_READ);
1109
1110And since your callback will be called with a pointer to the watcher, you
1111can cast it back to your own type:
1112
1113 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1114 { 1617 {
1115 struct my_io *w = (struct my_io *)w_; 1618 // actual processing
1116 ... 1619 read (STDIN_FILENO, ...);
1620
1621 // have to start the I/O watcher again, as
1622 // we have handled the event
1623 ev_io_start (EV_P_ &io);
1117 } 1624 }
1118 1625
1119More interesting and less C-conformant ways of casting your callback type 1626 // initialisation
1120instead have been omitted. 1627 ev_idle_init (&idle, idle_cb);
1628 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1629 ev_io_start (EV_DEFAULT_ &io);
1121 1630
1122Another common scenario is to use some data structure with multiple 1631In the "real" world, it might also be beneficial to start a timer, so that
1123embedded watchers: 1632low-priority connections can not be locked out forever under load. This
1124 1633enables your program to keep a lower latency for important connections
1125 struct my_biggy 1634during short periods of high load, while not completely locking out less
1126 { 1635important ones.
1127 int some_data;
1128 ev_timer t1;
1129 ev_timer t2;
1130 }
1131
1132In this case getting the pointer to C<my_biggy> is a bit more
1133complicated: Either you store the address of your C<my_biggy> struct
1134in the C<data> member of the watcher (for woozies), or you need to use
1135some pointer arithmetic using C<offsetof> inside your watchers (for real
1136programmers):
1137
1138 #include <stddef.h>
1139
1140 static void
1141 t1_cb (EV_P_ ev_timer *w, int revents)
1142 {
1143 struct my_biggy big = (struct my_biggy *
1144 (((char *)w) - offsetof (struct my_biggy, t1));
1145 }
1146
1147 static void
1148 t2_cb (EV_P_ ev_timer *w, int revents)
1149 {
1150 struct my_biggy big = (struct my_biggy *
1151 (((char *)w) - offsetof (struct my_biggy, t2));
1152 }
1153 1636
1154 1637
1155=head1 WATCHER TYPES 1638=head1 WATCHER TYPES
1156 1639
1157This section describes each watcher in detail, but will not repeat 1640This section describes each watcher in detail, but will not repeat
1181In general you can register as many read and/or write event watchers per 1664In general you can register as many read and/or write event watchers per
1182fd as you want (as long as you don't confuse yourself). Setting all file 1665fd as you want (as long as you don't confuse yourself). Setting all file
1183descriptors to non-blocking mode is also usually a good idea (but not 1666descriptors to non-blocking mode is also usually a good idea (but not
1184required if you know what you are doing). 1667required if you know what you are doing).
1185 1668
1186If you cannot use non-blocking mode, then force the use of a
1187known-to-be-good backend (at the time of this writing, this includes only
1188C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>).
1189
1190Another thing you have to watch out for is that it is quite easy to 1669Another thing you have to watch out for is that it is quite easy to
1191receive "spurious" readiness notifications, that is your callback might 1670receive "spurious" readiness notifications, that is, your callback might
1192be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1671be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1193because there is no data. Not only are some backends known to create a 1672because there is no data. It is very easy to get into this situation even
1194lot of those (for example Solaris ports), it is very easy to get into 1673with a relatively standard program structure. Thus it is best to always
1195this situation even with a relatively standard program structure. Thus 1674use non-blocking I/O: An extra C<read>(2) returning C<EAGAIN> is far
1196it is best to always use non-blocking I/O: An extra C<read>(2) returning
1197C<EAGAIN> is far preferable to a program hanging until some data arrives. 1675preferable to a program hanging until some data arrives.
1198 1676
1199If you cannot run the fd in non-blocking mode (for example you should 1677If you cannot run the fd in non-blocking mode (for example you should
1200not play around with an Xlib connection), then you have to separately 1678not play around with an Xlib connection), then you have to separately
1201re-test whether a file descriptor is really ready with a known-to-be good 1679re-test whether a file descriptor is really ready with a known-to-be good
1202interface such as poll (fortunately in our Xlib example, Xlib already 1680interface such as poll (fortunately in the case of Xlib, it already does
1203does this on its own, so its quite safe to use). Some people additionally 1681this on its own, so its quite safe to use). Some people additionally
1204use C<SIGALRM> and an interval timer, just to be sure you won't block 1682use C<SIGALRM> and an interval timer, just to be sure you won't block
1205indefinitely. 1683indefinitely.
1206 1684
1207But really, best use non-blocking mode. 1685But really, best use non-blocking mode.
1208 1686
1209=head3 The special problem of disappearing file descriptors 1687=head3 The special problem of disappearing file descriptors
1210 1688
1211Some backends (e.g. kqueue, epoll) need to be told about closing a file 1689Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1212descriptor (either due to calling C<close> explicitly or any other means, 1690a file descriptor (either due to calling C<close> explicitly or any other
1213such as C<dup2>). The reason is that you register interest in some file 1691means, such as C<dup2>). The reason is that you register interest in some
1214descriptor, but when it goes away, the operating system will silently drop 1692file descriptor, but when it goes away, the operating system will silently
1215this interest. If another file descriptor with the same number then is 1693drop this interest. If another file descriptor with the same number then
1216registered with libev, there is no efficient way to see that this is, in 1694is registered with libev, there is no efficient way to see that this is,
1217fact, a different file descriptor. 1695in fact, a different file descriptor.
1218 1696
1219To avoid having to explicitly tell libev about such cases, libev follows 1697To avoid having to explicitly tell libev about such cases, libev follows
1220the following policy: Each time C<ev_io_set> is being called, libev 1698the following policy: Each time C<ev_io_set> is being called, libev
1221will assume that this is potentially a new file descriptor, otherwise 1699will assume that this is potentially a new file descriptor, otherwise
1222it is assumed that the file descriptor stays the same. That means that 1700it is assumed that the file descriptor stays the same. That means that
1236 1714
1237There is no workaround possible except not registering events 1715There is no workaround possible except not registering events
1238for potentially C<dup ()>'ed file descriptors, or to resort to 1716for potentially C<dup ()>'ed file descriptors, or to resort to
1239C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. 1717C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1240 1718
1719=head3 The special problem of files
1720
1721Many people try to use C<select> (or libev) on file descriptors
1722representing files, and expect it to become ready when their program
1723doesn't block on disk accesses (which can take a long time on their own).
1724
1725However, this cannot ever work in the "expected" way - you get a readiness
1726notification as soon as the kernel knows whether and how much data is
1727there, and in the case of open files, that's always the case, so you
1728always get a readiness notification instantly, and your read (or possibly
1729write) will still block on the disk I/O.
1730
1731Another way to view it is that in the case of sockets, pipes, character
1732devices and so on, there is another party (the sender) that delivers data
1733on its own, but in the case of files, there is no such thing: the disk
1734will not send data on its own, simply because it doesn't know what you
1735wish to read - you would first have to request some data.
1736
1737Since files are typically not-so-well supported by advanced notification
1738mechanism, libev tries hard to emulate POSIX behaviour with respect
1739to files, even though you should not use it. The reason for this is
1740convenience: sometimes you want to watch STDIN or STDOUT, which is
1741usually a tty, often a pipe, but also sometimes files or special devices
1742(for example, C<epoll> on Linux works with F</dev/random> but not with
1743F</dev/urandom>), and even though the file might better be served with
1744asynchronous I/O instead of with non-blocking I/O, it is still useful when
1745it "just works" instead of freezing.
1746
1747So avoid file descriptors pointing to files when you know it (e.g. use
1748libeio), but use them when it is convenient, e.g. for STDIN/STDOUT, or
1749when you rarely read from a file instead of from a socket, and want to
1750reuse the same code path.
1751
1241=head3 The special problem of fork 1752=head3 The special problem of fork
1242 1753
1243Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit 1754Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()>
1244useless behaviour. Libev fully supports fork, but needs to be told about 1755at all or exhibit useless behaviour. Libev fully supports fork, but needs
1245it in the child. 1756to be told about it in the child if you want to continue to use it in the
1757child.
1246 1758
1247To support fork in your programs, you either have to call 1759To support fork in your child processes, you have to call C<ev_loop_fork
1248C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child, 1760()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
1249enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1761C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1250C<EVBACKEND_POLL>.
1251 1762
1252=head3 The special problem of SIGPIPE 1763=head3 The special problem of SIGPIPE
1253 1764
1254While not really specific to libev, it is easy to forget about C<SIGPIPE>: 1765While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1255when writing to a pipe whose other end has been closed, your program gets 1766when writing to a pipe whose other end has been closed, your program gets
1258 1769
1259So when you encounter spurious, unexplained daemon exits, make sure you 1770So when you encounter spurious, unexplained daemon exits, make sure you
1260ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1771ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1261somewhere, as that would have given you a big clue). 1772somewhere, as that would have given you a big clue).
1262 1773
1774=head3 The special problem of accept()ing when you can't
1775
1776Many implementations of the POSIX C<accept> function (for example,
1777found in post-2004 Linux) have the peculiar behaviour of not removing a
1778connection from the pending queue in all error cases.
1779
1780For example, larger servers often run out of file descriptors (because
1781of resource limits), causing C<accept> to fail with C<ENFILE> but not
1782rejecting the connection, leading to libev signalling readiness on
1783the next iteration again (the connection still exists after all), and
1784typically causing the program to loop at 100% CPU usage.
1785
1786Unfortunately, the set of errors that cause this issue differs between
1787operating systems, there is usually little the app can do to remedy the
1788situation, and no known thread-safe method of removing the connection to
1789cope with overload is known (to me).
1790
1791One of the easiest ways to handle this situation is to just ignore it
1792- when the program encounters an overload, it will just loop until the
1793situation is over. While this is a form of busy waiting, no OS offers an
1794event-based way to handle this situation, so it's the best one can do.
1795
1796A better way to handle the situation is to log any errors other than
1797C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1798messages, and continue as usual, which at least gives the user an idea of
1799what could be wrong ("raise the ulimit!"). For extra points one could stop
1800the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1801usage.
1802
1803If your program is single-threaded, then you could also keep a dummy file
1804descriptor for overload situations (e.g. by opening F</dev/null>), and
1805when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1806close that fd, and create a new dummy fd. This will gracefully refuse
1807clients under typical overload conditions.
1808
1809The last way to handle it is to simply log the error and C<exit>, as
1810is often done with C<malloc> failures, but this results in an easy
1811opportunity for a DoS attack.
1263 1812
1264=head3 Watcher-Specific Functions 1813=head3 Watcher-Specific Functions
1265 1814
1266=over 4 1815=over 4
1267 1816
1299 ... 1848 ...
1300 struct ev_loop *loop = ev_default_init (0); 1849 struct ev_loop *loop = ev_default_init (0);
1301 ev_io stdin_readable; 1850 ev_io stdin_readable;
1302 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1851 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1303 ev_io_start (loop, &stdin_readable); 1852 ev_io_start (loop, &stdin_readable);
1304 ev_loop (loop, 0); 1853 ev_run (loop, 0);
1305 1854
1306 1855
1307=head2 C<ev_timer> - relative and optionally repeating timeouts 1856=head2 C<ev_timer> - relative and optionally repeating timeouts
1308 1857
1309Timer watchers are simple relative timers that generate an event after a 1858Timer watchers are simple relative timers that generate an event after a
1314year, it will still time out after (roughly) one hour. "Roughly" because 1863year, it will still time out after (roughly) one hour. "Roughly" because
1315detecting time jumps is hard, and some inaccuracies are unavoidable (the 1864detecting time jumps is hard, and some inaccuracies are unavoidable (the
1316monotonic clock option helps a lot here). 1865monotonic clock option helps a lot here).
1317 1866
1318The callback is guaranteed to be invoked only I<after> its timeout has 1867The callback is guaranteed to be invoked only I<after> its timeout has
1319passed, but if multiple timers become ready during the same loop iteration 1868passed (not I<at>, so on systems with very low-resolution clocks this
1320then order of execution is undefined. 1869might introduce a small delay, see "the special problem of being too
1870early", below). If multiple timers become ready during the same loop
1871iteration then the ones with earlier time-out values are invoked before
1872ones of the same priority with later time-out values (but this is no
1873longer true when a callback calls C<ev_run> recursively).
1321 1874
1322=head3 Be smart about timeouts 1875=head3 Be smart about timeouts
1323 1876
1324Many real-world problems involve some kind of timeout, usually for error 1877Many real-world problems involve some kind of timeout, usually for error
1325recovery. A typical example is an HTTP request - if the other side hangs, 1878recovery. A typical example is an HTTP request - if the other side hangs,
1369C<after> argument to C<ev_timer_set>, and only ever use the C<repeat> 1922C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1370member and C<ev_timer_again>. 1923member and C<ev_timer_again>.
1371 1924
1372At start: 1925At start:
1373 1926
1374 ev_timer_init (timer, callback); 1927 ev_init (timer, callback);
1375 timer->repeat = 60.; 1928 timer->repeat = 60.;
1376 ev_timer_again (loop, timer); 1929 ev_timer_again (loop, timer);
1377 1930
1378Each time there is some activity: 1931Each time there is some activity:
1379 1932
1400 1953
1401In this case, it would be more efficient to leave the C<ev_timer> alone, 1954In this case, it would be more efficient to leave the C<ev_timer> alone,
1402but remember the time of last activity, and check for a real timeout only 1955but remember the time of last activity, and check for a real timeout only
1403within the callback: 1956within the callback:
1404 1957
1958 ev_tstamp timeout = 60.;
1405 ev_tstamp last_activity; // time of last activity 1959 ev_tstamp last_activity; // time of last activity
1960 ev_timer timer;
1406 1961
1407 static void 1962 static void
1408 callback (EV_P_ ev_timer *w, int revents) 1963 callback (EV_P_ ev_timer *w, int revents)
1409 { 1964 {
1410 ev_tstamp now = ev_now (EV_A); 1965 // calculate when the timeout would happen
1411 ev_tstamp timeout = last_activity + 60.; 1966 ev_tstamp after = last_activity - ev_now (EV_A) + timeout;
1412 1967
1413 // if last_activity + 60. is older than now, we did time out 1968 // if negative, it means we the timeout already occurred
1414 if (timeout < now) 1969 if (after < 0.)
1415 { 1970 {
1416 // timeout occured, take action 1971 // timeout occurred, take action
1417 } 1972 }
1418 else 1973 else
1419 { 1974 {
1420 // callback was invoked, but there was some activity, re-arm 1975 // callback was invoked, but there was some recent
1421 // the watcher to fire in last_activity + 60, which is 1976 // activity. simply restart the timer to time out
1422 // guaranteed to be in the future, so "again" is positive: 1977 // after "after" seconds, which is the earliest time
1423 w->again = timeout - now; 1978 // the timeout can occur.
1979 ev_timer_set (w, after, 0.);
1424 ev_timer_again (EV_A_ w); 1980 ev_timer_start (EV_A_ w);
1425 } 1981 }
1426 } 1982 }
1427 1983
1428To summarise the callback: first calculate the real timeout (defined 1984To summarise the callback: first calculate in how many seconds the
1429as "60 seconds after the last activity"), then check if that time has 1985timeout will occur (by calculating the absolute time when it would occur,
1430been reached, which means something I<did>, in fact, time out. Otherwise 1986C<last_activity + timeout>, and subtracting the current time, C<ev_now
1431the callback was invoked too early (C<timeout> is in the future), so 1987(EV_A)> from that).
1432re-schedule the timer to fire at that future time, to see if maybe we have
1433a timeout then.
1434 1988
1435Note how C<ev_timer_again> is used, taking advantage of the 1989If this value is negative, then we are already past the timeout, i.e. we
1436C<ev_timer_again> optimisation when the timer is already running. 1990timed out, and need to do whatever is needed in this case.
1991
1992Otherwise, we now the earliest time at which the timeout would trigger,
1993and simply start the timer with this timeout value.
1994
1995In other words, each time the callback is invoked it will check whether
1996the timeout occurred. If not, it will simply reschedule itself to check
1997again at the earliest time it could time out. Rinse. Repeat.
1437 1998
1438This scheme causes more callback invocations (about one every 60 seconds 1999This scheme causes more callback invocations (about one every 60 seconds
1439minus half the average time between activity), but virtually no calls to 2000minus half the average time between activity), but virtually no calls to
1440libev to change the timeout. 2001libev to change the timeout.
1441 2002
1442To start the timer, simply initialise the watcher and set C<last_activity> 2003To start the machinery, simply initialise the watcher and set
1443to the current time (meaning we just have some activity :), then call the 2004C<last_activity> to the current time (meaning there was some activity just
1444callback, which will "do the right thing" and start the timer: 2005now), then call the callback, which will "do the right thing" and start
2006the timer:
1445 2007
2008 last_activity = ev_now (EV_A);
1446 ev_timer_init (timer, callback); 2009 ev_init (&timer, callback);
1447 last_activity = ev_now (loop); 2010 callback (EV_A_ &timer, 0);
1448 callback (loop, timer, EV_TIMEOUT);
1449 2011
1450And when there is some activity, simply store the current time in 2012When there is some activity, simply store the current time in
1451C<last_activity>, no libev calls at all: 2013C<last_activity>, no libev calls at all:
1452 2014
2015 if (activity detected)
1453 last_actiivty = ev_now (loop); 2016 last_activity = ev_now (EV_A);
2017
2018When your timeout value changes, then the timeout can be changed by simply
2019providing a new value, stopping the timer and calling the callback, which
2020will again do the right thing (for example, time out immediately :).
2021
2022 timeout = new_value;
2023 ev_timer_stop (EV_A_ &timer);
2024 callback (EV_A_ &timer, 0);
1454 2025
1455This technique is slightly more complex, but in most cases where the 2026This technique is slightly more complex, but in most cases where the
1456time-out is unlikely to be triggered, much more efficient. 2027time-out is unlikely to be triggered, much more efficient.
1457
1458Changing the timeout is trivial as well (if it isn't hard-coded in the
1459callback :) - just change the timeout and invoke the callback, which will
1460fix things for you.
1461 2028
1462=item 4. Wee, just use a double-linked list for your timeouts. 2029=item 4. Wee, just use a double-linked list for your timeouts.
1463 2030
1464If there is not one request, but many thousands (millions...), all 2031If there is not one request, but many thousands (millions...), all
1465employing some kind of timeout with the same timeout value, then one can 2032employing some kind of timeout with the same timeout value, then one can
1492Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 2059Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1493rather complicated, but extremely efficient, something that really pays 2060rather complicated, but extremely efficient, something that really pays
1494off after the first million or so of active timers, i.e. it's usually 2061off after the first million or so of active timers, i.e. it's usually
1495overkill :) 2062overkill :)
1496 2063
2064=head3 The special problem of being too early
2065
2066If you ask a timer to call your callback after three seconds, then
2067you expect it to be invoked after three seconds - but of course, this
2068cannot be guaranteed to infinite precision. Less obviously, it cannot be
2069guaranteed to any precision by libev - imagine somebody suspending the
2070process with a STOP signal for a few hours for example.
2071
2072So, libev tries to invoke your callback as soon as possible I<after> the
2073delay has occurred, but cannot guarantee this.
2074
2075A less obvious failure mode is calling your callback too early: many event
2076loops compare timestamps with a "elapsed delay >= requested delay", but
2077this can cause your callback to be invoked much earlier than you would
2078expect.
2079
2080To see why, imagine a system with a clock that only offers full second
2081resolution (think windows if you can't come up with a broken enough OS
2082yourself). If you schedule a one-second timer at the time 500.9, then the
2083event loop will schedule your timeout to elapse at a system time of 500
2084(500.9 truncated to the resolution) + 1, or 501.
2085
2086If an event library looks at the timeout 0.1s later, it will see "501 >=
2087501" and invoke the callback 0.1s after it was started, even though a
2088one-second delay was requested - this is being "too early", despite best
2089intentions.
2090
2091This is the reason why libev will never invoke the callback if the elapsed
2092delay equals the requested delay, but only when the elapsed delay is
2093larger than the requested delay. In the example above, libev would only invoke
2094the callback at system time 502, or 1.1s after the timer was started.
2095
2096So, while libev cannot guarantee that your callback will be invoked
2097exactly when requested, it I<can> and I<does> guarantee that the requested
2098delay has actually elapsed, or in other words, it always errs on the "too
2099late" side of things.
2100
1497=head3 The special problem of time updates 2101=head3 The special problem of time updates
1498 2102
1499Establishing the current time is a costly operation (it usually takes at 2103Establishing the current time is a costly operation (it usually takes
1500least two system calls): EV therefore updates its idea of the current 2104at least one system call): EV therefore updates its idea of the current
1501time only before and after C<ev_loop> collects new events, which causes a 2105time only before and after C<ev_run> collects new events, which causes a
1502growing difference between C<ev_now ()> and C<ev_time ()> when handling 2106growing difference between C<ev_now ()> and C<ev_time ()> when handling
1503lots of events in one iteration. 2107lots of events in one iteration.
1504 2108
1505The relative timeouts are calculated relative to the C<ev_now ()> 2109The relative timeouts are calculated relative to the C<ev_now ()>
1506time. This is usually the right thing as this timestamp refers to the time 2110time. This is usually the right thing as this timestamp refers to the time
1507of the event triggering whatever timeout you are modifying/starting. If 2111of the event triggering whatever timeout you are modifying/starting. If
1508you suspect event processing to be delayed and you I<need> to base the 2112you suspect event processing to be delayed and you I<need> to base the
1509timeout on the current time, use something like this to adjust for this: 2113timeout on the current time, use something like the following to adjust
2114for it:
1510 2115
1511 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 2116 ev_timer_set (&timer, after + (ev_time () - ev_now ()), 0.);
1512 2117
1513If the event loop is suspended for a long time, you can also force an 2118If the event loop is suspended for a long time, you can also force an
1514update of the time returned by C<ev_now ()> by calling C<ev_now_update 2119update of the time returned by C<ev_now ()> by calling C<ev_now_update
1515()>. 2120()>, although that will push the event time of all outstanding events
2121further into the future.
2122
2123=head3 The special problem of unsynchronised clocks
2124
2125Modern systems have a variety of clocks - libev itself uses the normal
2126"wall clock" clock and, if available, the monotonic clock (to avoid time
2127jumps).
2128
2129Neither of these clocks is synchronised with each other or any other clock
2130on the system, so C<ev_time ()> might return a considerably different time
2131than C<gettimeofday ()> or C<time ()>. On a GNU/Linux system, for example,
2132a call to C<gettimeofday> might return a second count that is one higher
2133than a directly following call to C<time>.
2134
2135The moral of this is to only compare libev-related timestamps with
2136C<ev_time ()> and C<ev_now ()>, at least if you want better precision than
2137a second or so.
2138
2139One more problem arises due to this lack of synchronisation: if libev uses
2140the system monotonic clock and you compare timestamps from C<ev_time>
2141or C<ev_now> from when you started your timer and when your callback is
2142invoked, you will find that sometimes the callback is a bit "early".
2143
2144This is because C<ev_timer>s work in real time, not wall clock time, so
2145libev makes sure your callback is not invoked before the delay happened,
2146I<measured according to the real time>, not the system clock.
2147
2148If your timeouts are based on a physical timescale (e.g. "time out this
2149connection after 100 seconds") then this shouldn't bother you as it is
2150exactly the right behaviour.
2151
2152If you want to compare wall clock/system timestamps to your timers, then
2153you need to use C<ev_periodic>s, as these are based on the wall clock
2154time, where your comparisons will always generate correct results.
2155
2156=head3 The special problems of suspended animation
2157
2158When you leave the server world it is quite customary to hit machines that
2159can suspend/hibernate - what happens to the clocks during such a suspend?
2160
2161Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
2162all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
2163to run until the system is suspended, but they will not advance while the
2164system is suspended. That means, on resume, it will be as if the program
2165was frozen for a few seconds, but the suspend time will not be counted
2166towards C<ev_timer> when a monotonic clock source is used. The real time
2167clock advanced as expected, but if it is used as sole clocksource, then a
2168long suspend would be detected as a time jump by libev, and timers would
2169be adjusted accordingly.
2170
2171I would not be surprised to see different behaviour in different between
2172operating systems, OS versions or even different hardware.
2173
2174The other form of suspend (job control, or sending a SIGSTOP) will see a
2175time jump in the monotonic clocks and the realtime clock. If the program
2176is suspended for a very long time, and monotonic clock sources are in use,
2177then you can expect C<ev_timer>s to expire as the full suspension time
2178will be counted towards the timers. When no monotonic clock source is in
2179use, then libev will again assume a timejump and adjust accordingly.
2180
2181It might be beneficial for this latter case to call C<ev_suspend>
2182and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
2183deterministic behaviour in this case (you can do nothing against
2184C<SIGSTOP>).
1516 2185
1517=head3 Watcher-Specific Functions and Data Members 2186=head3 Watcher-Specific Functions and Data Members
1518 2187
1519=over 4 2188=over 4
1520 2189
1521=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 2190=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1522 2191
1523=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 2192=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
1524 2193
1525Configure the timer to trigger after C<after> seconds. If C<repeat> 2194Configure the timer to trigger after C<after> seconds (fractional and
1526is C<0.>, then it will automatically be stopped once the timeout is 2195negative values are supported). If C<repeat> is C<0.>, then it will
1527reached. If it is positive, then the timer will automatically be 2196automatically be stopped once the timeout is reached. If it is positive,
1528configured to trigger again C<repeat> seconds later, again, and again, 2197then the timer will automatically be configured to trigger again C<repeat>
1529until stopped manually. 2198seconds later, again, and again, until stopped manually.
1530 2199
1531The timer itself will do a best-effort at avoiding drift, that is, if 2200The timer itself will do a best-effort at avoiding drift, that is, if
1532you configure a timer to trigger every 10 seconds, then it will normally 2201you configure a timer to trigger every 10 seconds, then it will normally
1533trigger at exactly 10 second intervals. If, however, your program cannot 2202trigger at exactly 10 second intervals. If, however, your program cannot
1534keep up with the timer (because it takes longer than those 10 seconds to 2203keep up with the timer (because it takes longer than those 10 seconds to
1535do stuff) the timer will not fire more than once per event loop iteration. 2204do stuff) the timer will not fire more than once per event loop iteration.
1536 2205
1537=item ev_timer_again (loop, ev_timer *) 2206=item ev_timer_again (loop, ev_timer *)
1538 2207
1539This will act as if the timer timed out and restart it again if it is 2208This will act as if the timer timed out, and restarts it again if it is
1540repeating. The exact semantics are: 2209repeating. It basically works like calling C<ev_timer_stop>, updating the
2210timeout to the C<repeat> value and calling C<ev_timer_start>.
1541 2211
2212The exact semantics are as in the following rules, all of which will be
2213applied to the watcher:
2214
2215=over 4
2216
1542If the timer is pending, its pending status is cleared. 2217=item If the timer is pending, the pending status is always cleared.
1543 2218
1544If the timer is started but non-repeating, stop it (as if it timed out). 2219=item If the timer is started but non-repeating, stop it (as if it timed
2220out, without invoking it).
1545 2221
1546If the timer is repeating, either start it if necessary (with the 2222=item If the timer is repeating, make the C<repeat> value the new timeout
1547C<repeat> value), or reset the running timer to the C<repeat> value. 2223and start the timer, if necessary.
1548 2224
2225=back
2226
1549This sounds a bit complicated, see "Be smart about timeouts", above, for a 2227This sounds a bit complicated, see L</Be smart about timeouts>, above, for a
1550usage example. 2228usage example.
2229
2230=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
2231
2232Returns the remaining time until a timer fires. If the timer is active,
2233then this time is relative to the current event loop time, otherwise it's
2234the timeout value currently configured.
2235
2236That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
2237C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
2238will return C<4>. When the timer expires and is restarted, it will return
2239roughly C<7> (likely slightly less as callback invocation takes some time,
2240too), and so on.
1551 2241
1552=item ev_tstamp repeat [read-write] 2242=item ev_tstamp repeat [read-write]
1553 2243
1554The current C<repeat> value. Will be used each time the watcher times out 2244The current C<repeat> value. Will be used each time the watcher times out
1555or C<ev_timer_again> is called, and determines the next timeout (if any), 2245or C<ev_timer_again> is called, and determines the next timeout (if any),
1581 } 2271 }
1582 2272
1583 ev_timer mytimer; 2273 ev_timer mytimer;
1584 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 2274 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1585 ev_timer_again (&mytimer); /* start timer */ 2275 ev_timer_again (&mytimer); /* start timer */
1586 ev_loop (loop, 0); 2276 ev_run (loop, 0);
1587 2277
1588 // and in some piece of code that gets executed on any "activity": 2278 // and in some piece of code that gets executed on any "activity":
1589 // reset the timeout to start ticking again at 10 seconds 2279 // reset the timeout to start ticking again at 10 seconds
1590 ev_timer_again (&mytimer); 2280 ev_timer_again (&mytimer);
1591 2281
1593=head2 C<ev_periodic> - to cron or not to cron? 2283=head2 C<ev_periodic> - to cron or not to cron?
1594 2284
1595Periodic watchers are also timers of a kind, but they are very versatile 2285Periodic watchers are also timers of a kind, but they are very versatile
1596(and unfortunately a bit complex). 2286(and unfortunately a bit complex).
1597 2287
1598Unlike C<ev_timer>'s, they are not based on real time (or relative time) 2288Unlike C<ev_timer>, periodic watchers are not based on real time (or
1599but on wall clock time (absolute time). You can tell a periodic watcher 2289relative time, the physical time that passes) but on wall clock time
1600to trigger after some specific point in time. For example, if you tell a 2290(absolute time, the thing you can read on your calendar or clock). The
1601periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 2291difference is that wall clock time can run faster or slower than real
1602+ 10.>, that is, an absolute time not a delay) and then reset your system 2292time, and time jumps are not uncommon (e.g. when you adjust your
1603clock to January of the previous year, then it will take more than year 2293wrist-watch).
1604to trigger the event (unlike an C<ev_timer>, which would still trigger
1605roughly 10 seconds later as it uses a relative timeout).
1606 2294
2295You can tell a periodic watcher to trigger after some specific point
2296in time: for example, if you tell a periodic watcher to trigger "in 10
2297seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
2298not a delay) and then reset your system clock to January of the previous
2299year, then it will take a year or more to trigger the event (unlike an
2300C<ev_timer>, which would still trigger roughly 10 seconds after starting
2301it, as it uses a relative timeout).
2302
1607C<ev_periodic>s can also be used to implement vastly more complex timers, 2303C<ev_periodic> watchers can also be used to implement vastly more complex
1608such as triggering an event on each "midnight, local time", or other 2304timers, such as triggering an event on each "midnight, local time", or
1609complicated rules. 2305other complicated rules. This cannot easily be done with C<ev_timer>
2306watchers, as those cannot react to time jumps.
1610 2307
1611As with timers, the callback is guaranteed to be invoked only when the 2308As with timers, the callback is guaranteed to be invoked only when the
1612time (C<at>) has passed, but if multiple periodic timers become ready 2309point in time where it is supposed to trigger has passed. If multiple
1613during the same loop iteration, then order of execution is undefined. 2310timers become ready during the same loop iteration then the ones with
2311earlier time-out values are invoked before ones with later time-out values
2312(but this is no longer true when a callback calls C<ev_run> recursively).
1614 2313
1615=head3 Watcher-Specific Functions and Data Members 2314=head3 Watcher-Specific Functions and Data Members
1616 2315
1617=over 4 2316=over 4
1618 2317
1619=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 2318=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1620 2319
1621=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 2320=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1622 2321
1623Lots of arguments, lets sort it out... There are basically three modes of 2322Lots of arguments, let's sort it out... There are basically three modes of
1624operation, and we will explain them from simplest to most complex: 2323operation, and we will explain them from simplest to most complex:
1625 2324
1626=over 4 2325=over 4
1627 2326
1628=item * absolute timer (at = time, interval = reschedule_cb = 0) 2327=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1629 2328
1630In this configuration the watcher triggers an event after the wall clock 2329In this configuration the watcher triggers an event after the wall clock
1631time C<at> has passed. It will not repeat and will not adjust when a time 2330time C<offset> has passed. It will not repeat and will not adjust when a
1632jump occurs, that is, if it is to be run at January 1st 2011 then it will 2331time jump occurs, that is, if it is to be run at January 1st 2011 then it
1633only run when the system clock reaches or surpasses this time. 2332will be stopped and invoked when the system clock reaches or surpasses
2333this point in time.
1634 2334
1635=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 2335=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1636 2336
1637In this mode the watcher will always be scheduled to time out at the next 2337In this mode the watcher will always be scheduled to time out at the next
1638C<at + N * interval> time (for some integer N, which can also be negative) 2338C<offset + N * interval> time (for some integer N, which can also be
1639and then repeat, regardless of any time jumps. 2339negative) and then repeat, regardless of any time jumps. The C<offset>
2340argument is merely an offset into the C<interval> periods.
1640 2341
1641This can be used to create timers that do not drift with respect to the 2342This can be used to create timers that do not drift with respect to the
1642system clock, for example, here is a C<ev_periodic> that triggers each 2343system clock, for example, here is an C<ev_periodic> that triggers each
1643hour, on the hour: 2344hour, on the hour (with respect to UTC):
1644 2345
1645 ev_periodic_set (&periodic, 0., 3600., 0); 2346 ev_periodic_set (&periodic, 0., 3600., 0);
1646 2347
1647This doesn't mean there will always be 3600 seconds in between triggers, 2348This doesn't mean there will always be 3600 seconds in between triggers,
1648but only that the callback will be called when the system time shows a 2349but only that the callback will be called when the system time shows a
1649full hour (UTC), or more correctly, when the system time is evenly divisible 2350full hour (UTC), or more correctly, when the system time is evenly divisible
1650by 3600. 2351by 3600.
1651 2352
1652Another way to think about it (for the mathematically inclined) is that 2353Another way to think about it (for the mathematically inclined) is that
1653C<ev_periodic> will try to run the callback in this mode at the next possible 2354C<ev_periodic> will try to run the callback in this mode at the next possible
1654time where C<time = at (mod interval)>, regardless of any time jumps. 2355time where C<time = offset (mod interval)>, regardless of any time jumps.
1655 2356
1656For numerical stability it is preferable that the C<at> value is near 2357The C<interval> I<MUST> be positive, and for numerical stability, the
1657C<ev_now ()> (the current time), but there is no range requirement for 2358interval value should be higher than C<1/8192> (which is around 100
1658this value, and in fact is often specified as zero. 2359microseconds) and C<offset> should be higher than C<0> and should have
2360at most a similar magnitude as the current time (say, within a factor of
2361ten). Typical values for offset are, in fact, C<0> or something between
2362C<0> and C<interval>, which is also the recommended range.
1659 2363
1660Note also that there is an upper limit to how often a timer can fire (CPU 2364Note also that there is an upper limit to how often a timer can fire (CPU
1661speed for example), so if C<interval> is very small then timing stability 2365speed for example), so if C<interval> is very small then timing stability
1662will of course deteriorate. Libev itself tries to be exact to be about one 2366will of course deteriorate. Libev itself tries to be exact to be about one
1663millisecond (if the OS supports it and the machine is fast enough). 2367millisecond (if the OS supports it and the machine is fast enough).
1664 2368
1665=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 2369=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1666 2370
1667In this mode the values for C<interval> and C<at> are both being 2371In this mode the values for C<interval> and C<offset> are both being
1668ignored. Instead, each time the periodic watcher gets scheduled, the 2372ignored. Instead, each time the periodic watcher gets scheduled, the
1669reschedule callback will be called with the watcher as first, and the 2373reschedule callback will be called with the watcher as first, and the
1670current time as second argument. 2374current time as second argument.
1671 2375
1672NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 2376NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1673ever, or make ANY event loop modifications whatsoever>. 2377or make ANY other event loop modifications whatsoever, unless explicitly
2378allowed by documentation here>.
1674 2379
1675If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 2380If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1676it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 2381it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1677only event loop modification you are allowed to do). 2382only event loop modification you are allowed to do).
1678 2383
1692 2397
1693NOTE: I<< This callback must always return a time that is higher than or 2398NOTE: I<< This callback must always return a time that is higher than or
1694equal to the passed C<now> value >>. 2399equal to the passed C<now> value >>.
1695 2400
1696This can be used to create very complex timers, such as a timer that 2401This can be used to create very complex timers, such as a timer that
1697triggers on "next midnight, local time". To do this, you would calculate the 2402triggers on "next midnight, local time". To do this, you would calculate
1698next midnight after C<now> and return the timestamp value for this. How 2403the next midnight after C<now> and return the timestamp value for
1699you do this is, again, up to you (but it is not trivial, which is the main 2404this. Here is a (completely untested, no error checking) example on how to
1700reason I omitted it as an example). 2405do this:
2406
2407 #include <time.h>
2408
2409 static ev_tstamp
2410 my_rescheduler (ev_periodic *w, ev_tstamp now)
2411 {
2412 time_t tnow = (time_t)now;
2413 struct tm tm;
2414 localtime_r (&tnow, &tm);
2415
2416 tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2417 ++tm.tm_mday; // midnight next day
2418
2419 return mktime (&tm);
2420 }
2421
2422Note: this code might run into trouble on days that have more then two
2423midnights (beginning and end).
1701 2424
1702=back 2425=back
1703 2426
1704=item ev_periodic_again (loop, ev_periodic *) 2427=item ev_periodic_again (loop, ev_periodic *)
1705 2428
1708a different time than the last time it was called (e.g. in a crond like 2431a different time than the last time it was called (e.g. in a crond like
1709program when the crontabs have changed). 2432program when the crontabs have changed).
1710 2433
1711=item ev_tstamp ev_periodic_at (ev_periodic *) 2434=item ev_tstamp ev_periodic_at (ev_periodic *)
1712 2435
1713When active, returns the absolute time that the watcher is supposed to 2436When active, returns the absolute time that the watcher is supposed
1714trigger next. 2437to trigger next. This is not the same as the C<offset> argument to
2438C<ev_periodic_set>, but indeed works even in interval and manual
2439rescheduling modes.
1715 2440
1716=item ev_tstamp offset [read-write] 2441=item ev_tstamp offset [read-write]
1717 2442
1718When repeating, this contains the offset value, otherwise this is the 2443When repeating, this contains the offset value, otherwise this is the
1719absolute point in time (the C<at> value passed to C<ev_periodic_set>). 2444absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
2445although libev might modify this value for better numerical stability).
1720 2446
1721Can be modified any time, but changes only take effect when the periodic 2447Can be modified any time, but changes only take effect when the periodic
1722timer fires or C<ev_periodic_again> is being called. 2448timer fires or C<ev_periodic_again> is being called.
1723 2449
1724=item ev_tstamp interval [read-write] 2450=item ev_tstamp interval [read-write]
1740Example: Call a callback every hour, or, more precisely, whenever the 2466Example: Call a callback every hour, or, more precisely, whenever the
1741system time is divisible by 3600. The callback invocation times have 2467system time is divisible by 3600. The callback invocation times have
1742potentially a lot of jitter, but good long-term stability. 2468potentially a lot of jitter, but good long-term stability.
1743 2469
1744 static void 2470 static void
1745 clock_cb (struct ev_loop *loop, ev_io *w, int revents) 2471 clock_cb (struct ev_loop *loop, ev_periodic *w, int revents)
1746 { 2472 {
1747 ... its now a full hour (UTC, or TAI or whatever your clock follows) 2473 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1748 } 2474 }
1749 2475
1750 ev_periodic hourly_tick; 2476 ev_periodic hourly_tick;
1767 2493
1768 ev_periodic hourly_tick; 2494 ev_periodic hourly_tick;
1769 ev_periodic_init (&hourly_tick, clock_cb, 2495 ev_periodic_init (&hourly_tick, clock_cb,
1770 fmod (ev_now (loop), 3600.), 3600., 0); 2496 fmod (ev_now (loop), 3600.), 3600., 0);
1771 ev_periodic_start (loop, &hourly_tick); 2497 ev_periodic_start (loop, &hourly_tick);
1772 2498
1773 2499
1774=head2 C<ev_signal> - signal me when a signal gets signalled! 2500=head2 C<ev_signal> - signal me when a signal gets signalled!
1775 2501
1776Signal watchers will trigger an event when the process receives a specific 2502Signal watchers will trigger an event when the process receives a specific
1777signal one or more times. Even though signals are very asynchronous, libev 2503signal one or more times. Even though signals are very asynchronous, libev
1778will try it's best to deliver signals synchronously, i.e. as part of the 2504will try its best to deliver signals synchronously, i.e. as part of the
1779normal event processing, like any other event. 2505normal event processing, like any other event.
1780 2506
1781If you want signals asynchronously, just use C<sigaction> as you would 2507If you want signals to be delivered truly asynchronously, just use
1782do without libev and forget about sharing the signal. You can even use 2508C<sigaction> as you would do without libev and forget about sharing
1783C<ev_async> from a signal handler to synchronously wake up an event loop. 2509the signal. You can even use C<ev_async> from a signal handler to
2510synchronously wake up an event loop.
1784 2511
1785You can configure as many watchers as you like per signal. Only when the 2512You can configure as many watchers as you like for the same signal, but
1786first watcher gets started will libev actually register a signal handler 2513only within the same loop, i.e. you can watch for C<SIGINT> in your
1787with the kernel (thus it coexists with your own signal handlers as long as 2514default loop and for C<SIGIO> in another loop, but you cannot watch for
1788you don't register any with libev for the same signal). Similarly, when 2515C<SIGINT> in both the default loop and another loop at the same time. At
1789the last signal watcher for a signal is stopped, libev will reset the 2516the moment, C<SIGCHLD> is permanently tied to the default loop.
1790signal handler to SIG_DFL (regardless of what it was set to before). 2517
2518Only after the first watcher for a signal is started will libev actually
2519register something with the kernel. It thus coexists with your own signal
2520handlers as long as you don't register any with libev for the same signal.
1791 2521
1792If possible and supported, libev will install its handlers with 2522If possible and supported, libev will install its handlers with
1793C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2523C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1794interrupted. If you have a problem with system calls getting interrupted by 2524not be unduly interrupted. If you have a problem with system calls getting
1795signals you can block all signals in an C<ev_check> watcher and unblock 2525interrupted by signals you can block all signals in an C<ev_check> watcher
1796them in an C<ev_prepare> watcher. 2526and unblock them in an C<ev_prepare> watcher.
2527
2528=head3 The special problem of inheritance over fork/execve/pthread_create
2529
2530Both the signal mask (C<sigprocmask>) and the signal disposition
2531(C<sigaction>) are unspecified after starting a signal watcher (and after
2532stopping it again), that is, libev might or might not block the signal,
2533and might or might not set or restore the installed signal handler (but
2534see C<EVFLAG_NOSIGMASK>).
2535
2536While this does not matter for the signal disposition (libev never
2537sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2538C<execve>), this matters for the signal mask: many programs do not expect
2539certain signals to be blocked.
2540
2541This means that before calling C<exec> (from the child) you should reset
2542the signal mask to whatever "default" you expect (all clear is a good
2543choice usually).
2544
2545The simplest way to ensure that the signal mask is reset in the child is
2546to install a fork handler with C<pthread_atfork> that resets it. That will
2547catch fork calls done by libraries (such as the libc) as well.
2548
2549In current versions of libev, the signal will not be blocked indefinitely
2550unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2551the window of opportunity for problems, it will not go away, as libev
2552I<has> to modify the signal mask, at least temporarily.
2553
2554So I can't stress this enough: I<If you do not reset your signal mask when
2555you expect it to be empty, you have a race condition in your code>. This
2556is not a libev-specific thing, this is true for most event libraries.
2557
2558=head3 The special problem of threads signal handling
2559
2560POSIX threads has problematic signal handling semantics, specifically,
2561a lot of functionality (sigfd, sigwait etc.) only really works if all
2562threads in a process block signals, which is hard to achieve.
2563
2564When you want to use sigwait (or mix libev signal handling with your own
2565for the same signals), you can tackle this problem by globally blocking
2566all signals before creating any threads (or creating them with a fully set
2567sigprocmask) and also specifying the C<EVFLAG_NOSIGMASK> when creating
2568loops. Then designate one thread as "signal receiver thread" which handles
2569these signals. You can pass on any signals that libev might be interested
2570in by calling C<ev_feed_signal>.
1797 2571
1798=head3 Watcher-Specific Functions and Data Members 2572=head3 Watcher-Specific Functions and Data Members
1799 2573
1800=over 4 2574=over 4
1801 2575
1817Example: Try to exit cleanly on SIGINT. 2591Example: Try to exit cleanly on SIGINT.
1818 2592
1819 static void 2593 static void
1820 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2594 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1821 { 2595 {
1822 ev_unloop (loop, EVUNLOOP_ALL); 2596 ev_break (loop, EVBREAK_ALL);
1823 } 2597 }
1824 2598
1825 ev_signal signal_watcher; 2599 ev_signal signal_watcher;
1826 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 2600 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1827 ev_signal_start (loop, &signal_watcher); 2601 ev_signal_start (loop, &signal_watcher);
1833some child status changes (most typically when a child of yours dies or 2607some child status changes (most typically when a child of yours dies or
1834exits). It is permissible to install a child watcher I<after> the child 2608exits). It is permissible to install a child watcher I<after> the child
1835has been forked (which implies it might have already exited), as long 2609has been forked (which implies it might have already exited), as long
1836as the event loop isn't entered (or is continued from a watcher), i.e., 2610as the event loop isn't entered (or is continued from a watcher), i.e.,
1837forking and then immediately registering a watcher for the child is fine, 2611forking and then immediately registering a watcher for the child is fine,
1838but forking and registering a watcher a few event loop iterations later is 2612but forking and registering a watcher a few event loop iterations later or
1839not. 2613in the next callback invocation is not.
1840 2614
1841Only the default event loop is capable of handling signals, and therefore 2615Only the default event loop is capable of handling signals, and therefore
1842you can only register child watchers in the default event loop. 2616you can only register child watchers in the default event loop.
1843 2617
2618Due to some design glitches inside libev, child watchers will always be
2619handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2620libev)
2621
1844=head3 Process Interaction 2622=head3 Process Interaction
1845 2623
1846Libev grabs C<SIGCHLD> as soon as the default event loop is 2624Libev grabs C<SIGCHLD> as soon as the default event loop is
1847initialised. This is necessary to guarantee proper behaviour even if 2625initialised. This is necessary to guarantee proper behaviour even if the
1848the first child watcher is started after the child exits. The occurrence 2626first child watcher is started after the child exits. The occurrence
1849of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2627of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1850synchronously as part of the event loop processing. Libev always reaps all 2628synchronously as part of the event loop processing. Libev always reaps all
1851children, even ones not watched. 2629children, even ones not watched.
1852 2630
1853=head3 Overriding the Built-In Processing 2631=head3 Overriding the Built-In Processing
1863=head3 Stopping the Child Watcher 2641=head3 Stopping the Child Watcher
1864 2642
1865Currently, the child watcher never gets stopped, even when the 2643Currently, the child watcher never gets stopped, even when the
1866child terminates, so normally one needs to stop the watcher in the 2644child terminates, so normally one needs to stop the watcher in the
1867callback. Future versions of libev might stop the watcher automatically 2645callback. Future versions of libev might stop the watcher automatically
1868when a child exit is detected. 2646when a child exit is detected (calling C<ev_child_stop> twice is not a
2647problem).
1869 2648
1870=head3 Watcher-Specific Functions and Data Members 2649=head3 Watcher-Specific Functions and Data Members
1871 2650
1872=over 4 2651=over 4
1873 2652
1931 2710
1932=head2 C<ev_stat> - did the file attributes just change? 2711=head2 C<ev_stat> - did the file attributes just change?
1933 2712
1934This watches a file system path for attribute changes. That is, it calls 2713This watches a file system path for attribute changes. That is, it calls
1935C<stat> on that path in regular intervals (or when the OS says it changed) 2714C<stat> on that path in regular intervals (or when the OS says it changed)
1936and sees if it changed compared to the last time, invoking the callback if 2715and sees if it changed compared to the last time, invoking the callback
1937it did. 2716if it did. Starting the watcher C<stat>'s the file, so only changes that
2717happen after the watcher has been started will be reported.
1938 2718
1939The path does not need to exist: changing from "path exists" to "path does 2719The path does not need to exist: changing from "path exists" to "path does
1940not exist" is a status change like any other. The condition "path does not 2720not exist" is a status change like any other. The condition "path does not
1941exist" (or more correctly "path cannot be stat'ed") is signified by the 2721exist" (or more correctly "path cannot be stat'ed") is signified by the
1942C<st_nlink> field being zero (which is otherwise always forced to be at 2722C<st_nlink> field being zero (which is otherwise always forced to be at
2009the process. The exception are C<ev_stat> watchers - those call C<stat 2789the process. The exception are C<ev_stat> watchers - those call C<stat
2010()>, which is a synchronous operation. 2790()>, which is a synchronous operation.
2011 2791
2012For local paths, this usually doesn't matter: unless the system is very 2792For local paths, this usually doesn't matter: unless the system is very
2013busy or the intervals between stat's are large, a stat call will be fast, 2793busy or the intervals between stat's are large, a stat call will be fast,
2014as the path data is suually in memory already (except when starting the 2794as the path data is usually in memory already (except when starting the
2015watcher). 2795watcher).
2016 2796
2017For networked file systems, calling C<stat ()> can block an indefinite 2797For networked file systems, calling C<stat ()> can block an indefinite
2018time due to network issues, and even under good conditions, a stat call 2798time due to network issues, and even under good conditions, a stat call
2019often takes multiple milliseconds. 2799often takes multiple milliseconds.
2172Apart from keeping your process non-blocking (which is a useful 2952Apart from keeping your process non-blocking (which is a useful
2173effect on its own sometimes), idle watchers are a good place to do 2953effect on its own sometimes), idle watchers are a good place to do
2174"pseudo-background processing", or delay processing stuff to after the 2954"pseudo-background processing", or delay processing stuff to after the
2175event loop has handled all outstanding events. 2955event loop has handled all outstanding events.
2176 2956
2957=head3 Abusing an C<ev_idle> watcher for its side-effect
2958
2959As long as there is at least one active idle watcher, libev will never
2960sleep unnecessarily. Or in other words, it will loop as fast as possible.
2961For this to work, the idle watcher doesn't need to be invoked at all - the
2962lowest priority will do.
2963
2964This mode of operation can be useful together with an C<ev_check> watcher,
2965to do something on each event loop iteration - for example to balance load
2966between different connections.
2967
2968See L</Abusing an ev_check watcher for its side-effect> for a longer
2969example.
2970
2177=head3 Watcher-Specific Functions and Data Members 2971=head3 Watcher-Specific Functions and Data Members
2178 2972
2179=over 4 2973=over 4
2180 2974
2181=item ev_idle_init (ev_signal *, callback) 2975=item ev_idle_init (ev_idle *, callback)
2182 2976
2183Initialises and configures the idle watcher - it has no parameters of any 2977Initialises and configures the idle watcher - it has no parameters of any
2184kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2978kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2185believe me. 2979believe me.
2186 2980
2192callback, free it. Also, use no error checking, as usual. 2986callback, free it. Also, use no error checking, as usual.
2193 2987
2194 static void 2988 static void
2195 idle_cb (struct ev_loop *loop, ev_idle *w, int revents) 2989 idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
2196 { 2990 {
2991 // stop the watcher
2992 ev_idle_stop (loop, w);
2993
2994 // now we can free it
2197 free (w); 2995 free (w);
2996
2198 // now do something you wanted to do when the program has 2997 // now do something you wanted to do when the program has
2199 // no longer anything immediate to do. 2998 // no longer anything immediate to do.
2200 } 2999 }
2201 3000
2202 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 3001 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2203 ev_idle_init (idle_watcher, idle_cb); 3002 ev_idle_init (idle_watcher, idle_cb);
2204 ev_idle_start (loop, idle_cb); 3003 ev_idle_start (loop, idle_watcher);
2205 3004
2206 3005
2207=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 3006=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2208 3007
2209Prepare and check watchers are usually (but not always) used in pairs: 3008Prepare and check watchers are often (but not always) used in pairs:
2210prepare watchers get invoked before the process blocks and check watchers 3009prepare watchers get invoked before the process blocks and check watchers
2211afterwards. 3010afterwards.
2212 3011
2213You I<must not> call C<ev_loop> or similar functions that enter 3012You I<must not> call C<ev_run> (or similar functions that enter the
2214the current event loop from either C<ev_prepare> or C<ev_check> 3013current event loop) or C<ev_loop_fork> from either C<ev_prepare> or
2215watchers. Other loops than the current one are fine, however. The 3014C<ev_check> watchers. Other loops than the current one are fine,
2216rationale behind this is that you do not need to check for recursion in 3015however. The rationale behind this is that you do not need to check
2217those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 3016for recursion in those watchers, i.e. the sequence will always be
2218C<ev_check> so if you have one watcher of each kind they will always be 3017C<ev_prepare>, blocking, C<ev_check> so if you have one watcher of each
2219called in pairs bracketing the blocking call. 3018kind they will always be called in pairs bracketing the blocking call.
2220 3019
2221Their main purpose is to integrate other event mechanisms into libev and 3020Their main purpose is to integrate other event mechanisms into libev and
2222their use is somewhat advanced. They could be used, for example, to track 3021their use is somewhat advanced. They could be used, for example, to track
2223variable changes, implement your own watchers, integrate net-snmp or a 3022variable changes, implement your own watchers, integrate net-snmp or a
2224coroutine library and lots more. They are also occasionally useful if 3023coroutine library and lots more. They are also occasionally useful if
2242with priority higher than or equal to the event loop and one coroutine 3041with priority higher than or equal to the event loop and one coroutine
2243of lower priority, but only once, using idle watchers to keep the event 3042of lower priority, but only once, using idle watchers to keep the event
2244loop from blocking if lower-priority coroutines are active, thus mapping 3043loop from blocking if lower-priority coroutines are active, thus mapping
2245low-priority coroutines to idle/background tasks). 3044low-priority coroutines to idle/background tasks).
2246 3045
2247It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 3046When used for this purpose, it is recommended to give C<ev_check> watchers
2248priority, to ensure that they are being run before any other watchers 3047highest (C<EV_MAXPRI>) priority, to ensure that they are being run before
2249after the poll (this doesn't matter for C<ev_prepare> watchers). 3048any other watchers after the poll (this doesn't matter for C<ev_prepare>
3049watchers).
2250 3050
2251Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not 3051Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
2252activate ("feed") events into libev. While libev fully supports this, they 3052activate ("feed") events into libev. While libev fully supports this, they
2253might get executed before other C<ev_check> watchers did their job. As 3053might get executed before other C<ev_check> watchers did their job. As
2254C<ev_check> watchers are often used to embed other (non-libev) event 3054C<ev_check> watchers are often used to embed other (non-libev) event
2255loops those other event loops might be in an unusable state until their 3055loops those other event loops might be in an unusable state until their
2256C<ev_check> watcher ran (always remind yourself to coexist peacefully with 3056C<ev_check> watcher ran (always remind yourself to coexist peacefully with
2257others). 3057others).
3058
3059=head3 Abusing an C<ev_check> watcher for its side-effect
3060
3061C<ev_check> (and less often also C<ev_prepare>) watchers can also be
3062useful because they are called once per event loop iteration. For
3063example, if you want to handle a large number of connections fairly, you
3064normally only do a bit of work for each active connection, and if there
3065is more work to do, you wait for the next event loop iteration, so other
3066connections have a chance of making progress.
3067
3068Using an C<ev_check> watcher is almost enough: it will be called on the
3069next event loop iteration. However, that isn't as soon as possible -
3070without external events, your C<ev_check> watcher will not be invoked.
3071
3072This is where C<ev_idle> watchers come in handy - all you need is a
3073single global idle watcher that is active as long as you have one active
3074C<ev_check> watcher. The C<ev_idle> watcher makes sure the event loop
3075will not sleep, and the C<ev_check> watcher makes sure a callback gets
3076invoked. Neither watcher alone can do that.
2258 3077
2259=head3 Watcher-Specific Functions and Data Members 3078=head3 Watcher-Specific Functions and Data Members
2260 3079
2261=over 4 3080=over 4
2262 3081
2302 struct pollfd fds [nfd]; 3121 struct pollfd fds [nfd];
2303 // actual code will need to loop here and realloc etc. 3122 // actual code will need to loop here and realloc etc.
2304 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 3123 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2305 3124
2306 /* the callback is illegal, but won't be called as we stop during check */ 3125 /* the callback is illegal, but won't be called as we stop during check */
2307 ev_timer_init (&tw, 0, timeout * 1e-3); 3126 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2308 ev_timer_start (loop, &tw); 3127 ev_timer_start (loop, &tw);
2309 3128
2310 // create one ev_io per pollfd 3129 // create one ev_io per pollfd
2311 for (int i = 0; i < nfd; ++i) 3130 for (int i = 0; i < nfd; ++i)
2312 { 3131 {
2386 3205
2387 if (timeout >= 0) 3206 if (timeout >= 0)
2388 // create/start timer 3207 // create/start timer
2389 3208
2390 // poll 3209 // poll
2391 ev_loop (EV_A_ 0); 3210 ev_run (EV_A_ 0);
2392 3211
2393 // stop timer again 3212 // stop timer again
2394 if (timeout >= 0) 3213 if (timeout >= 0)
2395 ev_timer_stop (EV_A_ &to); 3214 ev_timer_stop (EV_A_ &to);
2396 3215
2425some fds have to be watched and handled very quickly (with low latency), 3244some fds have to be watched and handled very quickly (with low latency),
2426and even priorities and idle watchers might have too much overhead. In 3245and even priorities and idle watchers might have too much overhead. In
2427this case you would put all the high priority stuff in one loop and all 3246this case you would put all the high priority stuff in one loop and all
2428the rest in a second one, and embed the second one in the first. 3247the rest in a second one, and embed the second one in the first.
2429 3248
2430As long as the watcher is active, the callback will be invoked every time 3249As long as the watcher is active, the callback will be invoked every
2431there might be events pending in the embedded loop. The callback must then 3250time there might be events pending in the embedded loop. The callback
2432call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 3251must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2433their callbacks (you could also start an idle watcher to give the embedded 3252sweep and invoke their callbacks (the callback doesn't need to invoke the
2434loop strictly lower priority for example). You can also set the callback 3253C<ev_embed_sweep> function directly, it could also start an idle watcher
2435to C<0>, in which case the embed watcher will automatically execute the 3254to give the embedded loop strictly lower priority for example).
2436embedded loop sweep.
2437 3255
2438As long as the watcher is started it will automatically handle events. The 3256You can also set the callback to C<0>, in which case the embed watcher
2439callback will be invoked whenever some events have been handled. You can 3257will automatically execute the embedded loop sweep whenever necessary.
2440set the callback to C<0> to avoid having to specify one if you are not
2441interested in that.
2442 3258
2443Also, there have not currently been made special provisions for forking: 3259Fork detection will be handled transparently while the C<ev_embed> watcher
2444when you fork, you not only have to call C<ev_loop_fork> on both loops, 3260is active, i.e., the embedded loop will automatically be forked when the
2445but you will also have to stop and restart any C<ev_embed> watchers 3261embedding loop forks. In other cases, the user is responsible for calling
2446yourself - but you can use a fork watcher to handle this automatically, 3262C<ev_loop_fork> on the embedded loop.
2447and future versions of libev might do just that.
2448 3263
2449Unfortunately, not all backends are embeddable: only the ones returned by 3264Unfortunately, not all backends are embeddable: only the ones returned by
2450C<ev_embeddable_backends> are, which, unfortunately, does not include any 3265C<ev_embeddable_backends> are, which, unfortunately, does not include any
2451portable one. 3266portable one.
2452 3267
2467 3282
2468=over 4 3283=over 4
2469 3284
2470=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 3285=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
2471 3286
2472=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 3287=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
2473 3288
2474Configures the watcher to embed the given loop, which must be 3289Configures the watcher to embed the given loop, which must be
2475embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 3290embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
2476invoked automatically, otherwise it is the responsibility of the callback 3291invoked automatically, otherwise it is the responsibility of the callback
2477to invoke it (it will continue to be called until the sweep has been done, 3292to invoke it (it will continue to be called until the sweep has been done,
2478if you do not want that, you need to temporarily stop the embed watcher). 3293if you do not want that, you need to temporarily stop the embed watcher).
2479 3294
2480=item ev_embed_sweep (loop, ev_embed *) 3295=item ev_embed_sweep (loop, ev_embed *)
2481 3296
2482Make a single, non-blocking sweep over the embedded loop. This works 3297Make a single, non-blocking sweep over the embedded loop. This works
2483similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 3298similarly to C<ev_run (embedded_loop, EVRUN_NOWAIT)>, but in the most
2484appropriate way for embedded loops. 3299appropriate way for embedded loops.
2485 3300
2486=item struct ev_loop *other [read-only] 3301=item struct ev_loop *other [read-only]
2487 3302
2488The embedded event loop. 3303The embedded event loop.
2498used). 3313used).
2499 3314
2500 struct ev_loop *loop_hi = ev_default_init (0); 3315 struct ev_loop *loop_hi = ev_default_init (0);
2501 struct ev_loop *loop_lo = 0; 3316 struct ev_loop *loop_lo = 0;
2502 ev_embed embed; 3317 ev_embed embed;
2503 3318
2504 // see if there is a chance of getting one that works 3319 // see if there is a chance of getting one that works
2505 // (remember that a flags value of 0 means autodetection) 3320 // (remember that a flags value of 0 means autodetection)
2506 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3321 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2507 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3322 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2508 : 0; 3323 : 0;
2522C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 3337C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2523 3338
2524 struct ev_loop *loop = ev_default_init (0); 3339 struct ev_loop *loop = ev_default_init (0);
2525 struct ev_loop *loop_socket = 0; 3340 struct ev_loop *loop_socket = 0;
2526 ev_embed embed; 3341 ev_embed embed;
2527 3342
2528 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3343 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2529 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3344 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2530 { 3345 {
2531 ev_embed_init (&embed, 0, loop_socket); 3346 ev_embed_init (&embed, 0, loop_socket);
2532 ev_embed_start (loop, &embed); 3347 ev_embed_start (loop, &embed);
2540 3355
2541=head2 C<ev_fork> - the audacity to resume the event loop after a fork 3356=head2 C<ev_fork> - the audacity to resume the event loop after a fork
2542 3357
2543Fork watchers are called when a C<fork ()> was detected (usually because 3358Fork watchers are called when a C<fork ()> was detected (usually because
2544whoever is a good citizen cared to tell libev about it by calling 3359whoever is a good citizen cared to tell libev about it by calling
2545C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the 3360C<ev_loop_fork>). The invocation is done before the event loop blocks next
2546event loop blocks next and before C<ev_check> watchers are being called, 3361and before C<ev_check> watchers are being called, and only in the child
2547and only in the child after the fork. If whoever good citizen calling 3362after the fork. If whoever good citizen calling C<ev_default_fork> cheats
2548C<ev_default_fork> cheats and calls it in the wrong process, the fork 3363and calls it in the wrong process, the fork handlers will be invoked, too,
2549handlers will be invoked, too, of course. 3364of course.
3365
3366=head3 The special problem of life after fork - how is it possible?
3367
3368Most uses of C<fork ()> consist of forking, then some simple calls to set
3369up/change the process environment, followed by a call to C<exec()>. This
3370sequence should be handled by libev without any problems.
3371
3372This changes when the application actually wants to do event handling
3373in the child, or both parent in child, in effect "continuing" after the
3374fork.
3375
3376The default mode of operation (for libev, with application help to detect
3377forks) is to duplicate all the state in the child, as would be expected
3378when I<either> the parent I<or> the child process continues.
3379
3380When both processes want to continue using libev, then this is usually the
3381wrong result. In that case, usually one process (typically the parent) is
3382supposed to continue with all watchers in place as before, while the other
3383process typically wants to start fresh, i.e. without any active watchers.
3384
3385The cleanest and most efficient way to achieve that with libev is to
3386simply create a new event loop, which of course will be "empty", and
3387use that for new watchers. This has the advantage of not touching more
3388memory than necessary, and thus avoiding the copy-on-write, and the
3389disadvantage of having to use multiple event loops (which do not support
3390signal watchers).
3391
3392When this is not possible, or you want to use the default loop for
3393other reasons, then in the process that wants to start "fresh", call
3394C<ev_loop_destroy (EV_DEFAULT)> followed by C<ev_default_loop (...)>.
3395Destroying the default loop will "orphan" (not stop) all registered
3396watchers, so you have to be careful not to execute code that modifies
3397those watchers. Note also that in that case, you have to re-register any
3398signal watchers.
2550 3399
2551=head3 Watcher-Specific Functions and Data Members 3400=head3 Watcher-Specific Functions and Data Members
2552 3401
2553=over 4 3402=over 4
2554 3403
2555=item ev_fork_init (ev_signal *, callback) 3404=item ev_fork_init (ev_fork *, callback)
2556 3405
2557Initialises and configures the fork watcher - it has no parameters of any 3406Initialises and configures the fork watcher - it has no parameters of any
2558kind. There is a C<ev_fork_set> macro, but using it is utterly pointless, 3407kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
2559believe me. 3408really.
2560 3409
2561=back 3410=back
2562 3411
2563 3412
3413=head2 C<ev_cleanup> - even the best things end
3414
3415Cleanup watchers are called just before the event loop is being destroyed
3416by a call to C<ev_loop_destroy>.
3417
3418While there is no guarantee that the event loop gets destroyed, cleanup
3419watchers provide a convenient method to install cleanup hooks for your
3420program, worker threads and so on - you just to make sure to destroy the
3421loop when you want them to be invoked.
3422
3423Cleanup watchers are invoked in the same way as any other watcher. Unlike
3424all other watchers, they do not keep a reference to the event loop (which
3425makes a lot of sense if you think about it). Like all other watchers, you
3426can call libev functions in the callback, except C<ev_cleanup_start>.
3427
3428=head3 Watcher-Specific Functions and Data Members
3429
3430=over 4
3431
3432=item ev_cleanup_init (ev_cleanup *, callback)
3433
3434Initialises and configures the cleanup watcher - it has no parameters of
3435any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
3436pointless, I assure you.
3437
3438=back
3439
3440Example: Register an atexit handler to destroy the default loop, so any
3441cleanup functions are called.
3442
3443 static void
3444 program_exits (void)
3445 {
3446 ev_loop_destroy (EV_DEFAULT_UC);
3447 }
3448
3449 ...
3450 atexit (program_exits);
3451
3452
2564=head2 C<ev_async> - how to wake up another event loop 3453=head2 C<ev_async> - how to wake up an event loop
2565 3454
2566In general, you cannot use an C<ev_loop> from multiple threads or other 3455In general, you cannot use an C<ev_loop> from multiple threads or other
2567asynchronous sources such as signal handlers (as opposed to multiple event 3456asynchronous sources such as signal handlers (as opposed to multiple event
2568loops - those are of course safe to use in different threads). 3457loops - those are of course safe to use in different threads).
2569 3458
2570Sometimes, however, you need to wake up another event loop you do not 3459Sometimes, however, you need to wake up an event loop you do not control,
2571control, for example because it belongs to another thread. This is what 3460for example because it belongs to another thread. This is what C<ev_async>
2572C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you 3461watchers do: as long as the C<ev_async> watcher is active, you can signal
2573can signal it by calling C<ev_async_send>, which is thread- and signal 3462it by calling C<ev_async_send>, which is thread- and signal safe.
2574safe.
2575 3463
2576This functionality is very similar to C<ev_signal> watchers, as signals, 3464This functionality is very similar to C<ev_signal> watchers, as signals,
2577too, are asynchronous in nature, and signals, too, will be compressed 3465too, are asynchronous in nature, and signals, too, will be compressed
2578(i.e. the number of callback invocations may be less than the number of 3466(i.e. the number of callback invocations may be less than the number of
2579C<ev_async_sent> calls). 3467C<ev_async_send> calls). In fact, you could use signal watchers as a kind
2580 3468of "global async watchers" by using a watcher on an otherwise unused
2581Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not 3469signal, and C<ev_feed_signal> to signal this watcher from another thread,
2582just the default loop. 3470even without knowing which loop owns the signal.
2583 3471
2584=head3 Queueing 3472=head3 Queueing
2585 3473
2586C<ev_async> does not support queueing of data in any way. The reason 3474C<ev_async> does not support queueing of data in any way. The reason
2587is that the author does not know of a simple (or any) algorithm for a 3475is that the author does not know of a simple (or any) algorithm for a
2588multiple-writer-single-reader queue that works in all cases and doesn't 3476multiple-writer-single-reader queue that works in all cases and doesn't
2589need elaborate support such as pthreads. 3477need elaborate support such as pthreads or unportable memory access
3478semantics.
2590 3479
2591That means that if you want to queue data, you have to provide your own 3480That means that if you want to queue data, you have to provide your own
2592queue. But at least I can tell you how to implement locking around your 3481queue. But at least I can tell you how to implement locking around your
2593queue: 3482queue:
2594 3483
2678trust me. 3567trust me.
2679 3568
2680=item ev_async_send (loop, ev_async *) 3569=item ev_async_send (loop, ev_async *)
2681 3570
2682Sends/signals/activates the given C<ev_async> watcher, that is, feeds 3571Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2683an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3572an C<EV_ASYNC> event on the watcher into the event loop, and instantly
3573returns.
3574
2684C<ev_feed_event>, this call is safe to do from other threads, signal or 3575Unlike C<ev_feed_event>, this call is safe to do from other threads,
2685similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 3576signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
2686section below on what exactly this means). 3577embedding section below on what exactly this means).
2687 3578
2688This call incurs the overhead of a system call only once per loop iteration, 3579Note that, as with other watchers in libev, multiple events might get
2689so while the overhead might be noticeable, it doesn't apply to repeated 3580compressed into a single callback invocation (another way to look at
2690calls to C<ev_async_send>. 3581this is that C<ev_async> watchers are level-triggered: they are set on
3582C<ev_async_send>, reset when the event loop detects that).
3583
3584This call incurs the overhead of at most one extra system call per event
3585loop iteration, if the event loop is blocked, and no syscall at all if
3586the event loop (or your program) is processing events. That means that
3587repeated calls are basically free (there is no need to avoid calls for
3588performance reasons) and that the overhead becomes smaller (typically
3589zero) under load.
2691 3590
2692=item bool = ev_async_pending (ev_async *) 3591=item bool = ev_async_pending (ev_async *)
2693 3592
2694Returns a non-zero value when C<ev_async_send> has been called on the 3593Returns a non-zero value when C<ev_async_send> has been called on the
2695watcher but the event has not yet been processed (or even noted) by the 3594watcher but the event has not yet been processed (or even noted) by the
2698C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 3597C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2699the loop iterates next and checks for the watcher to have become active, 3598the loop iterates next and checks for the watcher to have become active,
2700it will reset the flag again. C<ev_async_pending> can be used to very 3599it will reset the flag again. C<ev_async_pending> can be used to very
2701quickly check whether invoking the loop might be a good idea. 3600quickly check whether invoking the loop might be a good idea.
2702 3601
2703Not that this does I<not> check whether the watcher itself is pending, only 3602Not that this does I<not> check whether the watcher itself is pending,
2704whether it has been requested to make this watcher pending. 3603only whether it has been requested to make this watcher pending: there
3604is a time window between the event loop checking and resetting the async
3605notification, and the callback being invoked.
2705 3606
2706=back 3607=back
2707 3608
2708 3609
2709=head1 OTHER FUNCTIONS 3610=head1 OTHER FUNCTIONS
2710 3611
2711There are some other functions of possible interest. Described. Here. Now. 3612There are some other functions of possible interest. Described. Here. Now.
2712 3613
2713=over 4 3614=over 4
2714 3615
2715=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 3616=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)
2716 3617
2717This function combines a simple timer and an I/O watcher, calls your 3618This function combines a simple timer and an I/O watcher, calls your
2718callback on whichever event happens first and automatically stops both 3619callback on whichever event happens first and automatically stops both
2719watchers. This is useful if you want to wait for a single event on an fd 3620watchers. This is useful if you want to wait for a single event on an fd
2720or timeout without having to allocate/configure/start/stop/free one or 3621or timeout without having to allocate/configure/start/stop/free one or
2726 3627
2727If C<timeout> is less than 0, then no timeout watcher will be 3628If C<timeout> is less than 0, then no timeout watcher will be
2728started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3629started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2729repeat = 0) will be started. C<0> is a valid timeout. 3630repeat = 0) will be started. C<0> is a valid timeout.
2730 3631
2731The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3632The callback has the type C<void (*cb)(int revents, void *arg)> and is
2732passed an C<revents> set like normal event callbacks (a combination of 3633passed an C<revents> set like normal event callbacks (a combination of
2733C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3634C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
2734value passed to C<ev_once>. Note that it is possible to receive I<both> 3635value passed to C<ev_once>. Note that it is possible to receive I<both>
2735a timeout and an io event at the same time - you probably should give io 3636a timeout and an io event at the same time - you probably should give io
2736events precedence. 3637events precedence.
2737 3638
2738Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3639Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2739 3640
2740 static void stdin_ready (int revents, void *arg) 3641 static void stdin_ready (int revents, void *arg)
2741 { 3642 {
2742 if (revents & EV_READ) 3643 if (revents & EV_READ)
2743 /* stdin might have data for us, joy! */; 3644 /* stdin might have data for us, joy! */;
2744 else if (revents & EV_TIMEOUT) 3645 else if (revents & EV_TIMER)
2745 /* doh, nothing entered */; 3646 /* doh, nothing entered */;
2746 } 3647 }
2747 3648
2748 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3649 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2749 3650
2750=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2751
2752Feeds the given event set into the event loop, as if the specified event
2753had happened for the specified watcher (which must be a pointer to an
2754initialised but not necessarily started event watcher).
2755
2756=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3651=item ev_feed_fd_event (loop, int fd, int revents)
2757 3652
2758Feed an event on the given fd, as if a file descriptor backend detected 3653Feed an event on the given fd, as if a file descriptor backend detected
2759the given events it. 3654the given events.
2760 3655
2761=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3656=item ev_feed_signal_event (loop, int signum)
2762 3657
2763Feed an event as if the given signal occurred (C<loop> must be the default 3658Feed an event as if the given signal occurred. See also C<ev_feed_signal>,
2764loop!). 3659which is async-safe.
2765 3660
2766=back 3661=back
3662
3663
3664=head1 COMMON OR USEFUL IDIOMS (OR BOTH)
3665
3666This section explains some common idioms that are not immediately
3667obvious. Note that examples are sprinkled over the whole manual, and this
3668section only contains stuff that wouldn't fit anywhere else.
3669
3670=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
3671
3672Each watcher has, by default, a C<void *data> member that you can read
3673or modify at any time: libev will completely ignore it. This can be used
3674to associate arbitrary data with your watcher. If you need more data and
3675don't want to allocate memory separately and store a pointer to it in that
3676data member, you can also "subclass" the watcher type and provide your own
3677data:
3678
3679 struct my_io
3680 {
3681 ev_io io;
3682 int otherfd;
3683 void *somedata;
3684 struct whatever *mostinteresting;
3685 };
3686
3687 ...
3688 struct my_io w;
3689 ev_io_init (&w.io, my_cb, fd, EV_READ);
3690
3691And since your callback will be called with a pointer to the watcher, you
3692can cast it back to your own type:
3693
3694 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
3695 {
3696 struct my_io *w = (struct my_io *)w_;
3697 ...
3698 }
3699
3700More interesting and less C-conformant ways of casting your callback
3701function type instead have been omitted.
3702
3703=head2 BUILDING YOUR OWN COMPOSITE WATCHERS
3704
3705Another common scenario is to use some data structure with multiple
3706embedded watchers, in effect creating your own watcher that combines
3707multiple libev event sources into one "super-watcher":
3708
3709 struct my_biggy
3710 {
3711 int some_data;
3712 ev_timer t1;
3713 ev_timer t2;
3714 }
3715
3716In this case getting the pointer to C<my_biggy> is a bit more
3717complicated: Either you store the address of your C<my_biggy> struct in
3718the C<data> member of the watcher (for woozies or C++ coders), or you need
3719to use some pointer arithmetic using C<offsetof> inside your watchers (for
3720real programmers):
3721
3722 #include <stddef.h>
3723
3724 static void
3725 t1_cb (EV_P_ ev_timer *w, int revents)
3726 {
3727 struct my_biggy big = (struct my_biggy *)
3728 (((char *)w) - offsetof (struct my_biggy, t1));
3729 }
3730
3731 static void
3732 t2_cb (EV_P_ ev_timer *w, int revents)
3733 {
3734 struct my_biggy big = (struct my_biggy *)
3735 (((char *)w) - offsetof (struct my_biggy, t2));
3736 }
3737
3738=head2 AVOIDING FINISHING BEFORE RETURNING
3739
3740Often you have structures like this in event-based programs:
3741
3742 callback ()
3743 {
3744 free (request);
3745 }
3746
3747 request = start_new_request (..., callback);
3748
3749The intent is to start some "lengthy" operation. The C<request> could be
3750used to cancel the operation, or do other things with it.
3751
3752It's not uncommon to have code paths in C<start_new_request> that
3753immediately invoke the callback, for example, to report errors. Or you add
3754some caching layer that finds that it can skip the lengthy aspects of the
3755operation and simply invoke the callback with the result.
3756
3757The problem here is that this will happen I<before> C<start_new_request>
3758has returned, so C<request> is not set.
3759
3760Even if you pass the request by some safer means to the callback, you
3761might want to do something to the request after starting it, such as
3762canceling it, which probably isn't working so well when the callback has
3763already been invoked.
3764
3765A common way around all these issues is to make sure that
3766C<start_new_request> I<always> returns before the callback is invoked. If
3767C<start_new_request> immediately knows the result, it can artificially
3768delay invoking the callback by using a C<prepare> or C<idle> watcher for
3769example, or more sneakily, by reusing an existing (stopped) watcher and
3770pushing it into the pending queue:
3771
3772 ev_set_cb (watcher, callback);
3773 ev_feed_event (EV_A_ watcher, 0);
3774
3775This way, C<start_new_request> can safely return before the callback is
3776invoked, while not delaying callback invocation too much.
3777
3778=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
3779
3780Often (especially in GUI toolkits) there are places where you have
3781I<modal> interaction, which is most easily implemented by recursively
3782invoking C<ev_run>.
3783
3784This brings the problem of exiting - a callback might want to finish the
3785main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
3786a modal "Are you sure?" dialog is still waiting), or just the nested one
3787and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
3788other combination: In these cases, a simple C<ev_break> will not work.
3789
3790The solution is to maintain "break this loop" variable for each C<ev_run>
3791invocation, and use a loop around C<ev_run> until the condition is
3792triggered, using C<EVRUN_ONCE>:
3793
3794 // main loop
3795 int exit_main_loop = 0;
3796
3797 while (!exit_main_loop)
3798 ev_run (EV_DEFAULT_ EVRUN_ONCE);
3799
3800 // in a modal watcher
3801 int exit_nested_loop = 0;
3802
3803 while (!exit_nested_loop)
3804 ev_run (EV_A_ EVRUN_ONCE);
3805
3806To exit from any of these loops, just set the corresponding exit variable:
3807
3808 // exit modal loop
3809 exit_nested_loop = 1;
3810
3811 // exit main program, after modal loop is finished
3812 exit_main_loop = 1;
3813
3814 // exit both
3815 exit_main_loop = exit_nested_loop = 1;
3816
3817=head2 THREAD LOCKING EXAMPLE
3818
3819Here is a fictitious example of how to run an event loop in a different
3820thread from where callbacks are being invoked and watchers are
3821created/added/removed.
3822
3823For a real-world example, see the C<EV::Loop::Async> perl module,
3824which uses exactly this technique (which is suited for many high-level
3825languages).
3826
3827The example uses a pthread mutex to protect the loop data, a condition
3828variable to wait for callback invocations, an async watcher to notify the
3829event loop thread and an unspecified mechanism to wake up the main thread.
3830
3831First, you need to associate some data with the event loop:
3832
3833 typedef struct {
3834 mutex_t lock; /* global loop lock */
3835 ev_async async_w;
3836 thread_t tid;
3837 cond_t invoke_cv;
3838 } userdata;
3839
3840 void prepare_loop (EV_P)
3841 {
3842 // for simplicity, we use a static userdata struct.
3843 static userdata u;
3844
3845 ev_async_init (&u->async_w, async_cb);
3846 ev_async_start (EV_A_ &u->async_w);
3847
3848 pthread_mutex_init (&u->lock, 0);
3849 pthread_cond_init (&u->invoke_cv, 0);
3850
3851 // now associate this with the loop
3852 ev_set_userdata (EV_A_ u);
3853 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3854 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3855
3856 // then create the thread running ev_run
3857 pthread_create (&u->tid, 0, l_run, EV_A);
3858 }
3859
3860The callback for the C<ev_async> watcher does nothing: the watcher is used
3861solely to wake up the event loop so it takes notice of any new watchers
3862that might have been added:
3863
3864 static void
3865 async_cb (EV_P_ ev_async *w, int revents)
3866 {
3867 // just used for the side effects
3868 }
3869
3870The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
3871protecting the loop data, respectively.
3872
3873 static void
3874 l_release (EV_P)
3875 {
3876 userdata *u = ev_userdata (EV_A);
3877 pthread_mutex_unlock (&u->lock);
3878 }
3879
3880 static void
3881 l_acquire (EV_P)
3882 {
3883 userdata *u = ev_userdata (EV_A);
3884 pthread_mutex_lock (&u->lock);
3885 }
3886
3887The event loop thread first acquires the mutex, and then jumps straight
3888into C<ev_run>:
3889
3890 void *
3891 l_run (void *thr_arg)
3892 {
3893 struct ev_loop *loop = (struct ev_loop *)thr_arg;
3894
3895 l_acquire (EV_A);
3896 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
3897 ev_run (EV_A_ 0);
3898 l_release (EV_A);
3899
3900 return 0;
3901 }
3902
3903Instead of invoking all pending watchers, the C<l_invoke> callback will
3904signal the main thread via some unspecified mechanism (signals? pipe
3905writes? C<Async::Interrupt>?) and then waits until all pending watchers
3906have been called (in a while loop because a) spurious wakeups are possible
3907and b) skipping inter-thread-communication when there are no pending
3908watchers is very beneficial):
3909
3910 static void
3911 l_invoke (EV_P)
3912 {
3913 userdata *u = ev_userdata (EV_A);
3914
3915 while (ev_pending_count (EV_A))
3916 {
3917 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
3918 pthread_cond_wait (&u->invoke_cv, &u->lock);
3919 }
3920 }
3921
3922Now, whenever the main thread gets told to invoke pending watchers, it
3923will grab the lock, call C<ev_invoke_pending> and then signal the loop
3924thread to continue:
3925
3926 static void
3927 real_invoke_pending (EV_P)
3928 {
3929 userdata *u = ev_userdata (EV_A);
3930
3931 pthread_mutex_lock (&u->lock);
3932 ev_invoke_pending (EV_A);
3933 pthread_cond_signal (&u->invoke_cv);
3934 pthread_mutex_unlock (&u->lock);
3935 }
3936
3937Whenever you want to start/stop a watcher or do other modifications to an
3938event loop, you will now have to lock:
3939
3940 ev_timer timeout_watcher;
3941 userdata *u = ev_userdata (EV_A);
3942
3943 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
3944
3945 pthread_mutex_lock (&u->lock);
3946 ev_timer_start (EV_A_ &timeout_watcher);
3947 ev_async_send (EV_A_ &u->async_w);
3948 pthread_mutex_unlock (&u->lock);
3949
3950Note that sending the C<ev_async> watcher is required because otherwise
3951an event loop currently blocking in the kernel will have no knowledge
3952about the newly added timer. By waking up the loop it will pick up any new
3953watchers in the next event loop iteration.
3954
3955=head2 THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS
3956
3957While the overhead of a callback that e.g. schedules a thread is small, it
3958is still an overhead. If you embed libev, and your main usage is with some
3959kind of threads or coroutines, you might want to customise libev so that
3960doesn't need callbacks anymore.
3961
3962Imagine you have coroutines that you can switch to using a function
3963C<switch_to (coro)>, that libev runs in a coroutine called C<libev_coro>
3964and that due to some magic, the currently active coroutine is stored in a
3965global called C<current_coro>. Then you can build your own "wait for libev
3966event" primitive by changing C<EV_CB_DECLARE> and C<EV_CB_INVOKE> (note
3967the differing C<;> conventions):
3968
3969 #define EV_CB_DECLARE(type) struct my_coro *cb;
3970 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
3971
3972That means instead of having a C callback function, you store the
3973coroutine to switch to in each watcher, and instead of having libev call
3974your callback, you instead have it switch to that coroutine.
3975
3976A coroutine might now wait for an event with a function called
3977C<wait_for_event>. (the watcher needs to be started, as always, but it doesn't
3978matter when, or whether the watcher is active or not when this function is
3979called):
3980
3981 void
3982 wait_for_event (ev_watcher *w)
3983 {
3984 ev_set_cb (w, current_coro);
3985 switch_to (libev_coro);
3986 }
3987
3988That basically suspends the coroutine inside C<wait_for_event> and
3989continues the libev coroutine, which, when appropriate, switches back to
3990this or any other coroutine.
3991
3992You can do similar tricks if you have, say, threads with an event queue -
3993instead of storing a coroutine, you store the queue object and instead of
3994switching to a coroutine, you push the watcher onto the queue and notify
3995any waiters.
3996
3997To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
3998files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
3999
4000 // my_ev.h
4001 #define EV_CB_DECLARE(type) struct my_coro *cb;
4002 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
4003 #include "../libev/ev.h"
4004
4005 // my_ev.c
4006 #define EV_H "my_ev.h"
4007 #include "../libev/ev.c"
4008
4009And then use F<my_ev.h> when you would normally use F<ev.h>, and compile
4010F<my_ev.c> into your project. When properly specifying include paths, you
4011can even use F<ev.h> as header file name directly.
2767 4012
2768 4013
2769=head1 LIBEVENT EMULATION 4014=head1 LIBEVENT EMULATION
2770 4015
2771Libev offers a compatibility emulation layer for libevent. It cannot 4016Libev offers a compatibility emulation layer for libevent. It cannot
2772emulate the internals of libevent, so here are some usage hints: 4017emulate the internals of libevent, so here are some usage hints:
2773 4018
2774=over 4 4019=over 4
4020
4021=item * Only the libevent-1.4.1-beta API is being emulated.
4022
4023This was the newest libevent version available when libev was implemented,
4024and is still mostly unchanged in 2010.
2775 4025
2776=item * Use it by including <event.h>, as usual. 4026=item * Use it by including <event.h>, as usual.
2777 4027
2778=item * The following members are fully supported: ev_base, ev_callback, 4028=item * The following members are fully supported: ev_base, ev_callback,
2779ev_arg, ev_fd, ev_res, ev_events. 4029ev_arg, ev_fd, ev_res, ev_events.
2785=item * Priorities are not currently supported. Initialising priorities 4035=item * Priorities are not currently supported. Initialising priorities
2786will fail and all watchers will have the same priority, even though there 4036will fail and all watchers will have the same priority, even though there
2787is an ev_pri field. 4037is an ev_pri field.
2788 4038
2789=item * In libevent, the last base created gets the signals, in libev, the 4039=item * In libevent, the last base created gets the signals, in libev, the
2790first base created (== the default loop) gets the signals. 4040base that registered the signal gets the signals.
2791 4041
2792=item * Other members are not supported. 4042=item * Other members are not supported.
2793 4043
2794=item * The libev emulation is I<not> ABI compatible to libevent, you need 4044=item * The libev emulation is I<not> ABI compatible to libevent, you need
2795to use the libev header file and library. 4045to use the libev header file and library.
2796 4046
2797=back 4047=back
2798 4048
2799=head1 C++ SUPPORT 4049=head1 C++ SUPPORT
4050
4051=head2 C API
4052
4053The normal C API should work fine when used from C++: both ev.h and the
4054libev sources can be compiled as C++. Therefore, code that uses the C API
4055will work fine.
4056
4057Proper exception specifications might have to be added to callbacks passed
4058to libev: exceptions may be thrown only from watcher callbacks, all other
4059callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4060callbacks) must not throw exceptions, and might need a C<noexcept>
4061specification. If you have code that needs to be compiled as both C and
4062C++ you can use the C<EV_NOEXCEPT> macro for this:
4063
4064 static void
4065 fatal_error (const char *msg) EV_NOEXCEPT
4066 {
4067 perror (msg);
4068 abort ();
4069 }
4070
4071 ...
4072 ev_set_syserr_cb (fatal_error);
4073
4074The only API functions that can currently throw exceptions are C<ev_run>,
4075C<ev_invoke>, C<ev_invoke_pending> and C<ev_loop_destroy> (the latter
4076because it runs cleanup watchers).
4077
4078Throwing exceptions in watcher callbacks is only supported if libev itself
4079is compiled with a C++ compiler or your C and C++ environments allow
4080throwing exceptions through C libraries (most do).
4081
4082=head2 C++ API
2800 4083
2801Libev comes with some simplistic wrapper classes for C++ that mainly allow 4084Libev comes with some simplistic wrapper classes for C++ that mainly allow
2802you to use some convenience methods to start/stop watchers and also change 4085you to use some convenience methods to start/stop watchers and also change
2803the callback model to a model using method callbacks on objects. 4086the callback model to a model using method callbacks on objects.
2804 4087
2805To use it, 4088To use it,
2806 4089
2807 #include <ev++.h> 4090 #include <ev++.h>
2808 4091
2809This automatically includes F<ev.h> and puts all of its definitions (many 4092This automatically includes F<ev.h> and puts all of its definitions (many
2810of them macros) into the global namespace. All C++ specific things are 4093of them macros) into the global namespace. All C++ specific things are
2811put into the C<ev> namespace. It should support all the same embedding 4094put into the C<ev> namespace. It should support all the same embedding
2814Care has been taken to keep the overhead low. The only data member the C++ 4097Care has been taken to keep the overhead low. The only data member the C++
2815classes add (compared to plain C-style watchers) is the event loop pointer 4098classes add (compared to plain C-style watchers) is the event loop pointer
2816that the watcher is associated with (or no additional members at all if 4099that the watcher is associated with (or no additional members at all if
2817you disable C<EV_MULTIPLICITY> when embedding libev). 4100you disable C<EV_MULTIPLICITY> when embedding libev).
2818 4101
2819Currently, functions, and static and non-static member functions can be 4102Currently, functions, static and non-static member functions and classes
2820used as callbacks. Other types should be easy to add as long as they only 4103with C<operator ()> can be used as callbacks. Other types should be easy
2821need one additional pointer for context. If you need support for other 4104to add as long as they only need one additional pointer for context. If
2822types of functors please contact the author (preferably after implementing 4105you need support for other types of functors please contact the author
2823it). 4106(preferably after implementing it).
4107
4108For all this to work, your C++ compiler either has to use the same calling
4109conventions as your C compiler (for static member functions), or you have
4110to embed libev and compile libev itself as C++.
2824 4111
2825Here is a list of things available in the C<ev> namespace: 4112Here is a list of things available in the C<ev> namespace:
2826 4113
2827=over 4 4114=over 4
2828 4115
2838=item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc. 4125=item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
2839 4126
2840For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of 4127For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
2841the same name in the C<ev> namespace, with the exception of C<ev_signal> 4128the same name in the C<ev> namespace, with the exception of C<ev_signal>
2842which is called C<ev::sig> to avoid clashes with the C<signal> macro 4129which is called C<ev::sig> to avoid clashes with the C<signal> macro
2843defines by many implementations. 4130defined by many implementations.
2844 4131
2845All of those classes have these methods: 4132All of those classes have these methods:
2846 4133
2847=over 4 4134=over 4
2848 4135
2849=item ev::TYPE::TYPE () 4136=item ev::TYPE::TYPE ()
2850 4137
2851=item ev::TYPE::TYPE (struct ev_loop *) 4138=item ev::TYPE::TYPE (loop)
2852 4139
2853=item ev::TYPE::~TYPE 4140=item ev::TYPE::~TYPE
2854 4141
2855The constructor (optionally) takes an event loop to associate the watcher 4142The constructor (optionally) takes an event loop to associate the watcher
2856with. If it is omitted, it will use C<EV_DEFAULT>. 4143with. If it is omitted, it will use C<EV_DEFAULT>.
2888 4175
2889 myclass obj; 4176 myclass obj;
2890 ev::io iow; 4177 ev::io iow;
2891 iow.set <myclass, &myclass::io_cb> (&obj); 4178 iow.set <myclass, &myclass::io_cb> (&obj);
2892 4179
4180=item w->set (object *)
4181
4182This is a variation of a method callback - leaving out the method to call
4183will default the method to C<operator ()>, which makes it possible to use
4184functor objects without having to manually specify the C<operator ()> all
4185the time. Incidentally, you can then also leave out the template argument
4186list.
4187
4188The C<operator ()> method prototype must be C<void operator ()(watcher &w,
4189int revents)>.
4190
4191See the method-C<set> above for more details.
4192
4193Example: use a functor object as callback.
4194
4195 struct myfunctor
4196 {
4197 void operator() (ev::io &w, int revents)
4198 {
4199 ...
4200 }
4201 }
4202
4203 myfunctor f;
4204
4205 ev::io w;
4206 w.set (&f);
4207
2893=item w->set<function> (void *data = 0) 4208=item w->set<function> (void *data = 0)
2894 4209
2895Also sets a callback, but uses a static method or plain function as 4210Also sets a callback, but uses a static method or plain function as
2896callback. The optional C<data> argument will be stored in the watcher's 4211callback. The optional C<data> argument will be stored in the watcher's
2897C<data> member and is free for you to use. 4212C<data> member and is free for you to use.
2903Example: Use a plain function as callback. 4218Example: Use a plain function as callback.
2904 4219
2905 static void io_cb (ev::io &w, int revents) { } 4220 static void io_cb (ev::io &w, int revents) { }
2906 iow.set <io_cb> (); 4221 iow.set <io_cb> ();
2907 4222
2908=item w->set (struct ev_loop *) 4223=item w->set (loop)
2909 4224
2910Associates a different C<struct ev_loop> with this watcher. You can only 4225Associates a different C<struct ev_loop> with this watcher. You can only
2911do this when the watcher is inactive (and not pending either). 4226do this when the watcher is inactive (and not pending either).
2912 4227
2913=item w->set ([arguments]) 4228=item w->set ([arguments])
2914 4229
2915Basically the same as C<ev_TYPE_set>, with the same arguments. Must be 4230Basically the same as C<ev_TYPE_set> (except for C<ev::embed> watchers>),
4231with the same arguments. Either this method or a suitable start method
2916called at least once. Unlike the C counterpart, an active watcher gets 4232must be called at least once. Unlike the C counterpart, an active watcher
2917automatically stopped and restarted when reconfiguring it with this 4233gets automatically stopped and restarted when reconfiguring it with this
2918method. 4234method.
4235
4236For C<ev::embed> watchers this method is called C<set_embed>, to avoid
4237clashing with the C<set (loop)> method.
2919 4238
2920=item w->start () 4239=item w->start ()
2921 4240
2922Starts the watcher. Note that there is no C<loop> argument, as the 4241Starts the watcher. Note that there is no C<loop> argument, as the
2923constructor already stores the event loop. 4242constructor already stores the event loop.
2924 4243
4244=item w->start ([arguments])
4245
4246Instead of calling C<set> and C<start> methods separately, it is often
4247convenient to wrap them in one call. Uses the same type of arguments as
4248the configure C<set> method of the watcher.
4249
2925=item w->stop () 4250=item w->stop ()
2926 4251
2927Stops the watcher if it is active. Again, no C<loop> argument. 4252Stops the watcher if it is active. Again, no C<loop> argument.
2928 4253
2929=item w->again () (C<ev::timer>, C<ev::periodic> only) 4254=item w->again () (C<ev::timer>, C<ev::periodic> only)
2941 4266
2942=back 4267=back
2943 4268
2944=back 4269=back
2945 4270
2946Example: Define a class with an IO and idle watcher, start one of them in 4271Example: Define a class with two I/O and idle watchers, start the I/O
2947the constructor. 4272watchers in the constructor.
2948 4273
2949 class myclass 4274 class myclass
2950 { 4275 {
2951 ev::io io ; void io_cb (ev::io &w, int revents); 4276 ev::io io ; void io_cb (ev::io &w, int revents);
4277 ev::io io2 ; void io2_cb (ev::io &w, int revents);
2952 ev::idle idle; void idle_cb (ev::idle &w, int revents); 4278 ev::idle idle; void idle_cb (ev::idle &w, int revents);
2953 4279
2954 myclass (int fd) 4280 myclass (int fd)
2955 { 4281 {
2956 io .set <myclass, &myclass::io_cb > (this); 4282 io .set <myclass, &myclass::io_cb > (this);
4283 io2 .set <myclass, &myclass::io2_cb > (this);
2957 idle.set <myclass, &myclass::idle_cb> (this); 4284 idle.set <myclass, &myclass::idle_cb> (this);
2958 4285
2959 io.start (fd, ev::READ); 4286 io.set (fd, ev::WRITE); // configure the watcher
4287 io.start (); // start it whenever convenient
4288
4289 io2.start (fd, ev::READ); // set + start in one call
2960 } 4290 }
2961 }; 4291 };
2962 4292
2963 4293
2964=head1 OTHER LANGUAGE BINDINGS 4294=head1 OTHER LANGUAGE BINDINGS
2983L<http://software.schmorp.de/pkg/EV>. 4313L<http://software.schmorp.de/pkg/EV>.
2984 4314
2985=item Python 4315=item Python
2986 4316
2987Python bindings can be found at L<http://code.google.com/p/pyev/>. It 4317Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2988seems to be quite complete and well-documented. Note, however, that the 4318seems to be quite complete and well-documented.
2989patch they require for libev is outright dangerous as it breaks the ABI
2990for everybody else, and therefore, should never be applied in an installed
2991libev (if python requires an incompatible ABI then it needs to embed
2992libev).
2993 4319
2994=item Ruby 4320=item Ruby
2995 4321
2996Tony Arcieri has written a ruby extension that offers access to a subset 4322Tony Arcieri has written a ruby extension that offers access to a subset
2997of the libev API and adds file handle abstractions, asynchronous DNS and 4323of the libev API and adds file handle abstractions, asynchronous DNS and
2998more on top of it. It can be found via gem servers. Its homepage is at 4324more on top of it. It can be found via gem servers. Its homepage is at
2999L<http://rev.rubyforge.org/>. 4325L<http://rev.rubyforge.org/>.
3000 4326
4327Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
4328makes rev work even on mingw.
4329
4330=item Haskell
4331
4332A haskell binding to libev is available at
4333L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
4334
3001=item D 4335=item D
3002 4336
3003Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 4337Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3004be found at L<http://proj.llucax.com.ar/wiki/evd>. 4338be found at L<http://www.llucax.com.ar/proj/ev.d/index.html>.
3005 4339
3006=item Ocaml 4340=item Ocaml
3007 4341
3008Erkki Seppala has written Ocaml bindings for libev, to be found at 4342Erkki Seppala has written Ocaml bindings for libev, to be found at
3009L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 4343L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
4344
4345=item Lua
4346
4347Brian Maher has written a partial interface to libev for lua (at the
4348time of this writing, only C<ev_io> and C<ev_timer>), to be found at
4349L<http://github.com/brimworks/lua-ev>.
4350
4351=item Javascript
4352
4353Node.js (L<http://nodejs.org>) uses libev as the underlying event library.
4354
4355=item Others
4356
4357There are others, and I stopped counting.
3010 4358
3011=back 4359=back
3012 4360
3013 4361
3014=head1 MACRO MAGIC 4362=head1 MACRO MAGIC
3028loop argument"). The C<EV_A> form is used when this is the sole argument, 4376loop argument"). The C<EV_A> form is used when this is the sole argument,
3029C<EV_A_> is used when other arguments are following. Example: 4377C<EV_A_> is used when other arguments are following. Example:
3030 4378
3031 ev_unref (EV_A); 4379 ev_unref (EV_A);
3032 ev_timer_add (EV_A_ watcher); 4380 ev_timer_add (EV_A_ watcher);
3033 ev_loop (EV_A_ 0); 4381 ev_run (EV_A_ 0);
3034 4382
3035It assumes the variable C<loop> of type C<struct ev_loop *> is in scope, 4383It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
3036which is often provided by the following macro. 4384which is often provided by the following macro.
3037 4385
3038=item C<EV_P>, C<EV_P_> 4386=item C<EV_P>, C<EV_P_>
3051suitable for use with C<EV_A>. 4399suitable for use with C<EV_A>.
3052 4400
3053=item C<EV_DEFAULT>, C<EV_DEFAULT_> 4401=item C<EV_DEFAULT>, C<EV_DEFAULT_>
3054 4402
3055Similar to the other two macros, this gives you the value of the default 4403Similar to the other two macros, this gives you the value of the default
3056loop, if multiple loops are supported ("ev loop default"). 4404loop, if multiple loops are supported ("ev loop default"). The default loop
4405will be initialised if it isn't already initialised.
4406
4407For non-multiplicity builds, these macros do nothing, so you always have
4408to initialise the loop somewhere.
3057 4409
3058=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_> 4410=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
3059 4411
3060Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the 4412Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
3061default loop has been initialised (C<UC> == unchecked). Their behaviour 4413default loop has been initialised (C<UC> == unchecked). Their behaviour
3078 } 4430 }
3079 4431
3080 ev_check check; 4432 ev_check check;
3081 ev_check_init (&check, check_cb); 4433 ev_check_init (&check, check_cb);
3082 ev_check_start (EV_DEFAULT_ &check); 4434 ev_check_start (EV_DEFAULT_ &check);
3083 ev_loop (EV_DEFAULT_ 0); 4435 ev_run (EV_DEFAULT_ 0);
3084 4436
3085=head1 EMBEDDING 4437=head1 EMBEDDING
3086 4438
3087Libev can (and often is) directly embedded into host 4439Libev can (and often is) directly embedded into host
3088applications. Examples of applications that embed it include the Deliantra 4440applications. Examples of applications that embed it include the Deliantra
3128 ev_vars.h 4480 ev_vars.h
3129 ev_wrap.h 4481 ev_wrap.h
3130 4482
3131 ev_win32.c required on win32 platforms only 4483 ev_win32.c required on win32 platforms only
3132 4484
3133 ev_select.c only when select backend is enabled (which is enabled by default) 4485 ev_select.c only when select backend is enabled
3134 ev_poll.c only when poll backend is enabled (disabled by default) 4486 ev_poll.c only when poll backend is enabled
3135 ev_epoll.c only when the epoll backend is enabled (disabled by default) 4487 ev_epoll.c only when the epoll backend is enabled
4488 ev_linuxaio.c only when the linux aio backend is enabled
3136 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4489 ev_kqueue.c only when the kqueue backend is enabled
3137 ev_port.c only when the solaris port backend is enabled (disabled by default) 4490 ev_port.c only when the solaris port backend is enabled
3138 4491
3139F<ev.c> includes the backend files directly when enabled, so you only need 4492F<ev.c> includes the backend files directly when enabled, so you only need
3140to compile this single file. 4493to compile this single file.
3141 4494
3142=head3 LIBEVENT COMPATIBILITY API 4495=head3 LIBEVENT COMPATIBILITY API
3168 libev.m4 4521 libev.m4
3169 4522
3170=head2 PREPROCESSOR SYMBOLS/MACROS 4523=head2 PREPROCESSOR SYMBOLS/MACROS
3171 4524
3172Libev can be configured via a variety of preprocessor symbols you have to 4525Libev can be configured via a variety of preprocessor symbols you have to
3173define before including any of its files. The default in the absence of 4526define before including (or compiling) any of its files. The default in
3174autoconf is documented for every option. 4527the absence of autoconf is documented for every option.
4528
4529Symbols marked with "(h)" do not change the ABI, and can have different
4530values when compiling libev vs. including F<ev.h>, so it is permissible
4531to redefine them before including F<ev.h> without breaking compatibility
4532to a compiled library. All other symbols change the ABI, which means all
4533users of libev and the libev code itself must be compiled with compatible
4534settings.
3175 4535
3176=over 4 4536=over 4
3177 4537
4538=item EV_COMPAT3 (h)
4539
4540Backwards compatibility is a major concern for libev. This is why this
4541release of libev comes with wrappers for the functions and symbols that
4542have been renamed between libev version 3 and 4.
4543
4544You can disable these wrappers (to test compatibility with future
4545versions) by defining C<EV_COMPAT3> to C<0> when compiling your
4546sources. This has the additional advantage that you can drop the C<struct>
4547from C<struct ev_loop> declarations, as libev will provide an C<ev_loop>
4548typedef in that case.
4549
4550In some future version, the default for C<EV_COMPAT3> will become C<0>,
4551and in some even more future version the compatibility code will be
4552removed completely.
4553
3178=item EV_STANDALONE 4554=item EV_STANDALONE (h)
3179 4555
3180Must always be C<1> if you do not use autoconf configuration, which 4556Must always be C<1> if you do not use autoconf configuration, which
3181keeps libev from including F<config.h>, and it also defines dummy 4557keeps libev from including F<config.h>, and it also defines dummy
3182implementations for some libevent functions (such as logging, which is not 4558implementations for some libevent functions (such as logging, which is not
3183supported). It will also not define any of the structs usually found in 4559supported). It will also not define any of the structs usually found in
3184F<event.h> that are not directly supported by the libev core alone. 4560F<event.h> that are not directly supported by the libev core alone.
3185 4561
4562In standalone mode, libev will still try to automatically deduce the
4563configuration, but has to be more conservative.
4564
4565=item EV_USE_FLOOR
4566
4567If defined to be C<1>, libev will use the C<floor ()> function for its
4568periodic reschedule calculations, otherwise libev will fall back on a
4569portable (slower) implementation. If you enable this, you usually have to
4570link against libm or something equivalent. Enabling this when the C<floor>
4571function is not available will fail, so the safe default is to not enable
4572this.
4573
3186=item EV_USE_MONOTONIC 4574=item EV_USE_MONOTONIC
3187 4575
3188If defined to be C<1>, libev will try to detect the availability of the 4576If defined to be C<1>, libev will try to detect the availability of the
3189monotonic clock option at both compile time and runtime. Otherwise no use 4577monotonic clock option at both compile time and runtime. Otherwise no
3190of the monotonic clock option will be attempted. If you enable this, you 4578use of the monotonic clock option will be attempted. If you enable this,
3191usually have to link against librt or something similar. Enabling it when 4579you usually have to link against librt or something similar. Enabling it
3192the functionality isn't available is safe, though, although you have 4580when the functionality isn't available is safe, though, although you have
3193to make sure you link against any libraries where the C<clock_gettime> 4581to make sure you link against any libraries where the C<clock_gettime>
3194function is hiding in (often F<-lrt>). 4582function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3195 4583
3196=item EV_USE_REALTIME 4584=item EV_USE_REALTIME
3197 4585
3198If defined to be C<1>, libev will try to detect the availability of the 4586If defined to be C<1>, libev will try to detect the availability of the
3199real-time clock option at compile time (and assume its availability at 4587real-time clock option at compile time (and assume its availability
3200runtime if successful). Otherwise no use of the real-time clock option will 4588at runtime if successful). Otherwise no use of the real-time clock
3201be attempted. This effectively replaces C<gettimeofday> by C<clock_get 4589option will be attempted. This effectively replaces C<gettimeofday>
3202(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 4590by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3203note about libraries in the description of C<EV_USE_MONOTONIC>, though. 4591correctness. See the note about libraries in the description of
4592C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
4593C<EV_USE_CLOCK_SYSCALL>.
4594
4595=item EV_USE_CLOCK_SYSCALL
4596
4597If defined to be C<1>, libev will try to use a direct syscall instead
4598of calling the system-provided C<clock_gettime> function. This option
4599exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
4600unconditionally pulls in C<libpthread>, slowing down single-threaded
4601programs needlessly. Using a direct syscall is slightly slower (in
4602theory), because no optimised vdso implementation can be used, but avoids
4603the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
4604higher, as it simplifies linking (no need for C<-lrt>).
3204 4605
3205=item EV_USE_NANOSLEEP 4606=item EV_USE_NANOSLEEP
3206 4607
3207If defined to be C<1>, libev will assume that C<nanosleep ()> is available 4608If defined to be C<1>, libev will assume that C<nanosleep ()> is available
3208and will use it for delays. Otherwise it will use C<select ()>. 4609and will use it for delays. Otherwise it will use C<select ()>.
3224 4625
3225=item EV_SELECT_USE_FD_SET 4626=item EV_SELECT_USE_FD_SET
3226 4627
3227If defined to C<1>, then the select backend will use the system C<fd_set> 4628If defined to C<1>, then the select backend will use the system C<fd_set>
3228structure. This is useful if libev doesn't compile due to a missing 4629structure. This is useful if libev doesn't compile due to a missing
3229C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on 4630C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
3230exotic systems. This usually limits the range of file descriptors to some 4631on exotic systems. This usually limits the range of file descriptors to
3231low limit such as 1024 or might have other limitations (winsocket only 4632some low limit such as 1024 or might have other limitations (winsocket
3232allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 4633only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
3233influence the size of the C<fd_set> used. 4634configures the maximum size of the C<fd_set>.
3234 4635
3235=item EV_SELECT_IS_WINSOCKET 4636=item EV_SELECT_IS_WINSOCKET
3236 4637
3237When defined to C<1>, the select backend will assume that 4638When defined to C<1>, the select backend will assume that
3238select/socket/connect etc. don't understand file descriptors but 4639select/socket/connect etc. don't understand file descriptors but
3240be used is the winsock select). This means that it will call 4641be used is the winsock select). This means that it will call
3241C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 4642C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3242it is assumed that all these functions actually work on fds, even 4643it is assumed that all these functions actually work on fds, even
3243on win32. Should not be defined on non-win32 platforms. 4644on win32. Should not be defined on non-win32 platforms.
3244 4645
3245=item EV_FD_TO_WIN32_HANDLE 4646=item EV_FD_TO_WIN32_HANDLE(fd)
3246 4647
3247If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 4648If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3248file descriptors to socket handles. When not defining this symbol (the 4649file descriptors to socket handles. When not defining this symbol (the
3249default), then libev will call C<_get_osfhandle>, which is usually 4650default), then libev will call C<_get_osfhandle>, which is usually
3250correct. In some cases, programs use their own file descriptor management, 4651correct. In some cases, programs use their own file descriptor management,
3251in which case they can provide this function to map fds to socket handles. 4652in which case they can provide this function to map fds to socket handles.
3252 4653
4654=item EV_WIN32_HANDLE_TO_FD(handle)
4655
4656If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
4657using the standard C<_open_osfhandle> function. For programs implementing
4658their own fd to handle mapping, overwriting this function makes it easier
4659to do so. This can be done by defining this macro to an appropriate value.
4660
4661=item EV_WIN32_CLOSE_FD(fd)
4662
4663If programs implement their own fd to handle mapping on win32, then this
4664macro can be used to override the C<close> function, useful to unregister
4665file descriptors again. Note that the replacement function has to close
4666the underlying OS handle.
4667
4668=item EV_USE_WSASOCKET
4669
4670If defined to be C<1>, libev will use C<WSASocket> to create its internal
4671communication socket, which works better in some environments. Otherwise,
4672the normal C<socket> function will be used, which works better in other
4673environments.
4674
3253=item EV_USE_POLL 4675=item EV_USE_POLL
3254 4676
3255If defined to be C<1>, libev will compile in support for the C<poll>(2) 4677If defined to be C<1>, libev will compile in support for the C<poll>(2)
3256backend. Otherwise it will be enabled on non-win32 platforms. It 4678backend. Otherwise it will be enabled on non-win32 platforms. It
3257takes precedence over select. 4679takes precedence over select.
3261If defined to be C<1>, libev will compile in support for the Linux 4683If defined to be C<1>, libev will compile in support for the Linux
3262C<epoll>(7) backend. Its availability will be detected at runtime, 4684C<epoll>(7) backend. Its availability will be detected at runtime,
3263otherwise another method will be used as fallback. This is the preferred 4685otherwise another method will be used as fallback. This is the preferred
3264backend for GNU/Linux systems. If undefined, it will be enabled if the 4686backend for GNU/Linux systems. If undefined, it will be enabled if the
3265headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4687headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4688
4689=item EV_USE_LINUXAIO
4690
4691If defined to be C<1>, libev will compile in support for the Linux
4692aio backend. Due to it's currenbt limitations it has to be requested
4693explicitly. If undefined, it will be enabled on linux, otherwise
4694disabled.
3266 4695
3267=item EV_USE_KQUEUE 4696=item EV_USE_KQUEUE
3268 4697
3269If defined to be C<1>, libev will compile in support for the BSD style 4698If defined to be C<1>, libev will compile in support for the BSD style
3270C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4699C<kqueue>(2) backend. Its actual availability will be detected at runtime,
3292If defined to be C<1>, libev will compile in support for the Linux inotify 4721If defined to be C<1>, libev will compile in support for the Linux inotify
3293interface to speed up C<ev_stat> watchers. Its actual availability will 4722interface to speed up C<ev_stat> watchers. Its actual availability will
3294be detected at runtime. If undefined, it will be enabled if the headers 4723be detected at runtime. If undefined, it will be enabled if the headers
3295indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4724indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
3296 4725
4726=item EV_NO_SMP
4727
4728If defined to be C<1>, libev will assume that memory is always coherent
4729between threads, that is, threads can be used, but threads never run on
4730different cpus (or different cpu cores). This reduces dependencies
4731and makes libev faster.
4732
4733=item EV_NO_THREADS
4734
4735If defined to be C<1>, libev will assume that it will never be called from
4736different threads (that includes signal handlers), which is a stronger
4737assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
4738libev faster.
4739
3297=item EV_ATOMIC_T 4740=item EV_ATOMIC_T
3298 4741
3299Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4742Libev requires an integer type (suitable for storing C<0> or C<1>) whose
3300access is atomic with respect to other threads or signal contexts. No such 4743access is atomic with respect to other threads or signal contexts. No
3301type is easily found in the C language, so you can provide your own type 4744such type is easily found in the C language, so you can provide your own
3302that you know is safe for your purposes. It is used both for signal handler "locking" 4745type that you know is safe for your purposes. It is used both for signal
3303as well as for signal and thread safety in C<ev_async> watchers. 4746handler "locking" as well as for signal and thread safety in C<ev_async>
4747watchers.
3304 4748
3305In the absence of this define, libev will use C<sig_atomic_t volatile> 4749In the absence of this define, libev will use C<sig_atomic_t volatile>
3306(from F<signal.h>), which is usually good enough on most platforms. 4750(from F<signal.h>), which is usually good enough on most platforms.
3307 4751
3308=item EV_H 4752=item EV_H (h)
3309 4753
3310The name of the F<ev.h> header file used to include it. The default if 4754The name of the F<ev.h> header file used to include it. The default if
3311undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 4755undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3312used to virtually rename the F<ev.h> header file in case of conflicts. 4756used to virtually rename the F<ev.h> header file in case of conflicts.
3313 4757
3314=item EV_CONFIG_H 4758=item EV_CONFIG_H (h)
3315 4759
3316If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 4760If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3317F<ev.c>'s idea of where to find the F<config.h> file, similarly to 4761F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3318C<EV_H>, above. 4762C<EV_H>, above.
3319 4763
3320=item EV_EVENT_H 4764=item EV_EVENT_H (h)
3321 4765
3322Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 4766Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3323of how the F<event.h> header can be found, the default is C<"event.h">. 4767of how the F<event.h> header can be found, the default is C<"event.h">.
3324 4768
3325=item EV_PROTOTYPES 4769=item EV_PROTOTYPES (h)
3326 4770
3327If defined to be C<0>, then F<ev.h> will not define any function 4771If defined to be C<0>, then F<ev.h> will not define any function
3328prototypes, but still define all the structs and other symbols. This is 4772prototypes, but still define all the structs and other symbols. This is
3329occasionally useful if you want to provide your own wrapper functions 4773occasionally useful if you want to provide your own wrapper functions
3330around libev functions. 4774around libev functions.
3335will have the C<struct ev_loop *> as first argument, and you can create 4779will have the C<struct ev_loop *> as first argument, and you can create
3336additional independent event loops. Otherwise there will be no support 4780additional independent event loops. Otherwise there will be no support
3337for multiple event loops and there is no first event loop pointer 4781for multiple event loops and there is no first event loop pointer
3338argument. Instead, all functions act on the single default loop. 4782argument. Instead, all functions act on the single default loop.
3339 4783
4784Note that C<EV_DEFAULT> and C<EV_DEFAULT_> will no longer provide a
4785default loop when multiplicity is switched off - you always have to
4786initialise the loop manually in this case.
4787
3340=item EV_MINPRI 4788=item EV_MINPRI
3341 4789
3342=item EV_MAXPRI 4790=item EV_MAXPRI
3343 4791
3344The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to 4792The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
3352fine. 4800fine.
3353 4801
3354If your embedding application does not need any priorities, defining these 4802If your embedding application does not need any priorities, defining these
3355both to C<0> will save some memory and CPU. 4803both to C<0> will save some memory and CPU.
3356 4804
3357=item EV_PERIODIC_ENABLE 4805=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
4806EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
4807EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3358 4808
3359If undefined or defined to be C<1>, then periodic timers are supported. If 4809If undefined or defined to be C<1> (and the platform supports it), then
3360defined to be C<0>, then they are not. Disabling them saves a few kB of 4810the respective watcher type is supported. If defined to be C<0>, then it
3361code. 4811is not. Disabling watcher types mainly saves code size.
3362 4812
3363=item EV_IDLE_ENABLE 4813=item EV_FEATURES
3364
3365If undefined or defined to be C<1>, then idle watchers are supported. If
3366defined to be C<0>, then they are not. Disabling them saves a few kB of
3367code.
3368
3369=item EV_EMBED_ENABLE
3370
3371If undefined or defined to be C<1>, then embed watchers are supported. If
3372defined to be C<0>, then they are not. Embed watchers rely on most other
3373watcher types, which therefore must not be disabled.
3374
3375=item EV_STAT_ENABLE
3376
3377If undefined or defined to be C<1>, then stat watchers are supported. If
3378defined to be C<0>, then they are not.
3379
3380=item EV_FORK_ENABLE
3381
3382If undefined or defined to be C<1>, then fork watchers are supported. If
3383defined to be C<0>, then they are not.
3384
3385=item EV_ASYNC_ENABLE
3386
3387If undefined or defined to be C<1>, then async watchers are supported. If
3388defined to be C<0>, then they are not.
3389
3390=item EV_MINIMAL
3391 4814
3392If you need to shave off some kilobytes of code at the expense of some 4815If you need to shave off some kilobytes of code at the expense of some
3393speed, define this symbol to C<1>. Currently this is used to override some 4816speed (but with the full API), you can define this symbol to request
3394inlining decisions, saves roughly 30% code size on amd64. It also selects a 4817certain subsets of functionality. The default is to enable all features
3395much smaller 2-heap for timer management over the default 4-heap. 4818that can be enabled on the platform.
4819
4820A typical way to use this symbol is to define it to C<0> (or to a bitset
4821with some broad features you want) and then selectively re-enable
4822additional parts you want, for example if you want everything minimal,
4823but multiple event loop support, async and child watchers and the poll
4824backend, use this:
4825
4826 #define EV_FEATURES 0
4827 #define EV_MULTIPLICITY 1
4828 #define EV_USE_POLL 1
4829 #define EV_CHILD_ENABLE 1
4830 #define EV_ASYNC_ENABLE 1
4831
4832The actual value is a bitset, it can be a combination of the following
4833values (by default, all of these are enabled):
4834
4835=over 4
4836
4837=item C<1> - faster/larger code
4838
4839Use larger code to speed up some operations.
4840
4841Currently this is used to override some inlining decisions (enlarging the
4842code size by roughly 30% on amd64).
4843
4844When optimising for size, use of compiler flags such as C<-Os> with
4845gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
4846assertions.
4847
4848The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
4849(e.g. gcc with C<-Os>).
4850
4851=item C<2> - faster/larger data structures
4852
4853Replaces the small 2-heap for timer management by a faster 4-heap, larger
4854hash table sizes and so on. This will usually further increase code size
4855and can additionally have an effect on the size of data structures at
4856runtime.
4857
4858The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
4859(e.g. gcc with C<-Os>).
4860
4861=item C<4> - full API configuration
4862
4863This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
4864enables multiplicity (C<EV_MULTIPLICITY>=1).
4865
4866=item C<8> - full API
4867
4868This enables a lot of the "lesser used" API functions. See C<ev.h> for
4869details on which parts of the API are still available without this
4870feature, and do not complain if this subset changes over time.
4871
4872=item C<16> - enable all optional watcher types
4873
4874Enables all optional watcher types. If you want to selectively enable
4875only some watcher types other than I/O and timers (e.g. prepare,
4876embed, async, child...) you can enable them manually by defining
4877C<EV_watchertype_ENABLE> to C<1> instead.
4878
4879=item C<32> - enable all backends
4880
4881This enables all backends - without this feature, you need to enable at
4882least one backend manually (C<EV_USE_SELECT> is a good choice).
4883
4884=item C<64> - enable OS-specific "helper" APIs
4885
4886Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
4887default.
4888
4889=back
4890
4891Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
4892reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
4893code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
4894watchers, timers and monotonic clock support.
4895
4896With an intelligent-enough linker (gcc+binutils are intelligent enough
4897when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
4898your program might be left out as well - a binary starting a timer and an
4899I/O watcher then might come out at only 5Kb.
4900
4901=item EV_API_STATIC
4902
4903If this symbol is defined (by default it is not), then all identifiers
4904will have static linkage. This means that libev will not export any
4905identifiers, and you cannot link against libev anymore. This can be useful
4906when you embed libev, only want to use libev functions in a single file,
4907and do not want its identifiers to be visible.
4908
4909To use this, define C<EV_API_STATIC> and include F<ev.c> in the file that
4910wants to use libev.
4911
4912This option only works when libev is compiled with a C compiler, as C++
4913doesn't support the required declaration syntax.
4914
4915=item EV_AVOID_STDIO
4916
4917If this is set to C<1> at compiletime, then libev will avoid using stdio
4918functions (printf, scanf, perror etc.). This will increase the code size
4919somewhat, but if your program doesn't otherwise depend on stdio and your
4920libc allows it, this avoids linking in the stdio library which is quite
4921big.
4922
4923Note that error messages might become less precise when this option is
4924enabled.
4925
4926=item EV_NSIG
4927
4928The highest supported signal number, +1 (or, the number of
4929signals): Normally, libev tries to deduce the maximum number of signals
4930automatically, but sometimes this fails, in which case it can be
4931specified. Also, using a lower number than detected (C<32> should be
4932good for about any system in existence) can save some memory, as libev
4933statically allocates some 12-24 bytes per signal number.
3396 4934
3397=item EV_PID_HASHSIZE 4935=item EV_PID_HASHSIZE
3398 4936
3399C<ev_child> watchers use a small hash table to distribute workload by 4937C<ev_child> watchers use a small hash table to distribute workload by
3400pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 4938pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3401than enough. If you need to manage thousands of children you might want to 4939usually more than enough. If you need to manage thousands of children you
3402increase this value (I<must> be a power of two). 4940might want to increase this value (I<must> be a power of two).
3403 4941
3404=item EV_INOTIFY_HASHSIZE 4942=item EV_INOTIFY_HASHSIZE
3405 4943
3406C<ev_stat> watchers use a small hash table to distribute workload by 4944C<ev_stat> watchers use a small hash table to distribute workload by
3407inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4945inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3408usually more than enough. If you need to manage thousands of C<ev_stat> 4946disabled), usually more than enough. If you need to manage thousands of
3409watchers you might want to increase this value (I<must> be a power of 4947C<ev_stat> watchers you might want to increase this value (I<must> be a
3410two). 4948power of two).
3411 4949
3412=item EV_USE_4HEAP 4950=item EV_USE_4HEAP
3413 4951
3414Heaps are not very cache-efficient. To improve the cache-efficiency of the 4952Heaps are not very cache-efficient. To improve the cache-efficiency of the
3415timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4953timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3416to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4954to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3417faster performance with many (thousands) of watchers. 4955faster performance with many (thousands) of watchers.
3418 4956
3419The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4957The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3420(disabled). 4958will be C<0>.
3421 4959
3422=item EV_HEAP_CACHE_AT 4960=item EV_HEAP_CACHE_AT
3423 4961
3424Heaps are not very cache-efficient. To improve the cache-efficiency of the 4962Heaps are not very cache-efficient. To improve the cache-efficiency of the
3425timer and periodics heaps, libev can cache the timestamp (I<at>) within 4963timer and periodics heaps, libev can cache the timestamp (I<at>) within
3426the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4964the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3427which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4965which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3428but avoids random read accesses on heap changes. This improves performance 4966but avoids random read accesses on heap changes. This improves performance
3429noticeably with many (hundreds) of watchers. 4967noticeably with many (hundreds) of watchers.
3430 4968
3431The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4969The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3432(disabled). 4970will be C<0>.
3433 4971
3434=item EV_VERIFY 4972=item EV_VERIFY
3435 4973
3436Controls how much internal verification (see C<ev_loop_verify ()>) will 4974Controls how much internal verification (see C<ev_verify ()>) will
3437be done: If set to C<0>, no internal verification code will be compiled 4975be done: If set to C<0>, no internal verification code will be compiled
3438in. If set to C<1>, then verification code will be compiled in, but not 4976in. If set to C<1>, then verification code will be compiled in, but not
3439called. If set to C<2>, then the internal verification code will be 4977called. If set to C<2>, then the internal verification code will be
3440called once per loop, which can slow down libev. If set to C<3>, then the 4978called once per loop, which can slow down libev. If set to C<3>, then the
3441verification code will be called very frequently, which will slow down 4979verification code will be called very frequently, which will slow down
3442libev considerably. 4980libev considerably.
3443 4981
4982Verification errors are reported via C's C<assert> mechanism, so if you
4983disable that (e.g. by defining C<NDEBUG>) then no errors will be reported.
4984
3444The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4985The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3445C<0>. 4986will be C<0>.
3446 4987
3447=item EV_COMMON 4988=item EV_COMMON
3448 4989
3449By default, all watchers have a C<void *data> member. By redefining 4990By default, all watchers have a C<void *data> member. By redefining
3450this macro to a something else you can include more and other types of 4991this macro to something else you can include more and other types of
3451members. You have to define it each time you include one of the files, 4992members. You have to define it each time you include one of the files,
3452though, and it must be identical each time. 4993though, and it must be identical each time.
3453 4994
3454For example, the perl EV module uses something like this: 4995For example, the perl EV module uses something like this:
3455 4996
3508file. 5049file.
3509 5050
3510The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 5051The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3511that everybody includes and which overrides some configure choices: 5052that everybody includes and which overrides some configure choices:
3512 5053
3513 #define EV_MINIMAL 1 5054 #define EV_FEATURES 8
3514 #define EV_USE_POLL 0 5055 #define EV_USE_SELECT 1
3515 #define EV_MULTIPLICITY 0
3516 #define EV_PERIODIC_ENABLE 0 5056 #define EV_PREPARE_ENABLE 1
5057 #define EV_IDLE_ENABLE 1
3517 #define EV_STAT_ENABLE 0 5058 #define EV_SIGNAL_ENABLE 1
3518 #define EV_FORK_ENABLE 0 5059 #define EV_CHILD_ENABLE 1
5060 #define EV_USE_STDEXCEPT 0
3519 #define EV_CONFIG_H <config.h> 5061 #define EV_CONFIG_H <config.h>
3520 #define EV_MINPRI 0
3521 #define EV_MAXPRI 0
3522 5062
3523 #include "ev++.h" 5063 #include "ev++.h"
3524 5064
3525And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 5065And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3526 5066
3527 #include "ev_cpp.h" 5067 #include "ev_cpp.h"
3528 #include "ev.c" 5068 #include "ev.c"
3529 5069
3530=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES 5070=head1 INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT
3531 5071
3532=head2 THREADS AND COROUTINES 5072=head2 THREADS AND COROUTINES
3533 5073
3534=head3 THREADS 5074=head3 THREADS
3535 5075
3586default loop and triggering an C<ev_async> watcher from the default loop 5126default loop and triggering an C<ev_async> watcher from the default loop
3587watcher callback into the event loop interested in the signal. 5127watcher callback into the event loop interested in the signal.
3588 5128
3589=back 5129=back
3590 5130
5131See also L</THREAD LOCKING EXAMPLE>.
5132
3591=head3 COROUTINES 5133=head3 COROUTINES
3592 5134
3593Libev is very accommodating to coroutines ("cooperative threads"): 5135Libev is very accommodating to coroutines ("cooperative threads"):
3594libev fully supports nesting calls to its functions from different 5136libev fully supports nesting calls to its functions from different
3595coroutines (e.g. you can call C<ev_loop> on the same loop from two 5137coroutines (e.g. you can call C<ev_run> on the same loop from two
3596different coroutines, and switch freely between both coroutines running the 5138different coroutines, and switch freely between both coroutines running
3597loop, as long as you don't confuse yourself). The only exception is that 5139the loop, as long as you don't confuse yourself). The only exception is
3598you must not do this from C<ev_periodic> reschedule callbacks. 5140that you must not do this from C<ev_periodic> reschedule callbacks.
3599 5141
3600Care has been taken to ensure that libev does not keep local state inside 5142Care has been taken to ensure that libev does not keep local state inside
3601C<ev_loop>, and other calls do not usually allow for coroutine switches as 5143C<ev_run>, and other calls do not usually allow for coroutine switches as
3602they do not call any callbacks. 5144they do not call any callbacks.
3603 5145
3604=head2 COMPILER WARNINGS 5146=head2 COMPILER WARNINGS
3605 5147
3606Depending on your compiler and compiler settings, you might get no or a 5148Depending on your compiler and compiler settings, you might get no or a
3617maintainable. 5159maintainable.
3618 5160
3619And of course, some compiler warnings are just plain stupid, or simply 5161And of course, some compiler warnings are just plain stupid, or simply
3620wrong (because they don't actually warn about the condition their message 5162wrong (because they don't actually warn about the condition their message
3621seems to warn about). For example, certain older gcc versions had some 5163seems to warn about). For example, certain older gcc versions had some
3622warnings that resulted an extreme number of false positives. These have 5164warnings that resulted in an extreme number of false positives. These have
3623been fixed, but some people still insist on making code warn-free with 5165been fixed, but some people still insist on making code warn-free with
3624such buggy versions. 5166such buggy versions.
3625 5167
3626While libev is written to generate as few warnings as possible, 5168While libev is written to generate as few warnings as possible,
3627"warn-free" code is not a goal, and it is recommended not to build libev 5169"warn-free" code is not a goal, and it is recommended not to build libev
3663I suggest using suppression lists. 5205I suggest using suppression lists.
3664 5206
3665 5207
3666=head1 PORTABILITY NOTES 5208=head1 PORTABILITY NOTES
3667 5209
5210=head2 GNU/LINUX 32 BIT LIMITATIONS
5211
5212GNU/Linux is the only common platform that supports 64 bit file/large file
5213interfaces but I<disables> them by default.
5214
5215That means that libev compiled in the default environment doesn't support
5216files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
5217
5218Unfortunately, many programs try to work around this GNU/Linux issue
5219by enabling the large file API, which makes them incompatible with the
5220standard libev compiled for their system.
5221
5222Likewise, libev cannot enable the large file API itself as this would
5223suddenly make it incompatible to the default compile time environment,
5224i.e. all programs not using special compile switches.
5225
5226=head2 OS/X AND DARWIN BUGS
5227
5228The whole thing is a bug if you ask me - basically any system interface
5229you touch is broken, whether it is locales, poll, kqueue or even the
5230OpenGL drivers.
5231
5232=head3 C<kqueue> is buggy
5233
5234The kqueue syscall is broken in all known versions - most versions support
5235only sockets, many support pipes.
5236
5237Libev tries to work around this by not using C<kqueue> by default on this
5238rotten platform, but of course you can still ask for it when creating a
5239loop - embedding a socket-only kqueue loop into a select-based one is
5240probably going to work well.
5241
5242=head3 C<poll> is buggy
5243
5244Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
5245implementation by something calling C<kqueue> internally around the 10.5.6
5246release, so now C<kqueue> I<and> C<poll> are broken.
5247
5248Libev tries to work around this by not using C<poll> by default on
5249this rotten platform, but of course you can still ask for it when creating
5250a loop.
5251
5252=head3 C<select> is buggy
5253
5254All that's left is C<select>, and of course Apple found a way to fuck this
5255one up as well: On OS/X, C<select> actively limits the number of file
5256descriptors you can pass in to 1024 - your program suddenly crashes when
5257you use more.
5258
5259There is an undocumented "workaround" for this - defining
5260C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
5261work on OS/X.
5262
5263=head2 SOLARIS PROBLEMS AND WORKAROUNDS
5264
5265=head3 C<errno> reentrancy
5266
5267The default compile environment on Solaris is unfortunately so
5268thread-unsafe that you can't even use components/libraries compiled
5269without C<-D_REENTRANT> in a threaded program, which, of course, isn't
5270defined by default. A valid, if stupid, implementation choice.
5271
5272If you want to use libev in threaded environments you have to make sure
5273it's compiled with C<_REENTRANT> defined.
5274
5275=head3 Event port backend
5276
5277The scalable event interface for Solaris is called "event
5278ports". Unfortunately, this mechanism is very buggy in all major
5279releases. If you run into high CPU usage, your program freezes or you get
5280a large number of spurious wakeups, make sure you have all the relevant
5281and latest kernel patches applied. No, I don't know which ones, but there
5282are multiple ones to apply, and afterwards, event ports actually work
5283great.
5284
5285If you can't get it to work, you can try running the program by setting
5286the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
5287C<select> backends.
5288
5289=head2 AIX POLL BUG
5290
5291AIX unfortunately has a broken C<poll.h> header. Libev works around
5292this by trying to avoid the poll backend altogether (i.e. it's not even
5293compiled in), which normally isn't a big problem as C<select> works fine
5294with large bitsets on AIX, and AIX is dead anyway.
5295
3668=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 5296=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
5297
5298=head3 General issues
3669 5299
3670Win32 doesn't support any of the standards (e.g. POSIX) that libev 5300Win32 doesn't support any of the standards (e.g. POSIX) that libev
3671requires, and its I/O model is fundamentally incompatible with the POSIX 5301requires, and its I/O model is fundamentally incompatible with the POSIX
3672model. Libev still offers limited functionality on this platform in 5302model. Libev still offers limited functionality on this platform in
3673the form of the C<EVBACKEND_SELECT> backend, and only supports socket 5303the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3674descriptors. This only applies when using Win32 natively, not when using 5304descriptors. This only applies when using Win32 natively, not when using
3675e.g. cygwin. 5305e.g. cygwin. Actually, it only applies to the microsofts own compilers,
5306as every compiler comes with a slightly differently broken/incompatible
5307environment.
3676 5308
3677Lifting these limitations would basically require the full 5309Lifting these limitations would basically require the full
3678re-implementation of the I/O system. If you are into these kinds of 5310re-implementation of the I/O system. If you are into this kind of thing,
3679things, then note that glib does exactly that for you in a very portable 5311then note that glib does exactly that for you in a very portable way (note
3680way (note also that glib is the slowest event library known to man). 5312also that glib is the slowest event library known to man).
3681 5313
3682There is no supported compilation method available on windows except 5314There is no supported compilation method available on windows except
3683embedding it into other applications. 5315embedding it into other applications.
5316
5317Sensible signal handling is officially unsupported by Microsoft - libev
5318tries its best, but under most conditions, signals will simply not work.
3684 5319
3685Not a libev limitation but worth mentioning: windows apparently doesn't 5320Not a libev limitation but worth mentioning: windows apparently doesn't
3686accept large writes: instead of resulting in a partial write, windows will 5321accept large writes: instead of resulting in a partial write, windows will
3687either accept everything or return C<ENOBUFS> if the buffer is too large, 5322either accept everything or return C<ENOBUFS> if the buffer is too large,
3688so make sure you only write small amounts into your sockets (less than a 5323so make sure you only write small amounts into your sockets (less than a
3693the abysmal performance of winsockets, using a large number of sockets 5328the abysmal performance of winsockets, using a large number of sockets
3694is not recommended (and not reasonable). If your program needs to use 5329is not recommended (and not reasonable). If your program needs to use
3695more than a hundred or so sockets, then likely it needs to use a totally 5330more than a hundred or so sockets, then likely it needs to use a totally
3696different implementation for windows, as libev offers the POSIX readiness 5331different implementation for windows, as libev offers the POSIX readiness
3697notification model, which cannot be implemented efficiently on windows 5332notification model, which cannot be implemented efficiently on windows
3698(Microsoft monopoly games). 5333(due to Microsoft monopoly games).
3699 5334
3700A typical way to use libev under windows is to embed it (see the embedding 5335A typical way to use libev under windows is to embed it (see the embedding
3701section for details) and use the following F<evwrap.h> header file instead 5336section for details) and use the following F<evwrap.h> header file instead
3702of F<ev.h>: 5337of F<ev.h>:
3703 5338
3710you do I<not> compile the F<ev.c> or any other embedded source files!): 5345you do I<not> compile the F<ev.c> or any other embedded source files!):
3711 5346
3712 #include "evwrap.h" 5347 #include "evwrap.h"
3713 #include "ev.c" 5348 #include "ev.c"
3714 5349
3715=over 4
3716
3717=item The winsocket select function 5350=head3 The winsocket C<select> function
3718 5351
3719The winsocket C<select> function doesn't follow POSIX in that it 5352The winsocket C<select> function doesn't follow POSIX in that it
3720requires socket I<handles> and not socket I<file descriptors> (it is 5353requires socket I<handles> and not socket I<file descriptors> (it is
3721also extremely buggy). This makes select very inefficient, and also 5354also extremely buggy). This makes select very inefficient, and also
3722requires a mapping from file descriptors to socket handles (the Microsoft 5355requires a mapping from file descriptors to socket handles (the Microsoft
3731 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 5364 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3732 5365
3733Note that winsockets handling of fd sets is O(n), so you can easily get a 5366Note that winsockets handling of fd sets is O(n), so you can easily get a
3734complexity in the O(n²) range when using win32. 5367complexity in the O(n²) range when using win32.
3735 5368
3736=item Limited number of file descriptors 5369=head3 Limited number of file descriptors
3737 5370
3738Windows has numerous arbitrary (and low) limits on things. 5371Windows has numerous arbitrary (and low) limits on things.
3739 5372
3740Early versions of winsocket's select only supported waiting for a maximum 5373Early versions of winsocket's select only supported waiting for a maximum
3741of C<64> handles (probably owning to the fact that all windows kernels 5374of C<64> handles (probably owning to the fact that all windows kernels
3742can only wait for C<64> things at the same time internally; Microsoft 5375can only wait for C<64> things at the same time internally; Microsoft
3743recommends spawning a chain of threads and wait for 63 handles and the 5376recommends spawning a chain of threads and wait for 63 handles and the
3744previous thread in each. Great). 5377previous thread in each. Sounds great!).
3745 5378
3746Newer versions support more handles, but you need to define C<FD_SETSIZE> 5379Newer versions support more handles, but you need to define C<FD_SETSIZE>
3747to some high number (e.g. C<2048>) before compiling the winsocket select 5380to some high number (e.g. C<2048>) before compiling the winsocket select
3748call (which might be in libev or elsewhere, for example, perl does its own 5381call (which might be in libev or elsewhere, for example, perl and many
3749select emulation on windows). 5382other interpreters do their own select emulation on windows).
3750 5383
3751Another limit is the number of file descriptors in the Microsoft runtime 5384Another limit is the number of file descriptors in the Microsoft runtime
3752libraries, which by default is C<64> (there must be a hidden I<64> fetish 5385libraries, which by default is C<64> (there must be a hidden I<64>
3753or something like this inside Microsoft). You can increase this by calling 5386fetish or something like this inside Microsoft). You can increase this
3754C<_setmaxstdio>, which can increase this limit to C<2048> (another 5387by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3755arbitrary limit), but is broken in many versions of the Microsoft runtime 5388(another arbitrary limit), but is broken in many versions of the Microsoft
3756libraries.
3757
3758This might get you to about C<512> or C<2048> sockets (depending on 5389runtime libraries. This might get you to about C<512> or C<2048> sockets
3759windows version and/or the phase of the moon). To get more, you need to 5390(depending on windows version and/or the phase of the moon). To get more,
3760wrap all I/O functions and provide your own fd management, but the cost of 5391you need to wrap all I/O functions and provide your own fd management, but
3761calling select (O(n²)) will likely make this unworkable. 5392the cost of calling select (O(n²)) will likely make this unworkable.
3762
3763=back
3764 5393
3765=head2 PORTABILITY REQUIREMENTS 5394=head2 PORTABILITY REQUIREMENTS
3766 5395
3767In addition to a working ISO-C implementation and of course the 5396In addition to a working ISO-C implementation and of course the
3768backend-specific APIs, libev relies on a few additional extensions: 5397backend-specific APIs, libev relies on a few additional extensions:
3775Libev assumes not only that all watcher pointers have the same internal 5404Libev assumes not only that all watcher pointers have the same internal
3776structure (guaranteed by POSIX but not by ISO C for example), but it also 5405structure (guaranteed by POSIX but not by ISO C for example), but it also
3777assumes that the same (machine) code can be used to call any watcher 5406assumes that the same (machine) code can be used to call any watcher
3778callback: The watcher callbacks have different type signatures, but libev 5407callback: The watcher callbacks have different type signatures, but libev
3779calls them using an C<ev_watcher *> internally. 5408calls them using an C<ev_watcher *> internally.
5409
5410=item null pointers and integer zero are represented by 0 bytes
5411
5412Libev uses C<memset> to initialise structs and arrays to C<0> bytes, and
5413relies on this setting pointers and integers to null.
5414
5415=item pointer accesses must be thread-atomic
5416
5417Accessing a pointer value must be atomic, it must both be readable and
5418writable in one piece - this is the case on all current architectures.
3780 5419
3781=item C<sig_atomic_t volatile> must be thread-atomic as well 5420=item C<sig_atomic_t volatile> must be thread-atomic as well
3782 5421
3783The type C<sig_atomic_t volatile> (or whatever is defined as 5422The type C<sig_atomic_t volatile> (or whatever is defined as
3784C<EV_ATOMIC_T>) must be atomic with respect to accesses from different 5423C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
3793thread" or will block signals process-wide, both behaviours would 5432thread" or will block signals process-wide, both behaviours would
3794be compatible with libev. Interaction between C<sigprocmask> and 5433be compatible with libev. Interaction between C<sigprocmask> and
3795C<pthread_sigmask> could complicate things, however. 5434C<pthread_sigmask> could complicate things, however.
3796 5435
3797The most portable way to handle signals is to block signals in all threads 5436The most portable way to handle signals is to block signals in all threads
3798except the initial one, and run the default loop in the initial thread as 5437except the initial one, and run the signal handling loop in the initial
3799well. 5438thread as well.
3800 5439
3801=item C<long> must be large enough for common memory allocation sizes 5440=item C<long> must be large enough for common memory allocation sizes
3802 5441
3803To improve portability and simplify its API, libev uses C<long> internally 5442To improve portability and simplify its API, libev uses C<long> internally
3804instead of C<size_t> when allocating its data structures. On non-POSIX 5443instead of C<size_t> when allocating its data structures. On non-POSIX
3807watchers. 5446watchers.
3808 5447
3809=item C<double> must hold a time value in seconds with enough accuracy 5448=item C<double> must hold a time value in seconds with enough accuracy
3810 5449
3811The type C<double> is used to represent timestamps. It is required to 5450The type C<double> is used to represent timestamps. It is required to
3812have at least 51 bits of mantissa (and 9 bits of exponent), which is good 5451have at least 51 bits of mantissa (and 9 bits of exponent), which is
3813enough for at least into the year 4000. This requirement is fulfilled by 5452good enough for at least into the year 4000 with millisecond accuracy
5453(the design goal for libev). This requirement is overfulfilled by
3814implementations implementing IEEE 754 (basically all existing ones). 5454implementations using IEEE 754, which is basically all existing ones.
5455
5456With IEEE 754 doubles, you get microsecond accuracy until at least the
5457year 2255 (and millisecond accuracy till the year 287396 - by then, libev
5458is either obsolete or somebody patched it to use C<long double> or
5459something like that, just kidding).
3815 5460
3816=back 5461=back
3817 5462
3818If you know of other additional requirements drop me a note. 5463If you know of other additional requirements drop me a note.
3819 5464
3881=item Processing ev_async_send: O(number_of_async_watchers) 5526=item Processing ev_async_send: O(number_of_async_watchers)
3882 5527
3883=item Processing signals: O(max_signal_number) 5528=item Processing signals: O(max_signal_number)
3884 5529
3885Sending involves a system call I<iff> there were no other C<ev_async_send> 5530Sending involves a system call I<iff> there were no other C<ev_async_send>
3886calls in the current loop iteration. Checking for async and signal events 5531calls in the current loop iteration and the loop is currently
5532blocked. Checking for async and signal events involves iterating over all
3887involves iterating over all running async watchers or all signal numbers. 5533running async watchers or all signal numbers.
3888 5534
3889=back 5535=back
3890 5536
3891 5537
5538=head1 PORTING FROM LIBEV 3.X TO 4.X
5539
5540The major version 4 introduced some incompatible changes to the API.
5541
5542At the moment, the C<ev.h> header file provides compatibility definitions
5543for all changes, so most programs should still compile. The compatibility
5544layer might be removed in later versions of libev, so better update to the
5545new API early than late.
5546
5547=over 4
5548
5549=item C<EV_COMPAT3> backwards compatibility mechanism
5550
5551The backward compatibility mechanism can be controlled by
5552C<EV_COMPAT3>. See L</"PREPROCESSOR SYMBOLS/MACROS"> in the L</EMBEDDING>
5553section.
5554
5555=item C<ev_default_destroy> and C<ev_default_fork> have been removed
5556
5557These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
5558
5559 ev_loop_destroy (EV_DEFAULT_UC);
5560 ev_loop_fork (EV_DEFAULT);
5561
5562=item function/symbol renames
5563
5564A number of functions and symbols have been renamed:
5565
5566 ev_loop => ev_run
5567 EVLOOP_NONBLOCK => EVRUN_NOWAIT
5568 EVLOOP_ONESHOT => EVRUN_ONCE
5569
5570 ev_unloop => ev_break
5571 EVUNLOOP_CANCEL => EVBREAK_CANCEL
5572 EVUNLOOP_ONE => EVBREAK_ONE
5573 EVUNLOOP_ALL => EVBREAK_ALL
5574
5575 EV_TIMEOUT => EV_TIMER
5576
5577 ev_loop_count => ev_iteration
5578 ev_loop_depth => ev_depth
5579 ev_loop_verify => ev_verify
5580
5581Most functions working on C<struct ev_loop> objects don't have an
5582C<ev_loop_> prefix, so it was removed; C<ev_loop>, C<ev_unloop> and
5583associated constants have been renamed to not collide with the C<struct
5584ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
5585as all other watcher types. Note that C<ev_loop_fork> is still called
5586C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
5587typedef.
5588
5589=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
5590
5591The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
5592mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
5593and work, but the library code will of course be larger.
5594
5595=back
5596
5597
5598=head1 GLOSSARY
5599
5600=over 4
5601
5602=item active
5603
5604A watcher is active as long as it has been started and not yet stopped.
5605See L</WATCHER STATES> for details.
5606
5607=item application
5608
5609In this document, an application is whatever is using libev.
5610
5611=item backend
5612
5613The part of the code dealing with the operating system interfaces.
5614
5615=item callback
5616
5617The address of a function that is called when some event has been
5618detected. Callbacks are being passed the event loop, the watcher that
5619received the event, and the actual event bitset.
5620
5621=item callback/watcher invocation
5622
5623The act of calling the callback associated with a watcher.
5624
5625=item event
5626
5627A change of state of some external event, such as data now being available
5628for reading on a file descriptor, time having passed or simply not having
5629any other events happening anymore.
5630
5631In libev, events are represented as single bits (such as C<EV_READ> or
5632C<EV_TIMER>).
5633
5634=item event library
5635
5636A software package implementing an event model and loop.
5637
5638=item event loop
5639
5640An entity that handles and processes external events and converts them
5641into callback invocations.
5642
5643=item event model
5644
5645The model used to describe how an event loop handles and processes
5646watchers and events.
5647
5648=item pending
5649
5650A watcher is pending as soon as the corresponding event has been
5651detected. See L</WATCHER STATES> for details.
5652
5653=item real time
5654
5655The physical time that is observed. It is apparently strictly monotonic :)
5656
5657=item wall-clock time
5658
5659The time and date as shown on clocks. Unlike real time, it can actually
5660be wrong and jump forwards and backwards, e.g. when you adjust your
5661clock.
5662
5663=item watcher
5664
5665A data structure that describes interest in certain events. Watchers need
5666to be started (attached to an event loop) before they can receive events.
5667
5668=back
5669
3892=head1 AUTHOR 5670=head1 AUTHOR
3893 5671
3894Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 5672Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
5673Magnusson and Emanuele Giaquinta, and minor corrections by many others.
3895 5674

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines