3 libev - a high performance full-featured event loop written in C
14 ev_timer timeout_watcher;
16 /* called when data readable on stdin */
18 stdin_cb (EV_P_ struct ev_io *w, int revents)
20 /* puts ("stdin ready"); */
21 ev_io_stop (EV_A_ w); /* just a syntax example */
22 ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
26 timeout_cb (EV_P_ struct ev_timer *w, int revents)
28 /* puts ("timeout"); */
29 ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
35 struct ev_loop *loop = ev_default_loop (0);
37 /* initialise an io watcher, then start it */
38 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
39 ev_io_start (loop, &stdin_watcher);
41 /* simple non-repeating 5.5 second timeout */
42 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
43 ev_timer_start (loop, &timeout_watcher);
45 /* loop till timeout or data ready */
53 The newest version of this document is also available as a html-formatted
54 web page you might find easier to navigate when reading it for the first
55 time: L<http://cvs.schmorp.de/libev/ev.html>.
57 Libev is an event loop: you register interest in certain events (such as a
58 file descriptor being readable or a timeout occurring), and it will manage
59 these event sources and provide your program with events.
61 To do this, it must take more or less complete control over your process
62 (or thread) by executing the I<event loop> handler, and will then
63 communicate events via a callback mechanism.
65 You register interest in certain events by registering so-called I<event
66 watchers>, which are relatively small C structures you initialise with the
67 details of the event, and then hand it over to libev by I<starting> the
72 Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
73 BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
74 for file descriptor events (C<ev_io>), the Linux C<inotify> interface
75 (for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
76 with customised rescheduling (C<ev_periodic>), synchronous signals
77 (C<ev_signal>), process status change events (C<ev_child>), and event
78 watchers dealing with the event loop mechanism itself (C<ev_idle>,
79 C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as
80 file watchers (C<ev_stat>) and even limited support for fork events
83 It also is quite fast (see this
84 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
89 Libev is very configurable. In this manual the default configuration will
90 be described, which supports multiple event loops. For more info about
91 various configuration options please have a look at B<EMBED> section in
92 this manual. If libev was configured without support for multiple event
93 loops, then all functions taking an initial argument of name C<loop>
94 (which is always of type C<struct ev_loop *>) will not have this argument.
96 =head2 TIME REPRESENTATION
98 Libev represents time as a single floating point number, representing the
99 (fractional) number of seconds since the (POSIX) epoch (somewhere near
100 the beginning of 1970, details are complicated, don't ask). This type is
101 called C<ev_tstamp>, which is what you should use too. It usually aliases
102 to the C<double> type in C, and when you need to do any calculations on
103 it, you should treat it as some floatingpoint value. Unlike the name
104 component C<stamp> might indicate, it is also used for time differences
107 =head1 GLOBAL FUNCTIONS
109 These functions can be called anytime, even before initialising the
114 =item ev_tstamp ev_time ()
116 Returns the current time as libev would use it. Please note that the
117 C<ev_now> function is usually faster and also often returns the timestamp
118 you actually want to know.
120 =item ev_sleep (ev_tstamp interval)
122 Sleep for the given interval: The current thread will be blocked until
123 either it is interrupted or the given time interval has passed. Basically
124 this is a subsecond-resolution C<sleep ()>.
126 =item int ev_version_major ()
128 =item int ev_version_minor ()
130 You can find out the major and minor ABI version numbers of the library
131 you linked against by calling the functions C<ev_version_major> and
132 C<ev_version_minor>. If you want, you can compare against the global
133 symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
134 version of the library your program was compiled against.
136 These version numbers refer to the ABI version of the library, not the
139 Usually, it's a good idea to terminate if the major versions mismatch,
140 as this indicates an incompatible change. Minor versions are usually
141 compatible to older versions, so a larger minor version alone is usually
144 Example: Make sure we haven't accidentally been linked against the wrong
147 assert (("libev version mismatch",
148 ev_version_major () == EV_VERSION_MAJOR
149 && ev_version_minor () >= EV_VERSION_MINOR));
151 =item unsigned int ev_supported_backends ()
153 Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
154 value) compiled into this binary of libev (independent of their
155 availability on the system you are running on). See C<ev_default_loop> for
156 a description of the set values.
158 Example: make sure we have the epoll method, because yeah this is cool and
159 a must have and can we have a torrent of it please!!!11
161 assert (("sorry, no epoll, no sex",
162 ev_supported_backends () & EVBACKEND_EPOLL));
164 =item unsigned int ev_recommended_backends ()
166 Return the set of all backends compiled into this binary of libev and also
167 recommended for this platform. This set is often smaller than the one
168 returned by C<ev_supported_backends>, as for example kqueue is broken on
169 most BSDs and will not be autodetected unless you explicitly request it
170 (assuming you know what you are doing). This is the set of backends that
171 libev will probe for if you specify no backends explicitly.
173 =item unsigned int ev_embeddable_backends ()
175 Returns the set of backends that are embeddable in other event loops. This
176 is the theoretical, all-platform, value. To find which backends
177 might be supported on the current system, you would need to look at
178 C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
181 See the description of C<ev_embed> watchers for more info.
183 =item ev_set_allocator (void *(*cb)(void *ptr, long size))
185 Sets the allocation function to use (the prototype is similar - the
186 semantics is identical - to the realloc C function). It is used to
187 allocate and free memory (no surprises here). If it returns zero when
188 memory needs to be allocated, the library might abort or take some
189 potentially destructive action. The default is your system realloc
192 You could override this function in high-availability programs to, say,
193 free some memory if it cannot allocate memory, to use a special allocator,
194 or even to sleep a while and retry until some memory is available.
196 Example: Replace the libev allocator with one that waits a bit and then
200 persistent_realloc (void *ptr, size_t size)
204 void *newptr = realloc (ptr, size);
214 ev_set_allocator (persistent_realloc);
216 =item ev_set_syserr_cb (void (*cb)(const char *msg));
218 Set the callback function to call on a retryable syscall error (such
219 as failed select, poll, epoll_wait). The message is a printable string
220 indicating the system call or subsystem causing the problem. If this
221 callback is set, then libev will expect it to remedy the sitution, no
222 matter what, when it returns. That is, libev will generally retry the
223 requested operation, or, if the condition doesn't go away, do bad stuff
226 Example: This is basically the same thing that libev does internally, too.
229 fatal_error (const char *msg)
236 ev_set_syserr_cb (fatal_error);
240 =head1 FUNCTIONS CONTROLLING THE EVENT LOOP
242 An event loop is described by a C<struct ev_loop *>. The library knows two
243 types of such loops, the I<default> loop, which supports signals and child
244 events, and dynamically created loops which do not.
246 If you use threads, a common model is to run the default event loop
247 in your main thread (or in a separate thread) and for each thread you
248 create, you also create another event loop. Libev itself does no locking
249 whatsoever, so if you mix calls to the same event loop in different
250 threads, make sure you lock (this is usually a bad idea, though, even if
251 done correctly, because it's hideous and inefficient).
255 =item struct ev_loop *ev_default_loop (unsigned int flags)
257 This will initialise the default event loop if it hasn't been initialised
258 yet and return it. If the default loop could not be initialised, returns
259 false. If it already was initialised it simply returns it (and ignores the
260 flags. If that is troubling you, check C<ev_backend ()> afterwards).
262 If you don't know what event loop to use, use the one returned from this
265 The flags argument can be used to specify special behaviour or specific
266 backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
268 The following flags are supported:
274 The default flags value. Use this if you have no clue (it's the right
277 =item C<EVFLAG_NOENV>
279 If this flag bit is ored into the flag value (or the program runs setuid
280 or setgid) then libev will I<not> look at the environment variable
281 C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
282 override the flags completely if it is found in the environment. This is
283 useful to try out specific backends to test their performance, or to work
286 =item C<EVFLAG_FORKCHECK>
288 Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after
289 a fork, you can also make libev check for a fork in each iteration by
292 This works by calling C<getpid ()> on every iteration of the loop,
293 and thus this might slow down your event loop if you do a lot of loop
294 iterations and little real work, but is usually not noticeable (on my
295 Linux system for example, C<getpid> is actually a simple 5-insn sequence
296 without a syscall and thus I<very> fast, but my Linux system also has
297 C<pthread_atfork> which is even faster).
299 The big advantage of this flag is that you can forget about fork (and
300 forget about forgetting to tell libev about forking) when you use this
303 This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS>
304 environment variable.
306 =item C<EVBACKEND_SELECT> (value 1, portable select backend)
308 This is your standard select(2) backend. Not I<completely> standard, as
309 libev tries to roll its own fd_set with no limits on the number of fds,
310 but if that fails, expect a fairly low limit on the number of fds when
311 using this backend. It doesn't scale too well (O(highest_fd)), but its
312 usually the fastest backend for a low number of (low-numbered :) fds.
314 To get good performance out of this backend you need a high amount of
315 parallelity (most of the file descriptors should be busy). If you are
316 writing a server, you should C<accept ()> in a loop to accept as many
317 connections as possible during one iteration. You might also want to have
318 a look at C<ev_set_io_collect_interval ()> to increase the amount of
319 readyness notifications you get per iteration.
321 =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
323 And this is your standard poll(2) backend. It's more complicated
324 than select, but handles sparse fds better and has no artificial
325 limit on the number of fds you can use (except it will slow down
326 considerably with a lot of inactive fds). It scales similarly to select,
327 i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
330 =item C<EVBACKEND_EPOLL> (value 4, Linux)
332 For few fds, this backend is a bit little slower than poll and select,
333 but it scales phenomenally better. While poll and select usually scale
334 like O(total_fds) where n is the total number of fds (or the highest fd),
335 epoll scales either O(1) or O(active_fds). The epoll design has a number
336 of shortcomings, such as silently dropping events in some hard-to-detect
337 cases and rewiring a syscall per fd change, no fork support and bad
340 While stopping, setting and starting an I/O watcher in the same iteration
341 will result in some caching, there is still a syscall per such incident
342 (because the fd could point to a different file description now), so its
343 best to avoid that. Also, C<dup ()>'ed file descriptors might not work
344 very well if you register events for both fds.
346 Please note that epoll sometimes generates spurious notifications, so you
347 need to use non-blocking I/O or other means to avoid blocking when no data
348 (or space) is available.
350 Best performance from this backend is achieved by not unregistering all
351 watchers for a file descriptor until it has been closed, if possible, i.e.
352 keep at least one watcher active per fd at all times.
354 While nominally embeddeble in other event loops, this feature is broken in
355 all kernel versions tested so far.
357 =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
359 Kqueue deserves special mention, as at the time of this writing, it
360 was broken on all BSDs except NetBSD (usually it doesn't work reliably
361 with anything but sockets and pipes, except on Darwin, where of course
362 it's completely useless). For this reason it's not being "autodetected"
363 unless you explicitly specify it explicitly in the flags (i.e. using
364 C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
367 You still can embed kqueue into a normal poll or select backend and use it
368 only for sockets (after having made sure that sockets work with kqueue on
369 the target platform). See C<ev_embed> watchers for more info.
371 It scales in the same way as the epoll backend, but the interface to the
372 kernel is more efficient (which says nothing about its actual speed, of
373 course). While stopping, setting and starting an I/O watcher does never
374 cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
375 two event changes per incident, support for C<fork ()> is very bad and it
376 drops fds silently in similarly hard-to-detect cases.
378 This backend usually performs well under most conditions.
380 While nominally embeddable in other event loops, this doesn't work
381 everywhere, so you might need to test for this. And since it is broken
382 almost everywhere, you should only use it when you have a lot of sockets
383 (for which it usually works), by embedding it into another event loop
384 (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
387 =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
389 This is not implemented yet (and might never be, unless you send me an
390 implementation). According to reports, C</dev/poll> only supports sockets
391 and is not embeddable, which would limit the usefulness of this backend
394 =item C<EVBACKEND_PORT> (value 32, Solaris 10)
396 This uses the Solaris 10 event port mechanism. As with everything on Solaris,
397 it's really slow, but it still scales very well (O(active_fds)).
399 Please note that solaris event ports can deliver a lot of spurious
400 notifications, so you need to use non-blocking I/O or other means to avoid
401 blocking when no data (or space) is available.
403 While this backend scales well, it requires one system call per active
404 file descriptor per loop iteration. For small and medium numbers of file
405 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
406 might perform better.
408 =item C<EVBACKEND_ALL>
410 Try all backends (even potentially broken ones that wouldn't be tried
411 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
412 C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
414 It is definitely not recommended to use this flag.
418 If one or more of these are ored into the flags value, then only these
419 backends will be tried (in the reverse order as given here). If none are
420 specified, most compiled-in backend will be tried, usually in reverse
421 order of their flag values :)
423 The most typical usage is like this:
425 if (!ev_default_loop (0))
426 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
428 Restrict libev to the select and poll backends, and do not allow
429 environment settings to be taken into account:
431 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
433 Use whatever libev has to offer, but make sure that kqueue is used if
434 available (warning, breaks stuff, best use only with your own private
435 event loop and only if you know the OS supports your types of fds):
437 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
439 =item struct ev_loop *ev_loop_new (unsigned int flags)
441 Similar to C<ev_default_loop>, but always creates a new event loop that is
442 always distinct from the default loop. Unlike the default loop, it cannot
443 handle signal and child watchers, and attempts to do so will be greeted by
444 undefined behaviour (or a failed assertion if assertions are enabled).
446 Example: Try to create a event loop that uses epoll and nothing else.
448 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
450 fatal ("no epoll found here, maybe it hides under your chair");
452 =item ev_default_destroy ()
454 Destroys the default loop again (frees all memory and kernel state
455 etc.). None of the active event watchers will be stopped in the normal
456 sense, so e.g. C<ev_is_active> might still return true. It is your
457 responsibility to either stop all watchers cleanly yoursef I<before>
458 calling this function, or cope with the fact afterwards (which is usually
459 the easiest thing, you can just ignore the watchers and/or C<free ()> them
462 Note that certain global state, such as signal state, will not be freed by
463 this function, and related watchers (such as signal and child watchers)
464 would need to be stopped manually.
466 In general it is not advisable to call this function except in the
467 rare occasion where you really need to free e.g. the signal handling
468 pipe fds. If you need dynamically allocated loops it is better to use
469 C<ev_loop_new> and C<ev_loop_destroy>).
471 =item ev_loop_destroy (loop)
473 Like C<ev_default_destroy>, but destroys an event loop created by an
474 earlier call to C<ev_loop_new>.
476 =item ev_default_fork ()
478 This function reinitialises the kernel state for backends that have
479 one. Despite the name, you can call it anytime, but it makes most sense
480 after forking, in either the parent or child process (or both, but that
481 again makes little sense).
483 You I<must> call this function in the child process after forking if and
484 only if you want to use the event library in both processes. If you just
485 fork+exec, you don't have to call it.
487 The function itself is quite fast and it's usually not a problem to call
488 it just in case after a fork. To make this easy, the function will fit in
489 quite nicely into a call to C<pthread_atfork>:
491 pthread_atfork (0, 0, ev_default_fork);
493 At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
494 without calling this function, so if you force one of those backends you
497 =item ev_loop_fork (loop)
499 Like C<ev_default_fork>, but acts on an event loop created by
500 C<ev_loop_new>. Yes, you have to call this on every allocated event loop
501 after fork, and how you do this is entirely your own problem.
503 =item unsigned int ev_loop_count (loop)
505 Returns the count of loop iterations for the loop, which is identical to
506 the number of times libev did poll for new events. It starts at C<0> and
507 happily wraps around with enough iterations.
509 This value can sometimes be useful as a generation counter of sorts (it
510 "ticks" the number of loop iterations), as it roughly corresponds with
511 C<ev_prepare> and C<ev_check> calls.
513 =item unsigned int ev_backend (loop)
515 Returns one of the C<EVBACKEND_*> flags indicating the event backend in
518 =item ev_tstamp ev_now (loop)
520 Returns the current "event loop time", which is the time the event loop
521 received events and started processing them. This timestamp does not
522 change as long as callbacks are being processed, and this is also the base
523 time used for relative timers. You can treat it as the timestamp of the
524 event occurring (or more correctly, libev finding out about it).
526 =item ev_loop (loop, int flags)
528 Finally, this is it, the event handler. This function usually is called
529 after you initialised all your watchers and you want to start handling
532 If the flags argument is specified as C<0>, it will not return until
533 either no event watchers are active anymore or C<ev_unloop> was called.
535 Please note that an explicit C<ev_unloop> is usually better than
536 relying on all watchers to be stopped when deciding when a program has
537 finished (especially in interactive programs), but having a program that
538 automatically loops as long as it has to and no longer by virtue of
539 relying on its watchers stopping correctly is a thing of beauty.
541 A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
542 those events and any outstanding ones, but will not block your process in
543 case there are no events and will return after one iteration of the loop.
545 A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
546 neccessary) and will handle those and any outstanding ones. It will block
547 your process until at least one new event arrives, and will return after
548 one iteration of the loop. This is useful if you are waiting for some
549 external event in conjunction with something not expressible using other
550 libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
551 usually a better approach for this kind of thing.
553 Here are the gory details of what C<ev_loop> does:
555 - Before the first iteration, call any pending watchers.
556 * If EVFLAG_FORKCHECK was used, check for a fork.
557 - If a fork was detected, queue and call all fork watchers.
558 - Queue and call all prepare watchers.
559 - If we have been forked, recreate the kernel state.
560 - Update the kernel state with all outstanding changes.
561 - Update the "event loop time".
562 - Calculate for how long to sleep or block, if at all
563 (active idle watchers, EVLOOP_NONBLOCK or not having
564 any active watchers at all will result in not sleeping).
565 - Sleep if the I/O and timer collect interval say so.
566 - Block the process, waiting for any events.
567 - Queue all outstanding I/O (fd) events.
568 - Update the "event loop time" and do time jump handling.
569 - Queue all outstanding timers.
570 - Queue all outstanding periodics.
571 - If no events are pending now, queue all idle watchers.
572 - Queue all check watchers.
573 - Call all queued watchers in reverse order (i.e. check watchers first).
574 Signals and child watchers are implemented as I/O watchers, and will
575 be handled here by queueing them when their watcher gets executed.
576 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
577 were used, or there are no active watchers, return, otherwise
578 continue with step *.
580 Example: Queue some jobs and then loop until no events are outstanding
583 ... queue jobs here, make sure they register event watchers as long
584 ... as they still have work to do (even an idle watcher will do..)
585 ev_loop (my_loop, 0);
588 =item ev_unloop (loop, how)
590 Can be used to make a call to C<ev_loop> return early (but only after it
591 has processed all outstanding events). The C<how> argument must be either
592 C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
593 C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
595 This "unloop state" will be cleared when entering C<ev_loop> again.
599 =item ev_unref (loop)
601 Ref/unref can be used to add or remove a reference count on the event
602 loop: Every watcher keeps one reference, and as long as the reference
603 count is nonzero, C<ev_loop> will not return on its own. If you have
604 a watcher you never unregister that should not keep C<ev_loop> from
605 returning, ev_unref() after starting, and ev_ref() before stopping it. For
606 example, libev itself uses this for its internal signal pipe: It is not
607 visible to the libev user and should not keep C<ev_loop> from exiting if
608 no event watchers registered by it are active. It is also an excellent
609 way to do this for generic recurring timers or from within third-party
610 libraries. Just remember to I<unref after start> and I<ref before stop>
611 (but only if the watcher wasn't active before, or was active before,
614 Example: Create a signal watcher, but keep it from keeping C<ev_loop>
615 running when nothing else is active.
617 struct ev_signal exitsig;
618 ev_signal_init (&exitsig, sig_cb, SIGINT);
619 ev_signal_start (loop, &exitsig);
622 Example: For some weird reason, unregister the above signal handler again.
625 ev_signal_stop (loop, &exitsig);
627 =item ev_set_io_collect_interval (loop, ev_tstamp interval)
629 =item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
631 These advanced functions influence the time that libev will spend waiting
632 for events. Both are by default C<0>, meaning that libev will try to
633 invoke timer/periodic callbacks and I/O callbacks with minimum latency.
635 Setting these to a higher value (the C<interval> I<must> be >= C<0>)
636 allows libev to delay invocation of I/O and timer/periodic callbacks to
637 increase efficiency of loop iterations.
639 The background is that sometimes your program runs just fast enough to
640 handle one (or very few) event(s) per loop iteration. While this makes
641 the program responsive, it also wastes a lot of CPU time to poll for new
642 events, especially with backends like C<select ()> which have a high
643 overhead for the actual polling but can deliver many events at once.
645 By setting a higher I<io collect interval> you allow libev to spend more
646 time collecting I/O events, so you can handle more events per iteration,
647 at the cost of increasing latency. Timeouts (both C<ev_periodic> and
648 C<ev_timer>) will be not affected. Setting this to a non-null value will
649 introduce an additional C<ev_sleep ()> call into most loop iterations.
651 Likewise, by setting a higher I<timeout collect interval> you allow libev
652 to spend more time collecting timeouts, at the expense of increased
653 latency (the watcher callback will be called later). C<ev_io> watchers
654 will not be affected. Setting this to a non-null value will not introduce
655 any overhead in libev.
657 Many (busy) programs can usually benefit by setting the io collect
658 interval to a value near C<0.1> or so, which is often enough for
659 interactive servers (of course not for games), likewise for timeouts. It
660 usually doesn't make much sense to set it to a lower value than C<0.01>,
661 as this approsaches the timing granularity of most systems.
666 =head1 ANATOMY OF A WATCHER
668 A watcher is a structure that you create and register to record your
669 interest in some event. For instance, if you want to wait for STDIN to
670 become readable, you would create an C<ev_io> watcher for that:
672 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
675 ev_unloop (loop, EVUNLOOP_ALL);
678 struct ev_loop *loop = ev_default_loop (0);
679 struct ev_io stdin_watcher;
680 ev_init (&stdin_watcher, my_cb);
681 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
682 ev_io_start (loop, &stdin_watcher);
685 As you can see, you are responsible for allocating the memory for your
686 watcher structures (and it is usually a bad idea to do this on the stack,
687 although this can sometimes be quite valid).
689 Each watcher structure must be initialised by a call to C<ev_init
690 (watcher *, callback)>, which expects a callback to be provided. This
691 callback gets invoked each time the event occurs (or, in the case of io
692 watchers, each time the event loop detects that the file descriptor given
693 is readable and/or writable).
695 Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
696 with arguments specific to this watcher type. There is also a macro
697 to combine initialisation and setting in one call: C<< ev_<type>_init
698 (watcher *, callback, ...) >>.
700 To make the watcher actually watch out for events, you have to start it
701 with a watcher-specific start function (C<< ev_<type>_start (loop, watcher
702 *) >>), and you can stop watching for events at any time by calling the
703 corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
705 As long as your watcher is active (has been started but not stopped) you
706 must not touch the values stored in it. Most specifically you must never
707 reinitialise it or call its C<set> macro.
709 Each and every callback receives the event loop pointer as first, the
710 registered watcher structure as second, and a bitset of received events as
713 The received events usually include a single bit per event type received
714 (you can receive multiple events at the same time). The possible bit masks
723 The file descriptor in the C<ev_io> watcher has become readable and/or
728 The C<ev_timer> watcher has timed out.
732 The C<ev_periodic> watcher has timed out.
736 The signal specified in the C<ev_signal> watcher has been received by a thread.
740 The pid specified in the C<ev_child> watcher has received a status change.
744 The path specified in the C<ev_stat> watcher changed its attributes somehow.
748 The C<ev_idle> watcher has determined that you have nothing better to do.
754 All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
755 to gather new events, and all C<ev_check> watchers are invoked just after
756 C<ev_loop> has gathered them, but before it invokes any callbacks for any
757 received events. Callbacks of both watcher types can start and stop as
758 many watchers as they want, and all of them will be taken into account
759 (for example, a C<ev_prepare> watcher might start an idle watcher to keep
760 C<ev_loop> from blocking).
764 The embedded event loop specified in the C<ev_embed> watcher needs attention.
768 The event loop has been resumed in the child process after fork (see
773 An unspecified error has occured, the watcher has been stopped. This might
774 happen because the watcher could not be properly started because libev
775 ran out of memory, a file descriptor was found to be closed or any other
776 problem. You best act on it by reporting the problem and somehow coping
777 with the watcher being stopped.
779 Libev will usually signal a few "dummy" events together with an error,
780 for example it might indicate that a fd is readable or writable, and if
781 your callbacks is well-written it can just attempt the operation and cope
782 with the error from read() or write(). This will not work in multithreaded
783 programs, though, so beware.
787 =head2 GENERIC WATCHER FUNCTIONS
789 In the following description, C<TYPE> stands for the watcher type,
790 e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
794 =item C<ev_init> (ev_TYPE *watcher, callback)
796 This macro initialises the generic portion of a watcher. The contents
797 of the watcher object can be arbitrary (so C<malloc> will do). Only
798 the generic parts of the watcher are initialised, you I<need> to call
799 the type-specific C<ev_TYPE_set> macro afterwards to initialise the
800 type-specific parts. For each type there is also a C<ev_TYPE_init> macro
801 which rolls both calls into one.
803 You can reinitialise a watcher at any time as long as it has been stopped
804 (or never started) and there are no pending events outstanding.
806 The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher,
809 =item C<ev_TYPE_set> (ev_TYPE *, [args])
811 This macro initialises the type-specific parts of a watcher. You need to
812 call C<ev_init> at least once before you call this macro, but you can
813 call C<ev_TYPE_set> any number of times. You must not, however, call this
814 macro on a watcher that is active (it can be pending, however, which is a
815 difference to the C<ev_init> macro).
817 Although some watcher types do not have type-specific arguments
818 (e.g. C<ev_prepare>) you still need to call its C<set> macro.
820 =item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
822 This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
823 calls into a single call. This is the most convinient method to initialise
824 a watcher. The same limitations apply, of course.
826 =item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
828 Starts (activates) the given watcher. Only active watchers will receive
829 events. If the watcher is already active nothing will happen.
831 =item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
833 Stops the given watcher again (if active) and clears the pending
834 status. It is possible that stopped watchers are pending (for example,
835 non-repeating timers are being stopped when they become pending), but
836 C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If
837 you want to free or reuse the memory used by the watcher it is therefore a
838 good idea to always call its C<ev_TYPE_stop> function.
840 =item bool ev_is_active (ev_TYPE *watcher)
842 Returns a true value iff the watcher is active (i.e. it has been started
843 and not yet been stopped). As long as a watcher is active you must not modify
846 =item bool ev_is_pending (ev_TYPE *watcher)
848 Returns a true value iff the watcher is pending, (i.e. it has outstanding
849 events but its callback has not yet been invoked). As long as a watcher
850 is pending (but not active) you must not call an init function on it (but
851 C<ev_TYPE_set> is safe), you must not change its priority, and you must
852 make sure the watcher is available to libev (e.g. you cannot C<free ()>
855 =item callback ev_cb (ev_TYPE *watcher)
857 Returns the callback currently set on the watcher.
859 =item ev_cb_set (ev_TYPE *watcher, callback)
861 Change the callback. You can change the callback at virtually any time
864 =item ev_set_priority (ev_TYPE *watcher, priority)
866 =item int ev_priority (ev_TYPE *watcher)
868 Set and query the priority of the watcher. The priority is a small
869 integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
870 (default: C<-2>). Pending watchers with higher priority will be invoked
871 before watchers with lower priority, but priority will not keep watchers
872 from being executed (except for C<ev_idle> watchers).
874 This means that priorities are I<only> used for ordering callback
875 invocation after new events have been received. This is useful, for
876 example, to reduce latency after idling, or more often, to bind two
877 watchers on the same event and make sure one is called first.
879 If you need to suppress invocation when higher priority events are pending
880 you need to look at C<ev_idle> watchers, which provide this functionality.
882 You I<must not> change the priority of a watcher as long as it is active or
885 The default priority used by watchers when no priority has been set is
886 always C<0>, which is supposed to not be too high and not be too low :).
888 Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
889 fine, as long as you do not mind that the priority value you query might
890 or might not have been adjusted to be within valid range.
892 =item ev_invoke (loop, ev_TYPE *watcher, int revents)
894 Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
895 C<loop> nor C<revents> need to be valid as long as the watcher callback
896 can deal with that fact.
898 =item int ev_clear_pending (loop, ev_TYPE *watcher)
900 If the watcher is pending, this function returns clears its pending status
901 and returns its C<revents> bitset (as if its callback was invoked). If the
902 watcher isn't pending it does nothing and returns C<0>.
907 =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
909 Each watcher has, by default, a member C<void *data> that you can change
910 and read at any time, libev will completely ignore it. This can be used
911 to associate arbitrary data with your watcher. If you need more data and
912 don't want to allocate memory and store a pointer to it in that data
913 member, you can also "subclass" the watcher type and provide your own
921 struct whatever *mostinteresting;
924 And since your callback will be called with a pointer to the watcher, you
925 can cast it back to your own type:
927 static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
929 struct my_io *w = (struct my_io *)w_;
933 More interesting and less C-conformant ways of casting your callback type
934 instead have been omitted.
936 Another common scenario is having some data structure with multiple
946 In this case getting the pointer to C<my_biggy> is a bit more complicated,
947 you need to use C<offsetof>:
952 t1_cb (EV_P_ struct ev_timer *w, int revents)
954 struct my_biggy big = (struct my_biggy *
955 (((char *)w) - offsetof (struct my_biggy, t1));
959 t2_cb (EV_P_ struct ev_timer *w, int revents)
961 struct my_biggy big = (struct my_biggy *
962 (((char *)w) - offsetof (struct my_biggy, t2));
968 This section describes each watcher in detail, but will not repeat
969 information given in the last section. Any initialisation/set macros,
970 functions and members specific to the watcher type are explained.
972 Members are additionally marked with either I<[read-only]>, meaning that,
973 while the watcher is active, you can look at the member and expect some
974 sensible content, but you must not modify it (you can modify it while the
975 watcher is stopped to your hearts content), or I<[read-write]>, which
976 means you can expect it to have some sensible content while the watcher
977 is active, but you can also modify it. Modifying it may not do something
978 sensible or take immediate effect (or do anything at all), but libev will
979 not crash or malfunction in any way.
982 =head2 C<ev_io> - is this file descriptor readable or writable?
984 I/O watchers check whether a file descriptor is readable or writable
985 in each iteration of the event loop, or, more precisely, when reading
986 would not block the process and writing would at least be able to write
987 some data. This behaviour is called level-triggering because you keep
988 receiving events as long as the condition persists. Remember you can stop
989 the watcher if you don't want to act on the event and neither want to
990 receive future events.
992 In general you can register as many read and/or write event watchers per
993 fd as you want (as long as you don't confuse yourself). Setting all file
994 descriptors to non-blocking mode is also usually a good idea (but not
995 required if you know what you are doing).
997 If you must do this, then force the use of a known-to-be-good backend
998 (at the time of this writing, this includes only C<EVBACKEND_SELECT> and
1001 Another thing you have to watch out for is that it is quite easy to
1002 receive "spurious" readyness notifications, that is your callback might
1003 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1004 because there is no data. Not only are some backends known to create a
1005 lot of those (for example solaris ports), it is very easy to get into
1006 this situation even with a relatively standard program structure. Thus
1007 it is best to always use non-blocking I/O: An extra C<read>(2) returning
1008 C<EAGAIN> is far preferable to a program hanging until some data arrives.
1010 If you cannot run the fd in non-blocking mode (for example you should not
1011 play around with an Xlib connection), then you have to seperately re-test
1012 whether a file descriptor is really ready with a known-to-be good interface
1013 such as poll (fortunately in our Xlib example, Xlib already does this on
1014 its own, so its quite safe to use).
1016 =head3 The special problem of disappearing file descriptors
1018 Some backends (e.g. kqueue, epoll) need to be told about closing a file
1019 descriptor (either by calling C<close> explicitly or by any other means,
1020 such as C<dup>). The reason is that you register interest in some file
1021 descriptor, but when it goes away, the operating system will silently drop
1022 this interest. If another file descriptor with the same number then is
1023 registered with libev, there is no efficient way to see that this is, in
1024 fact, a different file descriptor.
1026 To avoid having to explicitly tell libev about such cases, libev follows
1027 the following policy: Each time C<ev_io_set> is being called, libev
1028 will assume that this is potentially a new file descriptor, otherwise
1029 it is assumed that the file descriptor stays the same. That means that
1030 you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
1031 descriptor even if the file descriptor number itself did not change.
1033 This is how one would do it normally anyway, the important point is that
1034 the libev application should not optimise around libev but should leave
1035 optimisations to libev.
1037 =head3 The special problem of dup'ed file descriptors
1039 Some backends (e.g. epoll), cannot register events for file descriptors,
1040 but only events for the underlying file descriptions. That means when you
1041 have C<dup ()>'ed file descriptors or weirder constellations, and register
1042 events for them, only one file descriptor might actually receive events.
1044 There is no workaround possible except not registering events
1045 for potentially C<dup ()>'ed file descriptors, or to resort to
1046 C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1048 =head3 The special problem of fork
1050 Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
1051 useless behaviour. Libev fully supports fork, but needs to be told about
1054 To support fork in your programs, you either have to call
1055 C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
1056 enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1060 =head3 Watcher-Specific Functions
1064 =item ev_io_init (ev_io *, callback, int fd, int events)
1066 =item ev_io_set (ev_io *, int fd, int events)
1068 Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1069 rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or
1070 C<EV_READ | EV_WRITE> to receive the given events.
1072 =item int fd [read-only]
1074 The file descriptor being watched.
1076 =item int events [read-only]
1078 The events being watched.
1084 Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1085 readable, but only once. Since it is likely line-buffered, you could
1086 attempt to read a whole line in the callback.
1089 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1091 ev_io_stop (loop, w);
1092 .. read from stdin here (or from w->fd) and haqndle any I/O errors
1096 struct ev_loop *loop = ev_default_init (0);
1097 struct ev_io stdin_readable;
1098 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1099 ev_io_start (loop, &stdin_readable);
1103 =head2 C<ev_timer> - relative and optionally repeating timeouts
1105 Timer watchers are simple relative timers that generate an event after a
1106 given time, and optionally repeating in regular intervals after that.
1108 The timers are based on real time, that is, if you register an event that
1109 times out after an hour and you reset your system clock to last years
1110 time, it will still time out after (roughly) and hour. "Roughly" because
1111 detecting time jumps is hard, and some inaccuracies are unavoidable (the
1112 monotonic clock option helps a lot here).
1114 The relative timeouts are calculated relative to the C<ev_now ()>
1115 time. This is usually the right thing as this timestamp refers to the time
1116 of the event triggering whatever timeout you are modifying/starting. If
1117 you suspect event processing to be delayed and you I<need> to base the timeout
1118 on the current time, use something like this to adjust for this:
1120 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1122 The callback is guarenteed to be invoked only when its timeout has passed,
1123 but if multiple timers become ready during the same loop iteration then
1124 order of execution is undefined.
1126 =head3 Watcher-Specific Functions and Data Members
1130 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1132 =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
1134 Configure the timer to trigger after C<after> seconds. If C<repeat> is
1135 C<0.>, then it will automatically be stopped. If it is positive, then the
1136 timer will automatically be configured to trigger again C<repeat> seconds
1137 later, again, and again, until stopped manually.
1139 The timer itself will do a best-effort at avoiding drift, that is, if you
1140 configure a timer to trigger every 10 seconds, then it will trigger at
1141 exactly 10 second intervals. If, however, your program cannot keep up with
1142 the timer (because it takes longer than those 10 seconds to do stuff) the
1143 timer will not fire more than once per event loop iteration.
1145 =item ev_timer_again (loop)
1147 This will act as if the timer timed out and restart it again if it is
1148 repeating. The exact semantics are:
1150 If the timer is pending, its pending status is cleared.
1152 If the timer is started but nonrepeating, stop it (as if it timed out).
1154 If the timer is repeating, either start it if necessary (with the
1155 C<repeat> value), or reset the running timer to the C<repeat> value.
1157 This sounds a bit complicated, but here is a useful and typical
1158 example: Imagine you have a tcp connection and you want a so-called idle
1159 timeout, that is, you want to be called when there have been, say, 60
1160 seconds of inactivity on the socket. The easiest way to do this is to
1161 configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1162 C<ev_timer_again> each time you successfully read or write some data. If
1163 you go into an idle state where you do not expect data to travel on the
1164 socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
1165 automatically restart it if need be.
1167 That means you can ignore the C<after> value and C<ev_timer_start>
1168 altogether and only ever use the C<repeat> value and C<ev_timer_again>:
1170 ev_timer_init (timer, callback, 0., 5.);
1171 ev_timer_again (loop, timer);
1174 ev_timer_again (loop, timer);
1177 ev_timer_again (loop, timer);
1179 This is more slightly efficient then stopping/starting the timer each time
1180 you want to modify its timeout value.
1182 =item ev_tstamp repeat [read-write]
1184 The current C<repeat> value. Will be used each time the watcher times out
1185 or C<ev_timer_again> is called and determines the next timeout (if any),
1186 which is also when any modifications are taken into account.
1192 Example: Create a timer that fires after 60 seconds.
1195 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1197 .. one minute over, w is actually stopped right here
1200 struct ev_timer mytimer;
1201 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1202 ev_timer_start (loop, &mytimer);
1204 Example: Create a timeout timer that times out after 10 seconds of
1208 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1210 .. ten seconds without any activity
1213 struct ev_timer mytimer;
1214 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1215 ev_timer_again (&mytimer); /* start timer */
1218 // and in some piece of code that gets executed on any "activity":
1219 // reset the timeout to start ticking again at 10 seconds
1220 ev_timer_again (&mytimer);
1223 =head2 C<ev_periodic> - to cron or not to cron?
1225 Periodic watchers are also timers of a kind, but they are very versatile
1226 (and unfortunately a bit complex).
1228 Unlike C<ev_timer>'s, they are not based on real time (or relative time)
1229 but on wallclock time (absolute time). You can tell a periodic watcher
1230 to trigger "at" some specific point in time. For example, if you tell a
1231 periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
1232 + 10.>) and then reset your system clock to the last year, then it will
1233 take a year to trigger the event (unlike an C<ev_timer>, which would trigger
1234 roughly 10 seconds later).
1236 They can also be used to implement vastly more complex timers, such as
1237 triggering an event on each midnight, local time or other, complicated,
1240 As with timers, the callback is guarenteed to be invoked only when the
1241 time (C<at>) has been passed, but if multiple periodic timers become ready
1242 during the same loop iteration then order of execution is undefined.
1244 =head3 Watcher-Specific Functions and Data Members
1248 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1250 =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1252 Lots of arguments, lets sort it out... There are basically three modes of
1253 operation, and we will explain them from simplest to complex:
1257 =item * absolute timer (at = time, interval = reschedule_cb = 0)
1259 In this configuration the watcher triggers an event at the wallclock time
1260 C<at> and doesn't repeat. It will not adjust when a time jump occurs,
1261 that is, if it is to be run at January 1st 2011 then it will run when the
1262 system time reaches or surpasses this time.
1264 =item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1266 In this mode the watcher will always be scheduled to time out at the next
1267 C<at + N * interval> time (for some integer N, which can also be negative)
1268 and then repeat, regardless of any time jumps.
1270 This can be used to create timers that do not drift with respect to system
1273 ev_periodic_set (&periodic, 0., 3600., 0);
1275 This doesn't mean there will always be 3600 seconds in between triggers,
1276 but only that the the callback will be called when the system time shows a
1277 full hour (UTC), or more correctly, when the system time is evenly divisible
1280 Another way to think about it (for the mathematically inclined) is that
1281 C<ev_periodic> will try to run the callback in this mode at the next possible
1282 time where C<time = at (mod interval)>, regardless of any time jumps.
1284 For numerical stability it is preferable that the C<at> value is near
1285 C<ev_now ()> (the current time), but there is no range requirement for
1288 =item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1290 In this mode the values for C<interval> and C<at> are both being
1291 ignored. Instead, each time the periodic watcher gets scheduled, the
1292 reschedule callback will be called with the watcher as first, and the
1293 current time as second argument.
1295 NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1296 ever, or make any event loop modifications>. If you need to stop it,
1297 return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1298 starting an C<ev_prepare> watcher, which is legal).
1300 Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
1301 ev_tstamp now)>, e.g.:
1303 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1308 It must return the next time to trigger, based on the passed time value
1309 (that is, the lowest time value larger than to the second argument). It
1310 will usually be called just before the callback will be triggered, but
1311 might be called at other times, too.
1313 NOTE: I<< This callback must always return a time that is later than the
1314 passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger.
1316 This can be used to create very complex timers, such as a timer that
1317 triggers on each midnight, local time. To do this, you would calculate the
1318 next midnight after C<now> and return the timestamp value for this. How
1319 you do this is, again, up to you (but it is not trivial, which is the main
1320 reason I omitted it as an example).
1324 =item ev_periodic_again (loop, ev_periodic *)
1326 Simply stops and restarts the periodic watcher again. This is only useful
1327 when you changed some parameters or the reschedule callback would return
1328 a different time than the last time it was called (e.g. in a crond like
1329 program when the crontabs have changed).
1331 =item ev_tstamp offset [read-write]
1333 When repeating, this contains the offset value, otherwise this is the
1334 absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1336 Can be modified any time, but changes only take effect when the periodic
1337 timer fires or C<ev_periodic_again> is being called.
1339 =item ev_tstamp interval [read-write]
1341 The current interval value. Can be modified any time, but changes only
1342 take effect when the periodic timer fires or C<ev_periodic_again> is being
1345 =item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]
1347 The current reschedule callback, or C<0>, if this functionality is
1348 switched off. Can be changed any time, but changes only take effect when
1349 the periodic timer fires or C<ev_periodic_again> is being called.
1351 =item ev_tstamp at [read-only]
1353 When active, contains the absolute time that the watcher is supposed to
1360 Example: Call a callback every hour, or, more precisely, whenever the
1361 system clock is divisible by 3600. The callback invocation times have
1362 potentially a lot of jittering, but good long-term stability.
1365 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1367 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1370 struct ev_periodic hourly_tick;
1371 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1372 ev_periodic_start (loop, &hourly_tick);
1374 Example: The same as above, but use a reschedule callback to do it:
1379 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
1381 return fmod (now, 3600.) + 3600.;
1384 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1386 Example: Call a callback every hour, starting now:
1388 struct ev_periodic hourly_tick;
1389 ev_periodic_init (&hourly_tick, clock_cb,
1390 fmod (ev_now (loop), 3600.), 3600., 0);
1391 ev_periodic_start (loop, &hourly_tick);
1394 =head2 C<ev_signal> - signal me when a signal gets signalled!
1396 Signal watchers will trigger an event when the process receives a specific
1397 signal one or more times. Even though signals are very asynchronous, libev
1398 will try it's best to deliver signals synchronously, i.e. as part of the
1399 normal event processing, like any other event.
1401 You can configure as many watchers as you like per signal. Only when the
1402 first watcher gets started will libev actually register a signal watcher
1403 with the kernel (thus it coexists with your own signal handlers as long
1404 as you don't register any with libev). Similarly, when the last signal
1405 watcher for a signal is stopped libev will reset the signal handler to
1406 SIG_DFL (regardless of what it was set to before).
1408 =head3 Watcher-Specific Functions and Data Members
1412 =item ev_signal_init (ev_signal *, callback, int signum)
1414 =item ev_signal_set (ev_signal *, int signum)
1416 Configures the watcher to trigger on the given signal number (usually one
1417 of the C<SIGxxx> constants).
1419 =item int signum [read-only]
1421 The signal the watcher watches out for.
1426 =head2 C<ev_child> - watch out for process status changes
1428 Child watchers trigger when your process receives a SIGCHLD in response to
1429 some child status changes (most typically when a child of yours dies).
1431 =head3 Watcher-Specific Functions and Data Members
1435 =item ev_child_init (ev_child *, callback, int pid)
1437 =item ev_child_set (ev_child *, int pid)
1439 Configures the watcher to wait for status changes of process C<pid> (or
1440 I<any> process if C<pid> is specified as C<0>). The callback can look
1441 at the C<rstatus> member of the C<ev_child> watcher structure to see
1442 the status word (use the macros from C<sys/wait.h> and see your systems
1443 C<waitpid> documentation). The C<rpid> member contains the pid of the
1444 process causing the status change.
1446 =item int pid [read-only]
1448 The process id this watcher watches out for, or C<0>, meaning any process id.
1450 =item int rpid [read-write]
1452 The process id that detected a status change.
1454 =item int rstatus [read-write]
1456 The process exit/trace status caused by C<rpid> (see your systems
1457 C<waitpid> and C<sys/wait.h> documentation for details).
1463 Example: Try to exit cleanly on SIGINT and SIGTERM.
1466 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1468 ev_unloop (loop, EVUNLOOP_ALL);
1471 struct ev_signal signal_watcher;
1472 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1473 ev_signal_start (loop, &sigint_cb);
1476 =head2 C<ev_stat> - did the file attributes just change?
1478 This watches a filesystem path for attribute changes. That is, it calls
1479 C<stat> regularly (or when the OS says it changed) and sees if it changed
1480 compared to the last time, invoking the callback if it did.
1482 The path does not need to exist: changing from "path exists" to "path does
1483 not exist" is a status change like any other. The condition "path does
1484 not exist" is signified by the C<st_nlink> field being zero (which is
1485 otherwise always forced to be at least one) and all the other fields of
1486 the stat buffer having unspecified contents.
1488 The path I<should> be absolute and I<must not> end in a slash. If it is
1489 relative and your working directory changes, the behaviour is undefined.
1491 Since there is no standard to do this, the portable implementation simply
1492 calls C<stat (2)> regularly on the path to see if it changed somehow. You
1493 can specify a recommended polling interval for this case. If you specify
1494 a polling interval of C<0> (highly recommended!) then a I<suitable,
1495 unspecified default> value will be used (which you can expect to be around
1496 five seconds, although this might change dynamically). Libev will also
1497 impose a minimum interval which is currently around C<0.1>, but thats
1500 This watcher type is not meant for massive numbers of stat watchers,
1501 as even with OS-supported change notifications, this can be
1504 At the time of this writing, only the Linux inotify interface is
1505 implemented (implementing kqueue support is left as an exercise for the
1506 reader). Inotify will be used to give hints only and should not change the
1507 semantics of C<ev_stat> watchers, which means that libev sometimes needs
1508 to fall back to regular polling again even with inotify, but changes are
1509 usually detected immediately, and if the file exists there will be no
1514 When C<inotify (7)> support has been compiled into libev (generally only
1515 available on Linux) and present at runtime, it will be used to speed up
1516 change detection where possible. The inotify descriptor will be created lazily
1517 when the first C<ev_stat> watcher is being started.
1519 Inotify presense does not change the semantics of C<ev_stat> watchers
1520 except that changes might be detected earlier, and in some cases, to avoid
1521 making regular C<stat> calls. Even in the presense of inotify support
1522 there are many cases where libev has to resort to regular C<stat> polling.
1524 (There is no support for kqueue, as apparently it cannot be used to
1525 implement this functionality, due to the requirement of having a file
1526 descriptor open on the object at all times).
1528 =head3 The special problem of stat time resolution
1530 The C<stat ()> syscall only supports full-second resolution portably, and
1531 even on systems where the resolution is higher, many filesystems still
1532 only support whole seconds.
1534 That means that, if the time is the only thing that changes, you might
1535 miss updates: on the first update, C<ev_stat> detects a change and calls
1536 your callback, which does something. When there is another update within
1537 the same second, C<ev_stat> will be unable to detect it.
1539 The solution to this is to delay acting on a change for a second (or till
1540 the next second boundary), using a roughly one-second delay C<ev_timer>
1541 (C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01>
1542 is added to work around small timing inconsistencies of some operating
1545 =head3 Watcher-Specific Functions and Data Members
1549 =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1551 =item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)
1553 Configures the watcher to wait for status changes of the given
1554 C<path>. The C<interval> is a hint on how quickly a change is expected to
1555 be detected and should normally be specified as C<0> to let libev choose
1556 a suitable value. The memory pointed to by C<path> must point to the same
1557 path for as long as the watcher is active.
1559 The callback will be receive C<EV_STAT> when a change was detected,
1560 relative to the attributes at the time the watcher was started (or the
1561 last change was detected).
1563 =item ev_stat_stat (ev_stat *)
1565 Updates the stat buffer immediately with new values. If you change the
1566 watched path in your callback, you could call this fucntion to avoid
1567 detecting this change (while introducing a race condition). Can also be
1568 useful simply to find out the new values.
1570 =item ev_statdata attr [read-only]
1572 The most-recently detected attributes of the file. Although the type is of
1573 C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
1574 suitable for your system. If the C<st_nlink> member is C<0>, then there
1575 was some error while C<stat>ing the file.
1577 =item ev_statdata prev [read-only]
1579 The previous attributes of the file. The callback gets invoked whenever
1582 =item ev_tstamp interval [read-only]
1584 The specified interval.
1586 =item const char *path [read-only]
1588 The filesystem path that is being watched.
1594 Example: Watch C</etc/passwd> for attribute changes.
1597 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1599 /* /etc/passwd changed in some way */
1600 if (w->attr.st_nlink)
1602 printf ("passwd current size %ld\n", (long)w->attr.st_size);
1603 printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
1604 printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
1607 /* you shalt not abuse printf for puts */
1608 puts ("wow, /etc/passwd is not there, expect problems. "
1609 "if this is windows, they already arrived\n");
1615 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1616 ev_stat_start (loop, &passwd);
1618 Example: Like above, but additionally use a one-second delay so we do not
1619 miss updates (however, frequent updates will delay processing, too, so
1620 one might do the work both on C<ev_stat> callback invocation I<and> on
1621 C<ev_timer> callback invocation).
1623 static ev_stat passwd;
1624 static ev_timer timer;
1627 timer_cb (EV_P_ ev_timer *w, int revents)
1629 ev_timer_stop (EV_A_ w);
1631 /* now it's one second after the most recent passwd change */
1635 stat_cb (EV_P_ ev_stat *w, int revents)
1637 /* reset the one-second timer */
1638 ev_timer_again (EV_A_ &timer);
1642 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1643 ev_stat_start (loop, &passwd);
1644 ev_timer_init (&timer, timer_cb, 0., 1.01);
1647 =head2 C<ev_idle> - when you've got nothing better to do...
1649 Idle watchers trigger events when no other events of the same or higher
1650 priority are pending (prepare, check and other idle watchers do not
1653 That is, as long as your process is busy handling sockets or timeouts
1654 (or even signals, imagine) of the same or higher priority it will not be
1655 triggered. But when your process is idle (or only lower-priority watchers
1656 are pending), the idle watchers are being called once per event loop
1657 iteration - until stopped, that is, or your process receives more events
1658 and becomes busy again with higher priority stuff.
1660 The most noteworthy effect is that as long as any idle watchers are
1661 active, the process will not block when waiting for new events.
1663 Apart from keeping your process non-blocking (which is a useful
1664 effect on its own sometimes), idle watchers are a good place to do
1665 "pseudo-background processing", or delay processing stuff to after the
1666 event loop has handled all outstanding events.
1668 =head3 Watcher-Specific Functions and Data Members
1672 =item ev_idle_init (ev_signal *, callback)
1674 Initialises and configures the idle watcher - it has no parameters of any
1675 kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
1682 Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1683 callback, free it. Also, use no error checking, as usual.
1686 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
1689 // now do something you wanted to do when the program has
1690 // no longer asnything immediate to do.
1693 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1694 ev_idle_init (idle_watcher, idle_cb);
1695 ev_idle_start (loop, idle_cb);
1698 =head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1700 Prepare and check watchers are usually (but not always) used in tandem:
1701 prepare watchers get invoked before the process blocks and check watchers
1704 You I<must not> call C<ev_loop> or similar functions that enter
1705 the current event loop from either C<ev_prepare> or C<ev_check>
1706 watchers. Other loops than the current one are fine, however. The
1707 rationale behind this is that you do not need to check for recursion in
1708 those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1709 C<ev_check> so if you have one watcher of each kind they will always be
1710 called in pairs bracketing the blocking call.
1712 Their main purpose is to integrate other event mechanisms into libev and
1713 their use is somewhat advanced. This could be used, for example, to track
1714 variable changes, implement your own watchers, integrate net-snmp or a
1715 coroutine library and lots more. They are also occasionally useful if
1716 you cache some data and want to flush it before blocking (for example,
1717 in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1720 This is done by examining in each prepare call which file descriptors need
1721 to be watched by the other library, registering C<ev_io> watchers for
1722 them and starting an C<ev_timer> watcher for any timeouts (many libraries
1723 provide just this functionality). Then, in the check watcher you check for
1724 any events that occured (by checking the pending status of all watchers
1725 and stopping them) and call back into the library. The I/O and timer
1726 callbacks will never actually be called (but must be valid nevertheless,
1727 because you never know, you know?).
1729 As another example, the Perl Coro module uses these hooks to integrate
1730 coroutines into libev programs, by yielding to other active coroutines
1731 during each prepare and only letting the process block if no coroutines
1732 are ready to run (it's actually more complicated: it only runs coroutines
1733 with priority higher than or equal to the event loop and one coroutine
1734 of lower priority, but only once, using idle watchers to keep the event
1735 loop from blocking if lower-priority coroutines are active, thus mapping
1736 low-priority coroutines to idle/background tasks).
1738 It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1739 priority, to ensure that they are being run before any other watchers
1740 after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1741 too) should not activate ("feed") events into libev. While libev fully
1742 supports this, they will be called before other C<ev_check> watchers
1743 did their job. As C<ev_check> watchers are often used to embed other
1744 (non-libev) event loops those other event loops might be in an unusable
1745 state until their C<ev_check> watcher ran (always remind yourself to
1746 coexist peacefully with others).
1748 =head3 Watcher-Specific Functions and Data Members
1752 =item ev_prepare_init (ev_prepare *, callback)
1754 =item ev_check_init (ev_check *, callback)
1756 Initialises and configures the prepare or check watcher - they have no
1757 parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1758 macros, but using them is utterly, utterly and completely pointless.
1764 There are a number of principal ways to embed other event loops or modules
1765 into libev. Here are some ideas on how to include libadns into libev
1766 (there is a Perl module named C<EV::ADNS> that does this, which you could
1767 use for an actually working example. Another Perl module named C<EV::Glib>
1768 embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV
1769 into the Glib event loop).
1771 Method 1: Add IO watchers and a timeout watcher in a prepare handler,
1772 and in a check watcher, destroy them and call into libadns. What follows
1773 is pseudo-code only of course. This requires you to either use a low
1774 priority for the check watcher or use C<ev_clear_pending> explicitly, as
1775 the callbacks for the IO/timeout watchers might not have been called yet.
1777 static ev_io iow [nfd];
1781 io_cb (ev_loop *loop, ev_io *w, int revents)
1785 // create io watchers for each fd and a timer before blocking
1787 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1789 int timeout = 3600000;
1790 struct pollfd fds [nfd];
1791 // actual code will need to loop here and realloc etc.
1792 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1794 /* the callback is illegal, but won't be called as we stop during check */
1795 ev_timer_init (&tw, 0, timeout * 1e-3);
1796 ev_timer_start (loop, &tw);
1798 // create one ev_io per pollfd
1799 for (int i = 0; i < nfd; ++i)
1801 ev_io_init (iow + i, io_cb, fds [i].fd,
1802 ((fds [i].events & POLLIN ? EV_READ : 0)
1803 | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1805 fds [i].revents = 0;
1806 ev_io_start (loop, iow + i);
1810 // stop all watchers after blocking
1812 adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1814 ev_timer_stop (loop, &tw);
1816 for (int i = 0; i < nfd; ++i)
1818 // set the relevant poll flags
1819 // could also call adns_processreadable etc. here
1820 struct pollfd *fd = fds + i;
1821 int revents = ev_clear_pending (iow + i);
1822 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1823 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1825 // now stop the watcher
1826 ev_io_stop (loop, iow + i);
1829 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1832 Method 2: This would be just like method 1, but you run C<adns_afterpoll>
1833 in the prepare watcher and would dispose of the check watcher.
1835 Method 3: If the module to be embedded supports explicit event
1836 notification (adns does), you can also make use of the actual watcher
1837 callbacks, and only destroy/create the watchers in the prepare watcher.
1840 timer_cb (EV_P_ ev_timer *w, int revents)
1842 adns_state ads = (adns_state)w->data;
1845 adns_processtimeouts (ads, &tv_now);
1849 io_cb (EV_P_ ev_io *w, int revents)
1851 adns_state ads = (adns_state)w->data;
1854 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
1855 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
1858 // do not ever call adns_afterpoll
1860 Method 4: Do not use a prepare or check watcher because the module you
1861 want to embed is too inflexible to support it. Instead, youc na override
1862 their poll function. The drawback with this solution is that the main
1863 loop is now no longer controllable by EV. The C<Glib::EV> module does
1867 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
1871 for (n = 0; n < nfds; ++n)
1872 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
1875 // create/start timer
1882 ev_timer_stop (EV_A_ &to);
1884 // stop io watchers again - their callbacks should have set
1885 for (n = 0; n < nfds; ++n)
1886 ev_io_stop (EV_A_ iow [n]);
1892 =head2 C<ev_embed> - when one backend isn't enough...
1894 This is a rather advanced watcher type that lets you embed one event loop
1895 into another (currently only C<ev_io> events are supported in the embedded
1896 loop, other types of watchers might be handled in a delayed or incorrect
1897 fashion and must not be used).
1899 There are primarily two reasons you would want that: work around bugs and
1902 As an example for a bug workaround, the kqueue backend might only support
1903 sockets on some platform, so it is unusable as generic backend, but you
1904 still want to make use of it because you have many sockets and it scales
1905 so nicely. In this case, you would create a kqueue-based loop and embed it
1906 into your default loop (which might use e.g. poll). Overall operation will
1907 be a bit slower because first libev has to poll and then call kevent, but
1908 at least you can use both at what they are best.
1910 As for prioritising I/O: rarely you have the case where some fds have
1911 to be watched and handled very quickly (with low latency), and even
1912 priorities and idle watchers might have too much overhead. In this case
1913 you would put all the high priority stuff in one loop and all the rest in
1914 a second one, and embed the second one in the first.
1916 As long as the watcher is active, the callback will be invoked every time
1917 there might be events pending in the embedded loop. The callback must then
1918 call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke
1919 their callbacks (you could also start an idle watcher to give the embedded
1920 loop strictly lower priority for example). You can also set the callback
1921 to C<0>, in which case the embed watcher will automatically execute the
1922 embedded loop sweep.
1924 As long as the watcher is started it will automatically handle events. The
1925 callback will be invoked whenever some events have been handled. You can
1926 set the callback to C<0> to avoid having to specify one if you are not
1929 Also, there have not currently been made special provisions for forking:
1930 when you fork, you not only have to call C<ev_loop_fork> on both loops,
1931 but you will also have to stop and restart any C<ev_embed> watchers
1934 Unfortunately, not all backends are embeddable, only the ones returned by
1935 C<ev_embeddable_backends> are, which, unfortunately, does not include any
1938 So when you want to use this feature you will always have to be prepared
1939 that you cannot get an embeddable loop. The recommended way to get around
1940 this is to have a separate variables for your embeddable loop, try to
1941 create it, and if that fails, use the normal loop for everything.
1943 =head3 Watcher-Specific Functions and Data Members
1947 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
1949 =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
1951 Configures the watcher to embed the given loop, which must be
1952 embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
1953 invoked automatically, otherwise it is the responsibility of the callback
1954 to invoke it (it will continue to be called until the sweep has been done,
1955 if you do not want thta, you need to temporarily stop the embed watcher).
1957 =item ev_embed_sweep (loop, ev_embed *)
1959 Make a single, non-blocking sweep over the embedded loop. This works
1960 similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1961 apropriate way for embedded loops.
1963 =item struct ev_loop *other [read-only]
1965 The embedded event loop.
1971 Example: Try to get an embeddable event loop and embed it into the default
1972 event loop. If that is not possible, use the default loop. The default
1973 loop is stored in C<loop_hi>, while the mebeddable loop is stored in
1974 C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be
1977 struct ev_loop *loop_hi = ev_default_init (0);
1978 struct ev_loop *loop_lo = 0;
1979 struct ev_embed embed;
1981 // see if there is a chance of getting one that works
1982 // (remember that a flags value of 0 means autodetection)
1983 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
1984 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
1987 // if we got one, then embed it, otherwise default to loop_hi
1990 ev_embed_init (&embed, 0, loop_lo);
1991 ev_embed_start (loop_hi, &embed);
1996 Example: Check if kqueue is available but not recommended and create
1997 a kqueue backend for use with sockets (which usually work with any
1998 kqueue implementation). Store the kqueue/socket-only event loop in
1999 C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2001 struct ev_loop *loop = ev_default_init (0);
2002 struct ev_loop *loop_socket = 0;
2003 struct ev_embed embed;
2005 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2006 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2008 ev_embed_init (&embed, 0, loop_socket);
2009 ev_embed_start (loop, &embed);
2015 // now use loop_socket for all sockets, and loop for everything else
2018 =head2 C<ev_fork> - the audacity to resume the event loop after a fork
2020 Fork watchers are called when a C<fork ()> was detected (usually because
2021 whoever is a good citizen cared to tell libev about it by calling
2022 C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the
2023 event loop blocks next and before C<ev_check> watchers are being called,
2024 and only in the child after the fork. If whoever good citizen calling
2025 C<ev_default_fork> cheats and calls it in the wrong process, the fork
2026 handlers will be invoked, too, of course.
2028 =head3 Watcher-Specific Functions and Data Members
2032 =item ev_fork_init (ev_signal *, callback)
2034 Initialises and configures the fork watcher - it has no parameters of any
2035 kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
2041 =head1 OTHER FUNCTIONS
2043 There are some other functions of possible interest. Described. Here. Now.
2047 =item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
2049 This function combines a simple timer and an I/O watcher, calls your
2050 callback on whichever event happens first and automatically stop both
2051 watchers. This is useful if you want to wait for a single event on an fd
2052 or timeout without having to allocate/configure/start/stop/free one or
2053 more watchers yourself.
2055 If C<fd> is less than 0, then no I/O watcher will be started and events
2056 is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
2057 C<events> set will be craeted and started.
2059 If C<timeout> is less than 0, then no timeout watcher will be
2060 started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2061 repeat = 0) will be started. While C<0> is a valid timeout, it is of
2064 The callback has the type C<void (*cb)(int revents, void *arg)> and gets
2065 passed an C<revents> set like normal event callbacks (a combination of
2066 C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
2067 value passed to C<ev_once>:
2069 static void stdin_ready (int revents, void *arg)
2071 if (revents & EV_TIMEOUT)
2072 /* doh, nothing entered */;
2073 else if (revents & EV_READ)
2074 /* stdin might have data for us, joy! */;
2077 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2079 =item ev_feed_event (ev_loop *, watcher *, int revents)
2081 Feeds the given event set into the event loop, as if the specified event
2082 had happened for the specified watcher (which must be a pointer to an
2083 initialised but not necessarily started event watcher).
2085 =item ev_feed_fd_event (ev_loop *, int fd, int revents)
2087 Feed an event on the given fd, as if a file descriptor backend detected
2088 the given events it.
2090 =item ev_feed_signal_event (ev_loop *loop, int signum)
2092 Feed an event as if the given signal occured (C<loop> must be the default
2098 =head1 LIBEVENT EMULATION
2100 Libev offers a compatibility emulation layer for libevent. It cannot
2101 emulate the internals of libevent, so here are some usage hints:
2105 =item * Use it by including <event.h>, as usual.
2107 =item * The following members are fully supported: ev_base, ev_callback,
2108 ev_arg, ev_fd, ev_res, ev_events.
2110 =item * Avoid using ev_flags and the EVLIST_*-macros, while it is
2111 maintained by libev, it does not work exactly the same way as in libevent (consider
2114 =item * Priorities are not currently supported. Initialising priorities
2115 will fail and all watchers will have the same priority, even though there
2118 =item * Other members are not supported.
2120 =item * The libev emulation is I<not> ABI compatible to libevent, you need
2121 to use the libev header file and library.
2127 Libev comes with some simplistic wrapper classes for C++ that mainly allow
2128 you to use some convinience methods to start/stop watchers and also change
2129 the callback model to a model using method callbacks on objects.
2135 This automatically includes F<ev.h> and puts all of its definitions (many
2136 of them macros) into the global namespace. All C++ specific things are
2137 put into the C<ev> namespace. It should support all the same embedding
2138 options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
2140 Care has been taken to keep the overhead low. The only data member the C++
2141 classes add (compared to plain C-style watchers) is the event loop pointer
2142 that the watcher is associated with (or no additional members at all if
2143 you disable C<EV_MULTIPLICITY> when embedding libev).
2145 Currently, functions, and static and non-static member functions can be
2146 used as callbacks. Other types should be easy to add as long as they only
2147 need one additional pointer for context. If you need support for other
2148 types of functors please contact the author (preferably after implementing
2151 Here is a list of things available in the C<ev> namespace:
2155 =item C<ev::READ>, C<ev::WRITE> etc.
2157 These are just enum values with the same values as the C<EV_READ> etc.
2158 macros from F<ev.h>.
2160 =item C<ev::tstamp>, C<ev::now>
2162 Aliases to the same types/functions as with the C<ev_> prefix.
2164 =item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
2166 For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
2167 the same name in the C<ev> namespace, with the exception of C<ev_signal>
2168 which is called C<ev::sig> to avoid clashes with the C<signal> macro
2169 defines by many implementations.
2171 All of those classes have these methods:
2175 =item ev::TYPE::TYPE ()
2177 =item ev::TYPE::TYPE (struct ev_loop *)
2179 =item ev::TYPE::~TYPE
2181 The constructor (optionally) takes an event loop to associate the watcher
2182 with. If it is omitted, it will use C<EV_DEFAULT>.
2184 The constructor calls C<ev_init> for you, which means you have to call the
2185 C<set> method before starting it.
2187 It will not set a callback, however: You have to call the templated C<set>
2188 method to set a callback before you can start the watcher.
2190 (The reason why you have to use a method is a limitation in C++ which does
2191 not allow explicit template arguments for constructors).
2193 The destructor automatically stops the watcher if it is active.
2195 =item w->set<class, &class::method> (object *)
2197 This method sets the callback method to call. The method has to have a
2198 signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
2199 first argument and the C<revents> as second. The object must be given as
2200 parameter and is stored in the C<data> member of the watcher.
2202 This method synthesizes efficient thunking code to call your method from
2203 the C callback that libev requires. If your compiler can inline your
2204 callback (i.e. it is visible to it at the place of the C<set> call and
2205 your compiler is good :), then the method will be fully inlined into the
2206 thunking function, making it as fast as a direct C callback.
2208 Example: simple class declaration and watcher initialisation
2212 void io_cb (ev::io &w, int revents) { }
2217 iow.set <myclass, &myclass::io_cb> (&obj);
2219 =item w->set<function> (void *data = 0)
2221 Also sets a callback, but uses a static method or plain function as
2222 callback. The optional C<data> argument will be stored in the watcher's
2223 C<data> member and is free for you to use.
2225 The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
2227 See the method-C<set> above for more details.
2231 static void io_cb (ev::io &w, int revents) { }
2234 =item w->set (struct ev_loop *)
2236 Associates a different C<struct ev_loop> with this watcher. You can only
2237 do this when the watcher is inactive (and not pending either).
2239 =item w->set ([args])
2241 Basically the same as C<ev_TYPE_set>, with the same args. Must be
2242 called at least once. Unlike the C counterpart, an active watcher gets
2243 automatically stopped and restarted when reconfiguring it with this
2248 Starts the watcher. Note that there is no C<loop> argument, as the
2249 constructor already stores the event loop.
2253 Stops the watcher if it is active. Again, no C<loop> argument.
2255 =item w->again () (C<ev::timer>, C<ev::periodic> only)
2257 For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
2258 C<ev_TYPE_again> function.
2260 =item w->sweep () (C<ev::embed> only)
2262 Invokes C<ev_embed_sweep>.
2264 =item w->update () (C<ev::stat> only)
2266 Invokes C<ev_stat_stat>.
2272 Example: Define a class with an IO and idle watcher, start one of them in
2277 ev_io io; void io_cb (ev::io &w, int revents);
2278 ev_idle idle void idle_cb (ev::idle &w, int revents);
2283 myclass::myclass (int fd)
2285 io .set <myclass, &myclass::io_cb > (this);
2286 idle.set <myclass, &myclass::idle_cb> (this);
2288 io.start (fd, ev::READ);
2294 Libev can be compiled with a variety of options, the most fundamantal
2295 of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2296 functions and callbacks have an initial C<struct ev_loop *> argument.
2298 To make it easier to write programs that cope with either variant, the
2299 following macros are defined:
2303 =item C<EV_A>, C<EV_A_>
2305 This provides the loop I<argument> for functions, if one is required ("ev
2306 loop argument"). The C<EV_A> form is used when this is the sole argument,
2307 C<EV_A_> is used when other arguments are following. Example:
2310 ev_timer_add (EV_A_ watcher);
2313 It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
2314 which is often provided by the following macro.
2316 =item C<EV_P>, C<EV_P_>
2318 This provides the loop I<parameter> for functions, if one is required ("ev
2319 loop parameter"). The C<EV_P> form is used when this is the sole parameter,
2320 C<EV_P_> is used when other parameters are following. Example:
2322 // this is how ev_unref is being declared
2323 static void ev_unref (EV_P);
2325 // this is how you can declare your typical callback
2326 static void cb (EV_P_ ev_timer *w, int revents)
2328 It declares a parameter C<loop> of type C<struct ev_loop *>, quite
2329 suitable for use with C<EV_A>.
2331 =item C<EV_DEFAULT>, C<EV_DEFAULT_>
2333 Similar to the other two macros, this gives you the value of the default
2334 loop, if multiple loops are supported ("ev loop default").
2338 Example: Declare and initialise a check watcher, utilising the above
2339 macros so it will work regardless of whether multiple loops are supported
2343 check_cb (EV_P_ ev_timer *w, int revents)
2345 ev_check_stop (EV_A_ w);
2349 ev_check_init (&check, check_cb);
2350 ev_check_start (EV_DEFAULT_ &check);
2351 ev_loop (EV_DEFAULT_ 0);
2355 Libev can (and often is) directly embedded into host
2356 applications. Examples of applications that embed it include the Deliantra
2357 Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
2360 The goal is to enable you to just copy the necessary files into your
2361 source directory without having to change even a single line in them, so
2362 you can easily upgrade by simply copying (or having a checked-out copy of
2363 libev somewhere in your source tree).
2367 Depending on what features you need you need to include one or more sets of files
2370 =head3 CORE EVENT LOOP
2372 To include only the libev core (all the C<ev_*> functions), with manual
2373 configuration (no autoconf):
2375 #define EV_STANDALONE 1
2378 This will automatically include F<ev.h>, too, and should be done in a
2379 single C source file only to provide the function implementations. To use
2380 it, do the same for F<ev.h> in all files wishing to use this API (best
2381 done by writing a wrapper around F<ev.h> that you can include instead and
2382 where you can put other configuration options):
2384 #define EV_STANDALONE 1
2387 Both header files and implementation files can be compiled with a C++
2388 compiler (at least, thats a stated goal, and breakage will be treated
2391 You need the following files in your source tree, or in a directory
2392 in your include path (e.g. in libev/ when using -Ilibev):
2399 ev_win32.c required on win32 platforms only
2401 ev_select.c only when select backend is enabled (which is enabled by default)
2402 ev_poll.c only when poll backend is enabled (disabled by default)
2403 ev_epoll.c only when the epoll backend is enabled (disabled by default)
2404 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
2405 ev_port.c only when the solaris port backend is enabled (disabled by default)
2407 F<ev.c> includes the backend files directly when enabled, so you only need
2408 to compile this single file.
2410 =head3 LIBEVENT COMPATIBILITY API
2412 To include the libevent compatibility API, also include:
2416 in the file including F<ev.c>, and:
2420 in the files that want to use the libevent API. This also includes F<ev.h>.
2422 You need the following additional files for this:
2427 =head3 AUTOCONF SUPPORT
2429 Instead of using C<EV_STANDALONE=1> and providing your config in
2430 whatever way you want, you can also C<m4_include([libev.m4])> in your
2431 F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
2432 include F<config.h> and configure itself accordingly.
2434 For this of course you need the m4 file:
2438 =head2 PREPROCESSOR SYMBOLS/MACROS
2440 Libev can be configured via a variety of preprocessor symbols you have to define
2441 before including any of its files. The default is not to build for multiplicity
2442 and only include the select backend.
2448 Must always be C<1> if you do not use autoconf configuration, which
2449 keeps libev from including F<config.h>, and it also defines dummy
2450 implementations for some libevent functions (such as logging, which is not
2451 supported). It will also not define any of the structs usually found in
2452 F<event.h> that are not directly supported by the libev core alone.
2454 =item EV_USE_MONOTONIC
2456 If defined to be C<1>, libev will try to detect the availability of the
2457 monotonic clock option at both compiletime and runtime. Otherwise no use
2458 of the monotonic clock option will be attempted. If you enable this, you
2459 usually have to link against librt or something similar. Enabling it when
2460 the functionality isn't available is safe, though, although you have
2461 to make sure you link against any libraries where the C<clock_gettime>
2462 function is hiding in (often F<-lrt>).
2464 =item EV_USE_REALTIME
2466 If defined to be C<1>, libev will try to detect the availability of the
2467 realtime clock option at compiletime (and assume its availability at
2468 runtime if successful). Otherwise no use of the realtime clock option will
2469 be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2470 (CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2471 note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2473 =item EV_USE_NANOSLEEP
2475 If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2476 and will use it for delays. Otherwise it will use C<select ()>.
2480 If undefined or defined to be C<1>, libev will compile in support for the
2481 C<select>(2) backend. No attempt at autodetection will be done: if no
2482 other method takes over, select will be it. Otherwise the select backend
2483 will not be compiled in.
2485 =item EV_SELECT_USE_FD_SET
2487 If defined to C<1>, then the select backend will use the system C<fd_set>
2488 structure. This is useful if libev doesn't compile due to a missing
2489 C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on
2490 exotic systems. This usually limits the range of file descriptors to some
2491 low limit such as 1024 or might have other limitations (winsocket only
2492 allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
2493 influence the size of the C<fd_set> used.
2495 =item EV_SELECT_IS_WINSOCKET
2497 When defined to C<1>, the select backend will assume that
2498 select/socket/connect etc. don't understand file descriptors but
2499 wants osf handles on win32 (this is the case when the select to
2500 be used is the winsock select). This means that it will call
2501 C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
2502 it is assumed that all these functions actually work on fds, even
2503 on win32. Should not be defined on non-win32 platforms.
2505 =item EV_FD_TO_WIN32_HANDLE
2507 If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
2508 file descriptors to socket handles. When not defining this symbol (the
2509 default), then libev will call C<_get_osfhandle>, which is usually
2510 correct. In some cases, programs use their own file descriptor management,
2511 in which case they can provide this function to map fds to socket handles.
2515 If defined to be C<1>, libev will compile in support for the C<poll>(2)
2516 backend. Otherwise it will be enabled on non-win32 platforms. It
2517 takes precedence over select.
2521 If defined to be C<1>, libev will compile in support for the Linux
2522 C<epoll>(7) backend. Its availability will be detected at runtime,
2523 otherwise another method will be used as fallback. This is the
2524 preferred backend for GNU/Linux systems.
2528 If defined to be C<1>, libev will compile in support for the BSD style
2529 C<kqueue>(2) backend. Its actual availability will be detected at runtime,
2530 otherwise another method will be used as fallback. This is the preferred
2531 backend for BSD and BSD-like systems, although on most BSDs kqueue only
2532 supports some types of fds correctly (the only platform we found that
2533 supports ptys for example was NetBSD), so kqueue might be compiled in, but
2534 not be used unless explicitly requested. The best way to use it is to find
2535 out whether kqueue supports your type of fd properly and use an embedded
2540 If defined to be C<1>, libev will compile in support for the Solaris
2541 10 port style backend. Its availability will be detected at runtime,
2542 otherwise another method will be used as fallback. This is the preferred
2543 backend for Solaris 10 systems.
2545 =item EV_USE_DEVPOLL
2547 reserved for future expansion, works like the USE symbols above.
2549 =item EV_USE_INOTIFY
2551 If defined to be C<1>, libev will compile in support for the Linux inotify
2552 interface to speed up C<ev_stat> watchers. Its actual availability will
2553 be detected at runtime.
2557 The name of the F<ev.h> header file used to include it. The default if
2558 undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to
2559 virtually rename the F<ev.h> header file in case of conflicts.
2563 If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2564 F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2569 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2570 of how the F<event.h> header can be found, the dfeault is C<"event.h">.
2574 If defined to be C<0>, then F<ev.h> will not define any function
2575 prototypes, but still define all the structs and other symbols. This is
2576 occasionally useful if you want to provide your own wrapper functions
2577 around libev functions.
2579 =item EV_MULTIPLICITY
2581 If undefined or defined to C<1>, then all event-loop-specific functions
2582 will have the C<struct ev_loop *> as first argument, and you can create
2583 additional independent event loops. Otherwise there will be no support
2584 for multiple event loops and there is no first event loop pointer
2585 argument. Instead, all functions act on the single default loop.
2591 The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2592 C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2593 provide for more priorities by overriding those symbols (usually defined
2594 to be C<-2> and C<2>, respectively).
2596 When doing priority-based operations, libev usually has to linearly search
2597 all the priorities, so having many of them (hundreds) uses a lot of space
2598 and time, so using the defaults of five priorities (-2 .. +2) is usually
2601 If your embedding app does not need any priorities, defining these both to
2602 C<0> will save some memory and cpu.
2604 =item EV_PERIODIC_ENABLE
2606 If undefined or defined to be C<1>, then periodic timers are supported. If
2607 defined to be C<0>, then they are not. Disabling them saves a few kB of
2610 =item EV_IDLE_ENABLE
2612 If undefined or defined to be C<1>, then idle watchers are supported. If
2613 defined to be C<0>, then they are not. Disabling them saves a few kB of
2616 =item EV_EMBED_ENABLE
2618 If undefined or defined to be C<1>, then embed watchers are supported. If
2619 defined to be C<0>, then they are not.
2621 =item EV_STAT_ENABLE
2623 If undefined or defined to be C<1>, then stat watchers are supported. If
2624 defined to be C<0>, then they are not.
2626 =item EV_FORK_ENABLE
2628 If undefined or defined to be C<1>, then fork watchers are supported. If
2629 defined to be C<0>, then they are not.
2633 If you need to shave off some kilobytes of code at the expense of some
2634 speed, define this symbol to C<1>. Currently only used for gcc to override
2635 some inlining decisions, saves roughly 30% codesize of amd64.
2637 =item EV_PID_HASHSIZE
2639 C<ev_child> watchers use a small hash table to distribute workload by
2640 pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
2641 than enough. If you need to manage thousands of children you might want to
2642 increase this value (I<must> be a power of two).
2644 =item EV_INOTIFY_HASHSIZE
2646 C<ev_stat> watchers use a small hash table to distribute workload by
2647 inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2648 usually more than enough. If you need to manage thousands of C<ev_stat>
2649 watchers you might want to increase this value (I<must> be a power of
2654 By default, all watchers have a C<void *data> member. By redefining
2655 this macro to a something else you can include more and other types of
2656 members. You have to define it each time you include one of the files,
2657 though, and it must be identical each time.
2659 For example, the perl EV module uses something like this:
2662 SV *self; /* contains this struct */ \
2663 SV *cb_sv, *fh /* note no trailing ";" */
2665 =item EV_CB_DECLARE (type)
2667 =item EV_CB_INVOKE (watcher, revents)
2669 =item ev_set_cb (ev, cb)
2671 Can be used to change the callback member declaration in each watcher,
2672 and the way callbacks are invoked and set. Must expand to a struct member
2673 definition and a statement, respectively. See the F<ev.h> header file for
2674 their default definitions. One possible use for overriding these is to
2675 avoid the C<struct ev_loop *> as first argument in all cases, or to use
2676 method calls instead of plain function calls in C++.
2678 =head2 EXPORTED API SYMBOLS
2680 If you need to re-export the API (e.g. via a dll) and you need a list of
2681 exported symbols, you can use the provided F<Symbol.*> files which list
2682 all public symbols, one per line:
2684 Symbols.ev for libev proper
2685 Symbols.event for the libevent emulation
2687 This can also be used to rename all public symbols to avoid clashes with
2688 multiple versions of libev linked together (which is obviously bad in
2689 itself, but sometimes it is inconvinient to avoid this).
2691 A sed command like this will create wrapper C<#define>'s that you need to
2692 include before including F<ev.h>:
2694 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2696 This would create a file F<wrap.h> which essentially looks like this:
2698 #define ev_backend myprefix_ev_backend
2699 #define ev_check_start myprefix_ev_check_start
2700 #define ev_check_stop myprefix_ev_check_stop
2705 For a real-world example of a program the includes libev
2706 verbatim, you can have a look at the EV perl module
2707 (L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
2708 the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public
2709 interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2710 will be compiled. It is pretty complex because it provides its own header
2713 The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2714 that everybody includes and which overrides some configure choices:
2716 #define EV_MINIMAL 1
2717 #define EV_USE_POLL 0
2718 #define EV_MULTIPLICITY 0
2719 #define EV_PERIODIC_ENABLE 0
2720 #define EV_STAT_ENABLE 0
2721 #define EV_FORK_ENABLE 0
2722 #define EV_CONFIG_H <config.h>
2728 And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2736 In this section the complexities of (many of) the algorithms used inside
2737 libev will be explained. For complexity discussions about backends see the
2738 documentation for C<ev_default_init>.
2740 All of the following are about amortised time: If an array needs to be
2741 extended, libev needs to realloc and move the whole array, but this
2742 happens asymptotically never with higher number of elements, so O(1) might
2743 mean it might do a lengthy realloc operation in rare cases, but on average
2744 it is much faster and asymptotically approaches constant time.
2748 =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2750 This means that, when you have a watcher that triggers in one hour and
2751 there are 100 watchers that would trigger before that then inserting will
2752 have to skip roughly seven (C<ld 100>) of these watchers.
2754 =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2756 That means that changing a timer costs less than removing/adding them
2757 as only the relative motion in the event queue has to be paid for.
2759 =item Starting io/check/prepare/idle/signal/child watchers: O(1)
2761 These just add the watcher into an array or at the head of a list.
2763 =item Stopping check/prepare/idle watchers: O(1)
2765 =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2767 These watchers are stored in lists then need to be walked to find the
2768 correct watcher to remove. The lists are usually short (you don't usually
2769 have many watchers waiting for the same fd or signal).
2771 =item Finding the next timer in each loop iteration: O(1)
2773 By virtue of using a binary heap, the next timer is always found at the
2774 beginning of the storage array.
2776 =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2778 A change means an I/O watcher gets started or stopped, which requires
2779 libev to recalculate its status (and possibly tell the kernel, depending
2780 on backend and wether C<ev_io_set> was used).
2782 =item Activating one watcher (putting it into the pending state): O(1)
2784 =item Priority handling: O(number_of_priorities)
2786 Priorities are implemented by allocating some space for each
2787 priority. When doing priority-based operations, libev usually has to
2788 linearly search all the priorities, but starting/stopping and activating
2789 watchers becomes O(1) w.r.t. prioritiy handling.
2794 =head1 Win32 platform limitations and workarounds
2796 Win32 doesn't support any of the standards (e.g. POSIX) that libev
2797 requires, and its I/O model is fundamentally incompatible with the POSIX
2798 model. Libev still offers limited functionality on this platform in
2799 the form of the C<EVBACKEND_SELECT> backend, and only supports socket
2800 descriptors. This only applies when using Win32 natively, not when using
2803 There is no supported compilation method available on windows except
2804 embedding it into other applications.
2806 Due to the many, low, and arbitrary limits on the win32 platform and the
2807 abysmal performance of winsockets, using a large number of sockets is not
2808 recommended (and not reasonable). If your program needs to use more than
2809 a hundred or so sockets, then likely it needs to use a totally different
2810 implementation for windows, as libev offers the POSIX model, which cannot
2811 be implemented efficiently on windows (microsoft monopoly games).
2815 =item The winsocket select function
2817 The winsocket C<select> function doesn't follow POSIX in that it requires
2818 socket I<handles> and not socket I<file descriptors>. This makes select
2819 very inefficient, and also requires a mapping from file descriptors
2820 to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>,
2821 C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor
2822 symbols for more info.
2824 The configuration for a "naked" win32 using the microsoft runtime
2825 libraries and raw winsocket select is:
2827 #define EV_USE_SELECT 1
2828 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
2830 Note that winsockets handling of fd sets is O(n), so you can easily get a
2831 complexity in the O(n²) range when using win32.
2833 =item Limited number of file descriptors
2835 Windows has numerous arbitrary (and low) limits on things. Early versions
2836 of winsocket's select only supported waiting for a max. of C<64> handles
2837 (probably owning to the fact that all windows kernels can only wait for
2838 C<64> things at the same time internally; microsoft recommends spawning a
2839 chain of threads and wait for 63 handles and the previous thread in each).
2841 Newer versions support more handles, but you need to define C<FD_SETSIZE>
2842 to some high number (e.g. C<2048>) before compiling the winsocket select
2843 call (which might be in libev or elsewhere, for example, perl does its own
2844 select emulation on windows).
2846 Another limit is the number of file descriptors in the microsoft runtime
2847 libraries, which by default is C<64> (there must be a hidden I<64> fetish
2848 or something like this inside microsoft). You can increase this by calling
2849 C<_setmaxstdio>, which can increase this limit to C<2048> (another
2850 arbitrary limit), but is broken in many versions of the microsoft runtime
2853 This might get you to about C<512> or C<2048> sockets (depending on
2854 windows version and/or the phase of the moon). To get more, you need to
2855 wrap all I/O functions and provide your own fd management, but the cost of
2856 calling select (O(n²)) will likely make this unworkable.
2863 Marc Lehmann <libev@schmorp.de>.