]> git.llucax.com Git - software/libev.git/blob - ev.pod
*** empty log message ***
[software/libev.git] / ev.pod
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 =head1 EXAMPLE PROGRAM
10
11   #include <ev.h>
12
13   ev_io stdin_watcher;
14   ev_timer timeout_watcher;
15
16   /* called when data readable on stdin */
17   static void
18   stdin_cb (EV_P_ struct ev_io *w, int revents)
19   {
20     /* puts ("stdin ready"); */
21     ev_io_stop (EV_A_ w); /* just a syntax example */
22     ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
23   }
24
25   static void
26   timeout_cb (EV_P_ struct ev_timer *w, int revents)
27   {
28     /* puts ("timeout"); */
29     ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
30   }
31
32   int
33   main (void)
34   {
35     struct ev_loop *loop = ev_default_loop (0);
36
37     /* initialise an io watcher, then start it */
38     ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
39     ev_io_start (loop, &stdin_watcher);
40
41     /* simple non-repeating 5.5 second timeout */
42     ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
43     ev_timer_start (loop, &timeout_watcher);
44
45     /* loop till timeout or data ready */
46     ev_loop (loop, 0);
47
48     return 0;
49   }
50
51 =head1 DESCRIPTION
52
53 Libev is an event loop: you register interest in certain events (such as a
54 file descriptor being readable or a timeout occuring), and it will manage
55 these event sources and provide your program with events.
56
57 To do this, it must take more or less complete control over your process
58 (or thread) by executing the I<event loop> handler, and will then
59 communicate events via a callback mechanism.
60
61 You register interest in certain events by registering so-called I<event
62 watchers>, which are relatively small C structures you initialise with the
63 details of the event, and then hand it over to libev by I<starting> the
64 watcher.
65
66 =head1 FEATURES
67
68 Libev supports C<select>, C<poll>, the linux-specific C<epoll>, the
69 bsd-specific C<kqueue> and the solaris-specific event port mechanisms
70 for file descriptor events (C<ev_io>), relative timers (C<ev_timer>),
71 absolute timers with customised rescheduling (C<ev_periodic>), synchronous
72 signals (C<ev_signal>), process status change events (C<ev_child>), and
73 event watchers dealing with the event loop mechanism itself (C<ev_idle>,
74 C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as
75 file watchers (C<ev_stat>) and even limited support for fork events
76 (C<ev_fork>).
77
78 It also is quite fast (see this
79 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
80 for example).
81
82 =head1 CONVENTIONS
83
84 Libev is very configurable. In this manual the default configuration will
85 be described, which supports multiple event loops. For more info about
86 various configuration options please have a look at B<EMBED> section in
87 this manual. If libev was configured without support for multiple event
88 loops, then all functions taking an initial argument of name C<loop>
89 (which is always of type C<struct ev_loop *>) will not have this argument.
90
91 =head1 TIME REPRESENTATION
92
93 Libev represents time as a single floating point number, representing the
94 (fractional) number of seconds since the (POSIX) epoch (somewhere near
95 the beginning of 1970, details are complicated, don't ask). This type is
96 called C<ev_tstamp>, which is what you should use too. It usually aliases
97 to the C<double> type in C, and when you need to do any calculations on
98 it, you should treat it as such.
99
100 =head1 GLOBAL FUNCTIONS
101
102 These functions can be called anytime, even before initialising the
103 library in any way.
104
105 =over 4
106
107 =item ev_tstamp ev_time ()
108
109 Returns the current time as libev would use it. Please note that the
110 C<ev_now> function is usually faster and also often returns the timestamp
111 you actually want to know.
112
113 =item int ev_version_major ()
114
115 =item int ev_version_minor ()
116
117 You can find out the major and minor version numbers of the library
118 you linked against by calling the functions C<ev_version_major> and
119 C<ev_version_minor>. If you want, you can compare against the global
120 symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
121 version of the library your program was compiled against.
122
123 Usually, it's a good idea to terminate if the major versions mismatch,
124 as this indicates an incompatible change.  Minor versions are usually
125 compatible to older versions, so a larger minor version alone is usually
126 not a problem.
127
128 Example: Make sure we haven't accidentally been linked against the wrong
129 version.
130
131   assert (("libev version mismatch",
132            ev_version_major () == EV_VERSION_MAJOR
133            && ev_version_minor () >= EV_VERSION_MINOR));
134
135 =item unsigned int ev_supported_backends ()
136
137 Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
138 value) compiled into this binary of libev (independent of their
139 availability on the system you are running on). See C<ev_default_loop> for
140 a description of the set values.
141
142 Example: make sure we have the epoll method, because yeah this is cool and
143 a must have and can we have a torrent of it please!!!11
144
145   assert (("sorry, no epoll, no sex",
146            ev_supported_backends () & EVBACKEND_EPOLL));
147
148 =item unsigned int ev_recommended_backends ()
149
150 Return the set of all backends compiled into this binary of libev and also
151 recommended for this platform. This set is often smaller than the one
152 returned by C<ev_supported_backends>, as for example kqueue is broken on
153 most BSDs and will not be autodetected unless you explicitly request it
154 (assuming you know what you are doing). This is the set of backends that
155 libev will probe for if you specify no backends explicitly.
156
157 =item unsigned int ev_embeddable_backends ()
158
159 Returns the set of backends that are embeddable in other event loops. This
160 is the theoretical, all-platform, value. To find which backends
161 might be supported on the current system, you would need to look at
162 C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
163 recommended ones.
164
165 See the description of C<ev_embed> watchers for more info.
166
167 =item ev_set_allocator (void *(*cb)(void *ptr, size_t size))
168
169 Sets the allocation function to use (the prototype and semantics are
170 identical to the realloc C function). It is used to allocate and free
171 memory (no surprises here). If it returns zero when memory needs to be
172 allocated, the library might abort or take some potentially destructive
173 action. The default is your system realloc function.
174
175 You could override this function in high-availability programs to, say,
176 free some memory if it cannot allocate memory, to use a special allocator,
177 or even to sleep a while and retry until some memory is available.
178
179 Example: Replace the libev allocator with one that waits a bit and then
180 retries).
181
182    static void *
183    persistent_realloc (void *ptr, size_t size)
184    {
185      for (;;)
186        {
187          void *newptr = realloc (ptr, size);
188
189          if (newptr)
190            return newptr;
191
192          sleep (60);
193        }
194    }
195
196    ...
197    ev_set_allocator (persistent_realloc);
198
199 =item ev_set_syserr_cb (void (*cb)(const char *msg));
200
201 Set the callback function to call on a retryable syscall error (such
202 as failed select, poll, epoll_wait). The message is a printable string
203 indicating the system call or subsystem causing the problem. If this
204 callback is set, then libev will expect it to remedy the sitution, no
205 matter what, when it returns. That is, libev will generally retry the
206 requested operation, or, if the condition doesn't go away, do bad stuff
207 (such as abort).
208
209 Example: This is basically the same thing that libev does internally, too.
210
211    static void
212    fatal_error (const char *msg)
213    {
214      perror (msg);
215      abort ();
216    }
217
218    ...
219    ev_set_syserr_cb (fatal_error);
220
221 =back
222
223 =head1 FUNCTIONS CONTROLLING THE EVENT LOOP
224
225 An event loop is described by a C<struct ev_loop *>. The library knows two
226 types of such loops, the I<default> loop, which supports signals and child
227 events, and dynamically created loops which do not.
228
229 If you use threads, a common model is to run the default event loop
230 in your main thread (or in a separate thread) and for each thread you
231 create, you also create another event loop. Libev itself does no locking
232 whatsoever, so if you mix calls to the same event loop in different
233 threads, make sure you lock (this is usually a bad idea, though, even if
234 done correctly, because it's hideous and inefficient).
235
236 =over 4
237
238 =item struct ev_loop *ev_default_loop (unsigned int flags)
239
240 This will initialise the default event loop if it hasn't been initialised
241 yet and return it. If the default loop could not be initialised, returns
242 false. If it already was initialised it simply returns it (and ignores the
243 flags. If that is troubling you, check C<ev_backend ()> afterwards).
244
245 If you don't know what event loop to use, use the one returned from this
246 function.
247
248 The flags argument can be used to specify special behaviour or specific
249 backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
250
251 The following flags are supported:
252
253 =over 4
254
255 =item C<EVFLAG_AUTO>
256
257 The default flags value. Use this if you have no clue (it's the right
258 thing, believe me).
259
260 =item C<EVFLAG_NOENV>
261
262 If this flag bit is ored into the flag value (or the program runs setuid
263 or setgid) then libev will I<not> look at the environment variable
264 C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
265 override the flags completely if it is found in the environment. This is
266 useful to try out specific backends to test their performance, or to work
267 around bugs.
268
269 =item C<EVBACKEND_SELECT>  (value 1, portable select backend)
270
271 This is your standard select(2) backend. Not I<completely> standard, as
272 libev tries to roll its own fd_set with no limits on the number of fds,
273 but if that fails, expect a fairly low limit on the number of fds when
274 using this backend. It doesn't scale too well (O(highest_fd)), but its usually
275 the fastest backend for a low number of fds.
276
277 =item C<EVBACKEND_POLL>    (value 2, poll backend, available everywhere except on windows)
278
279 And this is your standard poll(2) backend. It's more complicated than
280 select, but handles sparse fds better and has no artificial limit on the
281 number of fds you can use (except it will slow down considerably with a
282 lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
283
284 =item C<EVBACKEND_EPOLL>   (value 4, Linux)
285
286 For few fds, this backend is a bit little slower than poll and select,
287 but it scales phenomenally better. While poll and select usually scale like
288 O(total_fds) where n is the total number of fds (or the highest fd), epoll scales
289 either O(1) or O(active_fds).
290
291 While stopping and starting an I/O watcher in the same iteration will
292 result in some caching, there is still a syscall per such incident
293 (because the fd could point to a different file description now), so its
294 best to avoid that. Also, dup()ed file descriptors might not work very
295 well if you register events for both fds.
296
297 Please note that epoll sometimes generates spurious notifications, so you
298 need to use non-blocking I/O or other means to avoid blocking when no data
299 (or space) is available.
300
301 =item C<EVBACKEND_KQUEUE>  (value 8, most BSD clones)
302
303 Kqueue deserves special mention, as at the time of this writing, it
304 was broken on all BSDs except NetBSD (usually it doesn't work with
305 anything but sockets and pipes, except on Darwin, where of course its
306 completely useless). For this reason its not being "autodetected"
307 unless you explicitly specify it explicitly in the flags (i.e. using
308 C<EVBACKEND_KQUEUE>).
309
310 It scales in the same way as the epoll backend, but the interface to the
311 kernel is more efficient (which says nothing about its actual speed, of
312 course). While starting and stopping an I/O watcher does not cause an
313 extra syscall as with epoll, it still adds up to four event changes per
314 incident, so its best to avoid that.
315
316 =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
317
318 This is not implemented yet (and might never be).
319
320 =item C<EVBACKEND_PORT>    (value 32, Solaris 10)
321
322 This uses the Solaris 10 port mechanism. As with everything on Solaris,
323 it's really slow, but it still scales very well (O(active_fds)).
324
325 Please note that solaris ports can result in a lot of spurious
326 notifications, so you need to use non-blocking I/O or other means to avoid
327 blocking when no data (or space) is available.
328
329 =item C<EVBACKEND_ALL>
330
331 Try all backends (even potentially broken ones that wouldn't be tried
332 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
333 C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
334
335 =back
336
337 If one or more of these are ored into the flags value, then only these
338 backends will be tried (in the reverse order as given here). If none are
339 specified, most compiled-in backend will be tried, usually in reverse
340 order of their flag values :)
341
342 The most typical usage is like this:
343
344   if (!ev_default_loop (0))
345     fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
346
347 Restrict libev to the select and poll backends, and do not allow
348 environment settings to be taken into account:
349
350   ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
351
352 Use whatever libev has to offer, but make sure that kqueue is used if
353 available (warning, breaks stuff, best use only with your own private
354 event loop and only if you know the OS supports your types of fds):
355
356   ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
357
358 =item struct ev_loop *ev_loop_new (unsigned int flags)
359
360 Similar to C<ev_default_loop>, but always creates a new event loop that is
361 always distinct from the default loop. Unlike the default loop, it cannot
362 handle signal and child watchers, and attempts to do so will be greeted by
363 undefined behaviour (or a failed assertion if assertions are enabled).
364
365 Example: Try to create a event loop that uses epoll and nothing else.
366
367   struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
368   if (!epoller)
369     fatal ("no epoll found here, maybe it hides under your chair");
370
371 =item ev_default_destroy ()
372
373 Destroys the default loop again (frees all memory and kernel state
374 etc.). None of the active event watchers will be stopped in the normal
375 sense, so e.g. C<ev_is_active> might still return true. It is your
376 responsibility to either stop all watchers cleanly yoursef I<before>
377 calling this function, or cope with the fact afterwards (which is usually
378 the easiest thing, youc na just ignore the watchers and/or C<free ()> them
379 for example).
380
381 =item ev_loop_destroy (loop)
382
383 Like C<ev_default_destroy>, but destroys an event loop created by an
384 earlier call to C<ev_loop_new>.
385
386 =item ev_default_fork ()
387
388 This function reinitialises the kernel state for backends that have
389 one. Despite the name, you can call it anytime, but it makes most sense
390 after forking, in either the parent or child process (or both, but that
391 again makes little sense).
392
393 You I<must> call this function in the child process after forking if and
394 only if you want to use the event library in both processes. If you just
395 fork+exec, you don't have to call it.
396
397 The function itself is quite fast and it's usually not a problem to call
398 it just in case after a fork. To make this easy, the function will fit in
399 quite nicely into a call to C<pthread_atfork>:
400
401     pthread_atfork (0, 0, ev_default_fork);
402
403 At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
404 without calling this function, so if you force one of those backends you
405 do not need to care.
406
407 =item ev_loop_fork (loop)
408
409 Like C<ev_default_fork>, but acts on an event loop created by
410 C<ev_loop_new>. Yes, you have to call this on every allocated event loop
411 after fork, and how you do this is entirely your own problem.
412
413 =item unsigned int ev_backend (loop)
414
415 Returns one of the C<EVBACKEND_*> flags indicating the event backend in
416 use.
417
418 =item ev_tstamp ev_now (loop)
419
420 Returns the current "event loop time", which is the time the event loop
421 received events and started processing them. This timestamp does not
422 change as long as callbacks are being processed, and this is also the base
423 time used for relative timers. You can treat it as the timestamp of the
424 event occuring (or more correctly, libev finding out about it).
425
426 =item ev_loop (loop, int flags)
427
428 Finally, this is it, the event handler. This function usually is called
429 after you initialised all your watchers and you want to start handling
430 events.
431
432 If the flags argument is specified as C<0>, it will not return until
433 either no event watchers are active anymore or C<ev_unloop> was called.
434
435 Please note that an explicit C<ev_unloop> is usually better than
436 relying on all watchers to be stopped when deciding when a program has
437 finished (especially in interactive programs), but having a program that
438 automatically loops as long as it has to and no longer by virtue of
439 relying on its watchers stopping correctly is a thing of beauty.
440
441 A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
442 those events and any outstanding ones, but will not block your process in
443 case there are no events and will return after one iteration of the loop.
444
445 A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
446 neccessary) and will handle those and any outstanding ones. It will block
447 your process until at least one new event arrives, and will return after
448 one iteration of the loop. This is useful if you are waiting for some
449 external event in conjunction with something not expressible using other
450 libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
451 usually a better approach for this kind of thing.
452
453 Here are the gory details of what C<ev_loop> does:
454
455    * If there are no active watchers (reference count is zero), return.
456    - Queue prepare watchers and then call all outstanding watchers.
457    - If we have been forked, recreate the kernel state.
458    - Update the kernel state with all outstanding changes.
459    - Update the "event loop time".
460    - Calculate for how long to block.
461    - Block the process, waiting for any events.
462    - Queue all outstanding I/O (fd) events.
463    - Update the "event loop time" and do time jump handling.
464    - Queue all outstanding timers.
465    - Queue all outstanding periodics.
466    - If no events are pending now, queue all idle watchers.
467    - Queue all check watchers.
468    - Call all queued watchers in reverse order (i.e. check watchers first).
469      Signals and child watchers are implemented as I/O watchers, and will
470      be handled here by queueing them when their watcher gets executed.
471    - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
472      were used, return, otherwise continue with step *.
473
474 Example: Queue some jobs and then loop until no events are outsanding
475 anymore.
476
477    ... queue jobs here, make sure they register event watchers as long
478    ... as they still have work to do (even an idle watcher will do..)
479    ev_loop (my_loop, 0);
480    ... jobs done. yeah!
481
482 =item ev_unloop (loop, how)
483
484 Can be used to make a call to C<ev_loop> return early (but only after it
485 has processed all outstanding events). The C<how> argument must be either
486 C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
487 C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
488
489 =item ev_ref (loop)
490
491 =item ev_unref (loop)
492
493 Ref/unref can be used to add or remove a reference count on the event
494 loop: Every watcher keeps one reference, and as long as the reference
495 count is nonzero, C<ev_loop> will not return on its own. If you have
496 a watcher you never unregister that should not keep C<ev_loop> from
497 returning, ev_unref() after starting, and ev_ref() before stopping it. For
498 example, libev itself uses this for its internal signal pipe: It is not
499 visible to the libev user and should not keep C<ev_loop> from exiting if
500 no event watchers registered by it are active. It is also an excellent
501 way to do this for generic recurring timers or from within third-party
502 libraries. Just remember to I<unref after start> and I<ref before stop>.
503
504 Example: Create a signal watcher, but keep it from keeping C<ev_loop>
505 running when nothing else is active.
506
507   struct ev_signal exitsig;
508   ev_signal_init (&exitsig, sig_cb, SIGINT);
509   ev_signal_start (loop, &exitsig);
510   evf_unref (loop);
511
512 Example: For some weird reason, unregister the above signal handler again.
513
514   ev_ref (loop);
515   ev_signal_stop (loop, &exitsig);
516
517 =back
518
519
520 =head1 ANATOMY OF A WATCHER
521
522 A watcher is a structure that you create and register to record your
523 interest in some event. For instance, if you want to wait for STDIN to
524 become readable, you would create an C<ev_io> watcher for that:
525
526   static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
527   {
528     ev_io_stop (w);
529     ev_unloop (loop, EVUNLOOP_ALL);
530   }
531
532   struct ev_loop *loop = ev_default_loop (0);
533   struct ev_io stdin_watcher;
534   ev_init (&stdin_watcher, my_cb);
535   ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
536   ev_io_start (loop, &stdin_watcher);
537   ev_loop (loop, 0);
538
539 As you can see, you are responsible for allocating the memory for your
540 watcher structures (and it is usually a bad idea to do this on the stack,
541 although this can sometimes be quite valid).
542
543 Each watcher structure must be initialised by a call to C<ev_init
544 (watcher *, callback)>, which expects a callback to be provided. This
545 callback gets invoked each time the event occurs (or, in the case of io
546 watchers, each time the event loop detects that the file descriptor given
547 is readable and/or writable).
548
549 Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
550 with arguments specific to this watcher type. There is also a macro
551 to combine initialisation and setting in one call: C<< ev_<type>_init
552 (watcher *, callback, ...) >>.
553
554 To make the watcher actually watch out for events, you have to start it
555 with a watcher-specific start function (C<< ev_<type>_start (loop, watcher
556 *) >>), and you can stop watching for events at any time by calling the
557 corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
558
559 As long as your watcher is active (has been started but not stopped) you
560 must not touch the values stored in it. Most specifically you must never
561 reinitialise it or call its C<set> macro.
562
563 Each and every callback receives the event loop pointer as first, the
564 registered watcher structure as second, and a bitset of received events as
565 third argument.
566
567 The received events usually include a single bit per event type received
568 (you can receive multiple events at the same time). The possible bit masks
569 are:
570
571 =over 4
572
573 =item C<EV_READ>
574
575 =item C<EV_WRITE>
576
577 The file descriptor in the C<ev_io> watcher has become readable and/or
578 writable.
579
580 =item C<EV_TIMEOUT>
581
582 The C<ev_timer> watcher has timed out.
583
584 =item C<EV_PERIODIC>
585
586 The C<ev_periodic> watcher has timed out.
587
588 =item C<EV_SIGNAL>
589
590 The signal specified in the C<ev_signal> watcher has been received by a thread.
591
592 =item C<EV_CHILD>
593
594 The pid specified in the C<ev_child> watcher has received a status change.
595
596 =item C<EV_STAT>
597
598 The path specified in the C<ev_stat> watcher changed its attributes somehow.
599
600 =item C<EV_IDLE>
601
602 The C<ev_idle> watcher has determined that you have nothing better to do.
603
604 =item C<EV_PREPARE>
605
606 =item C<EV_CHECK>
607
608 All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
609 to gather new events, and all C<ev_check> watchers are invoked just after
610 C<ev_loop> has gathered them, but before it invokes any callbacks for any
611 received events. Callbacks of both watcher types can start and stop as
612 many watchers as they want, and all of them will be taken into account
613 (for example, a C<ev_prepare> watcher might start an idle watcher to keep
614 C<ev_loop> from blocking).
615
616 =item C<EV_EMBED>
617
618 The embedded event loop specified in the C<ev_embed> watcher needs attention.
619
620 =item C<EV_FORK>
621
622 The event loop has been resumed in the child process after fork (see
623 C<ev_fork>).
624
625 =item C<EV_ERROR>
626
627 An unspecified error has occured, the watcher has been stopped. This might
628 happen because the watcher could not be properly started because libev
629 ran out of memory, a file descriptor was found to be closed or any other
630 problem. You best act on it by reporting the problem and somehow coping
631 with the watcher being stopped.
632
633 Libev will usually signal a few "dummy" events together with an error,
634 for example it might indicate that a fd is readable or writable, and if
635 your callbacks is well-written it can just attempt the operation and cope
636 with the error from read() or write(). This will not work in multithreaded
637 programs, though, so beware.
638
639 =back
640
641 =head2 GENERIC WATCHER FUNCTIONS
642
643 In the following description, C<TYPE> stands for the watcher type,
644 e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
645
646 =over 4
647
648 =item C<ev_init> (ev_TYPE *watcher, callback)
649
650 This macro initialises the generic portion of a watcher. The contents
651 of the watcher object can be arbitrary (so C<malloc> will do). Only
652 the generic parts of the watcher are initialised, you I<need> to call
653 the type-specific C<ev_TYPE_set> macro afterwards to initialise the
654 type-specific parts. For each type there is also a C<ev_TYPE_init> macro
655 which rolls both calls into one.
656
657 You can reinitialise a watcher at any time as long as it has been stopped
658 (or never started) and there are no pending events outstanding.
659
660 The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher,
661 int revents)>.
662
663 =item C<ev_TYPE_set> (ev_TYPE *, [args])
664
665 This macro initialises the type-specific parts of a watcher. You need to
666 call C<ev_init> at least once before you call this macro, but you can
667 call C<ev_TYPE_set> any number of times. You must not, however, call this
668 macro on a watcher that is active (it can be pending, however, which is a
669 difference to the C<ev_init> macro).
670
671 Although some watcher types do not have type-specific arguments
672 (e.g. C<ev_prepare>) you still need to call its C<set> macro.
673
674 =item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
675
676 This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
677 calls into a single call. This is the most convinient method to initialise
678 a watcher. The same limitations apply, of course.
679
680 =item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
681
682 Starts (activates) the given watcher. Only active watchers will receive
683 events. If the watcher is already active nothing will happen.
684
685 =item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
686
687 Stops the given watcher again (if active) and clears the pending
688 status. It is possible that stopped watchers are pending (for example,
689 non-repeating timers are being stopped when they become pending), but
690 C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If
691 you want to free or reuse the memory used by the watcher it is therefore a
692 good idea to always call its C<ev_TYPE_stop> function.
693
694 =item bool ev_is_active (ev_TYPE *watcher)
695
696 Returns a true value iff the watcher is active (i.e. it has been started
697 and not yet been stopped). As long as a watcher is active you must not modify
698 it.
699
700 =item bool ev_is_pending (ev_TYPE *watcher)
701
702 Returns a true value iff the watcher is pending, (i.e. it has outstanding
703 events but its callback has not yet been invoked). As long as a watcher
704 is pending (but not active) you must not call an init function on it (but
705 C<ev_TYPE_set> is safe) and you must make sure the watcher is available to
706 libev (e.g. you cnanot C<free ()> it).
707
708 =item callback ev_cb (ev_TYPE *watcher)
709
710 Returns the callback currently set on the watcher.
711
712 =item ev_cb_set (ev_TYPE *watcher, callback)
713
714 Change the callback. You can change the callback at virtually any time
715 (modulo threads).
716
717 =back
718
719
720 =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
721
722 Each watcher has, by default, a member C<void *data> that you can change
723 and read at any time, libev will completely ignore it. This can be used
724 to associate arbitrary data with your watcher. If you need more data and
725 don't want to allocate memory and store a pointer to it in that data
726 member, you can also "subclass" the watcher type and provide your own
727 data:
728
729   struct my_io
730   {
731     struct ev_io io;
732     int otherfd;
733     void *somedata;
734     struct whatever *mostinteresting;
735   }
736
737 And since your callback will be called with a pointer to the watcher, you
738 can cast it back to your own type:
739
740   static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
741   {
742     struct my_io *w = (struct my_io *)w_;
743     ...
744   }
745
746 More interesting and less C-conformant ways of casting your callback type
747 instead have been omitted.
748
749 Another common scenario is having some data structure with multiple
750 watchers:
751
752   struct my_biggy
753   {
754     int some_data;
755     ev_timer t1;
756     ev_timer t2;
757   }
758
759 In this case getting the pointer to C<my_biggy> is a bit more complicated,
760 you need to use C<offsetof>:
761
762   #include <stddef.h>
763
764   static void
765   t1_cb (EV_P_ struct ev_timer *w, int revents)
766   {
767     struct my_biggy big = (struct my_biggy *
768       (((char *)w) - offsetof (struct my_biggy, t1));
769   }
770
771   static void
772   t2_cb (EV_P_ struct ev_timer *w, int revents)
773   {
774     struct my_biggy big = (struct my_biggy *
775       (((char *)w) - offsetof (struct my_biggy, t2));
776   }
777
778
779 =head1 WATCHER TYPES
780
781 This section describes each watcher in detail, but will not repeat
782 information given in the last section. Any initialisation/set macros,
783 functions and members specific to the watcher type are explained.
784
785 Members are additionally marked with either I<[read-only]>, meaning that,
786 while the watcher is active, you can look at the member and expect some
787 sensible content, but you must not modify it (you can modify it while the
788 watcher is stopped to your hearts content), or I<[read-write]>, which
789 means you can expect it to have some sensible content while the watcher
790 is active, but you can also modify it. Modifying it may not do something
791 sensible or take immediate effect (or do anything at all), but libev will
792 not crash or malfunction in any way.
793
794
795 =head2 C<ev_io> - is this file descriptor readable or writable?
796
797 I/O watchers check whether a file descriptor is readable or writable
798 in each iteration of the event loop, or, more precisely, when reading
799 would not block the process and writing would at least be able to write
800 some data. This behaviour is called level-triggering because you keep
801 receiving events as long as the condition persists. Remember you can stop
802 the watcher if you don't want to act on the event and neither want to
803 receive future events.
804
805 In general you can register as many read and/or write event watchers per
806 fd as you want (as long as you don't confuse yourself). Setting all file
807 descriptors to non-blocking mode is also usually a good idea (but not
808 required if you know what you are doing).
809
810 You have to be careful with dup'ed file descriptors, though. Some backends
811 (the linux epoll backend is a notable example) cannot handle dup'ed file
812 descriptors correctly if you register interest in two or more fds pointing
813 to the same underlying file/socket/etc. description (that is, they share
814 the same underlying "file open").
815
816 If you must do this, then force the use of a known-to-be-good backend
817 (at the time of this writing, this includes only C<EVBACKEND_SELECT> and
818 C<EVBACKEND_POLL>).
819
820 Another thing you have to watch out for is that it is quite easy to
821 receive "spurious" readyness notifications, that is your callback might
822 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
823 because there is no data. Not only are some backends known to create a
824 lot of those (for example solaris ports), it is very easy to get into
825 this situation even with a relatively standard program structure. Thus
826 it is best to always use non-blocking I/O: An extra C<read>(2) returning
827 C<EAGAIN> is far preferable to a program hanging until some data arrives.
828
829 If you cannot run the fd in non-blocking mode (for example you should not
830 play around with an Xlib connection), then you have to seperately re-test
831 wether a file descriptor is really ready with a known-to-be good interface
832 such as poll (fortunately in our Xlib example, Xlib already does this on
833 its own, so its quite safe to use).
834
835 =over 4
836
837 =item ev_io_init (ev_io *, callback, int fd, int events)
838
839 =item ev_io_set (ev_io *, int fd, int events)
840
841 Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
842 rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or
843 C<EV_READ | EV_WRITE> to receive the given events.
844
845 =item int fd [read-only]
846
847 The file descriptor being watched.
848
849 =item int events [read-only]
850
851 The events being watched.
852
853 =back
854
855 Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
856 readable, but only once. Since it is likely line-buffered, you could
857 attempt to read a whole line in the callback.
858
859   static void
860   stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
861   {
862      ev_io_stop (loop, w);
863     .. read from stdin here (or from w->fd) and haqndle any I/O errors
864   }
865
866   ...
867   struct ev_loop *loop = ev_default_init (0);
868   struct ev_io stdin_readable;
869   ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
870   ev_io_start (loop, &stdin_readable);
871   ev_loop (loop, 0);
872
873
874 =head2 C<ev_timer> - relative and optionally repeating timeouts
875
876 Timer watchers are simple relative timers that generate an event after a
877 given time, and optionally repeating in regular intervals after that.
878
879 The timers are based on real time, that is, if you register an event that
880 times out after an hour and you reset your system clock to last years
881 time, it will still time out after (roughly) and hour. "Roughly" because
882 detecting time jumps is hard, and some inaccuracies are unavoidable (the
883 monotonic clock option helps a lot here).
884
885 The relative timeouts are calculated relative to the C<ev_now ()>
886 time. This is usually the right thing as this timestamp refers to the time
887 of the event triggering whatever timeout you are modifying/starting. If
888 you suspect event processing to be delayed and you I<need> to base the timeout
889 on the current time, use something like this to adjust for this:
890
891    ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
892
893 The callback is guarenteed to be invoked only when its timeout has passed,
894 but if multiple timers become ready during the same loop iteration then
895 order of execution is undefined.
896
897 =over 4
898
899 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
900
901 =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
902
903 Configure the timer to trigger after C<after> seconds. If C<repeat> is
904 C<0.>, then it will automatically be stopped. If it is positive, then the
905 timer will automatically be configured to trigger again C<repeat> seconds
906 later, again, and again, until stopped manually.
907
908 The timer itself will do a best-effort at avoiding drift, that is, if you
909 configure a timer to trigger every 10 seconds, then it will trigger at
910 exactly 10 second intervals. If, however, your program cannot keep up with
911 the timer (because it takes longer than those 10 seconds to do stuff) the
912 timer will not fire more than once per event loop iteration.
913
914 =item ev_timer_again (loop)
915
916 This will act as if the timer timed out and restart it again if it is
917 repeating. The exact semantics are:
918
919 If the timer is started but nonrepeating, stop it.
920
921 If the timer is repeating, either start it if necessary (with the repeat
922 value), or reset the running timer to the repeat value.
923
924 This sounds a bit complicated, but here is a useful and typical
925 example: Imagine you have a tcp connection and you want a so-called
926 idle timeout, that is, you want to be called when there have been,
927 say, 60 seconds of inactivity on the socket. The easiest way to do
928 this is to configure an C<ev_timer> with C<after>=C<repeat>=C<60> and calling
929 C<ev_timer_again> each time you successfully read or write some data. If
930 you go into an idle state where you do not expect data to travel on the
931 socket, you can stop the timer, and again will automatically restart it if
932 need be.
933
934 You can also ignore the C<after> value and C<ev_timer_start> altogether
935 and only ever use the C<repeat> value:
936
937    ev_timer_init (timer, callback, 0., 5.);
938    ev_timer_again (loop, timer);
939    ...
940    timer->again = 17.;
941    ev_timer_again (loop, timer);
942    ...
943    timer->again = 10.;
944    ev_timer_again (loop, timer);
945
946 This is more efficient then stopping/starting the timer eahc time you want
947 to modify its timeout value.
948
949 =item ev_tstamp repeat [read-write]
950
951 The current C<repeat> value. Will be used each time the watcher times out
952 or C<ev_timer_again> is called and determines the next timeout (if any),
953 which is also when any modifications are taken into account.
954
955 =back
956
957 Example: Create a timer that fires after 60 seconds.
958
959   static void
960   one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
961   {
962     .. one minute over, w is actually stopped right here
963   }
964
965   struct ev_timer mytimer;
966   ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
967   ev_timer_start (loop, &mytimer);
968
969 Example: Create a timeout timer that times out after 10 seconds of
970 inactivity.
971
972   static void
973   timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
974   {
975     .. ten seconds without any activity
976   }
977
978   struct ev_timer mytimer;
979   ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
980   ev_timer_again (&mytimer); /* start timer */
981   ev_loop (loop, 0);
982
983   // and in some piece of code that gets executed on any "activity":
984   // reset the timeout to start ticking again at 10 seconds
985   ev_timer_again (&mytimer);
986
987
988 =head2 C<ev_periodic> - to cron or not to cron?
989
990 Periodic watchers are also timers of a kind, but they are very versatile
991 (and unfortunately a bit complex).
992
993 Unlike C<ev_timer>'s, they are not based on real time (or relative time)
994 but on wallclock time (absolute time). You can tell a periodic watcher
995 to trigger "at" some specific point in time. For example, if you tell a
996 periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
997 + 10.>) and then reset your system clock to the last year, then it will
998 take a year to trigger the event (unlike an C<ev_timer>, which would trigger
999 roughly 10 seconds later and of course not if you reset your system time
1000 again).
1001
1002 They can also be used to implement vastly more complex timers, such as
1003 triggering an event on eahc midnight, local time.
1004
1005 As with timers, the callback is guarenteed to be invoked only when the
1006 time (C<at>) has been passed, but if multiple periodic timers become ready
1007 during the same loop iteration then order of execution is undefined.
1008
1009 =over 4
1010
1011 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1012
1013 =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1014
1015 Lots of arguments, lets sort it out... There are basically three modes of
1016 operation, and we will explain them from simplest to complex:
1017
1018 =over 4
1019
1020 =item * absolute timer (interval = reschedule_cb = 0)
1021
1022 In this configuration the watcher triggers an event at the wallclock time
1023 C<at> and doesn't repeat. It will not adjust when a time jump occurs,
1024 that is, if it is to be run at January 1st 2011 then it will run when the
1025 system time reaches or surpasses this time.
1026
1027 =item * non-repeating interval timer (interval > 0, reschedule_cb = 0)
1028
1029 In this mode the watcher will always be scheduled to time out at the next
1030 C<at + N * interval> time (for some integer N) and then repeat, regardless
1031 of any time jumps.
1032
1033 This can be used to create timers that do not drift with respect to system
1034 time:
1035
1036    ev_periodic_set (&periodic, 0., 3600., 0);
1037
1038 This doesn't mean there will always be 3600 seconds in between triggers,
1039 but only that the the callback will be called when the system time shows a
1040 full hour (UTC), or more correctly, when the system time is evenly divisible
1041 by 3600.
1042
1043 Another way to think about it (for the mathematically inclined) is that
1044 C<ev_periodic> will try to run the callback in this mode at the next possible
1045 time where C<time = at (mod interval)>, regardless of any time jumps.
1046
1047 =item * manual reschedule mode (reschedule_cb = callback)
1048
1049 In this mode the values for C<interval> and C<at> are both being
1050 ignored. Instead, each time the periodic watcher gets scheduled, the
1051 reschedule callback will be called with the watcher as first, and the
1052 current time as second argument.
1053
1054 NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1055 ever, or make any event loop modifications>. If you need to stop it,
1056 return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1057 starting a prepare watcher).
1058
1059 Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
1060 ev_tstamp now)>, e.g.:
1061
1062    static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1063    {
1064      return now + 60.;
1065    }
1066
1067 It must return the next time to trigger, based on the passed time value
1068 (that is, the lowest time value larger than to the second argument). It
1069 will usually be called just before the callback will be triggered, but
1070 might be called at other times, too.
1071
1072 NOTE: I<< This callback must always return a time that is later than the
1073 passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger.
1074
1075 This can be used to create very complex timers, such as a timer that
1076 triggers on each midnight, local time. To do this, you would calculate the
1077 next midnight after C<now> and return the timestamp value for this. How
1078 you do this is, again, up to you (but it is not trivial, which is the main
1079 reason I omitted it as an example).
1080
1081 =back
1082
1083 =item ev_periodic_again (loop, ev_periodic *)
1084
1085 Simply stops and restarts the periodic watcher again. This is only useful
1086 when you changed some parameters or the reschedule callback would return
1087 a different time than the last time it was called (e.g. in a crond like
1088 program when the crontabs have changed).
1089
1090 =item ev_tstamp interval [read-write]
1091
1092 The current interval value. Can be modified any time, but changes only
1093 take effect when the periodic timer fires or C<ev_periodic_again> is being
1094 called.
1095
1096 =item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]
1097
1098 The current reschedule callback, or C<0>, if this functionality is
1099 switched off. Can be changed any time, but changes only take effect when
1100 the periodic timer fires or C<ev_periodic_again> is being called.
1101
1102 =back
1103
1104 Example: Call a callback every hour, or, more precisely, whenever the
1105 system clock is divisible by 3600. The callback invocation times have
1106 potentially a lot of jittering, but good long-term stability.
1107
1108   static void
1109   clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1110   {
1111     ... its now a full hour (UTC, or TAI or whatever your clock follows)
1112   }
1113
1114   struct ev_periodic hourly_tick;
1115   ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1116   ev_periodic_start (loop, &hourly_tick);
1117
1118 Example: The same as above, but use a reschedule callback to do it:
1119
1120   #include <math.h>
1121
1122   static ev_tstamp
1123   my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
1124   {
1125     return fmod (now, 3600.) + 3600.;
1126   }
1127
1128   ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1129
1130 Example: Call a callback every hour, starting now:
1131
1132   struct ev_periodic hourly_tick;
1133   ev_periodic_init (&hourly_tick, clock_cb,
1134                     fmod (ev_now (loop), 3600.), 3600., 0);
1135   ev_periodic_start (loop, &hourly_tick);
1136   
1137
1138 =head2 C<ev_signal> - signal me when a signal gets signalled!
1139
1140 Signal watchers will trigger an event when the process receives a specific
1141 signal one or more times. Even though signals are very asynchronous, libev
1142 will try it's best to deliver signals synchronously, i.e. as part of the
1143 normal event processing, like any other event.
1144
1145 You can configure as many watchers as you like per signal. Only when the
1146 first watcher gets started will libev actually register a signal watcher
1147 with the kernel (thus it coexists with your own signal handlers as long
1148 as you don't register any with libev). Similarly, when the last signal
1149 watcher for a signal is stopped libev will reset the signal handler to
1150 SIG_DFL (regardless of what it was set to before).
1151
1152 =over 4
1153
1154 =item ev_signal_init (ev_signal *, callback, int signum)
1155
1156 =item ev_signal_set (ev_signal *, int signum)
1157
1158 Configures the watcher to trigger on the given signal number (usually one
1159 of the C<SIGxxx> constants).
1160
1161 =item int signum [read-only]
1162
1163 The signal the watcher watches out for.
1164
1165 =back
1166
1167
1168 =head2 C<ev_child> - watch out for process status changes
1169
1170 Child watchers trigger when your process receives a SIGCHLD in response to
1171 some child status changes (most typically when a child of yours dies).
1172
1173 =over 4
1174
1175 =item ev_child_init (ev_child *, callback, int pid)
1176
1177 =item ev_child_set (ev_child *, int pid)
1178
1179 Configures the watcher to wait for status changes of process C<pid> (or
1180 I<any> process if C<pid> is specified as C<0>). The callback can look
1181 at the C<rstatus> member of the C<ev_child> watcher structure to see
1182 the status word (use the macros from C<sys/wait.h> and see your systems
1183 C<waitpid> documentation). The C<rpid> member contains the pid of the
1184 process causing the status change.
1185
1186 =item int pid [read-only]
1187
1188 The process id this watcher watches out for, or C<0>, meaning any process id.
1189
1190 =item int rpid [read-write]
1191
1192 The process id that detected a status change.
1193
1194 =item int rstatus [read-write]
1195
1196 The process exit/trace status caused by C<rpid> (see your systems
1197 C<waitpid> and C<sys/wait.h> documentation for details).
1198
1199 =back
1200
1201 Example: Try to exit cleanly on SIGINT and SIGTERM.
1202
1203   static void
1204   sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1205   {
1206     ev_unloop (loop, EVUNLOOP_ALL);
1207   }
1208
1209   struct ev_signal signal_watcher;
1210   ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1211   ev_signal_start (loop, &sigint_cb);
1212
1213
1214 =head2 C<ev_stat> - did the file attributes just change?
1215
1216 This watches a filesystem path for attribute changes. That is, it calls
1217 C<stat> regularly (or when the OS says it changed) and sees if it changed
1218 compared to the last time, invoking the callback if it did.
1219
1220 The path does not need to exist: changing from "path exists" to "path does
1221 not exist" is a status change like any other. The condition "path does
1222 not exist" is signified by the C<st_nlink> field being zero (which is
1223 otherwise always forced to be at least one) and all the other fields of
1224 the stat buffer having unspecified contents.
1225
1226 Since there is no standard to do this, the portable implementation simply
1227 calls C<stat (2)> regulalry on the path to see if it changed somehow. You
1228 can specify a recommended polling interval for this case. If you specify
1229 a polling interval of C<0> (highly recommended!) then a I<suitable,
1230 unspecified default> value will be used (which you can expect to be around
1231 five seconds, although this might change dynamically). Libev will also
1232 impose a minimum interval which is currently around C<0.1>, but thats
1233 usually overkill.
1234
1235 This watcher type is not meant for massive numbers of stat watchers,
1236 as even with OS-supported change notifications, this can be
1237 resource-intensive.
1238
1239 At the time of this writing, no specific OS backends are implemented, but
1240 if demand increases, at least a kqueue and inotify backend will be added.
1241
1242 =over 4
1243
1244 =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1245
1246 =item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)
1247
1248 Configures the watcher to wait for status changes of the given
1249 C<path>. The C<interval> is a hint on how quickly a change is expected to
1250 be detected and should normally be specified as C<0> to let libev choose
1251 a suitable value. The memory pointed to by C<path> must point to the same
1252 path for as long as the watcher is active.
1253
1254 The callback will be receive C<EV_STAT> when a change was detected,
1255 relative to the attributes at the time the watcher was started (or the
1256 last change was detected).
1257
1258 =item ev_stat_stat (ev_stat *)
1259
1260 Updates the stat buffer immediately with new values. If you change the
1261 watched path in your callback, you could call this fucntion to avoid
1262 detecting this change (while introducing a race condition). Can also be
1263 useful simply to find out the new values.
1264
1265 =item ev_statdata attr [read-only]
1266
1267 The most-recently detected attributes of the file. Although the type is of
1268 C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
1269 suitable for your system. If the C<st_nlink> member is C<0>, then there
1270 was some error while C<stat>ing the file.
1271
1272 =item ev_statdata prev [read-only]
1273
1274 The previous attributes of the file. The callback gets invoked whenever
1275 C<prev> != C<attr>.
1276
1277 =item ev_tstamp interval [read-only]
1278
1279 The specified interval.
1280
1281 =item const char *path [read-only]
1282
1283 The filesystem path that is being watched.
1284
1285 =back
1286
1287 Example: Watch C</etc/passwd> for attribute changes.
1288
1289   static void
1290   passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1291   {
1292     /* /etc/passwd changed in some way */
1293     if (w->attr.st_nlink)
1294       {
1295         printf ("passwd current size  %ld\n", (long)w->attr.st_size);
1296         printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
1297         printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
1298       }
1299     else
1300       /* you shalt not abuse printf for puts */
1301       puts ("wow, /etc/passwd is not there, expect problems. "
1302             "if this is windows, they already arrived\n");
1303   }
1304
1305   ...
1306   ev_stat passwd;
1307
1308   ev_stat_init (&passwd, passwd_cb, "/etc/passwd");
1309   ev_stat_start (loop, &passwd);
1310
1311
1312 =head2 C<ev_idle> - when you've got nothing better to do...
1313
1314 Idle watchers trigger events when there are no other events are pending
1315 (prepare, check and other idle watchers do not count). That is, as long
1316 as your process is busy handling sockets or timeouts (or even signals,
1317 imagine) it will not be triggered. But when your process is idle all idle
1318 watchers are being called again and again, once per event loop iteration -
1319 until stopped, that is, or your process receives more events and becomes
1320 busy.
1321
1322 The most noteworthy effect is that as long as any idle watchers are
1323 active, the process will not block when waiting for new events.
1324
1325 Apart from keeping your process non-blocking (which is a useful
1326 effect on its own sometimes), idle watchers are a good place to do
1327 "pseudo-background processing", or delay processing stuff to after the
1328 event loop has handled all outstanding events.
1329
1330 =over 4
1331
1332 =item ev_idle_init (ev_signal *, callback)
1333
1334 Initialises and configures the idle watcher - it has no parameters of any
1335 kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
1336 believe me.
1337
1338 =back
1339
1340 Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1341 callback, free it. Also, use no error checking, as usual.
1342
1343   static void
1344   idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
1345   {
1346     free (w);
1347     // now do something you wanted to do when the program has
1348     // no longer asnything immediate to do.
1349   }
1350
1351   struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1352   ev_idle_init (idle_watcher, idle_cb);
1353   ev_idle_start (loop, idle_cb);
1354
1355
1356 =head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1357
1358 Prepare and check watchers are usually (but not always) used in tandem:
1359 prepare watchers get invoked before the process blocks and check watchers
1360 afterwards.
1361
1362 You I<must not> call C<ev_loop> or similar functions that enter
1363 the current event loop from either C<ev_prepare> or C<ev_check>
1364 watchers. Other loops than the current one are fine, however. The
1365 rationale behind this is that you do not need to check for recursion in
1366 those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1367 C<ev_check> so if you have one watcher of each kind they will always be
1368 called in pairs bracketing the blocking call.
1369
1370 Their main purpose is to integrate other event mechanisms into libev and
1371 their use is somewhat advanced. This could be used, for example, to track
1372 variable changes, implement your own watchers, integrate net-snmp or a
1373 coroutine library and lots more. They are also occasionally useful if
1374 you cache some data and want to flush it before blocking (for example,
1375 in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1376 watcher).
1377
1378 This is done by examining in each prepare call which file descriptors need
1379 to be watched by the other library, registering C<ev_io> watchers for
1380 them and starting an C<ev_timer> watcher for any timeouts (many libraries
1381 provide just this functionality). Then, in the check watcher you check for
1382 any events that occured (by checking the pending status of all watchers
1383 and stopping them) and call back into the library. The I/O and timer
1384 callbacks will never actually be called (but must be valid nevertheless,
1385 because you never know, you know?).
1386
1387 As another example, the Perl Coro module uses these hooks to integrate
1388 coroutines into libev programs, by yielding to other active coroutines
1389 during each prepare and only letting the process block if no coroutines
1390 are ready to run (it's actually more complicated: it only runs coroutines
1391 with priority higher than or equal to the event loop and one coroutine
1392 of lower priority, but only once, using idle watchers to keep the event
1393 loop from blocking if lower-priority coroutines are active, thus mapping
1394 low-priority coroutines to idle/background tasks).
1395
1396 =over 4
1397
1398 =item ev_prepare_init (ev_prepare *, callback)
1399
1400 =item ev_check_init (ev_check *, callback)
1401
1402 Initialises and configures the prepare or check watcher - they have no
1403 parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1404 macros, but using them is utterly, utterly and completely pointless.
1405
1406 =back
1407
1408 Example: To include a library such as adns, you would add IO watchers
1409 and a timeout watcher in a prepare handler, as required by libadns, and
1410 in a check watcher, destroy them and call into libadns. What follows is
1411 pseudo-code only of course:
1412
1413   static ev_io iow [nfd];
1414   static ev_timer tw;
1415
1416   static void
1417   io_cb (ev_loop *loop, ev_io *w, int revents)
1418   {
1419     // set the relevant poll flags
1420     // could also call adns_processreadable etc. here
1421     struct pollfd *fd = (struct pollfd *)w->data;
1422     if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1423     if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1424   }
1425
1426   // create io watchers for each fd and a timer before blocking
1427   static void
1428   adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1429   {
1430     int timeout = 3600000;truct pollfd fds [nfd];
1431     // actual code will need to loop here and realloc etc.
1432     adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1433
1434     /* the callback is illegal, but won't be called as we stop during check */
1435     ev_timer_init (&tw, 0, timeout * 1e-3);
1436     ev_timer_start (loop, &tw);
1437
1438     // create on ev_io per pollfd
1439     for (int i = 0; i < nfd; ++i)
1440       {
1441         ev_io_init (iow + i, io_cb, fds [i].fd,
1442           ((fds [i].events & POLLIN ? EV_READ : 0)
1443            | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1444
1445         fds [i].revents = 0;
1446         iow [i].data = fds + i;
1447         ev_io_start (loop, iow + i);
1448       }
1449   }
1450
1451   // stop all watchers after blocking
1452   static void
1453   adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1454   {
1455     ev_timer_stop (loop, &tw);
1456
1457     for (int i = 0; i < nfd; ++i)
1458       ev_io_stop (loop, iow + i);
1459
1460     adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1461   }
1462
1463
1464 =head2 C<ev_embed> - when one backend isn't enough...
1465
1466 This is a rather advanced watcher type that lets you embed one event loop
1467 into another (currently only C<ev_io> events are supported in the embedded
1468 loop, other types of watchers might be handled in a delayed or incorrect
1469 fashion and must not be used).
1470
1471 There are primarily two reasons you would want that: work around bugs and
1472 prioritise I/O.
1473
1474 As an example for a bug workaround, the kqueue backend might only support
1475 sockets on some platform, so it is unusable as generic backend, but you
1476 still want to make use of it because you have many sockets and it scales
1477 so nicely. In this case, you would create a kqueue-based loop and embed it
1478 into your default loop (which might use e.g. poll). Overall operation will
1479 be a bit slower because first libev has to poll and then call kevent, but
1480 at least you can use both at what they are best.
1481
1482 As for prioritising I/O: rarely you have the case where some fds have
1483 to be watched and handled very quickly (with low latency), and even
1484 priorities and idle watchers might have too much overhead. In this case
1485 you would put all the high priority stuff in one loop and all the rest in
1486 a second one, and embed the second one in the first.
1487
1488 As long as the watcher is active, the callback will be invoked every time
1489 there might be events pending in the embedded loop. The callback must then
1490 call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke
1491 their callbacks (you could also start an idle watcher to give the embedded
1492 loop strictly lower priority for example). You can also set the callback
1493 to C<0>, in which case the embed watcher will automatically execute the
1494 embedded loop sweep.
1495
1496 As long as the watcher is started it will automatically handle events. The
1497 callback will be invoked whenever some events have been handled. You can
1498 set the callback to C<0> to avoid having to specify one if you are not
1499 interested in that.
1500
1501 Also, there have not currently been made special provisions for forking:
1502 when you fork, you not only have to call C<ev_loop_fork> on both loops,
1503 but you will also have to stop and restart any C<ev_embed> watchers
1504 yourself.
1505
1506 Unfortunately, not all backends are embeddable, only the ones returned by
1507 C<ev_embeddable_backends> are, which, unfortunately, does not include any
1508 portable one.
1509
1510 So when you want to use this feature you will always have to be prepared
1511 that you cannot get an embeddable loop. The recommended way to get around
1512 this is to have a separate variables for your embeddable loop, try to
1513 create it, and if that fails, use the normal loop for everything:
1514
1515   struct ev_loop *loop_hi = ev_default_init (0);
1516   struct ev_loop *loop_lo = 0;
1517   struct ev_embed embed;
1518   
1519   // see if there is a chance of getting one that works
1520   // (remember that a flags value of 0 means autodetection)
1521   loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
1522     ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
1523     : 0;
1524
1525   // if we got one, then embed it, otherwise default to loop_hi
1526   if (loop_lo)
1527     {
1528       ev_embed_init (&embed, 0, loop_lo);
1529       ev_embed_start (loop_hi, &embed);
1530     }
1531   else
1532     loop_lo = loop_hi;
1533
1534 =over 4
1535
1536 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
1537
1538 =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
1539
1540 Configures the watcher to embed the given loop, which must be
1541 embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
1542 invoked automatically, otherwise it is the responsibility of the callback
1543 to invoke it (it will continue to be called until the sweep has been done,
1544 if you do not want thta, you need to temporarily stop the embed watcher).
1545
1546 =item ev_embed_sweep (loop, ev_embed *)
1547
1548 Make a single, non-blocking sweep over the embedded loop. This works
1549 similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1550 apropriate way for embedded loops.
1551
1552 =item struct ev_loop *loop [read-only]
1553
1554 The embedded event loop.
1555
1556 =back
1557
1558
1559 =head2 C<ev_fork> - the audacity to resume the event loop after a fork
1560
1561 Fork watchers are called when a C<fork ()> was detected (usually because
1562 whoever is a good citizen cared to tell libev about it by calling
1563 C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the
1564 event loop blocks next and before C<ev_check> watchers are being called,
1565 and only in the child after the fork. If whoever good citizen calling
1566 C<ev_default_fork> cheats and calls it in the wrong process, the fork
1567 handlers will be invoked, too, of course.
1568
1569 =over 4
1570
1571 =item ev_fork_init (ev_signal *, callback)
1572
1573 Initialises and configures the fork watcher - it has no parameters of any
1574 kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
1575 believe me.
1576
1577 =back
1578
1579
1580 =head1 OTHER FUNCTIONS
1581
1582 There are some other functions of possible interest. Described. Here. Now.
1583
1584 =over 4
1585
1586 =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
1587
1588 This function combines a simple timer and an I/O watcher, calls your
1589 callback on whichever event happens first and automatically stop both
1590 watchers. This is useful if you want to wait for a single event on an fd
1591 or timeout without having to allocate/configure/start/stop/free one or
1592 more watchers yourself.
1593
1594 If C<fd> is less than 0, then no I/O watcher will be started and events
1595 is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
1596 C<events> set will be craeted and started.
1597
1598 If C<timeout> is less than 0, then no timeout watcher will be
1599 started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
1600 repeat = 0) will be started. While C<0> is a valid timeout, it is of
1601 dubious value.
1602
1603 The callback has the type C<void (*cb)(int revents, void *arg)> and gets
1604 passed an C<revents> set like normal event callbacks (a combination of
1605 C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
1606 value passed to C<ev_once>:
1607
1608   static void stdin_ready (int revents, void *arg)
1609   {
1610     if (revents & EV_TIMEOUT)
1611       /* doh, nothing entered */;
1612     else if (revents & EV_READ)
1613       /* stdin might have data for us, joy! */;
1614   }
1615
1616   ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
1617
1618 =item ev_feed_event (ev_loop *, watcher *, int revents)
1619
1620 Feeds the given event set into the event loop, as if the specified event
1621 had happened for the specified watcher (which must be a pointer to an
1622 initialised but not necessarily started event watcher).
1623
1624 =item ev_feed_fd_event (ev_loop *, int fd, int revents)
1625
1626 Feed an event on the given fd, as if a file descriptor backend detected
1627 the given events it.
1628
1629 =item ev_feed_signal_event (ev_loop *loop, int signum)
1630
1631 Feed an event as if the given signal occured (C<loop> must be the default
1632 loop!).
1633
1634 =back
1635
1636
1637 =head1 LIBEVENT EMULATION
1638
1639 Libev offers a compatibility emulation layer for libevent. It cannot
1640 emulate the internals of libevent, so here are some usage hints:
1641
1642 =over 4
1643
1644 =item * Use it by including <event.h>, as usual.
1645
1646 =item * The following members are fully supported: ev_base, ev_callback,
1647 ev_arg, ev_fd, ev_res, ev_events.
1648
1649 =item * Avoid using ev_flags and the EVLIST_*-macros, while it is
1650 maintained by libev, it does not work exactly the same way as in libevent (consider
1651 it a private API).
1652
1653 =item * Priorities are not currently supported. Initialising priorities
1654 will fail and all watchers will have the same priority, even though there
1655 is an ev_pri field.
1656
1657 =item * Other members are not supported.
1658
1659 =item * The libev emulation is I<not> ABI compatible to libevent, you need
1660 to use the libev header file and library.
1661
1662 =back
1663
1664 =head1 C++ SUPPORT
1665
1666 Libev comes with some simplistic wrapper classes for C++ that mainly allow
1667 you to use some convinience methods to start/stop watchers and also change
1668 the callback model to a model using method callbacks on objects.
1669
1670 To use it,
1671    
1672   #include <ev++.h>
1673
1674 (it is not installed by default). This automatically includes F<ev.h>
1675 and puts all of its definitions (many of them macros) into the global
1676 namespace. All C++ specific things are put into the C<ev> namespace.
1677
1678 It should support all the same embedding options as F<ev.h>, most notably
1679 C<EV_MULTIPLICITY>.
1680
1681 Here is a list of things available in the C<ev> namespace:
1682
1683 =over 4
1684
1685 =item C<ev::READ>, C<ev::WRITE> etc.
1686
1687 These are just enum values with the same values as the C<EV_READ> etc.
1688 macros from F<ev.h>.
1689
1690 =item C<ev::tstamp>, C<ev::now>
1691
1692 Aliases to the same types/functions as with the C<ev_> prefix.
1693
1694 =item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
1695
1696 For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
1697 the same name in the C<ev> namespace, with the exception of C<ev_signal>
1698 which is called C<ev::sig> to avoid clashes with the C<signal> macro
1699 defines by many implementations.
1700
1701 All of those classes have these methods:
1702
1703 =over 4
1704
1705 =item ev::TYPE::TYPE (object *, object::method *)
1706
1707 =item ev::TYPE::TYPE (object *, object::method *, struct ev_loop *)
1708
1709 =item ev::TYPE::~TYPE
1710
1711 The constructor takes a pointer to an object and a method pointer to
1712 the event handler callback to call in this class. The constructor calls
1713 C<ev_init> for you, which means you have to call the C<set> method
1714 before starting it. If you do not specify a loop then the constructor
1715 automatically associates the default loop with this watcher.
1716
1717 The destructor automatically stops the watcher if it is active.
1718
1719 =item w->set (struct ev_loop *)
1720
1721 Associates a different C<struct ev_loop> with this watcher. You can only
1722 do this when the watcher is inactive (and not pending either).
1723
1724 =item w->set ([args])
1725
1726 Basically the same as C<ev_TYPE_set>, with the same args. Must be
1727 called at least once.  Unlike the C counterpart, an active watcher gets
1728 automatically stopped and restarted.
1729
1730 =item w->start ()
1731
1732 Starts the watcher. Note that there is no C<loop> argument as the
1733 constructor already takes the loop.
1734
1735 =item w->stop ()
1736
1737 Stops the watcher if it is active. Again, no C<loop> argument.
1738
1739 =item w->again ()       C<ev::timer>, C<ev::periodic> only
1740
1741 For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
1742 C<ev_TYPE_again> function.
1743
1744 =item w->sweep ()       C<ev::embed> only
1745
1746 Invokes C<ev_embed_sweep>.
1747
1748 =item w->update ()      C<ev::stat> only
1749
1750 Invokes C<ev_stat_stat>.
1751
1752 =back
1753
1754 =back
1755
1756 Example: Define a class with an IO and idle watcher, start one of them in
1757 the constructor.
1758
1759   class myclass
1760   {
1761     ev_io   io;   void io_cb   (ev::io   &w, int revents);
1762     ev_idle idle  void idle_cb (ev::idle &w, int revents);
1763
1764     myclass ();
1765   }
1766
1767   myclass::myclass (int fd)
1768   : io   (this, &myclass::io_cb),
1769     idle (this, &myclass::idle_cb)
1770   {
1771     io.start (fd, ev::READ);
1772   }
1773
1774
1775 =head1 MACRO MAGIC
1776
1777 Libev can be compiled with a variety of options, the most fundemantal is
1778 C<EV_MULTIPLICITY>. This option determines wether (most) functions and
1779 callbacks have an initial C<struct ev_loop *> argument.
1780
1781 To make it easier to write programs that cope with either variant, the
1782 following macros are defined:
1783
1784 =over 4
1785
1786 =item C<EV_A>, C<EV_A_>
1787
1788 This provides the loop I<argument> for functions, if one is required ("ev
1789 loop argument"). The C<EV_A> form is used when this is the sole argument,
1790 C<EV_A_> is used when other arguments are following. Example:
1791
1792   ev_unref (EV_A);
1793   ev_timer_add (EV_A_ watcher);
1794   ev_loop (EV_A_ 0);
1795
1796 It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
1797 which is often provided by the following macro.
1798
1799 =item C<EV_P>, C<EV_P_>
1800
1801 This provides the loop I<parameter> for functions, if one is required ("ev
1802 loop parameter"). The C<EV_P> form is used when this is the sole parameter,
1803 C<EV_P_> is used when other parameters are following. Example:
1804
1805   // this is how ev_unref is being declared
1806   static void ev_unref (EV_P);
1807
1808   // this is how you can declare your typical callback
1809   static void cb (EV_P_ ev_timer *w, int revents)
1810
1811 It declares a parameter C<loop> of type C<struct ev_loop *>, quite
1812 suitable for use with C<EV_A>.
1813
1814 =item C<EV_DEFAULT>, C<EV_DEFAULT_>
1815
1816 Similar to the other two macros, this gives you the value of the default
1817 loop, if multiple loops are supported ("ev loop default").
1818
1819 =back
1820
1821 Example: Declare and initialise a check watcher, working regardless of
1822 wether multiple loops are supported or not.
1823
1824   static void
1825   check_cb (EV_P_ ev_timer *w, int revents)
1826   {
1827     ev_check_stop (EV_A_ w);
1828   }
1829
1830   ev_check check;
1831   ev_check_init (&check, check_cb);
1832   ev_check_start (EV_DEFAULT_ &check);
1833   ev_loop (EV_DEFAULT_ 0);
1834
1835
1836 =head1 EMBEDDING
1837
1838 Libev can (and often is) directly embedded into host
1839 applications. Examples of applications that embed it include the Deliantra
1840 Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
1841 and rxvt-unicode.
1842
1843 The goal is to enable you to just copy the neecssary files into your
1844 source directory without having to change even a single line in them, so
1845 you can easily upgrade by simply copying (or having a checked-out copy of
1846 libev somewhere in your source tree).
1847
1848 =head2 FILESETS
1849
1850 Depending on what features you need you need to include one or more sets of files
1851 in your app.
1852
1853 =head3 CORE EVENT LOOP
1854
1855 To include only the libev core (all the C<ev_*> functions), with manual
1856 configuration (no autoconf):
1857
1858   #define EV_STANDALONE 1
1859   #include "ev.c"
1860
1861 This will automatically include F<ev.h>, too, and should be done in a
1862 single C source file only to provide the function implementations. To use
1863 it, do the same for F<ev.h> in all files wishing to use this API (best
1864 done by writing a wrapper around F<ev.h> that you can include instead and
1865 where you can put other configuration options):
1866
1867   #define EV_STANDALONE 1
1868   #include "ev.h"
1869
1870 Both header files and implementation files can be compiled with a C++
1871 compiler (at least, thats a stated goal, and breakage will be treated
1872 as a bug).
1873
1874 You need the following files in your source tree, or in a directory
1875 in your include path (e.g. in libev/ when using -Ilibev):
1876
1877   ev.h
1878   ev.c
1879   ev_vars.h
1880   ev_wrap.h
1881
1882   ev_win32.c      required on win32 platforms only
1883
1884   ev_select.c     only when select backend is enabled (which is by default)
1885   ev_poll.c       only when poll backend is enabled (disabled by default)
1886   ev_epoll.c      only when the epoll backend is enabled (disabled by default)
1887   ev_kqueue.c     only when the kqueue backend is enabled (disabled by default)
1888   ev_port.c       only when the solaris port backend is enabled (disabled by default)
1889
1890 F<ev.c> includes the backend files directly when enabled, so you only need
1891 to compile this single file.
1892
1893 =head3 LIBEVENT COMPATIBILITY API
1894
1895 To include the libevent compatibility API, also include:
1896
1897   #include "event.c"
1898
1899 in the file including F<ev.c>, and:
1900
1901   #include "event.h"
1902
1903 in the files that want to use the libevent API. This also includes F<ev.h>.
1904
1905 You need the following additional files for this:
1906
1907   event.h
1908   event.c
1909
1910 =head3 AUTOCONF SUPPORT
1911
1912 Instead of using C<EV_STANDALONE=1> and providing your config in
1913 whatever way you want, you can also C<m4_include([libev.m4])> in your
1914 F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
1915 include F<config.h> and configure itself accordingly.
1916
1917 For this of course you need the m4 file:
1918
1919   libev.m4
1920
1921 =head2 PREPROCESSOR SYMBOLS/MACROS
1922
1923 Libev can be configured via a variety of preprocessor symbols you have to define
1924 before including any of its files. The default is not to build for multiplicity
1925 and only include the select backend.
1926
1927 =over 4
1928
1929 =item EV_STANDALONE
1930
1931 Must always be C<1> if you do not use autoconf configuration, which
1932 keeps libev from including F<config.h>, and it also defines dummy
1933 implementations for some libevent functions (such as logging, which is not
1934 supported). It will also not define any of the structs usually found in
1935 F<event.h> that are not directly supported by the libev core alone.
1936
1937 =item EV_USE_MONOTONIC
1938
1939 If defined to be C<1>, libev will try to detect the availability of the
1940 monotonic clock option at both compiletime and runtime. Otherwise no use
1941 of the monotonic clock option will be attempted. If you enable this, you
1942 usually have to link against librt or something similar. Enabling it when
1943 the functionality isn't available is safe, though, althoguh you have
1944 to make sure you link against any libraries where the C<clock_gettime>
1945 function is hiding in (often F<-lrt>).
1946
1947 =item EV_USE_REALTIME
1948
1949 If defined to be C<1>, libev will try to detect the availability of the
1950 realtime clock option at compiletime (and assume its availability at
1951 runtime if successful). Otherwise no use of the realtime clock option will
1952 be attempted. This effectively replaces C<gettimeofday> by C<clock_get
1953 (CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries
1954 in the description of C<EV_USE_MONOTONIC>, though.
1955
1956 =item EV_USE_SELECT
1957
1958 If undefined or defined to be C<1>, libev will compile in support for the
1959 C<select>(2) backend. No attempt at autodetection will be done: if no
1960 other method takes over, select will be it. Otherwise the select backend
1961 will not be compiled in.
1962
1963 =item EV_SELECT_USE_FD_SET
1964
1965 If defined to C<1>, then the select backend will use the system C<fd_set>
1966 structure. This is useful if libev doesn't compile due to a missing
1967 C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on
1968 exotic systems. This usually limits the range of file descriptors to some
1969 low limit such as 1024 or might have other limitations (winsocket only
1970 allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
1971 influence the size of the C<fd_set> used.
1972
1973 =item EV_SELECT_IS_WINSOCKET
1974
1975 When defined to C<1>, the select backend will assume that
1976 select/socket/connect etc. don't understand file descriptors but
1977 wants osf handles on win32 (this is the case when the select to
1978 be used is the winsock select). This means that it will call
1979 C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
1980 it is assumed that all these functions actually work on fds, even
1981 on win32. Should not be defined on non-win32 platforms.
1982
1983 =item EV_USE_POLL
1984
1985 If defined to be C<1>, libev will compile in support for the C<poll>(2)
1986 backend. Otherwise it will be enabled on non-win32 platforms. It
1987 takes precedence over select.
1988
1989 =item EV_USE_EPOLL
1990
1991 If defined to be C<1>, libev will compile in support for the Linux
1992 C<epoll>(7) backend. Its availability will be detected at runtime,
1993 otherwise another method will be used as fallback. This is the
1994 preferred backend for GNU/Linux systems.
1995
1996 =item EV_USE_KQUEUE
1997
1998 If defined to be C<1>, libev will compile in support for the BSD style
1999 C<kqueue>(2) backend. Its actual availability will be detected at runtime,
2000 otherwise another method will be used as fallback. This is the preferred
2001 backend for BSD and BSD-like systems, although on most BSDs kqueue only
2002 supports some types of fds correctly (the only platform we found that
2003 supports ptys for example was NetBSD), so kqueue might be compiled in, but
2004 not be used unless explicitly requested. The best way to use it is to find
2005 out whether kqueue supports your type of fd properly and use an embedded
2006 kqueue loop.
2007
2008 =item EV_USE_PORT
2009
2010 If defined to be C<1>, libev will compile in support for the Solaris
2011 10 port style backend. Its availability will be detected at runtime,
2012 otherwise another method will be used as fallback. This is the preferred
2013 backend for Solaris 10 systems.
2014
2015 =item EV_USE_DEVPOLL
2016
2017 reserved for future expansion, works like the USE symbols above.
2018
2019 =item EV_H
2020
2021 The name of the F<ev.h> header file used to include it. The default if
2022 undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This
2023 can be used to virtually rename the F<ev.h> header file in case of conflicts.
2024
2025 =item EV_CONFIG_H
2026
2027 If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2028 F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2029 C<EV_H>, above.
2030
2031 =item EV_EVENT_H
2032
2033 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2034 of how the F<event.h> header can be found.
2035
2036 =item EV_PROTOTYPES
2037
2038 If defined to be C<0>, then F<ev.h> will not define any function
2039 prototypes, but still define all the structs and other symbols. This is
2040 occasionally useful if you want to provide your own wrapper functions
2041 around libev functions.
2042
2043 =item EV_MULTIPLICITY
2044
2045 If undefined or defined to C<1>, then all event-loop-specific functions
2046 will have the C<struct ev_loop *> as first argument, and you can create
2047 additional independent event loops. Otherwise there will be no support
2048 for multiple event loops and there is no first event loop pointer
2049 argument. Instead, all functions act on the single default loop.
2050
2051 =item EV_PERIODIC_ENABLE
2052
2053 If undefined or defined to be C<1>, then periodic timers are supported. If
2054 defined to be C<0>, then they are not. Disabling them saves a few kB of
2055 code.
2056
2057 =item EV_EMBED_ENABLE
2058
2059 If undefined or defined to be C<1>, then embed watchers are supported. If
2060 defined to be C<0>, then they are not.
2061
2062 =item EV_STAT_ENABLE
2063
2064 If undefined or defined to be C<1>, then stat watchers are supported. If
2065 defined to be C<0>, then they are not.
2066
2067 =item EV_FORK_ENABLE
2068
2069 If undefined or defined to be C<1>, then fork watchers are supported. If
2070 defined to be C<0>, then they are not.
2071
2072 =item EV_MINIMAL
2073
2074 If you need to shave off some kilobytes of code at the expense of some
2075 speed, define this symbol to C<1>. Currently only used for gcc to override
2076 some inlining decisions, saves roughly 30% codesize of amd64.
2077
2078 =item EV_PID_HASHSIZE
2079
2080 C<ev_child> watchers use a small hash table to distribute workload by
2081 pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
2082 than enough. If you need to manage thousands of children you might want to
2083 increase this value.
2084
2085 =item EV_COMMON
2086
2087 By default, all watchers have a C<void *data> member. By redefining
2088 this macro to a something else you can include more and other types of
2089 members. You have to define it each time you include one of the files,
2090 though, and it must be identical each time.
2091
2092 For example, the perl EV module uses something like this:
2093
2094   #define EV_COMMON                       \
2095     SV *self; /* contains this struct */  \
2096     SV *cb_sv, *fh /* note no trailing ";" */
2097
2098 =item EV_CB_DECLARE (type)
2099
2100 =item EV_CB_INVOKE (watcher, revents)
2101
2102 =item ev_set_cb (ev, cb)
2103
2104 Can be used to change the callback member declaration in each watcher,
2105 and the way callbacks are invoked and set. Must expand to a struct member
2106 definition and a statement, respectively. See the F<ev.v> header file for
2107 their default definitions. One possible use for overriding these is to
2108 avoid the C<struct ev_loop *> as first argument in all cases, or to use
2109 method calls instead of plain function calls in C++.
2110
2111 =head2 EXAMPLES
2112
2113 For a real-world example of a program the includes libev
2114 verbatim, you can have a look at the EV perl module
2115 (L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
2116 the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public
2117 interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2118 will be compiled. It is pretty complex because it provides its own header
2119 file.
2120
2121 The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2122 that everybody includes and which overrides some autoconf choices:
2123
2124   #define EV_USE_POLL 0
2125   #define EV_MULTIPLICITY 0
2126   #define EV_PERIODICS 0
2127   #define EV_CONFIG_H <config.h>
2128
2129   #include "ev++.h"
2130
2131 And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2132
2133   #include "ev_cpp.h"
2134   #include "ev.c"
2135
2136
2137 =head1 COMPLEXITIES
2138
2139 In this section the complexities of (many of) the algorithms used inside
2140 libev will be explained. For complexity discussions about backends see the
2141 documentation for C<ev_default_init>.
2142
2143 =over 4
2144
2145 =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2146
2147 =item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
2148
2149 =item Starting io/check/prepare/idle/signal/child watchers: O(1)
2150
2151 =item Stopping check/prepare/idle watchers: O(1)
2152
2153 =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))
2154
2155 =item Finding the next timer per loop iteration: O(1)
2156
2157 =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2158
2159 =item Activating one watcher: O(1)
2160
2161 =back
2162
2163
2164 =head1 AUTHOR
2165
2166 Marc Lehmann <libev@schmorp.de>.
2167