ViewVC Help
View File | Revision Log | Show Annotations | Download File
Revision: 1.136
Committed: Thu Mar 13 13:06:16 2008 UTC (16 years, 4 months ago) by root
Branch: MAIN
CVS Tags: rel-3_1
Changes since 1.135: +35 -0 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 =head1 NAME
3 libev - a high performance full-featured event loop written in C
5 =head1 SYNOPSIS
7 #include <ev.h>
11 // a single header file is required
12 #include <ev.h>
14 // every watcher type has its own typedef'd struct
15 // with the name ev_<type>
16 ev_io stdin_watcher;
17 ev_timer timeout_watcher;
19 // all watcher callbacks have a similar signature
20 // this callback is called when data is readable on stdin
21 static void
22 stdin_cb (EV_P_ struct ev_io *w, int revents)
23 {
24 puts ("stdin ready");
25 // for one-shot events, one must manually stop the watcher
26 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w);
29 // this causes all nested ev_loop's to stop iterating
30 ev_unloop (EV_A_ EVUNLOOP_ALL);
31 }
33 // another callback, this time for a time-out
34 static void
35 timeout_cb (EV_P_ struct ev_timer *w, int revents)
36 {
37 puts ("timeout");
38 // this causes the innermost ev_loop to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE);
40 }
42 int
43 main (void)
44 {
45 // use the default event loop unless you have special needs
46 struct ev_loop *loop = ev_default_loop (0);
48 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable
50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
51 ev_io_start (loop, &stdin_watcher);
53 // initialise a timer watcher, then start it
54 // simple non-repeating 5.5 second timeout
55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
56 ev_timer_start (loop, &timeout_watcher);
58 // now wait for events to arrive
59 ev_loop (loop, 0);
61 // unloop was called, so exit
62 return 0;
63 }
67 The newest version of this document is also available as an html-formatted
68 web page you might find easier to navigate when reading it for the first
69 time: L<>.
71 Libev is an event loop: you register interest in certain events (such as a
72 file descriptor being readable or a timeout occurring), and it will manage
73 these event sources and provide your program with events.
75 To do this, it must take more or less complete control over your process
76 (or thread) by executing the I<event loop> handler, and will then
77 communicate events via a callback mechanism.
79 You register interest in certain events by registering so-called I<event
80 watchers>, which are relatively small C structures you initialise with the
81 details of the event, and then hand it over to libev by I<starting> the
82 watcher.
84 =head2 FEATURES
86 Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
87 BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
88 for file descriptor events (C<ev_io>), the Linux C<inotify> interface
89 (for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
90 with customised rescheduling (C<ev_periodic>), synchronous signals
91 (C<ev_signal>), process status change events (C<ev_child>), and event
92 watchers dealing with the event loop mechanism itself (C<ev_idle>,
93 C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as
94 file watchers (C<ev_stat>) and even limited support for fork events
95 (C<ev_fork>).
97 It also is quite fast (see this
98 L<benchmark|> comparing it to libevent
99 for example).
101 =head2 CONVENTIONS
103 Libev is very configurable. In this manual the default (and most common)
104 configuration will be described, which supports multiple event loops. For
105 more info about various configuration options please have a look at
106 B<EMBED> section in this manual. If libev was configured without support
107 for multiple event loops, then all functions taking an initial argument of
108 name C<loop> (which is always of type C<struct ev_loop *>) will not have
109 this argument.
113 Libev represents time as a single floating point number, representing the
114 (fractional) number of seconds since the (POSIX) epoch (somewhere near
115 the beginning of 1970, details are complicated, don't ask). This type is
116 called C<ev_tstamp>, which is what you should use too. It usually aliases
117 to the C<double> type in C, and when you need to do any calculations on
118 it, you should treat it as some floatingpoint value. Unlike the name
119 component C<stamp> might indicate, it is also used for time differences
120 throughout libev.
124 These functions can be called anytime, even before initialising the
125 library in any way.
127 =over 4
129 =item ev_tstamp ev_time ()
131 Returns the current time as libev would use it. Please note that the
132 C<ev_now> function is usually faster and also often returns the timestamp
133 you actually want to know.
135 =item ev_sleep (ev_tstamp interval)
137 Sleep for the given interval: The current thread will be blocked until
138 either it is interrupted or the given time interval has passed. Basically
139 this is a subsecond-resolution C<sleep ()>.
141 =item int ev_version_major ()
143 =item int ev_version_minor ()
145 You can find out the major and minor ABI version numbers of the library
146 you linked against by calling the functions C<ev_version_major> and
147 C<ev_version_minor>. If you want, you can compare against the global
148 symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
149 version of the library your program was compiled against.
151 These version numbers refer to the ABI version of the library, not the
152 release version.
154 Usually, it's a good idea to terminate if the major versions mismatch,
155 as this indicates an incompatible change. Minor versions are usually
156 compatible to older versions, so a larger minor version alone is usually
157 not a problem.
159 Example: Make sure we haven't accidentally been linked against the wrong
160 version.
162 assert (("libev version mismatch",
163 ev_version_major () == EV_VERSION_MAJOR
164 && ev_version_minor () >= EV_VERSION_MINOR));
166 =item unsigned int ev_supported_backends ()
168 Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
169 value) compiled into this binary of libev (independent of their
170 availability on the system you are running on). See C<ev_default_loop> for
171 a description of the set values.
173 Example: make sure we have the epoll method, because yeah this is cool and
174 a must have and can we have a torrent of it please!!!11
176 assert (("sorry, no epoll, no sex",
177 ev_supported_backends () & EVBACKEND_EPOLL));
179 =item unsigned int ev_recommended_backends ()
181 Return the set of all backends compiled into this binary of libev and also
182 recommended for this platform. This set is often smaller than the one
183 returned by C<ev_supported_backends>, as for example kqueue is broken on
184 most BSDs and will not be autodetected unless you explicitly request it
185 (assuming you know what you are doing). This is the set of backends that
186 libev will probe for if you specify no backends explicitly.
188 =item unsigned int ev_embeddable_backends ()
190 Returns the set of backends that are embeddable in other event loops. This
191 is the theoretical, all-platform, value. To find which backends
192 might be supported on the current system, you would need to look at
193 C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
194 recommended ones.
196 See the description of C<ev_embed> watchers for more info.
198 =item ev_set_allocator (void *(*cb)(void *ptr, long size))
200 Sets the allocation function to use (the prototype is similar - the
201 semantics is identical - to the realloc C function). It is used to
202 allocate and free memory (no surprises here). If it returns zero when
203 memory needs to be allocated, the library might abort or take some
204 potentially destructive action. The default is your system realloc
205 function.
207 You could override this function in high-availability programs to, say,
208 free some memory if it cannot allocate memory, to use a special allocator,
209 or even to sleep a while and retry until some memory is available.
211 Example: Replace the libev allocator with one that waits a bit and then
212 retries).
214 static void *
215 persistent_realloc (void *ptr, size_t size)
216 {
217 for (;;)
218 {
219 void *newptr = realloc (ptr, size);
221 if (newptr)
222 return newptr;
224 sleep (60);
225 }
226 }
228 ...
229 ev_set_allocator (persistent_realloc);
231 =item ev_set_syserr_cb (void (*cb)(const char *msg));
233 Set the callback function to call on a retryable syscall error (such
234 as failed select, poll, epoll_wait). The message is a printable string
235 indicating the system call or subsystem causing the problem. If this
236 callback is set, then libev will expect it to remedy the sitution, no
237 matter what, when it returns. That is, libev will generally retry the
238 requested operation, or, if the condition doesn't go away, do bad stuff
239 (such as abort).
241 Example: This is basically the same thing that libev does internally, too.
243 static void
244 fatal_error (const char *msg)
245 {
246 perror (msg);
247 abort ();
248 }
250 ...
251 ev_set_syserr_cb (fatal_error);
253 =back
257 An event loop is described by a C<struct ev_loop *>. The library knows two
258 types of such loops, the I<default> loop, which supports signals and child
259 events, and dynamically created loops which do not.
261 If you use threads, a common model is to run the default event loop
262 in your main thread (or in a separate thread) and for each thread you
263 create, you also create another event loop. Libev itself does no locking
264 whatsoever, so if you mix calls to the same event loop in different
265 threads, make sure you lock (this is usually a bad idea, though, even if
266 done correctly, because it's hideous and inefficient).
268 =over 4
270 =item struct ev_loop *ev_default_loop (unsigned int flags)
272 This will initialise the default event loop if it hasn't been initialised
273 yet and return it. If the default loop could not be initialised, returns
274 false. If it already was initialised it simply returns it (and ignores the
275 flags. If that is troubling you, check C<ev_backend ()> afterwards).
277 If you don't know what event loop to use, use the one returned from this
278 function.
280 The default loop is the only loop that can handle C<ev_signal> and
281 C<ev_child> watchers, and to do this, it always registers a handler
282 for C<SIGCHLD>. If this is a problem for your app you can either
283 create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
284 can simply overwrite the C<SIGCHLD> signal handler I<after> calling
285 C<ev_default_init>.
287 The flags argument can be used to specify special behaviour or specific
288 backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
290 The following flags are supported:
292 =over 4
294 =item C<EVFLAG_AUTO>
296 The default flags value. Use this if you have no clue (it's the right
297 thing, believe me).
299 =item C<EVFLAG_NOENV>
301 If this flag bit is ored into the flag value (or the program runs setuid
302 or setgid) then libev will I<not> look at the environment variable
303 C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
304 override the flags completely if it is found in the environment. This is
305 useful to try out specific backends to test their performance, or to work
306 around bugs.
310 Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after
311 a fork, you can also make libev check for a fork in each iteration by
312 enabling this flag.
314 This works by calling C<getpid ()> on every iteration of the loop,
315 and thus this might slow down your event loop if you do a lot of loop
316 iterations and little real work, but is usually not noticeable (on my
317 GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
318 without a syscall and thus I<very> fast, but my GNU/Linux system also has
319 C<pthread_atfork> which is even faster).
321 The big advantage of this flag is that you can forget about fork (and
322 forget about forgetting to tell libev about forking) when you use this
323 flag.
325 This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS>
326 environment variable.
328 =item C<EVBACKEND_SELECT> (value 1, portable select backend)
330 This is your standard select(2) backend. Not I<completely> standard, as
331 libev tries to roll its own fd_set with no limits on the number of fds,
332 but if that fails, expect a fairly low limit on the number of fds when
333 using this backend. It doesn't scale too well (O(highest_fd)), but its
334 usually the fastest backend for a low number of (low-numbered :) fds.
336 To get good performance out of this backend you need a high amount of
337 parallelity (most of the file descriptors should be busy). If you are
338 writing a server, you should C<accept ()> in a loop to accept as many
339 connections as possible during one iteration. You might also want to have
340 a look at C<ev_set_io_collect_interval ()> to increase the amount of
341 readyness notifications you get per iteration.
343 =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
345 And this is your standard poll(2) backend. It's more complicated
346 than select, but handles sparse fds better and has no artificial
347 limit on the number of fds you can use (except it will slow down
348 considerably with a lot of inactive fds). It scales similarly to select,
349 i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
350 performance tips.
352 =item C<EVBACKEND_EPOLL> (value 4, Linux)
354 For few fds, this backend is a bit little slower than poll and select,
355 but it scales phenomenally better. While poll and select usually scale
356 like O(total_fds) where n is the total number of fds (or the highest fd),
357 epoll scales either O(1) or O(active_fds). The epoll design has a number
358 of shortcomings, such as silently dropping events in some hard-to-detect
359 cases and rewiring a syscall per fd change, no fork support and bad
360 support for dup.
362 While stopping, setting and starting an I/O watcher in the same iteration
363 will result in some caching, there is still a syscall per such incident
364 (because the fd could point to a different file description now), so its
365 best to avoid that. Also, C<dup ()>'ed file descriptors might not work
366 very well if you register events for both fds.
368 Please note that epoll sometimes generates spurious notifications, so you
369 need to use non-blocking I/O or other means to avoid blocking when no data
370 (or space) is available.
372 Best performance from this backend is achieved by not unregistering all
373 watchers for a file descriptor until it has been closed, if possible, i.e.
374 keep at least one watcher active per fd at all times.
376 While nominally embeddeble in other event loops, this feature is broken in
377 all kernel versions tested so far.
379 =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
381 Kqueue deserves special mention, as at the time of this writing, it
382 was broken on all BSDs except NetBSD (usually it doesn't work reliably
383 with anything but sockets and pipes, except on Darwin, where of course
384 it's completely useless). For this reason it's not being "autodetected"
385 unless you explicitly specify it explicitly in the flags (i.e. using
386 C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
387 system like NetBSD.
389 You still can embed kqueue into a normal poll or select backend and use it
390 only for sockets (after having made sure that sockets work with kqueue on
391 the target platform). See C<ev_embed> watchers for more info.
393 It scales in the same way as the epoll backend, but the interface to the
394 kernel is more efficient (which says nothing about its actual speed, of
395 course). While stopping, setting and starting an I/O watcher does never
396 cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
397 two event changes per incident, support for C<fork ()> is very bad and it
398 drops fds silently in similarly hard-to-detect cases.
400 This backend usually performs well under most conditions.
402 While nominally embeddable in other event loops, this doesn't work
403 everywhere, so you might need to test for this. And since it is broken
404 almost everywhere, you should only use it when you have a lot of sockets
405 (for which it usually works), by embedding it into another event loop
406 (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
407 sockets.
409 =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
411 This is not implemented yet (and might never be, unless you send me an
412 implementation). According to reports, C</dev/poll> only supports sockets
413 and is not embeddable, which would limit the usefulness of this backend
414 immensely.
416 =item C<EVBACKEND_PORT> (value 32, Solaris 10)
418 This uses the Solaris 10 event port mechanism. As with everything on Solaris,
419 it's really slow, but it still scales very well (O(active_fds)).
421 Please note that solaris event ports can deliver a lot of spurious
422 notifications, so you need to use non-blocking I/O or other means to avoid
423 blocking when no data (or space) is available.
425 While this backend scales well, it requires one system call per active
426 file descriptor per loop iteration. For small and medium numbers of file
427 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
428 might perform better.
430 On the positive side, ignoring the spurious readyness notifications, this
431 backend actually performed to specification in all tests and is fully
432 embeddable, which is a rare feat among the OS-specific backends.
434 =item C<EVBACKEND_ALL>
436 Try all backends (even potentially broken ones that wouldn't be tried
437 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
440 It is definitely not recommended to use this flag.
442 =back
444 If one or more of these are ored into the flags value, then only these
445 backends will be tried (in the reverse order as listed here). If none are
446 specified, all backends in C<ev_recommended_backends ()> will be tried.
448 The most typical usage is like this:
450 if (!ev_default_loop (0))
451 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
453 Restrict libev to the select and poll backends, and do not allow
454 environment settings to be taken into account:
458 Use whatever libev has to offer, but make sure that kqueue is used if
459 available (warning, breaks stuff, best use only with your own private
460 event loop and only if you know the OS supports your types of fds):
462 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
464 =item struct ev_loop *ev_loop_new (unsigned int flags)
466 Similar to C<ev_default_loop>, but always creates a new event loop that is
467 always distinct from the default loop. Unlike the default loop, it cannot
468 handle signal and child watchers, and attempts to do so will be greeted by
469 undefined behaviour (or a failed assertion if assertions are enabled).
471 Example: Try to create a event loop that uses epoll and nothing else.
473 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
474 if (!epoller)
475 fatal ("no epoll found here, maybe it hides under your chair");
477 =item ev_default_destroy ()
479 Destroys the default loop again (frees all memory and kernel state
480 etc.). None of the active event watchers will be stopped in the normal
481 sense, so e.g. C<ev_is_active> might still return true. It is your
482 responsibility to either stop all watchers cleanly yoursef I<before>
483 calling this function, or cope with the fact afterwards (which is usually
484 the easiest thing, you can just ignore the watchers and/or C<free ()> them
485 for example).
487 Note that certain global state, such as signal state, will not be freed by
488 this function, and related watchers (such as signal and child watchers)
489 would need to be stopped manually.
491 In general it is not advisable to call this function except in the
492 rare occasion where you really need to free e.g. the signal handling
493 pipe fds. If you need dynamically allocated loops it is better to use
494 C<ev_loop_new> and C<ev_loop_destroy>).
496 =item ev_loop_destroy (loop)
498 Like C<ev_default_destroy>, but destroys an event loop created by an
499 earlier call to C<ev_loop_new>.
501 =item ev_default_fork ()
503 This function sets a flag that causes subsequent C<ev_loop> iterations
504 to reinitialise the kernel state for backends that have one. Despite the
505 name, you can call it anytime, but it makes most sense after forking, in
506 the child process (or both child and parent, but that again makes little
507 sense). You I<must> call it in the child before using any of the libev
508 functions, and it will only take effect at the next C<ev_loop> iteration.
510 On the other hand, you only need to call this function in the child
511 process if and only if you want to use the event library in the child. If
512 you just fork+exec, you don't have to call it at all.
514 The function itself is quite fast and it's usually not a problem to call
515 it just in case after a fork. To make this easy, the function will fit in
516 quite nicely into a call to C<pthread_atfork>:
518 pthread_atfork (0, 0, ev_default_fork);
520 =item ev_loop_fork (loop)
522 Like C<ev_default_fork>, but acts on an event loop created by
523 C<ev_loop_new>. Yes, you have to call this on every allocated event loop
524 after fork, and how you do this is entirely your own problem.
526 =item int ev_is_default_loop (loop)
528 Returns true when the given loop actually is the default loop, false otherwise.
530 =item unsigned int ev_loop_count (loop)
532 Returns the count of loop iterations for the loop, which is identical to
533 the number of times libev did poll for new events. It starts at C<0> and
534 happily wraps around with enough iterations.
536 This value can sometimes be useful as a generation counter of sorts (it
537 "ticks" the number of loop iterations), as it roughly corresponds with
538 C<ev_prepare> and C<ev_check> calls.
540 =item unsigned int ev_backend (loop)
542 Returns one of the C<EVBACKEND_*> flags indicating the event backend in
543 use.
545 =item ev_tstamp ev_now (loop)
547 Returns the current "event loop time", which is the time the event loop
548 received events and started processing them. This timestamp does not
549 change as long as callbacks are being processed, and this is also the base
550 time used for relative timers. You can treat it as the timestamp of the
551 event occurring (or more correctly, libev finding out about it).
553 =item ev_loop (loop, int flags)
555 Finally, this is it, the event handler. This function usually is called
556 after you initialised all your watchers and you want to start handling
557 events.
559 If the flags argument is specified as C<0>, it will not return until
560 either no event watchers are active anymore or C<ev_unloop> was called.
562 Please note that an explicit C<ev_unloop> is usually better than
563 relying on all watchers to be stopped when deciding when a program has
564 finished (especially in interactive programs), but having a program that
565 automatically loops as long as it has to and no longer by virtue of
566 relying on its watchers stopping correctly is a thing of beauty.
568 A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
569 those events and any outstanding ones, but will not block your process in
570 case there are no events and will return after one iteration of the loop.
572 A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
573 neccessary) and will handle those and any outstanding ones. It will block
574 your process until at least one new event arrives, and will return after
575 one iteration of the loop. This is useful if you are waiting for some
576 external event in conjunction with something not expressible using other
577 libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
578 usually a better approach for this kind of thing.
580 Here are the gory details of what C<ev_loop> does:
582 - Before the first iteration, call any pending watchers.
583 * If EVFLAG_FORKCHECK was used, check for a fork.
584 - If a fork was detected, queue and call all fork watchers.
585 - Queue and call all prepare watchers.
586 - If we have been forked, recreate the kernel state.
587 - Update the kernel state with all outstanding changes.
588 - Update the "event loop time".
589 - Calculate for how long to sleep or block, if at all
590 (active idle watchers, EVLOOP_NONBLOCK or not having
591 any active watchers at all will result in not sleeping).
592 - Sleep if the I/O and timer collect interval say so.
593 - Block the process, waiting for any events.
594 - Queue all outstanding I/O (fd) events.
595 - Update the "event loop time" and do time jump handling.
596 - Queue all outstanding timers.
597 - Queue all outstanding periodics.
598 - If no events are pending now, queue all idle watchers.
599 - Queue all check watchers.
600 - Call all queued watchers in reverse order (i.e. check watchers first).
601 Signals and child watchers are implemented as I/O watchers, and will
602 be handled here by queueing them when their watcher gets executed.
603 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
604 were used, or there are no active watchers, return, otherwise
605 continue with step *.
607 Example: Queue some jobs and then loop until no events are outstanding
608 anymore.
610 ... queue jobs here, make sure they register event watchers as long
611 ... as they still have work to do (even an idle watcher will do..)
612 ev_loop (my_loop, 0);
613 ... jobs done. yeah!
615 =item ev_unloop (loop, how)
617 Can be used to make a call to C<ev_loop> return early (but only after it
618 has processed all outstanding events). The C<how> argument must be either
619 C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
620 C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
622 This "unloop state" will be cleared when entering C<ev_loop> again.
624 =item ev_ref (loop)
626 =item ev_unref (loop)
628 Ref/unref can be used to add or remove a reference count on the event
629 loop: Every watcher keeps one reference, and as long as the reference
630 count is nonzero, C<ev_loop> will not return on its own. If you have
631 a watcher you never unregister that should not keep C<ev_loop> from
632 returning, ev_unref() after starting, and ev_ref() before stopping it. For
633 example, libev itself uses this for its internal signal pipe: It is not
634 visible to the libev user and should not keep C<ev_loop> from exiting if
635 no event watchers registered by it are active. It is also an excellent
636 way to do this for generic recurring timers or from within third-party
637 libraries. Just remember to I<unref after start> and I<ref before stop>
638 (but only if the watcher wasn't active before, or was active before,
639 respectively).
641 Example: Create a signal watcher, but keep it from keeping C<ev_loop>
642 running when nothing else is active.
644 struct ev_signal exitsig;
645 ev_signal_init (&exitsig, sig_cb, SIGINT);
646 ev_signal_start (loop, &exitsig);
647 evf_unref (loop);
649 Example: For some weird reason, unregister the above signal handler again.
651 ev_ref (loop);
652 ev_signal_stop (loop, &exitsig);
654 =item ev_set_io_collect_interval (loop, ev_tstamp interval)
656 =item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
658 These advanced functions influence the time that libev will spend waiting
659 for events. Both are by default C<0>, meaning that libev will try to
660 invoke timer/periodic callbacks and I/O callbacks with minimum latency.
662 Setting these to a higher value (the C<interval> I<must> be >= C<0>)
663 allows libev to delay invocation of I/O and timer/periodic callbacks to
664 increase efficiency of loop iterations.
666 The background is that sometimes your program runs just fast enough to
667 handle one (or very few) event(s) per loop iteration. While this makes
668 the program responsive, it also wastes a lot of CPU time to poll for new
669 events, especially with backends like C<select ()> which have a high
670 overhead for the actual polling but can deliver many events at once.
672 By setting a higher I<io collect interval> you allow libev to spend more
673 time collecting I/O events, so you can handle more events per iteration,
674 at the cost of increasing latency. Timeouts (both C<ev_periodic> and
675 C<ev_timer>) will be not affected. Setting this to a non-null value will
676 introduce an additional C<ev_sleep ()> call into most loop iterations.
678 Likewise, by setting a higher I<timeout collect interval> you allow libev
679 to spend more time collecting timeouts, at the expense of increased
680 latency (the watcher callback will be called later). C<ev_io> watchers
681 will not be affected. Setting this to a non-null value will not introduce
682 any overhead in libev.
684 Many (busy) programs can usually benefit by setting the io collect
685 interval to a value near C<0.1> or so, which is often enough for
686 interactive servers (of course not for games), likewise for timeouts. It
687 usually doesn't make much sense to set it to a lower value than C<0.01>,
688 as this approsaches the timing granularity of most systems.
690 =back
695 A watcher is a structure that you create and register to record your
696 interest in some event. For instance, if you want to wait for STDIN to
697 become readable, you would create an C<ev_io> watcher for that:
699 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
700 {
701 ev_io_stop (w);
702 ev_unloop (loop, EVUNLOOP_ALL);
703 }
705 struct ev_loop *loop = ev_default_loop (0);
706 struct ev_io stdin_watcher;
707 ev_init (&stdin_watcher, my_cb);
708 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
709 ev_io_start (loop, &stdin_watcher);
710 ev_loop (loop, 0);
712 As you can see, you are responsible for allocating the memory for your
713 watcher structures (and it is usually a bad idea to do this on the stack,
714 although this can sometimes be quite valid).
716 Each watcher structure must be initialised by a call to C<ev_init
717 (watcher *, callback)>, which expects a callback to be provided. This
718 callback gets invoked each time the event occurs (or, in the case of io
719 watchers, each time the event loop detects that the file descriptor given
720 is readable and/or writable).
722 Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
723 with arguments specific to this watcher type. There is also a macro
724 to combine initialisation and setting in one call: C<< ev_<type>_init
725 (watcher *, callback, ...) >>.
727 To make the watcher actually watch out for events, you have to start it
728 with a watcher-specific start function (C<< ev_<type>_start (loop, watcher
729 *) >>), and you can stop watching for events at any time by calling the
730 corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
732 As long as your watcher is active (has been started but not stopped) you
733 must not touch the values stored in it. Most specifically you must never
734 reinitialise it or call its C<set> macro.
736 Each and every callback receives the event loop pointer as first, the
737 registered watcher structure as second, and a bitset of received events as
738 third argument.
740 The received events usually include a single bit per event type received
741 (you can receive multiple events at the same time). The possible bit masks
742 are:
744 =over 4
746 =item C<EV_READ>
748 =item C<EV_WRITE>
750 The file descriptor in the C<ev_io> watcher has become readable and/or
751 writable.
753 =item C<EV_TIMEOUT>
755 The C<ev_timer> watcher has timed out.
757 =item C<EV_PERIODIC>
759 The C<ev_periodic> watcher has timed out.
761 =item C<EV_SIGNAL>
763 The signal specified in the C<ev_signal> watcher has been received by a thread.
765 =item C<EV_CHILD>
767 The pid specified in the C<ev_child> watcher has received a status change.
769 =item C<EV_STAT>
771 The path specified in the C<ev_stat> watcher changed its attributes somehow.
773 =item C<EV_IDLE>
775 The C<ev_idle> watcher has determined that you have nothing better to do.
777 =item C<EV_PREPARE>
779 =item C<EV_CHECK>
781 All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
782 to gather new events, and all C<ev_check> watchers are invoked just after
783 C<ev_loop> has gathered them, but before it invokes any callbacks for any
784 received events. Callbacks of both watcher types can start and stop as
785 many watchers as they want, and all of them will be taken into account
786 (for example, a C<ev_prepare> watcher might start an idle watcher to keep
787 C<ev_loop> from blocking).
789 =item C<EV_EMBED>
791 The embedded event loop specified in the C<ev_embed> watcher needs attention.
793 =item C<EV_FORK>
795 The event loop has been resumed in the child process after fork (see
796 C<ev_fork>).
798 =item C<EV_ASYNC>
800 The given async watcher has been asynchronously notified (see C<ev_async>).
802 =item C<EV_ERROR>
804 An unspecified error has occured, the watcher has been stopped. This might
805 happen because the watcher could not be properly started because libev
806 ran out of memory, a file descriptor was found to be closed or any other
807 problem. You best act on it by reporting the problem and somehow coping
808 with the watcher being stopped.
810 Libev will usually signal a few "dummy" events together with an error,
811 for example it might indicate that a fd is readable or writable, and if
812 your callbacks is well-written it can just attempt the operation and cope
813 with the error from read() or write(). This will not work in multithreaded
814 programs, though, so beware.
816 =back
820 In the following description, C<TYPE> stands for the watcher type,
821 e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
823 =over 4
825 =item C<ev_init> (ev_TYPE *watcher, callback)
827 This macro initialises the generic portion of a watcher. The contents
828 of the watcher object can be arbitrary (so C<malloc> will do). Only
829 the generic parts of the watcher are initialised, you I<need> to call
830 the type-specific C<ev_TYPE_set> macro afterwards to initialise the
831 type-specific parts. For each type there is also a C<ev_TYPE_init> macro
832 which rolls both calls into one.
834 You can reinitialise a watcher at any time as long as it has been stopped
835 (or never started) and there are no pending events outstanding.
837 The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher,
838 int revents)>.
840 =item C<ev_TYPE_set> (ev_TYPE *, [args])
842 This macro initialises the type-specific parts of a watcher. You need to
843 call C<ev_init> at least once before you call this macro, but you can
844 call C<ev_TYPE_set> any number of times. You must not, however, call this
845 macro on a watcher that is active (it can be pending, however, which is a
846 difference to the C<ev_init> macro).
848 Although some watcher types do not have type-specific arguments
849 (e.g. C<ev_prepare>) you still need to call its C<set> macro.
851 =item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
853 This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
854 calls into a single call. This is the most convinient method to initialise
855 a watcher. The same limitations apply, of course.
857 =item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
859 Starts (activates) the given watcher. Only active watchers will receive
860 events. If the watcher is already active nothing will happen.
862 =item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
864 Stops the given watcher again (if active) and clears the pending
865 status. It is possible that stopped watchers are pending (for example,
866 non-repeating timers are being stopped when they become pending), but
867 C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If
868 you want to free or reuse the memory used by the watcher it is therefore a
869 good idea to always call its C<ev_TYPE_stop> function.
871 =item bool ev_is_active (ev_TYPE *watcher)
873 Returns a true value iff the watcher is active (i.e. it has been started
874 and not yet been stopped). As long as a watcher is active you must not modify
875 it.
877 =item bool ev_is_pending (ev_TYPE *watcher)
879 Returns a true value iff the watcher is pending, (i.e. it has outstanding
880 events but its callback has not yet been invoked). As long as a watcher
881 is pending (but not active) you must not call an init function on it (but
882 C<ev_TYPE_set> is safe), you must not change its priority, and you must
883 make sure the watcher is available to libev (e.g. you cannot C<free ()>
884 it).
886 =item callback ev_cb (ev_TYPE *watcher)
888 Returns the callback currently set on the watcher.
890 =item ev_cb_set (ev_TYPE *watcher, callback)
892 Change the callback. You can change the callback at virtually any time
893 (modulo threads).
895 =item ev_set_priority (ev_TYPE *watcher, priority)
897 =item int ev_priority (ev_TYPE *watcher)
899 Set and query the priority of the watcher. The priority is a small
900 integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
901 (default: C<-2>). Pending watchers with higher priority will be invoked
902 before watchers with lower priority, but priority will not keep watchers
903 from being executed (except for C<ev_idle> watchers).
905 This means that priorities are I<only> used for ordering callback
906 invocation after new events have been received. This is useful, for
907 example, to reduce latency after idling, or more often, to bind two
908 watchers on the same event and make sure one is called first.
910 If you need to suppress invocation when higher priority events are pending
911 you need to look at C<ev_idle> watchers, which provide this functionality.
913 You I<must not> change the priority of a watcher as long as it is active or
914 pending.
916 The default priority used by watchers when no priority has been set is
917 always C<0>, which is supposed to not be too high and not be too low :).
919 Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
920 fine, as long as you do not mind that the priority value you query might
921 or might not have been adjusted to be within valid range.
923 =item ev_invoke (loop, ev_TYPE *watcher, int revents)
925 Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
926 C<loop> nor C<revents> need to be valid as long as the watcher callback
927 can deal with that fact.
929 =item int ev_clear_pending (loop, ev_TYPE *watcher)
931 If the watcher is pending, this function returns clears its pending status
932 and returns its C<revents> bitset (as if its callback was invoked). If the
933 watcher isn't pending it does nothing and returns C<0>.
935 =back
940 Each watcher has, by default, a member C<void *data> that you can change
941 and read at any time, libev will completely ignore it. This can be used
942 to associate arbitrary data with your watcher. If you need more data and
943 don't want to allocate memory and store a pointer to it in that data
944 member, you can also "subclass" the watcher type and provide your own
945 data:
947 struct my_io
948 {
949 struct ev_io io;
950 int otherfd;
951 void *somedata;
952 struct whatever *mostinteresting;
953 }
955 And since your callback will be called with a pointer to the watcher, you
956 can cast it back to your own type:
958 static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
959 {
960 struct my_io *w = (struct my_io *)w_;
961 ...
962 }
964 More interesting and less C-conformant ways of casting your callback type
965 instead have been omitted.
967 Another common scenario is having some data structure with multiple
968 watchers:
970 struct my_biggy
971 {
972 int some_data;
973 ev_timer t1;
974 ev_timer t2;
975 }
977 In this case getting the pointer to C<my_biggy> is a bit more complicated,
978 you need to use C<offsetof>:
980 #include <stddef.h>
982 static void
983 t1_cb (EV_P_ struct ev_timer *w, int revents)
984 {
985 struct my_biggy big = (struct my_biggy *
986 (((char *)w) - offsetof (struct my_biggy, t1));
987 }
989 static void
990 t2_cb (EV_P_ struct ev_timer *w, int revents)
991 {
992 struct my_biggy big = (struct my_biggy *
993 (((char *)w) - offsetof (struct my_biggy, t2));
994 }
997 =head1 WATCHER TYPES
999 This section describes each watcher in detail, but will not repeat
1000 information given in the last section. Any initialisation/set macros,
1001 functions and members specific to the watcher type are explained.
1003 Members are additionally marked with either I<[read-only]>, meaning that,
1004 while the watcher is active, you can look at the member and expect some
1005 sensible content, but you must not modify it (you can modify it while the
1006 watcher is stopped to your hearts content), or I<[read-write]>, which
1007 means you can expect it to have some sensible content while the watcher
1008 is active, but you can also modify it. Modifying it may not do something
1009 sensible or take immediate effect (or do anything at all), but libev will
1010 not crash or malfunction in any way.
1013 =head2 C<ev_io> - is this file descriptor readable or writable?
1015 I/O watchers check whether a file descriptor is readable or writable
1016 in each iteration of the event loop, or, more precisely, when reading
1017 would not block the process and writing would at least be able to write
1018 some data. This behaviour is called level-triggering because you keep
1019 receiving events as long as the condition persists. Remember you can stop
1020 the watcher if you don't want to act on the event and neither want to
1021 receive future events.
1023 In general you can register as many read and/or write event watchers per
1024 fd as you want (as long as you don't confuse yourself). Setting all file
1025 descriptors to non-blocking mode is also usually a good idea (but not
1026 required if you know what you are doing).
1028 If you must do this, then force the use of a known-to-be-good backend
1029 (at the time of this writing, this includes only C<EVBACKEND_SELECT> and
1032 Another thing you have to watch out for is that it is quite easy to
1033 receive "spurious" readyness notifications, that is your callback might
1034 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1035 because there is no data. Not only are some backends known to create a
1036 lot of those (for example solaris ports), it is very easy to get into
1037 this situation even with a relatively standard program structure. Thus
1038 it is best to always use non-blocking I/O: An extra C<read>(2) returning
1039 C<EAGAIN> is far preferable to a program hanging until some data arrives.
1041 If you cannot run the fd in non-blocking mode (for example you should not
1042 play around with an Xlib connection), then you have to seperately re-test
1043 whether a file descriptor is really ready with a known-to-be good interface
1044 such as poll (fortunately in our Xlib example, Xlib already does this on
1045 its own, so its quite safe to use).
1047 =head3 The special problem of disappearing file descriptors
1049 Some backends (e.g. kqueue, epoll) need to be told about closing a file
1050 descriptor (either by calling C<close> explicitly or by any other means,
1051 such as C<dup>). The reason is that you register interest in some file
1052 descriptor, but when it goes away, the operating system will silently drop
1053 this interest. If another file descriptor with the same number then is
1054 registered with libev, there is no efficient way to see that this is, in
1055 fact, a different file descriptor.
1057 To avoid having to explicitly tell libev about such cases, libev follows
1058 the following policy: Each time C<ev_io_set> is being called, libev
1059 will assume that this is potentially a new file descriptor, otherwise
1060 it is assumed that the file descriptor stays the same. That means that
1061 you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
1062 descriptor even if the file descriptor number itself did not change.
1064 This is how one would do it normally anyway, the important point is that
1065 the libev application should not optimise around libev but should leave
1066 optimisations to libev.
1068 =head3 The special problem of dup'ed file descriptors
1070 Some backends (e.g. epoll), cannot register events for file descriptors,
1071 but only events for the underlying file descriptions. That means when you
1072 have C<dup ()>'ed file descriptors or weirder constellations, and register
1073 events for them, only one file descriptor might actually receive events.
1075 There is no workaround possible except not registering events
1076 for potentially C<dup ()>'ed file descriptors, or to resort to
1079 =head3 The special problem of fork
1081 Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
1082 useless behaviour. Libev fully supports fork, but needs to be told about
1083 it in the child.
1085 To support fork in your programs, you either have to call
1086 C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
1087 enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1091 =head3 Watcher-Specific Functions
1093 =over 4
1095 =item ev_io_init (ev_io *, callback, int fd, int events)
1097 =item ev_io_set (ev_io *, int fd, int events)
1099 Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1100 rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or
1101 C<EV_READ | EV_WRITE> to receive the given events.
1103 =item int fd [read-only]
1105 The file descriptor being watched.
1107 =item int events [read-only]
1109 The events being watched.
1111 =back
1113 =head3 Examples
1115 Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1116 readable, but only once. Since it is likely line-buffered, you could
1117 attempt to read a whole line in the callback.
1119 static void
1120 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1121 {
1122 ev_io_stop (loop, w);
1123 .. read from stdin here (or from w->fd) and haqndle any I/O errors
1124 }
1126 ...
1127 struct ev_loop *loop = ev_default_init (0);
1128 struct ev_io stdin_readable;
1129 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1130 ev_io_start (loop, &stdin_readable);
1131 ev_loop (loop, 0);
1134 =head2 C<ev_timer> - relative and optionally repeating timeouts
1136 Timer watchers are simple relative timers that generate an event after a
1137 given time, and optionally repeating in regular intervals after that.
1139 The timers are based on real time, that is, if you register an event that
1140 times out after an hour and you reset your system clock to last years
1141 time, it will still time out after (roughly) and hour. "Roughly" because
1142 detecting time jumps is hard, and some inaccuracies are unavoidable (the
1143 monotonic clock option helps a lot here).
1145 The relative timeouts are calculated relative to the C<ev_now ()>
1146 time. This is usually the right thing as this timestamp refers to the time
1147 of the event triggering whatever timeout you are modifying/starting. If
1148 you suspect event processing to be delayed and you I<need> to base the timeout
1149 on the current time, use something like this to adjust for this:
1151 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1153 The callback is guarenteed to be invoked only when its timeout has passed,
1154 but if multiple timers become ready during the same loop iteration then
1155 order of execution is undefined.
1157 =head3 Watcher-Specific Functions and Data Members
1159 =over 4
1161 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1163 =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
1165 Configure the timer to trigger after C<after> seconds. If C<repeat> is
1166 C<0.>, then it will automatically be stopped. If it is positive, then the
1167 timer will automatically be configured to trigger again C<repeat> seconds
1168 later, again, and again, until stopped manually.
1170 The timer itself will do a best-effort at avoiding drift, that is, if you
1171 configure a timer to trigger every 10 seconds, then it will trigger at
1172 exactly 10 second intervals. If, however, your program cannot keep up with
1173 the timer (because it takes longer than those 10 seconds to do stuff) the
1174 timer will not fire more than once per event loop iteration.
1176 =item ev_timer_again (loop, ev_timer *)
1178 This will act as if the timer timed out and restart it again if it is
1179 repeating. The exact semantics are:
1181 If the timer is pending, its pending status is cleared.
1183 If the timer is started but nonrepeating, stop it (as if it timed out).
1185 If the timer is repeating, either start it if necessary (with the
1186 C<repeat> value), or reset the running timer to the C<repeat> value.
1188 This sounds a bit complicated, but here is a useful and typical
1189 example: Imagine you have a tcp connection and you want a so-called idle
1190 timeout, that is, you want to be called when there have been, say, 60
1191 seconds of inactivity on the socket. The easiest way to do this is to
1192 configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1193 C<ev_timer_again> each time you successfully read or write some data. If
1194 you go into an idle state where you do not expect data to travel on the
1195 socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
1196 automatically restart it if need be.
1198 That means you can ignore the C<after> value and C<ev_timer_start>
1199 altogether and only ever use the C<repeat> value and C<ev_timer_again>:
1201 ev_timer_init (timer, callback, 0., 5.);
1202 ev_timer_again (loop, timer);
1203 ...
1204 timer->again = 17.;
1205 ev_timer_again (loop, timer);
1206 ...
1207 timer->again = 10.;
1208 ev_timer_again (loop, timer);
1210 This is more slightly efficient then stopping/starting the timer each time
1211 you want to modify its timeout value.
1213 =item ev_tstamp repeat [read-write]
1215 The current C<repeat> value. Will be used each time the watcher times out
1216 or C<ev_timer_again> is called and determines the next timeout (if any),
1217 which is also when any modifications are taken into account.
1219 =back
1221 =head3 Examples
1223 Example: Create a timer that fires after 60 seconds.
1225 static void
1226 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1227 {
1228 .. one minute over, w is actually stopped right here
1229 }
1231 struct ev_timer mytimer;
1232 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1233 ev_timer_start (loop, &mytimer);
1235 Example: Create a timeout timer that times out after 10 seconds of
1236 inactivity.
1238 static void
1239 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1240 {
1241 .. ten seconds without any activity
1242 }
1244 struct ev_timer mytimer;
1245 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1246 ev_timer_again (&mytimer); /* start timer */
1247 ev_loop (loop, 0);
1249 // and in some piece of code that gets executed on any "activity":
1250 // reset the timeout to start ticking again at 10 seconds
1251 ev_timer_again (&mytimer);
1254 =head2 C<ev_periodic> - to cron or not to cron?
1256 Periodic watchers are also timers of a kind, but they are very versatile
1257 (and unfortunately a bit complex).
1259 Unlike C<ev_timer>'s, they are not based on real time (or relative time)
1260 but on wallclock time (absolute time). You can tell a periodic watcher
1261 to trigger "at" some specific point in time. For example, if you tell a
1262 periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
1263 + 10.>) and then reset your system clock to the last year, then it will
1264 take a year to trigger the event (unlike an C<ev_timer>, which would trigger
1265 roughly 10 seconds later).
1267 They can also be used to implement vastly more complex timers, such as
1268 triggering an event on each midnight, local time or other, complicated,
1269 rules.
1271 As with timers, the callback is guarenteed to be invoked only when the
1272 time (C<at>) has been passed, but if multiple periodic timers become ready
1273 during the same loop iteration then order of execution is undefined.
1275 =head3 Watcher-Specific Functions and Data Members
1277 =over 4
1279 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1281 =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1283 Lots of arguments, lets sort it out... There are basically three modes of
1284 operation, and we will explain them from simplest to complex:
1286 =over 4
1288 =item * absolute timer (at = time, interval = reschedule_cb = 0)
1290 In this configuration the watcher triggers an event at the wallclock time
1291 C<at> and doesn't repeat. It will not adjust when a time jump occurs,
1292 that is, if it is to be run at January 1st 2011 then it will run when the
1293 system time reaches or surpasses this time.
1295 =item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1297 In this mode the watcher will always be scheduled to time out at the next
1298 C<at + N * interval> time (for some integer N, which can also be negative)
1299 and then repeat, regardless of any time jumps.
1301 This can be used to create timers that do not drift with respect to system
1302 time:
1304 ev_periodic_set (&periodic, 0., 3600., 0);
1306 This doesn't mean there will always be 3600 seconds in between triggers,
1307 but only that the the callback will be called when the system time shows a
1308 full hour (UTC), or more correctly, when the system time is evenly divisible
1309 by 3600.
1311 Another way to think about it (for the mathematically inclined) is that
1312 C<ev_periodic> will try to run the callback in this mode at the next possible
1313 time where C<time = at (mod interval)>, regardless of any time jumps.
1315 For numerical stability it is preferable that the C<at> value is near
1316 C<ev_now ()> (the current time), but there is no range requirement for
1317 this value.
1319 =item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1321 In this mode the values for C<interval> and C<at> are both being
1322 ignored. Instead, each time the periodic watcher gets scheduled, the
1323 reschedule callback will be called with the watcher as first, and the
1324 current time as second argument.
1326 NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1327 ever, or make any event loop modifications>. If you need to stop it,
1328 return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1329 starting an C<ev_prepare> watcher, which is legal).
1331 Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
1332 ev_tstamp now)>, e.g.:
1334 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1335 {
1336 return now + 60.;
1337 }
1339 It must return the next time to trigger, based on the passed time value
1340 (that is, the lowest time value larger than to the second argument). It
1341 will usually be called just before the callback will be triggered, but
1342 might be called at other times, too.
1344 NOTE: I<< This callback must always return a time that is later than the
1345 passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger.
1347 This can be used to create very complex timers, such as a timer that
1348 triggers on each midnight, local time. To do this, you would calculate the
1349 next midnight after C<now> and return the timestamp value for this. How
1350 you do this is, again, up to you (but it is not trivial, which is the main
1351 reason I omitted it as an example).
1353 =back
1355 =item ev_periodic_again (loop, ev_periodic *)
1357 Simply stops and restarts the periodic watcher again. This is only useful
1358 when you changed some parameters or the reschedule callback would return
1359 a different time than the last time it was called (e.g. in a crond like
1360 program when the crontabs have changed).
1362 =item ev_tstamp offset [read-write]
1364 When repeating, this contains the offset value, otherwise this is the
1365 absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1367 Can be modified any time, but changes only take effect when the periodic
1368 timer fires or C<ev_periodic_again> is being called.
1370 =item ev_tstamp interval [read-write]
1372 The current interval value. Can be modified any time, but changes only
1373 take effect when the periodic timer fires or C<ev_periodic_again> is being
1374 called.
1376 =item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]
1378 The current reschedule callback, or C<0>, if this functionality is
1379 switched off. Can be changed any time, but changes only take effect when
1380 the periodic timer fires or C<ev_periodic_again> is being called.
1382 =item ev_tstamp at [read-only]
1384 When active, contains the absolute time that the watcher is supposed to
1385 trigger next.
1387 =back
1389 =head3 Examples
1391 Example: Call a callback every hour, or, more precisely, whenever the
1392 system clock is divisible by 3600. The callback invocation times have
1393 potentially a lot of jittering, but good long-term stability.
1395 static void
1396 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1397 {
1398 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1399 }
1401 struct ev_periodic hourly_tick;
1402 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1403 ev_periodic_start (loop, &hourly_tick);
1405 Example: The same as above, but use a reschedule callback to do it:
1407 #include <math.h>
1409 static ev_tstamp
1410 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
1411 {
1412 return fmod (now, 3600.) + 3600.;
1413 }
1415 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1417 Example: Call a callback every hour, starting now:
1419 struct ev_periodic hourly_tick;
1420 ev_periodic_init (&hourly_tick, clock_cb,
1421 fmod (ev_now (loop), 3600.), 3600., 0);
1422 ev_periodic_start (loop, &hourly_tick);
1425 =head2 C<ev_signal> - signal me when a signal gets signalled!
1427 Signal watchers will trigger an event when the process receives a specific
1428 signal one or more times. Even though signals are very asynchronous, libev
1429 will try it's best to deliver signals synchronously, i.e. as part of the
1430 normal event processing, like any other event.
1432 You can configure as many watchers as you like per signal. Only when the
1433 first watcher gets started will libev actually register a signal watcher
1434 with the kernel (thus it coexists with your own signal handlers as long
1435 as you don't register any with libev). Similarly, when the last signal
1436 watcher for a signal is stopped libev will reset the signal handler to
1437 SIG_DFL (regardless of what it was set to before).
1439 If possible and supported, libev will install its handlers with
1440 C<SA_RESTART> behaviour enabled, so syscalls should not be unduly
1441 interrupted. If you have a problem with syscalls getting interrupted by
1442 signals you can block all signals in an C<ev_check> watcher and unblock
1443 them in an C<ev_prepare> watcher.
1445 =head3 Watcher-Specific Functions and Data Members
1447 =over 4
1449 =item ev_signal_init (ev_signal *, callback, int signum)
1451 =item ev_signal_set (ev_signal *, int signum)
1453 Configures the watcher to trigger on the given signal number (usually one
1454 of the C<SIGxxx> constants).
1456 =item int signum [read-only]
1458 The signal the watcher watches out for.
1460 =back
1462 =head3 Examples
1464 Example: Try to exit cleanly on SIGINT and SIGTERM.
1466 static void
1467 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1468 {
1469 ev_unloop (loop, EVUNLOOP_ALL);
1470 }
1472 struct ev_signal signal_watcher;
1473 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1474 ev_signal_start (loop, &sigint_cb);
1477 =head2 C<ev_child> - watch out for process status changes
1479 Child watchers trigger when your process receives a SIGCHLD in response to
1480 some child status changes (most typically when a child of yours dies). It
1481 is permissible to install a child watcher I<after> the child has been
1482 forked (which implies it might have already exited), as long as the event
1483 loop isn't entered (or is continued from a watcher).
1485 Only the default event loop is capable of handling signals, and therefore
1486 you can only rgeister child watchers in the default event loop.
1488 =head3 Process Interaction
1490 Libev grabs C<SIGCHLD> as soon as the default event loop is
1491 initialised. This is necessary to guarantee proper behaviour even if
1492 the first child watcher is started after the child exits. The occurance
1493 of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1494 synchronously as part of the event loop processing. Libev always reaps all
1495 children, even ones not watched.
1497 =head3 Overriding the Built-In Processing
1499 Libev offers no special support for overriding the built-in child
1500 processing, but if your application collides with libev's default child
1501 handler, you can override it easily by installing your own handler for
1502 C<SIGCHLD> after initialising the default loop, and making sure the
1503 default loop never gets destroyed. You are encouraged, however, to use an
1504 event-based approach to child reaping and thus use libev's support for
1505 that, so other libev users can use C<ev_child> watchers freely.
1507 =head3 Watcher-Specific Functions and Data Members
1509 =over 4
1511 =item ev_child_init (ev_child *, callback, int pid, int trace)
1513 =item ev_child_set (ev_child *, int pid, int trace)
1515 Configures the watcher to wait for status changes of process C<pid> (or
1516 I<any> process if C<pid> is specified as C<0>). The callback can look
1517 at the C<rstatus> member of the C<ev_child> watcher structure to see
1518 the status word (use the macros from C<sys/wait.h> and see your systems
1519 C<waitpid> documentation). The C<rpid> member contains the pid of the
1520 process causing the status change. C<trace> must be either C<0> (only
1521 activate the watcher when the process terminates) or C<1> (additionally
1522 activate the watcher when the process is stopped or continued).
1524 =item int pid [read-only]
1526 The process id this watcher watches out for, or C<0>, meaning any process id.
1528 =item int rpid [read-write]
1530 The process id that detected a status change.
1532 =item int rstatus [read-write]
1534 The process exit/trace status caused by C<rpid> (see your systems
1535 C<waitpid> and C<sys/wait.h> documentation for details).
1537 =back
1539 =head3 Examples
1541 Example: C<fork()> a new process and install a child handler to wait for
1542 its completion.
1544 ev_child cw;
1546 static void
1547 child_cb (EV_P_ struct ev_child *w, int revents)
1548 {
1549 ev_child_stop (EV_A_ w);
1550 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1551 }
1553 pid_t pid = fork ();
1555 if (pid < 0)
1556 // error
1557 else if (pid == 0)
1558 {
1559 // the forked child executes here
1560 exit (1);
1561 }
1562 else
1563 {
1564 ev_child_init (&cw, child_cb, pid, 0);
1565 ev_child_start (EV_DEFAULT_ &cw);
1566 }
1569 =head2 C<ev_stat> - did the file attributes just change?
1571 This watches a filesystem path for attribute changes. That is, it calls
1572 C<stat> regularly (or when the OS says it changed) and sees if it changed
1573 compared to the last time, invoking the callback if it did.
1575 The path does not need to exist: changing from "path exists" to "path does
1576 not exist" is a status change like any other. The condition "path does
1577 not exist" is signified by the C<st_nlink> field being zero (which is
1578 otherwise always forced to be at least one) and all the other fields of
1579 the stat buffer having unspecified contents.
1581 The path I<should> be absolute and I<must not> end in a slash. If it is
1582 relative and your working directory changes, the behaviour is undefined.
1584 Since there is no standard to do this, the portable implementation simply
1585 calls C<stat (2)> regularly on the path to see if it changed somehow. You
1586 can specify a recommended polling interval for this case. If you specify
1587 a polling interval of C<0> (highly recommended!) then a I<suitable,
1588 unspecified default> value will be used (which you can expect to be around
1589 five seconds, although this might change dynamically). Libev will also
1590 impose a minimum interval which is currently around C<0.1>, but thats
1591 usually overkill.
1593 This watcher type is not meant for massive numbers of stat watchers,
1594 as even with OS-supported change notifications, this can be
1595 resource-intensive.
1597 At the time of this writing, only the Linux inotify interface is
1598 implemented (implementing kqueue support is left as an exercise for the
1599 reader). Inotify will be used to give hints only and should not change the
1600 semantics of C<ev_stat> watchers, which means that libev sometimes needs
1601 to fall back to regular polling again even with inotify, but changes are
1602 usually detected immediately, and if the file exists there will be no
1603 polling.
1605 =head3 Inotify
1607 When C<inotify (7)> support has been compiled into libev (generally only
1608 available on Linux) and present at runtime, it will be used to speed up
1609 change detection where possible. The inotify descriptor will be created lazily
1610 when the first C<ev_stat> watcher is being started.
1612 Inotify presense does not change the semantics of C<ev_stat> watchers
1613 except that changes might be detected earlier, and in some cases, to avoid
1614 making regular C<stat> calls. Even in the presense of inotify support
1615 there are many cases where libev has to resort to regular C<stat> polling.
1617 (There is no support for kqueue, as apparently it cannot be used to
1618 implement this functionality, due to the requirement of having a file
1619 descriptor open on the object at all times).
1621 =head3 The special problem of stat time resolution
1623 The C<stat ()> syscall only supports full-second resolution portably, and
1624 even on systems where the resolution is higher, many filesystems still
1625 only support whole seconds.
1627 That means that, if the time is the only thing that changes, you might
1628 miss updates: on the first update, C<ev_stat> detects a change and calls
1629 your callback, which does something. When there is another update within
1630 the same second, C<ev_stat> will be unable to detect it.
1632 The solution to this is to delay acting on a change for a second (or till
1633 the next second boundary), using a roughly one-second delay C<ev_timer>
1634 (C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01>
1635 is added to work around small timing inconsistencies of some operating
1636 systems.
1638 =head3 Watcher-Specific Functions and Data Members
1640 =over 4
1642 =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1644 =item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)
1646 Configures the watcher to wait for status changes of the given
1647 C<path>. The C<interval> is a hint on how quickly a change is expected to
1648 be detected and should normally be specified as C<0> to let libev choose
1649 a suitable value. The memory pointed to by C<path> must point to the same
1650 path for as long as the watcher is active.
1652 The callback will be receive C<EV_STAT> when a change was detected,
1653 relative to the attributes at the time the watcher was started (or the
1654 last change was detected).
1656 =item ev_stat_stat (loop, ev_stat *)
1658 Updates the stat buffer immediately with new values. If you change the
1659 watched path in your callback, you could call this fucntion to avoid
1660 detecting this change (while introducing a race condition). Can also be
1661 useful simply to find out the new values.
1663 =item ev_statdata attr [read-only]
1665 The most-recently detected attributes of the file. Although the type is of
1666 C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
1667 suitable for your system. If the C<st_nlink> member is C<0>, then there
1668 was some error while C<stat>ing the file.
1670 =item ev_statdata prev [read-only]
1672 The previous attributes of the file. The callback gets invoked whenever
1673 C<prev> != C<attr>.
1675 =item ev_tstamp interval [read-only]
1677 The specified interval.
1679 =item const char *path [read-only]
1681 The filesystem path that is being watched.
1683 =back
1685 =head3 Examples
1687 Example: Watch C</etc/passwd> for attribute changes.
1689 static void
1690 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1691 {
1692 /* /etc/passwd changed in some way */
1693 if (w->attr.st_nlink)
1694 {
1695 printf ("passwd current size %ld\n", (long)w->attr.st_size);
1696 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
1697 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
1698 }
1699 else
1700 /* you shalt not abuse printf for puts */
1701 puts ("wow, /etc/passwd is not there, expect problems. "
1702 "if this is windows, they already arrived\n");
1703 }
1705 ...
1706 ev_stat passwd;
1708 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1709 ev_stat_start (loop, &passwd);
1711 Example: Like above, but additionally use a one-second delay so we do not
1712 miss updates (however, frequent updates will delay processing, too, so
1713 one might do the work both on C<ev_stat> callback invocation I<and> on
1714 C<ev_timer> callback invocation).
1716 static ev_stat passwd;
1717 static ev_timer timer;
1719 static void
1720 timer_cb (EV_P_ ev_timer *w, int revents)
1721 {
1722 ev_timer_stop (EV_A_ w);
1724 /* now it's one second after the most recent passwd change */
1725 }
1727 static void
1728 stat_cb (EV_P_ ev_stat *w, int revents)
1729 {
1730 /* reset the one-second timer */
1731 ev_timer_again (EV_A_ &timer);
1732 }
1734 ...
1735 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1736 ev_stat_start (loop, &passwd);
1737 ev_timer_init (&timer, timer_cb, 0., 1.01);
1740 =head2 C<ev_idle> - when you've got nothing better to do...
1742 Idle watchers trigger events when no other events of the same or higher
1743 priority are pending (prepare, check and other idle watchers do not
1744 count).
1746 That is, as long as your process is busy handling sockets or timeouts
1747 (or even signals, imagine) of the same or higher priority it will not be
1748 triggered. But when your process is idle (or only lower-priority watchers
1749 are pending), the idle watchers are being called once per event loop
1750 iteration - until stopped, that is, or your process receives more events
1751 and becomes busy again with higher priority stuff.
1753 The most noteworthy effect is that as long as any idle watchers are
1754 active, the process will not block when waiting for new events.
1756 Apart from keeping your process non-blocking (which is a useful
1757 effect on its own sometimes), idle watchers are a good place to do
1758 "pseudo-background processing", or delay processing stuff to after the
1759 event loop has handled all outstanding events.
1761 =head3 Watcher-Specific Functions and Data Members
1763 =over 4
1765 =item ev_idle_init (ev_signal *, callback)
1767 Initialises and configures the idle watcher - it has no parameters of any
1768 kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
1769 believe me.
1771 =back
1773 =head3 Examples
1775 Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1776 callback, free it. Also, use no error checking, as usual.
1778 static void
1779 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
1780 {
1781 free (w);
1782 // now do something you wanted to do when the program has
1783 // no longer anything immediate to do.
1784 }
1786 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1787 ev_idle_init (idle_watcher, idle_cb);
1788 ev_idle_start (loop, idle_cb);
1791 =head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1793 Prepare and check watchers are usually (but not always) used in tandem:
1794 prepare watchers get invoked before the process blocks and check watchers
1795 afterwards.
1797 You I<must not> call C<ev_loop> or similar functions that enter
1798 the current event loop from either C<ev_prepare> or C<ev_check>
1799 watchers. Other loops than the current one are fine, however. The
1800 rationale behind this is that you do not need to check for recursion in
1801 those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1802 C<ev_check> so if you have one watcher of each kind they will always be
1803 called in pairs bracketing the blocking call.
1805 Their main purpose is to integrate other event mechanisms into libev and
1806 their use is somewhat advanced. This could be used, for example, to track
1807 variable changes, implement your own watchers, integrate net-snmp or a
1808 coroutine library and lots more. They are also occasionally useful if
1809 you cache some data and want to flush it before blocking (for example,
1810 in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1811 watcher).
1813 This is done by examining in each prepare call which file descriptors need
1814 to be watched by the other library, registering C<ev_io> watchers for
1815 them and starting an C<ev_timer> watcher for any timeouts (many libraries
1816 provide just this functionality). Then, in the check watcher you check for
1817 any events that occured (by checking the pending status of all watchers
1818 and stopping them) and call back into the library. The I/O and timer
1819 callbacks will never actually be called (but must be valid nevertheless,
1820 because you never know, you know?).
1822 As another example, the Perl Coro module uses these hooks to integrate
1823 coroutines into libev programs, by yielding to other active coroutines
1824 during each prepare and only letting the process block if no coroutines
1825 are ready to run (it's actually more complicated: it only runs coroutines
1826 with priority higher than or equal to the event loop and one coroutine
1827 of lower priority, but only once, using idle watchers to keep the event
1828 loop from blocking if lower-priority coroutines are active, thus mapping
1829 low-priority coroutines to idle/background tasks).
1831 It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1832 priority, to ensure that they are being run before any other watchers
1833 after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1834 too) should not activate ("feed") events into libev. While libev fully
1835 supports this, they will be called before other C<ev_check> watchers
1836 did their job. As C<ev_check> watchers are often used to embed other
1837 (non-libev) event loops those other event loops might be in an unusable
1838 state until their C<ev_check> watcher ran (always remind yourself to
1839 coexist peacefully with others).
1841 =head3 Watcher-Specific Functions and Data Members
1843 =over 4
1845 =item ev_prepare_init (ev_prepare *, callback)
1847 =item ev_check_init (ev_check *, callback)
1849 Initialises and configures the prepare or check watcher - they have no
1850 parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1851 macros, but using them is utterly, utterly and completely pointless.
1853 =back
1855 =head3 Examples
1857 There are a number of principal ways to embed other event loops or modules
1858 into libev. Here are some ideas on how to include libadns into libev
1859 (there is a Perl module named C<EV::ADNS> that does this, which you could
1860 use for an actually working example. Another Perl module named C<EV::Glib>
1861 embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV
1862 into the Glib event loop).
1864 Method 1: Add IO watchers and a timeout watcher in a prepare handler,
1865 and in a check watcher, destroy them and call into libadns. What follows
1866 is pseudo-code only of course. This requires you to either use a low
1867 priority for the check watcher or use C<ev_clear_pending> explicitly, as
1868 the callbacks for the IO/timeout watchers might not have been called yet.
1870 static ev_io iow [nfd];
1871 static ev_timer tw;
1873 static void
1874 io_cb (ev_loop *loop, ev_io *w, int revents)
1875 {
1876 }
1878 // create io watchers for each fd and a timer before blocking
1879 static void
1880 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1881 {
1882 int timeout = 3600000;
1883 struct pollfd fds [nfd];
1884 // actual code will need to loop here and realloc etc.
1885 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1887 /* the callback is illegal, but won't be called as we stop during check */
1888 ev_timer_init (&tw, 0, timeout * 1e-3);
1889 ev_timer_start (loop, &tw);
1891 // create one ev_io per pollfd
1892 for (int i = 0; i < nfd; ++i)
1893 {
1894 ev_io_init (iow + i, io_cb, fds [i].fd,
1895 ((fds [i].events & POLLIN ? EV_READ : 0)
1896 | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1898 fds [i].revents = 0;
1899 ev_io_start (loop, iow + i);
1900 }
1901 }
1903 // stop all watchers after blocking
1904 static void
1905 adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1906 {
1907 ev_timer_stop (loop, &tw);
1909 for (int i = 0; i < nfd; ++i)
1910 {
1911 // set the relevant poll flags
1912 // could also call adns_processreadable etc. here
1913 struct pollfd *fd = fds + i;
1914 int revents = ev_clear_pending (iow + i);
1915 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1916 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1918 // now stop the watcher
1919 ev_io_stop (loop, iow + i);
1920 }
1922 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1923 }
1925 Method 2: This would be just like method 1, but you run C<adns_afterpoll>
1926 in the prepare watcher and would dispose of the check watcher.
1928 Method 3: If the module to be embedded supports explicit event
1929 notification (adns does), you can also make use of the actual watcher
1930 callbacks, and only destroy/create the watchers in the prepare watcher.
1932 static void
1933 timer_cb (EV_P_ ev_timer *w, int revents)
1934 {
1935 adns_state ads = (adns_state)w->data;
1936 update_now (EV_A);
1938 adns_processtimeouts (ads, &tv_now);
1939 }
1941 static void
1942 io_cb (EV_P_ ev_io *w, int revents)
1943 {
1944 adns_state ads = (adns_state)w->data;
1945 update_now (EV_A);
1947 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
1948 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
1949 }
1951 // do not ever call adns_afterpoll
1953 Method 4: Do not use a prepare or check watcher because the module you
1954 want to embed is too inflexible to support it. Instead, youc na override
1955 their poll function. The drawback with this solution is that the main
1956 loop is now no longer controllable by EV. The C<Glib::EV> module does
1957 this.
1959 static gint
1960 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
1961 {
1962 int got_events = 0;
1964 for (n = 0; n < nfds; ++n)
1965 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
1967 if (timeout >= 0)
1968 // create/start timer
1970 // poll
1971 ev_loop (EV_A_ 0);
1973 // stop timer again
1974 if (timeout >= 0)
1975 ev_timer_stop (EV_A_ &to);
1977 // stop io watchers again - their callbacks should have set
1978 for (n = 0; n < nfds; ++n)
1979 ev_io_stop (EV_A_ iow [n]);
1981 return got_events;
1982 }
1985 =head2 C<ev_embed> - when one backend isn't enough...
1987 This is a rather advanced watcher type that lets you embed one event loop
1988 into another (currently only C<ev_io> events are supported in the embedded
1989 loop, other types of watchers might be handled in a delayed or incorrect
1990 fashion and must not be used).
1992 There are primarily two reasons you would want that: work around bugs and
1993 prioritise I/O.
1995 As an example for a bug workaround, the kqueue backend might only support
1996 sockets on some platform, so it is unusable as generic backend, but you
1997 still want to make use of it because you have many sockets and it scales
1998 so nicely. In this case, you would create a kqueue-based loop and embed it
1999 into your default loop (which might use e.g. poll). Overall operation will
2000 be a bit slower because first libev has to poll and then call kevent, but
2001 at least you can use both at what they are best.
2003 As for prioritising I/O: rarely you have the case where some fds have
2004 to be watched and handled very quickly (with low latency), and even
2005 priorities and idle watchers might have too much overhead. In this case
2006 you would put all the high priority stuff in one loop and all the rest in
2007 a second one, and embed the second one in the first.
2009 As long as the watcher is active, the callback will be invoked every time
2010 there might be events pending in the embedded loop. The callback must then
2011 call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke
2012 their callbacks (you could also start an idle watcher to give the embedded
2013 loop strictly lower priority for example). You can also set the callback
2014 to C<0>, in which case the embed watcher will automatically execute the
2015 embedded loop sweep.
2017 As long as the watcher is started it will automatically handle events. The
2018 callback will be invoked whenever some events have been handled. You can
2019 set the callback to C<0> to avoid having to specify one if you are not
2020 interested in that.
2022 Also, there have not currently been made special provisions for forking:
2023 when you fork, you not only have to call C<ev_loop_fork> on both loops,
2024 but you will also have to stop and restart any C<ev_embed> watchers
2025 yourself.
2027 Unfortunately, not all backends are embeddable, only the ones returned by
2028 C<ev_embeddable_backends> are, which, unfortunately, does not include any
2029 portable one.
2031 So when you want to use this feature you will always have to be prepared
2032 that you cannot get an embeddable loop. The recommended way to get around
2033 this is to have a separate variables for your embeddable loop, try to
2034 create it, and if that fails, use the normal loop for everything.
2036 =head3 Watcher-Specific Functions and Data Members
2038 =over 4
2040 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
2042 =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
2044 Configures the watcher to embed the given loop, which must be
2045 embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
2046 invoked automatically, otherwise it is the responsibility of the callback
2047 to invoke it (it will continue to be called until the sweep has been done,
2048 if you do not want thta, you need to temporarily stop the embed watcher).
2050 =item ev_embed_sweep (loop, ev_embed *)
2052 Make a single, non-blocking sweep over the embedded loop. This works
2053 similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
2054 apropriate way for embedded loops.
2056 =item struct ev_loop *other [read-only]
2058 The embedded event loop.
2060 =back
2062 =head3 Examples
2064 Example: Try to get an embeddable event loop and embed it into the default
2065 event loop. If that is not possible, use the default loop. The default
2066 loop is stored in C<loop_hi>, while the mebeddable loop is stored in
2067 C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be
2068 used).
2070 struct ev_loop *loop_hi = ev_default_init (0);
2071 struct ev_loop *loop_lo = 0;
2072 struct ev_embed embed;
2074 // see if there is a chance of getting one that works
2075 // (remember that a flags value of 0 means autodetection)
2076 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2077 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2078 : 0;
2080 // if we got one, then embed it, otherwise default to loop_hi
2081 if (loop_lo)
2082 {
2083 ev_embed_init (&embed, 0, loop_lo);
2084 ev_embed_start (loop_hi, &embed);
2085 }
2086 else
2087 loop_lo = loop_hi;
2089 Example: Check if kqueue is available but not recommended and create
2090 a kqueue backend for use with sockets (which usually work with any
2091 kqueue implementation). Store the kqueue/socket-only event loop in
2092 C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2094 struct ev_loop *loop = ev_default_init (0);
2095 struct ev_loop *loop_socket = 0;
2096 struct ev_embed embed;
2098 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2099 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2100 {
2101 ev_embed_init (&embed, 0, loop_socket);
2102 ev_embed_start (loop, &embed);
2103 }
2105 if (!loop_socket)
2106 loop_socket = loop;
2108 // now use loop_socket for all sockets, and loop for everything else
2111 =head2 C<ev_fork> - the audacity to resume the event loop after a fork
2113 Fork watchers are called when a C<fork ()> was detected (usually because
2114 whoever is a good citizen cared to tell libev about it by calling
2115 C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the
2116 event loop blocks next and before C<ev_check> watchers are being called,
2117 and only in the child after the fork. If whoever good citizen calling
2118 C<ev_default_fork> cheats and calls it in the wrong process, the fork
2119 handlers will be invoked, too, of course.
2121 =head3 Watcher-Specific Functions and Data Members
2123 =over 4
2125 =item ev_fork_init (ev_signal *, callback)
2127 Initialises and configures the fork watcher - it has no parameters of any
2128 kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
2129 believe me.
2131 =back
2134 =head2 C<ev_async> - how to wake up another event loop
2136 In general, you cannot use an C<ev_loop> from multiple threads or other
2137 asynchronous sources such as signal handlers (as opposed to multiple event
2138 loops - those are of course safe to use in different threads).
2140 Sometimes, however, you need to wake up another event loop you do not
2141 control, for example because it belongs to another thread. This is what
2142 C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
2143 can signal it by calling C<ev_async_send>, which is thread- and signal
2144 safe.
2146 This functionality is very similar to C<ev_signal> watchers, as signals,
2147 too, are asynchronous in nature, and signals, too, will be compressed
2148 (i.e. the number of callback invocations may be less than the number of
2149 C<ev_async_sent> calls).
2151 Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
2152 just the default loop.
2154 =head3 Queueing
2156 C<ev_async> does not support queueing of data in any way. The reason
2157 is that the author does not know of a simple (or any) algorithm for a
2158 multiple-writer-single-reader queue that works in all cases and doesn't
2159 need elaborate support such as pthreads.
2161 That means that if you want to queue data, you have to provide your own
2162 queue. But at least I can tell you would implement locking around your
2163 queue:
2165 =over 4
2167 =item queueing from a signal handler context
2169 To implement race-free queueing, you simply add to the queue in the signal
2170 handler but you block the signal handler in the watcher callback. Here is an example that does that for
2171 some fictitiuous SIGUSR1 handler:
2173 static ev_async mysig;
2175 static void
2176 sigusr1_handler (void)
2177 {
2178 sometype data;
2180 // no locking etc.
2181 queue_put (data);
2182 ev_async_send (EV_DEFAULT_ &mysig);
2183 }
2185 static void
2186 mysig_cb (EV_P_ ev_async *w, int revents)
2187 {
2188 sometype data;
2189 sigset_t block, prev;
2191 sigemptyset (&block);
2192 sigaddset (&block, SIGUSR1);
2193 sigprocmask (SIG_BLOCK, &block, &prev);
2195 while (queue_get (&data))
2196 process (data);
2198 if (sigismember (&prev, SIGUSR1)
2199 sigprocmask (SIG_UNBLOCK, &block, 0);
2200 }
2202 (Note: pthreads in theory requires you to use C<pthread_setmask>
2203 instead of C<sigprocmask> when you use threads, but libev doesn't do it
2204 either...).
2206 =item queueing from a thread context
2208 The strategy for threads is different, as you cannot (easily) block
2209 threads but you can easily preempt them, so to queue safely you need to
2210 employ a traditional mutex lock, such as in this pthread example:
2212 static ev_async mysig;
2213 static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
2215 static void
2216 otherthread (void)
2217 {
2218 // only need to lock the actual queueing operation
2219 pthread_mutex_lock (&mymutex);
2220 queue_put (data);
2221 pthread_mutex_unlock (&mymutex);
2223 ev_async_send (EV_DEFAULT_ &mysig);
2224 }
2226 static void
2227 mysig_cb (EV_P_ ev_async *w, int revents)
2228 {
2229 pthread_mutex_lock (&mymutex);
2231 while (queue_get (&data))
2232 process (data);
2234 pthread_mutex_unlock (&mymutex);
2235 }
2237 =back
2240 =head3 Watcher-Specific Functions and Data Members
2242 =over 4
2244 =item ev_async_init (ev_async *, callback)
2246 Initialises and configures the async watcher - it has no parameters of any
2247 kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
2248 believe me.
2250 =item ev_async_send (loop, ev_async *)
2252 Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2253 an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2254 C<ev_feed_event>, this call is safe to do in other threads, signal or
2255 similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
2256 section below on what exactly this means).
2258 This call incurs the overhead of a syscall only once per loop iteration,
2259 so while the overhead might be noticable, it doesn't apply to repeated
2260 calls to C<ev_async_send>.
2262 =back
2267 There are some other functions of possible interest. Described. Here. Now.
2269 =over 4
2271 =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
2273 This function combines a simple timer and an I/O watcher, calls your
2274 callback on whichever event happens first and automatically stop both
2275 watchers. This is useful if you want to wait for a single event on an fd
2276 or timeout without having to allocate/configure/start/stop/free one or
2277 more watchers yourself.
2279 If C<fd> is less than 0, then no I/O watcher will be started and events
2280 is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
2281 C<events> set will be craeted and started.
2283 If C<timeout> is less than 0, then no timeout watcher will be
2284 started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2285 repeat = 0) will be started. While C<0> is a valid timeout, it is of
2286 dubious value.
2288 The callback has the type C<void (*cb)(int revents, void *arg)> and gets
2289 passed an C<revents> set like normal event callbacks (a combination of
2290 C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
2291 value passed to C<ev_once>:
2293 static void stdin_ready (int revents, void *arg)
2294 {
2295 if (revents & EV_TIMEOUT)
2296 /* doh, nothing entered */;
2297 else if (revents & EV_READ)
2298 /* stdin might have data for us, joy! */;
2299 }
2301 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2303 =item ev_feed_event (ev_loop *, watcher *, int revents)
2305 Feeds the given event set into the event loop, as if the specified event
2306 had happened for the specified watcher (which must be a pointer to an
2307 initialised but not necessarily started event watcher).
2309 =item ev_feed_fd_event (ev_loop *, int fd, int revents)
2311 Feed an event on the given fd, as if a file descriptor backend detected
2312 the given events it.
2314 =item ev_feed_signal_event (ev_loop *loop, int signum)
2316 Feed an event as if the given signal occured (C<loop> must be the default
2317 loop!).
2319 =back
2324 Libev offers a compatibility emulation layer for libevent. It cannot
2325 emulate the internals of libevent, so here are some usage hints:
2327 =over 4
2329 =item * Use it by including <event.h>, as usual.
2331 =item * The following members are fully supported: ev_base, ev_callback,
2332 ev_arg, ev_fd, ev_res, ev_events.
2334 =item * Avoid using ev_flags and the EVLIST_*-macros, while it is
2335 maintained by libev, it does not work exactly the same way as in libevent (consider
2336 it a private API).
2338 =item * Priorities are not currently supported. Initialising priorities
2339 will fail and all watchers will have the same priority, even though there
2340 is an ev_pri field.
2342 =item * Other members are not supported.
2344 =item * The libev emulation is I<not> ABI compatible to libevent, you need
2345 to use the libev header file and library.
2347 =back
2349 =head1 C++ SUPPORT
2351 Libev comes with some simplistic wrapper classes for C++ that mainly allow
2352 you to use some convinience methods to start/stop watchers and also change
2353 the callback model to a model using method callbacks on objects.
2355 To use it,
2357 #include <ev++.h>
2359 This automatically includes F<ev.h> and puts all of its definitions (many
2360 of them macros) into the global namespace. All C++ specific things are
2361 put into the C<ev> namespace. It should support all the same embedding
2362 options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
2364 Care has been taken to keep the overhead low. The only data member the C++
2365 classes add (compared to plain C-style watchers) is the event loop pointer
2366 that the watcher is associated with (or no additional members at all if
2367 you disable C<EV_MULTIPLICITY> when embedding libev).
2369 Currently, functions, and static and non-static member functions can be
2370 used as callbacks. Other types should be easy to add as long as they only
2371 need one additional pointer for context. If you need support for other
2372 types of functors please contact the author (preferably after implementing
2373 it).
2375 Here is a list of things available in the C<ev> namespace:
2377 =over 4
2379 =item C<ev::READ>, C<ev::WRITE> etc.
2381 These are just enum values with the same values as the C<EV_READ> etc.
2382 macros from F<ev.h>.
2384 =item C<ev::tstamp>, C<ev::now>
2386 Aliases to the same types/functions as with the C<ev_> prefix.
2388 =item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
2390 For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
2391 the same name in the C<ev> namespace, with the exception of C<ev_signal>
2392 which is called C<ev::sig> to avoid clashes with the C<signal> macro
2393 defines by many implementations.
2395 All of those classes have these methods:
2397 =over 4
2399 =item ev::TYPE::TYPE ()
2401 =item ev::TYPE::TYPE (struct ev_loop *)
2403 =item ev::TYPE::~TYPE
2405 The constructor (optionally) takes an event loop to associate the watcher
2406 with. If it is omitted, it will use C<EV_DEFAULT>.
2408 The constructor calls C<ev_init> for you, which means you have to call the
2409 C<set> method before starting it.
2411 It will not set a callback, however: You have to call the templated C<set>
2412 method to set a callback before you can start the watcher.
2414 (The reason why you have to use a method is a limitation in C++ which does
2415 not allow explicit template arguments for constructors).
2417 The destructor automatically stops the watcher if it is active.
2419 =item w->set<class, &class::method> (object *)
2421 This method sets the callback method to call. The method has to have a
2422 signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
2423 first argument and the C<revents> as second. The object must be given as
2424 parameter and is stored in the C<data> member of the watcher.
2426 This method synthesizes efficient thunking code to call your method from
2427 the C callback that libev requires. If your compiler can inline your
2428 callback (i.e. it is visible to it at the place of the C<set> call and
2429 your compiler is good :), then the method will be fully inlined into the
2430 thunking function, making it as fast as a direct C callback.
2432 Example: simple class declaration and watcher initialisation
2434 struct myclass
2435 {
2436 void io_cb (ev::io &w, int revents) { }
2437 }
2439 myclass obj;
2440 ev::io iow;
2441 iow.set <myclass, &myclass::io_cb> (&obj);
2443 =item w->set<function> (void *data = 0)
2445 Also sets a callback, but uses a static method or plain function as
2446 callback. The optional C<data> argument will be stored in the watcher's
2447 C<data> member and is free for you to use.
2449 The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
2451 See the method-C<set> above for more details.
2453 Example:
2455 static void io_cb (ev::io &w, int revents) { }
2456 iow.set <io_cb> ();
2458 =item w->set (struct ev_loop *)
2460 Associates a different C<struct ev_loop> with this watcher. You can only
2461 do this when the watcher is inactive (and not pending either).
2463 =item w->set ([args])
2465 Basically the same as C<ev_TYPE_set>, with the same args. Must be
2466 called at least once. Unlike the C counterpart, an active watcher gets
2467 automatically stopped and restarted when reconfiguring it with this
2468 method.
2470 =item w->start ()
2472 Starts the watcher. Note that there is no C<loop> argument, as the
2473 constructor already stores the event loop.
2475 =item w->stop ()
2477 Stops the watcher if it is active. Again, no C<loop> argument.
2479 =item w->again () (C<ev::timer>, C<ev::periodic> only)
2481 For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
2482 C<ev_TYPE_again> function.
2484 =item w->sweep () (C<ev::embed> only)
2486 Invokes C<ev_embed_sweep>.
2488 =item w->update () (C<ev::stat> only)
2490 Invokes C<ev_stat_stat>.
2492 =back
2494 =back
2496 Example: Define a class with an IO and idle watcher, start one of them in
2497 the constructor.
2499 class myclass
2500 {
2501 ev::io io; void io_cb (ev::io &w, int revents);
2502 ev:idle idle void idle_cb (ev::idle &w, int revents);
2504 myclass (int fd)
2505 {
2506 io .set <myclass, &myclass::io_cb > (this);
2507 idle.set <myclass, &myclass::idle_cb> (this);
2509 io.start (fd, ev::READ);
2510 }
2511 };
2516 Libev does not offer other language bindings itself, but bindings for a
2517 numbe rof languages exist in the form of third-party packages. If you know
2518 any interesting language binding in addition to the ones listed here, drop
2519 me a note.
2521 =over 4
2523 =item Perl
2525 The EV module implements the full libev API and is actually used to test
2526 libev. EV is developed together with libev. Apart from the EV core module,
2527 there are additional modules that implement libev-compatible interfaces
2528 to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the
2529 C<libglib> event core (C<Glib::EV> and C<EV::Glib>).
2531 It can be found and installed via CPAN, its homepage is found at
2532 L<>.
2534 =item Ruby
2536 Tony Arcieri has written a ruby extension that offers access to a subset
2537 of the libev API and adds filehandle abstractions, asynchronous DNS and
2538 more on top of it. It can be found via gem servers. Its homepage is at
2539 L<>.
2541 =item D
2543 Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2544 be found at L<;a=summary>.
2546 =back
2549 =head1 MACRO MAGIC
2551 Libev can be compiled with a variety of options, the most fundamantal
2552 of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2553 functions and callbacks have an initial C<struct ev_loop *> argument.
2555 To make it easier to write programs that cope with either variant, the
2556 following macros are defined:
2558 =over 4
2560 =item C<EV_A>, C<EV_A_>
2562 This provides the loop I<argument> for functions, if one is required ("ev
2563 loop argument"). The C<EV_A> form is used when this is the sole argument,
2564 C<EV_A_> is used when other arguments are following. Example:
2566 ev_unref (EV_A);
2567 ev_timer_add (EV_A_ watcher);
2568 ev_loop (EV_A_ 0);
2570 It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
2571 which is often provided by the following macro.
2573 =item C<EV_P>, C<EV_P_>
2575 This provides the loop I<parameter> for functions, if one is required ("ev
2576 loop parameter"). The C<EV_P> form is used when this is the sole parameter,
2577 C<EV_P_> is used when other parameters are following. Example:
2579 // this is how ev_unref is being declared
2580 static void ev_unref (EV_P);
2582 // this is how you can declare your typical callback
2583 static void cb (EV_P_ ev_timer *w, int revents)
2585 It declares a parameter C<loop> of type C<struct ev_loop *>, quite
2586 suitable for use with C<EV_A>.
2588 =item C<EV_DEFAULT>, C<EV_DEFAULT_>
2590 Similar to the other two macros, this gives you the value of the default
2591 loop, if multiple loops are supported ("ev loop default").
2593 =back
2595 Example: Declare and initialise a check watcher, utilising the above
2596 macros so it will work regardless of whether multiple loops are supported
2597 or not.
2599 static void
2600 check_cb (EV_P_ ev_timer *w, int revents)
2601 {
2602 ev_check_stop (EV_A_ w);
2603 }
2605 ev_check check;
2606 ev_check_init (&check, check_cb);
2607 ev_check_start (EV_DEFAULT_ &check);
2608 ev_loop (EV_DEFAULT_ 0);
2610 =head1 EMBEDDING
2612 Libev can (and often is) directly embedded into host
2613 applications. Examples of applications that embed it include the Deliantra
2614 Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
2615 and rxvt-unicode.
2617 The goal is to enable you to just copy the necessary files into your
2618 source directory without having to change even a single line in them, so
2619 you can easily upgrade by simply copying (or having a checked-out copy of
2620 libev somewhere in your source tree).
2622 =head2 FILESETS
2624 Depending on what features you need you need to include one or more sets of files
2625 in your app.
2627 =head3 CORE EVENT LOOP
2629 To include only the libev core (all the C<ev_*> functions), with manual
2630 configuration (no autoconf):
2632 #define EV_STANDALONE 1
2633 #include "ev.c"
2635 This will automatically include F<ev.h>, too, and should be done in a
2636 single C source file only to provide the function implementations. To use
2637 it, do the same for F<ev.h> in all files wishing to use this API (best
2638 done by writing a wrapper around F<ev.h> that you can include instead and
2639 where you can put other configuration options):
2641 #define EV_STANDALONE 1
2642 #include "ev.h"
2644 Both header files and implementation files can be compiled with a C++
2645 compiler (at least, thats a stated goal, and breakage will be treated
2646 as a bug).
2648 You need the following files in your source tree, or in a directory
2649 in your include path (e.g. in libev/ when using -Ilibev):
2651 ev.h
2652 ev.c
2653 ev_vars.h
2654 ev_wrap.h
2656 ev_win32.c required on win32 platforms only
2658 ev_select.c only when select backend is enabled (which is enabled by default)
2659 ev_poll.c only when poll backend is enabled (disabled by default)
2660 ev_epoll.c only when the epoll backend is enabled (disabled by default)
2661 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
2662 ev_port.c only when the solaris port backend is enabled (disabled by default)
2664 F<ev.c> includes the backend files directly when enabled, so you only need
2665 to compile this single file.
2669 To include the libevent compatibility API, also include:
2671 #include "event.c"
2673 in the file including F<ev.c>, and:
2675 #include "event.h"
2677 in the files that want to use the libevent API. This also includes F<ev.h>.
2679 You need the following additional files for this:
2681 event.h
2682 event.c
2686 Instead of using C<EV_STANDALONE=1> and providing your config in
2687 whatever way you want, you can also C<m4_include([libev.m4])> in your
2688 F<> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
2689 include F<config.h> and configure itself accordingly.
2691 For this of course you need the m4 file:
2693 libev.m4
2697 Libev can be configured via a variety of preprocessor symbols you have to define
2698 before including any of its files. The default is not to build for multiplicity
2699 and only include the select backend.
2701 =over 4
2703 =item EV_STANDALONE
2705 Must always be C<1> if you do not use autoconf configuration, which
2706 keeps libev from including F<config.h>, and it also defines dummy
2707 implementations for some libevent functions (such as logging, which is not
2708 supported). It will also not define any of the structs usually found in
2709 F<event.h> that are not directly supported by the libev core alone.
2713 If defined to be C<1>, libev will try to detect the availability of the
2714 monotonic clock option at both compiletime and runtime. Otherwise no use
2715 of the monotonic clock option will be attempted. If you enable this, you
2716 usually have to link against librt or something similar. Enabling it when
2717 the functionality isn't available is safe, though, although you have
2718 to make sure you link against any libraries where the C<clock_gettime>
2719 function is hiding in (often F<-lrt>).
2721 =item EV_USE_REALTIME
2723 If defined to be C<1>, libev will try to detect the availability of the
2724 realtime clock option at compiletime (and assume its availability at
2725 runtime if successful). Otherwise no use of the realtime clock option will
2726 be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2727 (CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2728 note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2732 If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2733 and will use it for delays. Otherwise it will use C<select ()>.
2735 =item EV_USE_SELECT
2737 If undefined or defined to be C<1>, libev will compile in support for the
2738 C<select>(2) backend. No attempt at autodetection will be done: if no
2739 other method takes over, select will be it. Otherwise the select backend
2740 will not be compiled in.
2744 If defined to C<1>, then the select backend will use the system C<fd_set>
2745 structure. This is useful if libev doesn't compile due to a missing
2746 C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on
2747 exotic systems. This usually limits the range of file descriptors to some
2748 low limit such as 1024 or might have other limitations (winsocket only
2749 allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
2750 influence the size of the C<fd_set> used.
2754 When defined to C<1>, the select backend will assume that
2755 select/socket/connect etc. don't understand file descriptors but
2756 wants osf handles on win32 (this is the case when the select to
2757 be used is the winsock select). This means that it will call
2758 C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
2759 it is assumed that all these functions actually work on fds, even
2760 on win32. Should not be defined on non-win32 platforms.
2762 =item EV_FD_TO_WIN32_HANDLE
2764 If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
2765 file descriptors to socket handles. When not defining this symbol (the
2766 default), then libev will call C<_get_osfhandle>, which is usually
2767 correct. In some cases, programs use their own file descriptor management,
2768 in which case they can provide this function to map fds to socket handles.
2770 =item EV_USE_POLL
2772 If defined to be C<1>, libev will compile in support for the C<poll>(2)
2773 backend. Otherwise it will be enabled on non-win32 platforms. It
2774 takes precedence over select.
2776 =item EV_USE_EPOLL
2778 If defined to be C<1>, libev will compile in support for the Linux
2779 C<epoll>(7) backend. Its availability will be detected at runtime,
2780 otherwise another method will be used as fallback. This is the
2781 preferred backend for GNU/Linux systems.
2783 =item EV_USE_KQUEUE
2785 If defined to be C<1>, libev will compile in support for the BSD style
2786 C<kqueue>(2) backend. Its actual availability will be detected at runtime,
2787 otherwise another method will be used as fallback. This is the preferred
2788 backend for BSD and BSD-like systems, although on most BSDs kqueue only
2789 supports some types of fds correctly (the only platform we found that
2790 supports ptys for example was NetBSD), so kqueue might be compiled in, but
2791 not be used unless explicitly requested. The best way to use it is to find
2792 out whether kqueue supports your type of fd properly and use an embedded
2793 kqueue loop.
2795 =item EV_USE_PORT
2797 If defined to be C<1>, libev will compile in support for the Solaris
2798 10 port style backend. Its availability will be detected at runtime,
2799 otherwise another method will be used as fallback. This is the preferred
2800 backend for Solaris 10 systems.
2802 =item EV_USE_DEVPOLL
2804 reserved for future expansion, works like the USE symbols above.
2806 =item EV_USE_INOTIFY
2808 If defined to be C<1>, libev will compile in support for the Linux inotify
2809 interface to speed up C<ev_stat> watchers. Its actual availability will
2810 be detected at runtime.
2812 =item EV_ATOMIC_T
2814 Libev requires an integer type (suitable for storing C<0> or C<1>) whose
2815 access is atomic with respect to other threads or signal contexts. No such
2816 type is easily found in the C language, so you can provide your own type
2817 that you know is safe for your purposes. It is used both for signal handler "locking"
2818 as well as for signal and thread safety in C<ev_async> watchers.
2820 In the absense of this define, libev will use C<sig_atomic_t volatile>
2821 (from F<signal.h>), which is usually good enough on most platforms.
2823 =item EV_H
2825 The name of the F<ev.h> header file used to include it. The default if
2826 undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2827 used to virtually rename the F<ev.h> header file in case of conflicts.
2829 =item EV_CONFIG_H
2831 If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2832 F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2833 C<EV_H>, above.
2835 =item EV_EVENT_H
2837 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2838 of how the F<event.h> header can be found, the default is C<"event.h">.
2840 =item EV_PROTOTYPES
2842 If defined to be C<0>, then F<ev.h> will not define any function
2843 prototypes, but still define all the structs and other symbols. This is
2844 occasionally useful if you want to provide your own wrapper functions
2845 around libev functions.
2849 If undefined or defined to C<1>, then all event-loop-specific functions
2850 will have the C<struct ev_loop *> as first argument, and you can create
2851 additional independent event loops. Otherwise there will be no support
2852 for multiple event loops and there is no first event loop pointer
2853 argument. Instead, all functions act on the single default loop.
2855 =item EV_MINPRI
2857 =item EV_MAXPRI
2859 The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2860 C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2861 provide for more priorities by overriding those symbols (usually defined
2862 to be C<-2> and C<2>, respectively).
2864 When doing priority-based operations, libev usually has to linearly search
2865 all the priorities, so having many of them (hundreds) uses a lot of space
2866 and time, so using the defaults of five priorities (-2 .. +2) is usually
2867 fine.
2869 If your embedding app does not need any priorities, defining these both to
2870 C<0> will save some memory and cpu.
2874 If undefined or defined to be C<1>, then periodic timers are supported. If
2875 defined to be C<0>, then they are not. Disabling them saves a few kB of
2876 code.
2878 =item EV_IDLE_ENABLE
2880 If undefined or defined to be C<1>, then idle watchers are supported. If
2881 defined to be C<0>, then they are not. Disabling them saves a few kB of
2882 code.
2884 =item EV_EMBED_ENABLE
2886 If undefined or defined to be C<1>, then embed watchers are supported. If
2887 defined to be C<0>, then they are not.
2889 =item EV_STAT_ENABLE
2891 If undefined or defined to be C<1>, then stat watchers are supported. If
2892 defined to be C<0>, then they are not.
2894 =item EV_FORK_ENABLE
2896 If undefined or defined to be C<1>, then fork watchers are supported. If
2897 defined to be C<0>, then they are not.
2899 =item EV_ASYNC_ENABLE
2901 If undefined or defined to be C<1>, then async watchers are supported. If
2902 defined to be C<0>, then they are not.
2904 =item EV_MINIMAL
2906 If you need to shave off some kilobytes of code at the expense of some
2907 speed, define this symbol to C<1>. Currently only used for gcc to override
2908 some inlining decisions, saves roughly 30% codesize of amd64.
2910 =item EV_PID_HASHSIZE
2912 C<ev_child> watchers use a small hash table to distribute workload by
2913 pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
2914 than enough. If you need to manage thousands of children you might want to
2915 increase this value (I<must> be a power of two).
2919 C<ev_stat> watchers use a small hash table to distribute workload by
2920 inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2921 usually more than enough. If you need to manage thousands of C<ev_stat>
2922 watchers you might want to increase this value (I<must> be a power of
2923 two).
2925 =item EV_COMMON
2927 By default, all watchers have a C<void *data> member. By redefining
2928 this macro to a something else you can include more and other types of
2929 members. You have to define it each time you include one of the files,
2930 though, and it must be identical each time.
2932 For example, the perl EV module uses something like this:
2934 #define EV_COMMON \
2935 SV *self; /* contains this struct */ \
2936 SV *cb_sv, *fh /* note no trailing ";" */
2938 =item EV_CB_DECLARE (type)
2940 =item EV_CB_INVOKE (watcher, revents)
2942 =item ev_set_cb (ev, cb)
2944 Can be used to change the callback member declaration in each watcher,
2945 and the way callbacks are invoked and set. Must expand to a struct member
2946 definition and a statement, respectively. See the F<ev.h> header file for
2947 their default definitions. One possible use for overriding these is to
2948 avoid the C<struct ev_loop *> as first argument in all cases, or to use
2949 method calls instead of plain function calls in C++.
2953 If you need to re-export the API (e.g. via a dll) and you need a list of
2954 exported symbols, you can use the provided F<Symbol.*> files which list
2955 all public symbols, one per line:
2957 Symbols.ev for libev proper
2958 Symbols.event for the libevent emulation
2960 This can also be used to rename all public symbols to avoid clashes with
2961 multiple versions of libev linked together (which is obviously bad in
2962 itself, but sometimes it is inconvinient to avoid this).
2964 A sed command like this will create wrapper C<#define>'s that you need to
2965 include before including F<ev.h>:
2967 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2969 This would create a file F<wrap.h> which essentially looks like this:
2971 #define ev_backend myprefix_ev_backend
2972 #define ev_check_start myprefix_ev_check_start
2973 #define ev_check_stop myprefix_ev_check_stop
2974 ...
2976 =head2 EXAMPLES
2978 For a real-world example of a program the includes libev
2979 verbatim, you can have a look at the EV perl module
2980 (L<>). It has the libev files in
2981 the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public
2982 interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2983 will be compiled. It is pretty complex because it provides its own header
2984 file.
2986 The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2987 that everybody includes and which overrides some configure choices:
2989 #define EV_MINIMAL 1
2990 #define EV_USE_POLL 0
2991 #define EV_MULTIPLICITY 0
2992 #define EV_PERIODIC_ENABLE 0
2993 #define EV_STAT_ENABLE 0
2994 #define EV_FORK_ENABLE 0
2995 #define EV_CONFIG_H <config.h>
2996 #define EV_MINPRI 0
2997 #define EV_MAXPRI 0
2999 #include "ev++.h"
3001 And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3003 #include "ev_cpp.h"
3004 #include "ev.c"
3007 =head1 COMPLEXITIES
3009 In this section the complexities of (many of) the algorithms used inside
3010 libev will be explained. For complexity discussions about backends see the
3011 documentation for C<ev_default_init>.
3013 All of the following are about amortised time: If an array needs to be
3014 extended, libev needs to realloc and move the whole array, but this
3015 happens asymptotically never with higher number of elements, so O(1) might
3016 mean it might do a lengthy realloc operation in rare cases, but on average
3017 it is much faster and asymptotically approaches constant time.
3019 =over 4
3021 =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
3023 This means that, when you have a watcher that triggers in one hour and
3024 there are 100 watchers that would trigger before that then inserting will
3025 have to skip roughly seven (C<ld 100>) of these watchers.
3027 =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
3029 That means that changing a timer costs less than removing/adding them
3030 as only the relative motion in the event queue has to be paid for.
3032 =item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
3034 These just add the watcher into an array or at the head of a list.
3036 =item Stopping check/prepare/idle/fork/async watchers: O(1)
3038 =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
3040 These watchers are stored in lists then need to be walked to find the
3041 correct watcher to remove. The lists are usually short (you don't usually
3042 have many watchers waiting for the same fd or signal).
3044 =item Finding the next timer in each loop iteration: O(1)
3046 By virtue of using a binary heap, the next timer is always found at the
3047 beginning of the storage array.
3049 =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3051 A change means an I/O watcher gets started or stopped, which requires
3052 libev to recalculate its status (and possibly tell the kernel, depending
3053 on backend and wether C<ev_io_set> was used).
3055 =item Activating one watcher (putting it into the pending state): O(1)
3057 =item Priority handling: O(number_of_priorities)
3059 Priorities are implemented by allocating some space for each
3060 priority. When doing priority-based operations, libev usually has to
3061 linearly search all the priorities, but starting/stopping and activating
3062 watchers becomes O(1) w.r.t. priority handling.
3064 =item Sending an ev_async: O(1)
3066 =item Processing ev_async_send: O(number_of_async_watchers)
3068 =item Processing signals: O(max_signal_number)
3070 Sending involves a syscall I<iff> there were no other C<ev_async_send>
3071 calls in the current loop iteration. Checking for async and signal events
3072 involves iterating over all running async watchers or all signal numbers.
3074 =back
3077 =head1 Win32 platform limitations and workarounds
3079 Win32 doesn't support any of the standards (e.g. POSIX) that libev
3080 requires, and its I/O model is fundamentally incompatible with the POSIX
3081 model. Libev still offers limited functionality on this platform in
3082 the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3083 descriptors. This only applies when using Win32 natively, not when using
3084 e.g. cygwin.
3086 There is no supported compilation method available on windows except
3087 embedding it into other applications.
3089 Due to the many, low, and arbitrary limits on the win32 platform and the
3090 abysmal performance of winsockets, using a large number of sockets is not
3091 recommended (and not reasonable). If your program needs to use more than
3092 a hundred or so sockets, then likely it needs to use a totally different
3093 implementation for windows, as libev offers the POSIX model, which cannot
3094 be implemented efficiently on windows (microsoft monopoly games).
3096 =over 4
3098 =item The winsocket select function
3100 The winsocket C<select> function doesn't follow POSIX in that it requires
3101 socket I<handles> and not socket I<file descriptors>. This makes select
3102 very inefficient, and also requires a mapping from file descriptors
3103 to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>,
3104 C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor
3105 symbols for more info.
3107 The configuration for a "naked" win32 using the microsoft runtime
3108 libraries and raw winsocket select is:
3110 #define EV_USE_SELECT 1
3111 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3113 Note that winsockets handling of fd sets is O(n), so you can easily get a
3114 complexity in the O(n²) range when using win32.
3116 =item Limited number of file descriptors
3118 Windows has numerous arbitrary (and low) limits on things. Early versions
3119 of winsocket's select only supported waiting for a max. of C<64> handles
3120 (probably owning to the fact that all windows kernels can only wait for
3121 C<64> things at the same time internally; microsoft recommends spawning a
3122 chain of threads and wait for 63 handles and the previous thread in each).
3124 Newer versions support more handles, but you need to define C<FD_SETSIZE>
3125 to some high number (e.g. C<2048>) before compiling the winsocket select
3126 call (which might be in libev or elsewhere, for example, perl does its own
3127 select emulation on windows).
3129 Another limit is the number of file descriptors in the microsoft runtime
3130 libraries, which by default is C<64> (there must be a hidden I<64> fetish
3131 or something like this inside microsoft). You can increase this by calling
3132 C<_setmaxstdio>, which can increase this limit to C<2048> (another
3133 arbitrary limit), but is broken in many versions of the microsoft runtime
3134 libraries.
3136 This might get you to about C<512> or C<2048> sockets (depending on
3137 windows version and/or the phase of the moon). To get more, you need to
3138 wrap all I/O functions and provide your own fd management, but the cost of
3139 calling select (O(n²)) will likely make this unworkable.
3141 =back
3144 =head1 AUTHOR
3146 Marc Lehmann <>.