ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
Revision: 1.86
Committed: Tue Dec 18 01:20:33 2007 UTC (16 years, 5 months ago) by root
Branch: MAIN
Changes since 1.85: +3 -1 lines
Log Message:
*** empty log message ***

File Contents

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