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