ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
Revision: 1.257
Committed: Wed Jul 15 16:08:24 2009 UTC (14 years, 10 months ago) by root
Branch: MAIN
Changes since 1.256: +30 -0 lines
Log Message:
*** empty log message ***

File Contents

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