ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.216 by root, Thu Nov 13 15:55:38 2008 UTC vs.
Revision 1.310 by root, Thu Oct 21 12:32:47 2010 UTC

8 8
9=head2 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 // a single header file is required 11 // a single header file is required
12 #include <ev.h> 12 #include <ev.h>
13
14 #include <stdio.h> // for puts
13 15
14 // every watcher type has its own typedef'd struct 16 // every watcher type has its own typedef'd struct
15 // with the name ev_TYPE 17 // with the name ev_TYPE
16 ev_io stdin_watcher; 18 ev_io stdin_watcher;
17 ev_timer timeout_watcher; 19 ev_timer timeout_watcher;
24 puts ("stdin ready"); 26 puts ("stdin ready");
25 // for one-shot events, one must manually stop the watcher 27 // for one-shot events, one must manually stop the watcher
26 // with its corresponding stop function. 28 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w); 29 ev_io_stop (EV_A_ w);
28 30
29 // this causes all nested ev_loop's to stop iterating 31 // this causes all nested ev_run's to stop iterating
30 ev_unloop (EV_A_ EVUNLOOP_ALL); 32 ev_break (EV_A_ EVBREAK_ALL);
31 } 33 }
32 34
33 // another callback, this time for a time-out 35 // another callback, this time for a time-out
34 static void 36 static void
35 timeout_cb (EV_P_ ev_timer *w, int revents) 37 timeout_cb (EV_P_ ev_timer *w, int revents)
36 { 38 {
37 puts ("timeout"); 39 puts ("timeout");
38 // this causes the innermost ev_loop to stop iterating 40 // this causes the innermost ev_run to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE); 41 ev_break (EV_A_ EVBREAK_ONE);
40 } 42 }
41 43
42 int 44 int
43 main (void) 45 main (void)
44 { 46 {
45 // use the default event loop unless you have special needs 47 // use the default event loop unless you have special needs
46 ev_loop *loop = ev_default_loop (0); 48 struct ev_loop *loop = ev_default_loop (0);
47 49
48 // initialise an io watcher, then start it 50 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable 51 // this one will watch for stdin to become readable
50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 52 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
51 ev_io_start (loop, &stdin_watcher); 53 ev_io_start (loop, &stdin_watcher);
54 // simple non-repeating 5.5 second timeout 56 // simple non-repeating 5.5 second timeout
55 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 57 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
56 ev_timer_start (loop, &timeout_watcher); 58 ev_timer_start (loop, &timeout_watcher);
57 59
58 // now wait for events to arrive 60 // now wait for events to arrive
59 ev_loop (loop, 0); 61 ev_run (loop, 0);
60 62
61 // unloop was called, so exit 63 // unloop was called, so exit
62 return 0; 64 return 0;
63 } 65 }
64 66
65=head1 DESCRIPTION 67=head1 ABOUT THIS DOCUMENT
68
69This document documents the libev software package.
66 70
67The newest version of this document is also available as an html-formatted 71The newest version of this document is also available as an html-formatted
68web page you might find easier to navigate when reading it for the first 72web page you might find easier to navigate when reading it for the first
69time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. 73time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
74
75While this document tries to be as complete as possible in documenting
76libev, its usage and the rationale behind its design, it is not a tutorial
77on event-based programming, nor will it introduce event-based programming
78with libev.
79
80Familiarity with event based programming techniques in general is assumed
81throughout this document.
82
83=head1 ABOUT LIBEV
70 84
71Libev is an event loop: you register interest in certain events (such as a 85Libev is an event loop: you register interest in certain events (such as a
72file descriptor being readable or a timeout occurring), and it will manage 86file descriptor being readable or a timeout occurring), and it will manage
73these event sources and provide your program with events. 87these event sources and provide your program with events.
74 88
84=head2 FEATURES 98=head2 FEATURES
85 99
86Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
87BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
88for file descriptor events (C<ev_io>), the Linux C<inotify> interface 102for file descriptor events (C<ev_io>), the Linux C<inotify> interface
89(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 103(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
90with customised rescheduling (C<ev_periodic>), synchronous signals 104inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
91(C<ev_signal>), process status change events (C<ev_child>), and event 105timers (C<ev_timer>), absolute timers with customised rescheduling
92watchers dealing with the event loop mechanism itself (C<ev_idle>, 106(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
93C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 107change events (C<ev_child>), and event watchers dealing with the event
94file watchers (C<ev_stat>) and even limited support for fork events 108loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
95(C<ev_fork>). 109C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
110limited support for fork events (C<ev_fork>).
96 111
97It also is quite fast (see this 112It also is quite fast (see this
98L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 113L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
99for example). 114for example).
100 115
103Libev is very configurable. In this manual the default (and most common) 118Libev is very configurable. In this manual the default (and most common)
104configuration will be described, which supports multiple event loops. For 119configuration will be described, which supports multiple event loops. For
105more info about various configuration options please have a look at 120more info about various configuration options please have a look at
106B<EMBED> section in this manual. If libev was configured without support 121B<EMBED> section in this manual. If libev was configured without support
107for multiple event loops, then all functions taking an initial argument of 122for multiple event loops, then all functions taking an initial argument of
108name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<struct ev_loop *>) will not have
109this argument. 124this argument.
110 125
111=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
112 127
113Libev represents time as a single floating point number, representing the 128Libev represents time as a single floating point number, representing
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 129the (fractional) number of seconds since the (POSIX) epoch (in practise
115the beginning of 1970, details are complicated, don't ask). This type is 130somewhere near the beginning of 1970, details are complicated, don't
116called C<ev_tstamp>, which is what you should use too. It usually aliases 131ask). This type is called C<ev_tstamp>, which is what you should use
117to the C<double> type in C, and when you need to do any calculations on 132too. It usually aliases to the C<double> type in C. When you need to do
118it, you should treat it as some floating point value. Unlike the name 133any calculations on it, you should treat it as some floating point value.
134
119component C<stamp> might indicate, it is also used for time differences 135Unlike the name component C<stamp> might indicate, it is also used for
120throughout libev. 136time differences (e.g. delays) throughout libev.
121 137
122=head1 ERROR HANDLING 138=head1 ERROR HANDLING
123 139
124Libev knows three classes of errors: operating system errors, usage errors 140Libev knows three classes of errors: operating system errors, usage errors
125and internal errors (bugs). 141and internal errors (bugs).
176as this indicates an incompatible change. Minor versions are usually 192as this indicates an incompatible change. Minor versions are usually
177compatible to older versions, so a larger minor version alone is usually 193compatible to older versions, so a larger minor version alone is usually
178not a problem. 194not a problem.
179 195
180Example: Make sure we haven't accidentally been linked against the wrong 196Example: Make sure we haven't accidentally been linked against the wrong
181version. 197version (note, however, that this will not detect ABI mismatches :).
182 198
183 assert (("libev version mismatch", 199 assert (("libev version mismatch",
184 ev_version_major () == EV_VERSION_MAJOR 200 ev_version_major () == EV_VERSION_MAJOR
185 && ev_version_minor () >= EV_VERSION_MINOR)); 201 && ev_version_minor () >= EV_VERSION_MINOR));
186 202
276 292
277=back 293=back
278 294
279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 295=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
280 296
281An event loop is described by a C<struct ev_loop *> (the C<struct> 297An event loop is described by a C<struct ev_loop *> (the C<struct> is
282is I<not> optional in this case, as there is also an C<ev_loop> 298I<not> optional in case unless libev 3 compatibility is disabled, as libev
283I<function>). 2993 had an C<ev_loop> function colliding with the struct name).
284 300
285The library knows two types of such loops, the I<default> loop, which 301The library knows two types of such loops, the I<default> loop, which
286supports signals and child events, and dynamically created loops which do 302supports signals and child events, and dynamically created event loops
287not. 303which do not.
288 304
289=over 4 305=over 4
290 306
291=item struct ev_loop *ev_default_loop (unsigned int flags) 307=item struct ev_loop *ev_default_loop (unsigned int flags)
292 308
330useful to try out specific backends to test their performance, or to work 346useful to try out specific backends to test their performance, or to work
331around bugs. 347around bugs.
332 348
333=item C<EVFLAG_FORKCHECK> 349=item C<EVFLAG_FORKCHECK>
334 350
335Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 351Instead of calling C<ev_loop_fork> manually after a fork, you can also
336a fork, you can also make libev check for a fork in each iteration by 352make libev check for a fork in each iteration by enabling this flag.
337enabling this flag.
338 353
339This works by calling C<getpid ()> on every iteration of the loop, 354This works by calling C<getpid ()> on every iteration of the loop,
340and thus this might slow down your event loop if you do a lot of loop 355and thus this might slow down your event loop if you do a lot of loop
341iterations and little real work, but is usually not noticeable (on my 356iterations and little real work, but is usually not noticeable (on my
342GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 357GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
348flag. 363flag.
349 364
350This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 365This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
351environment variable. 366environment variable.
352 367
368=item C<EVFLAG_NOINOTIFY>
369
370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374
375=item C<EVFLAG_SIGNALFD>
376
377When this flag is specified, then libev will attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379delivers signals synchronously, which makes it both faster and might make
380it possible to get the queued signal data. It can also simplify signal
381handling with threads, as long as you properly block signals in your
382threads that are not interested in handling them.
383
384Signalfd will not be used by default as this changes your signal mask, and
385there are a lot of shoddy libraries and programs (glib's threadpool for
386example) that can't properly initialise their signal masks.
387
353=item C<EVBACKEND_SELECT> (value 1, portable select backend) 388=item C<EVBACKEND_SELECT> (value 1, portable select backend)
354 389
355This is your standard select(2) backend. Not I<completely> standard, as 390This is your standard select(2) backend. Not I<completely> standard, as
356libev tries to roll its own fd_set with no limits on the number of fds, 391libev tries to roll its own fd_set with no limits on the number of fds,
357but if that fails, expect a fairly low limit on the number of fds when 392but if that fails, expect a fairly low limit on the number of fds when
380 415
381This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 416This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
382C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 417C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
383 418
384=item C<EVBACKEND_EPOLL> (value 4, Linux) 419=item C<EVBACKEND_EPOLL> (value 4, Linux)
420
421Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
422kernels).
385 423
386For few fds, this backend is a bit little slower than poll and select, 424For few fds, this backend is a bit little slower than poll and select,
387but it scales phenomenally better. While poll and select usually scale 425but it scales phenomenally better. While poll and select usually scale
388like O(total_fds) where n is the total number of fds (or the highest fd), 426like O(total_fds) where n is the total number of fds (or the highest fd),
389epoll scales either O(1) or O(active_fds). 427epoll scales either O(1) or O(active_fds).
401of course I<doesn't>, and epoll just loves to report events for totally 439of course I<doesn't>, and epoll just loves to report events for totally
402I<different> file descriptors (even already closed ones, so one cannot 440I<different> file descriptors (even already closed ones, so one cannot
403even remove them from the set) than registered in the set (especially 441even remove them from the set) than registered in the set (especially
404on SMP systems). Libev tries to counter these spurious notifications by 442on SMP systems). Libev tries to counter these spurious notifications by
405employing an additional generation counter and comparing that against the 443employing an additional generation counter and comparing that against the
406events to filter out spurious ones, recreating the set when required. 444events to filter out spurious ones, recreating the set when required. Last
445not least, it also refuses to work with some file descriptors which work
446perfectly fine with C<select> (files, many character devices...).
407 447
408While stopping, setting and starting an I/O watcher in the same iteration 448While stopping, setting and starting an I/O watcher in the same iteration
409will result in some caching, there is still a system call per such 449will result in some caching, there is still a system call per such
410incident (because the same I<file descriptor> could point to a different 450incident (because the same I<file descriptor> could point to a different
411I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 451I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
458 498
459While nominally embeddable in other event loops, this doesn't work 499While nominally embeddable in other event loops, this doesn't work
460everywhere, so you might need to test for this. And since it is broken 500everywhere, so you might need to test for this. And since it is broken
461almost everywhere, you should only use it when you have a lot of sockets 501almost everywhere, you should only use it when you have a lot of sockets
462(for which it usually works), by embedding it into another event loop 502(for which it usually works), by embedding it into another event loop
463(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it, 503(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
464using it only for sockets. 504also broken on OS X)) and, did I mention it, using it only for sockets.
465 505
466This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 506This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
467C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with 507C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
468C<NOTE_EOF>. 508C<NOTE_EOF>.
469 509
504 544
505It is definitely not recommended to use this flag. 545It is definitely not recommended to use this flag.
506 546
507=back 547=back
508 548
509If one or more of these are or'ed into the flags value, then only these 549If one or more of the backend flags are or'ed into the flags value,
510backends will be tried (in the reverse order as listed here). If none are 550then only these backends will be tried (in the reverse order as listed
511specified, all backends in C<ev_recommended_backends ()> will be tried. 551here). If none are specified, all backends in C<ev_recommended_backends
552()> will be tried.
512 553
513Example: This is the most typical usage. 554Example: This is the most typical usage.
514 555
515 if (!ev_default_loop (0)) 556 if (!ev_default_loop (0))
516 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 557 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
528 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 569 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
529 570
530=item struct ev_loop *ev_loop_new (unsigned int flags) 571=item struct ev_loop *ev_loop_new (unsigned int flags)
531 572
532Similar to C<ev_default_loop>, but always creates a new event loop that is 573Similar to C<ev_default_loop>, but always creates a new event loop that is
533always distinct from the default loop. Unlike the default loop, it cannot 574always distinct from the default loop.
534handle signal and child watchers, and attempts to do so will be greeted by
535undefined behaviour (or a failed assertion if assertions are enabled).
536 575
537Note that this function I<is> thread-safe, and the recommended way to use 576Note that this function I<is> thread-safe, and one common way to use
538libev with threads is indeed to create one loop per thread, and using the 577libev with threads is indeed to create one loop per thread, and using the
539default loop in the "main" or "initial" thread. 578default loop in the "main" or "initial" thread.
540 579
541Example: Try to create a event loop that uses epoll and nothing else. 580Example: Try to create a event loop that uses epoll and nothing else.
542 581
544 if (!epoller) 583 if (!epoller)
545 fatal ("no epoll found here, maybe it hides under your chair"); 584 fatal ("no epoll found here, maybe it hides under your chair");
546 585
547=item ev_default_destroy () 586=item ev_default_destroy ()
548 587
549Destroys the default loop again (frees all memory and kernel state 588Destroys the default loop (frees all memory and kernel state etc.). None
550etc.). None of the active event watchers will be stopped in the normal 589of the active event watchers will be stopped in the normal sense, so
551sense, so e.g. C<ev_is_active> might still return true. It is your 590e.g. C<ev_is_active> might still return true. It is your responsibility to
552responsibility to either stop all watchers cleanly yourself I<before> 591either stop all watchers cleanly yourself I<before> calling this function,
553calling this function, or cope with the fact afterwards (which is usually 592or cope with the fact afterwards (which is usually the easiest thing, you
554the easiest thing, you can just ignore the watchers and/or C<free ()> them 593can just ignore the watchers and/or C<free ()> them for example).
555for example).
556 594
557Note that certain global state, such as signal state (and installed signal 595Note that certain global state, such as signal state (and installed signal
558handlers), will not be freed by this function, and related watchers (such 596handlers), will not be freed by this function, and related watchers (such
559as signal and child watchers) would need to be stopped manually. 597as signal and child watchers) would need to be stopped manually.
560 598
561In general it is not advisable to call this function except in the 599In general it is not advisable to call this function except in the
562rare occasion where you really need to free e.g. the signal handling 600rare occasion where you really need to free e.g. the signal handling
563pipe fds. If you need dynamically allocated loops it is better to use 601pipe fds. If you need dynamically allocated loops it is better to use
564C<ev_loop_new> and C<ev_loop_destroy>). 602C<ev_loop_new> and C<ev_loop_destroy>.
565 603
566=item ev_loop_destroy (loop) 604=item ev_loop_destroy (loop)
567 605
568Like C<ev_default_destroy>, but destroys an event loop created by an 606Like C<ev_default_destroy>, but destroys an event loop created by an
569earlier call to C<ev_loop_new>. 607earlier call to C<ev_loop_new>.
570 608
571=item ev_default_fork () 609=item ev_default_fork ()
572 610
573This function sets a flag that causes subsequent C<ev_loop> iterations 611This function sets a flag that causes subsequent C<ev_run> iterations
574to reinitialise the kernel state for backends that have one. Despite the 612to reinitialise the kernel state for backends that have one. Despite the
575name, you can call it anytime, but it makes most sense after forking, in 613name, you can call it anytime, but it makes most sense after forking, in
576the child process (or both child and parent, but that again makes little 614the child process (or both child and parent, but that again makes little
577sense). You I<must> call it in the child before using any of the libev 615sense). You I<must> call it in the child before using any of the libev
578functions, and it will only take effect at the next C<ev_loop> iteration. 616functions, and it will only take effect at the next C<ev_run> iteration.
617
618Again, you I<have> to call it on I<any> loop that you want to re-use after
619a fork, I<even if you do not plan to use the loop in the parent>. This is
620because some kernel interfaces *cough* I<kqueue> *cough* do funny things
621during fork.
579 622
580On the other hand, you only need to call this function in the child 623On the other hand, you only need to call this function in the child
581process if and only if you want to use the event library in the child. If 624process if and only if you want to use the event loop in the child. If
582you just fork+exec, you don't have to call it at all. 625you just fork+exec or create a new loop in the child, you don't have to
626call it at all (in fact, C<epoll> is so badly broken that it makes a
627difference, but libev will usually detect this case on its own and do a
628costly reset of the backend).
583 629
584The function itself is quite fast and it's usually not a problem to call 630The function itself is quite fast and it's usually not a problem to call
585it just in case after a fork. To make this easy, the function will fit in 631it just in case after a fork. To make this easy, the function will fit in
586quite nicely into a call to C<pthread_atfork>: 632quite nicely into a call to C<pthread_atfork>:
587 633
589 635
590=item ev_loop_fork (loop) 636=item ev_loop_fork (loop)
591 637
592Like C<ev_default_fork>, but acts on an event loop created by 638Like C<ev_default_fork>, but acts on an event loop created by
593C<ev_loop_new>. Yes, you have to call this on every allocated event loop 639C<ev_loop_new>. Yes, you have to call this on every allocated event loop
594after fork that you want to re-use in the child, and how you do this is 640after fork that you want to re-use in the child, and how you keep track of
595entirely your own problem. 641them is entirely your own problem.
596 642
597=item int ev_is_default_loop (loop) 643=item int ev_is_default_loop (loop)
598 644
599Returns true when the given loop is, in fact, the default loop, and false 645Returns true when the given loop is, in fact, the default loop, and false
600otherwise. 646otherwise.
601 647
602=item unsigned int ev_loop_count (loop) 648=item unsigned int ev_iteration (loop)
603 649
604Returns the count of loop iterations for the loop, which is identical to 650Returns the current iteration count for the event loop, which is identical
605the number of times libev did poll for new events. It starts at C<0> and 651to the number of times libev did poll for new events. It starts at C<0>
606happily wraps around with enough iterations. 652and happily wraps around with enough iterations.
607 653
608This value can sometimes be useful as a generation counter of sorts (it 654This value can sometimes be useful as a generation counter of sorts (it
609"ticks" the number of loop iterations), as it roughly corresponds with 655"ticks" the number of loop iterations), as it roughly corresponds with
610C<ev_prepare> and C<ev_check> calls. 656C<ev_prepare> and C<ev_check> calls - and is incremented between the
657prepare and check phases.
658
659=item unsigned int ev_depth (loop)
660
661Returns the number of times C<ev_run> was entered minus the number of
662times C<ev_run> was exited, in other words, the recursion depth.
663
664Outside C<ev_run>, this number is zero. In a callback, this number is
665C<1>, unless C<ev_run> was invoked recursively (or from another thread),
666in which case it is higher.
667
668Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread
669etc.), doesn't count as "exit" - consider this as a hint to avoid such
670ungentleman-like behaviour unless it's really convenient.
611 671
612=item unsigned int ev_backend (loop) 672=item unsigned int ev_backend (loop)
613 673
614Returns one of the C<EVBACKEND_*> flags indicating the event backend in 674Returns one of the C<EVBACKEND_*> flags indicating the event backend in
615use. 675use.
624 684
625=item ev_now_update (loop) 685=item ev_now_update (loop)
626 686
627Establishes the current time by querying the kernel, updating the time 687Establishes the current time by querying the kernel, updating the time
628returned by C<ev_now ()> in the progress. This is a costly operation and 688returned by C<ev_now ()> in the progress. This is a costly operation and
629is usually done automatically within C<ev_loop ()>. 689is usually done automatically within C<ev_run ()>.
630 690
631This function is rarely useful, but when some event callback runs for a 691This function is rarely useful, but when some event callback runs for a
632very long time without entering the event loop, updating libev's idea of 692very long time without entering the event loop, updating libev's idea of
633the current time is a good idea. 693the current time is a good idea.
634 694
635See also "The special problem of time updates" in the C<ev_timer> section. 695See also L<The special problem of time updates> in the C<ev_timer> section.
636 696
697=item ev_suspend (loop)
698
699=item ev_resume (loop)
700
701These two functions suspend and resume an event loop, for use when the
702loop is not used for a while and timeouts should not be processed.
703
704A typical use case would be an interactive program such as a game: When
705the user presses C<^Z> to suspend the game and resumes it an hour later it
706would be best to handle timeouts as if no time had actually passed while
707the program was suspended. This can be achieved by calling C<ev_suspend>
708in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
709C<ev_resume> directly afterwards to resume timer processing.
710
711Effectively, all C<ev_timer> watchers will be delayed by the time spend
712between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
713will be rescheduled (that is, they will lose any events that would have
714occurred while suspended).
715
716After calling C<ev_suspend> you B<must not> call I<any> function on the
717given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
718without a previous call to C<ev_suspend>.
719
720Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
721event loop time (see C<ev_now_update>).
722
637=item ev_loop (loop, int flags) 723=item ev_run (loop, int flags)
638 724
639Finally, this is it, the event handler. This function usually is called 725Finally, this is it, the event handler. This function usually is called
640after you initialised all your watchers and you want to start handling 726after you have initialised all your watchers and you want to start
641events. 727handling events. It will ask the operating system for any new events, call
728the watcher callbacks, an then repeat the whole process indefinitely: This
729is why event loops are called I<loops>.
642 730
643If the flags argument is specified as C<0>, it will not return until 731If the flags argument is specified as C<0>, it will keep handling events
644either no event watchers are active anymore or C<ev_unloop> was called. 732until either no event watchers are active anymore or C<ev_break> was
733called.
645 734
646Please note that an explicit C<ev_unloop> is usually better than 735Please note that an explicit C<ev_break> is usually better than
647relying on all watchers to be stopped when deciding when a program has 736relying on all watchers to be stopped when deciding when a program has
648finished (especially in interactive programs), but having a program 737finished (especially in interactive programs), but having a program
649that automatically loops as long as it has to and no longer by virtue 738that automatically loops as long as it has to and no longer by virtue
650of relying on its watchers stopping correctly, that is truly a thing of 739of relying on its watchers stopping correctly, that is truly a thing of
651beauty. 740beauty.
652 741
653A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 742A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
654those events and any already outstanding ones, but will not block your 743those events and any already outstanding ones, but will not wait and
655process in case there are no events and will return after one iteration of 744block your process in case there are no events and will return after one
656the loop. 745iteration of the loop. This is sometimes useful to poll and handle new
746events while doing lengthy calculations, to keep the program responsive.
657 747
658A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 748A flags value of C<EVRUN_ONCE> will look for new events (waiting if
659necessary) and will handle those and any already outstanding ones. It 749necessary) and will handle those and any already outstanding ones. It
660will block your process until at least one new event arrives (which could 750will block your process until at least one new event arrives (which could
661be an event internal to libev itself, so there is no guarantee that a 751be an event internal to libev itself, so there is no guarantee that a
662user-registered callback will be called), and will return after one 752user-registered callback will be called), and will return after one
663iteration of the loop. 753iteration of the loop.
664 754
665This is useful if you are waiting for some external event in conjunction 755This is useful if you are waiting for some external event in conjunction
666with something not expressible using other libev watchers (i.e. "roll your 756with something not expressible using other libev watchers (i.e. "roll your
667own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is 757own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
668usually a better approach for this kind of thing. 758usually a better approach for this kind of thing.
669 759
670Here are the gory details of what C<ev_loop> does: 760Here are the gory details of what C<ev_run> does:
671 761
762 - Increment loop depth.
763 - Reset the ev_break status.
672 - Before the first iteration, call any pending watchers. 764 - Before the first iteration, call any pending watchers.
765 LOOP:
673 * If EVFLAG_FORKCHECK was used, check for a fork. 766 - If EVFLAG_FORKCHECK was used, check for a fork.
674 - If a fork was detected (by any means), queue and call all fork watchers. 767 - If a fork was detected (by any means), queue and call all fork watchers.
675 - Queue and call all prepare watchers. 768 - Queue and call all prepare watchers.
769 - If ev_break was called, goto FINISH.
676 - If we have been forked, detach and recreate the kernel state 770 - If we have been forked, detach and recreate the kernel state
677 as to not disturb the other process. 771 as to not disturb the other process.
678 - Update the kernel state with all outstanding changes. 772 - Update the kernel state with all outstanding changes.
679 - Update the "event loop time" (ev_now ()). 773 - Update the "event loop time" (ev_now ()).
680 - Calculate for how long to sleep or block, if at all 774 - Calculate for how long to sleep or block, if at all
681 (active idle watchers, EVLOOP_NONBLOCK or not having 775 (active idle watchers, EVRUN_NOWAIT or not having
682 any active watchers at all will result in not sleeping). 776 any active watchers at all will result in not sleeping).
683 - Sleep if the I/O and timer collect interval say so. 777 - Sleep if the I/O and timer collect interval say so.
778 - Increment loop iteration counter.
684 - Block the process, waiting for any events. 779 - Block the process, waiting for any events.
685 - Queue all outstanding I/O (fd) events. 780 - Queue all outstanding I/O (fd) events.
686 - Update the "event loop time" (ev_now ()), and do time jump adjustments. 781 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
687 - Queue all expired timers. 782 - Queue all expired timers.
688 - Queue all expired periodics. 783 - Queue all expired periodics.
689 - Unless any events are pending now, queue all idle watchers. 784 - Queue all idle watchers with priority higher than that of pending events.
690 - Queue all check watchers. 785 - Queue all check watchers.
691 - Call all queued watchers in reverse order (i.e. check watchers first). 786 - Call all queued watchers in reverse order (i.e. check watchers first).
692 Signals and child watchers are implemented as I/O watchers, and will 787 Signals and child watchers are implemented as I/O watchers, and will
693 be handled here by queueing them when their watcher gets executed. 788 be handled here by queueing them when their watcher gets executed.
694 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 789 - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT
695 were used, or there are no active watchers, return, otherwise 790 were used, or there are no active watchers, goto FINISH, otherwise
696 continue with step *. 791 continue with step LOOP.
792 FINISH:
793 - Reset the ev_break status iff it was EVBREAK_ONE.
794 - Decrement the loop depth.
795 - Return.
697 796
698Example: Queue some jobs and then loop until no events are outstanding 797Example: Queue some jobs and then loop until no events are outstanding
699anymore. 798anymore.
700 799
701 ... queue jobs here, make sure they register event watchers as long 800 ... queue jobs here, make sure they register event watchers as long
702 ... as they still have work to do (even an idle watcher will do..) 801 ... as they still have work to do (even an idle watcher will do..)
703 ev_loop (my_loop, 0); 802 ev_run (my_loop, 0);
704 ... jobs done or somebody called unloop. yeah! 803 ... jobs done or somebody called unloop. yeah!
705 804
706=item ev_unloop (loop, how) 805=item ev_break (loop, how)
707 806
708Can be used to make a call to C<ev_loop> return early (but only after it 807Can be used to make a call to C<ev_run> return early (but only after it
709has processed all outstanding events). The C<how> argument must be either 808has processed all outstanding events). The C<how> argument must be either
710C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 809C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
711C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 810C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
712 811
713This "unloop state" will be cleared when entering C<ev_loop> again. 812This "unloop state" will be cleared when entering C<ev_run> again.
714 813
715It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. 814It is safe to call C<ev_break> from outside any C<ev_run> calls. ##TODO##
716 815
717=item ev_ref (loop) 816=item ev_ref (loop)
718 817
719=item ev_unref (loop) 818=item ev_unref (loop)
720 819
721Ref/unref can be used to add or remove a reference count on the event 820Ref/unref can be used to add or remove a reference count on the event
722loop: Every watcher keeps one reference, and as long as the reference 821loop: Every watcher keeps one reference, and as long as the reference
723count is nonzero, C<ev_loop> will not return on its own. 822count is nonzero, C<ev_run> will not return on its own.
724 823
725If you have a watcher you never unregister that should not keep C<ev_loop> 824This is useful when you have a watcher that you never intend to
726from returning, call ev_unref() after starting, and ev_ref() before 825unregister, but that nevertheless should not keep C<ev_run> from
826returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
727stopping it. 827before stopping it.
728 828
729As an example, libev itself uses this for its internal signal pipe: It is 829As an example, libev itself uses this for its internal signal pipe: It
730not visible to the libev user and should not keep C<ev_loop> from exiting 830is not visible to the libev user and should not keep C<ev_run> from
731if no event watchers registered by it are active. It is also an excellent 831exiting if no event watchers registered by it are active. It is also an
732way to do this for generic recurring timers or from within third-party 832excellent way to do this for generic recurring timers or from within
733libraries. Just remember to I<unref after start> and I<ref before stop> 833third-party libraries. Just remember to I<unref after start> and I<ref
734(but only if the watcher wasn't active before, or was active before, 834before stop> (but only if the watcher wasn't active before, or was active
735respectively). 835before, respectively. Note also that libev might stop watchers itself
836(e.g. non-repeating timers) in which case you have to C<ev_ref>
837in the callback).
736 838
737Example: Create a signal watcher, but keep it from keeping C<ev_loop> 839Example: Create a signal watcher, but keep it from keeping C<ev_run>
738running when nothing else is active. 840running when nothing else is active.
739 841
740 ev_signal exitsig; 842 ev_signal exitsig;
741 ev_signal_init (&exitsig, sig_cb, SIGINT); 843 ev_signal_init (&exitsig, sig_cb, SIGINT);
742 ev_signal_start (loop, &exitsig); 844 ev_signal_start (loop, &exitsig);
769 871
770By setting a higher I<io collect interval> you allow libev to spend more 872By setting a higher I<io collect interval> you allow libev to spend more
771time collecting I/O events, so you can handle more events per iteration, 873time collecting I/O events, so you can handle more events per iteration,
772at the cost of increasing latency. Timeouts (both C<ev_periodic> and 874at the cost of increasing latency. Timeouts (both C<ev_periodic> and
773C<ev_timer>) will be not affected. Setting this to a non-null value will 875C<ev_timer>) will be not affected. Setting this to a non-null value will
774introduce an additional C<ev_sleep ()> call into most loop iterations. 876introduce an additional C<ev_sleep ()> call into most loop iterations. The
877sleep time ensures that libev will not poll for I/O events more often then
878once per this interval, on average.
775 879
776Likewise, by setting a higher I<timeout collect interval> you allow libev 880Likewise, by setting a higher I<timeout collect interval> you allow libev
777to spend more time collecting timeouts, at the expense of increased 881to spend more time collecting timeouts, at the expense of increased
778latency/jitter/inexactness (the watcher callback will be called 882latency/jitter/inexactness (the watcher callback will be called
779later). C<ev_io> watchers will not be affected. Setting this to a non-null 883later). C<ev_io> watchers will not be affected. Setting this to a non-null
781 885
782Many (busy) programs can usually benefit by setting the I/O collect 886Many (busy) programs can usually benefit by setting the I/O collect
783interval to a value near C<0.1> or so, which is often enough for 887interval to a value near C<0.1> or so, which is often enough for
784interactive servers (of course not for games), likewise for timeouts. It 888interactive servers (of course not for games), likewise for timeouts. It
785usually doesn't make much sense to set it to a lower value than C<0.01>, 889usually doesn't make much sense to set it to a lower value than C<0.01>,
786as this approaches the timing granularity of most systems. 890as this approaches the timing granularity of most systems. Note that if
891you do transactions with the outside world and you can't increase the
892parallelity, then this setting will limit your transaction rate (if you
893need to poll once per transaction and the I/O collect interval is 0.01,
894then you can't do more than 100 transactions per second).
787 895
788Setting the I<timeout collect interval> can improve the opportunity for 896Setting the I<timeout collect interval> can improve the opportunity for
789saving power, as the program will "bundle" timer callback invocations that 897saving power, as the program will "bundle" timer callback invocations that
790are "near" in time together, by delaying some, thus reducing the number of 898are "near" in time together, by delaying some, thus reducing the number of
791times the process sleeps and wakes up again. Another useful technique to 899times the process sleeps and wakes up again. Another useful technique to
792reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure 900reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
793they fire on, say, one-second boundaries only. 901they fire on, say, one-second boundaries only.
794 902
903Example: we only need 0.1s timeout granularity, and we wish not to poll
904more often than 100 times per second:
905
906 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
907 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
908
909=item ev_invoke_pending (loop)
910
911This call will simply invoke all pending watchers while resetting their
912pending state. Normally, C<ev_run> does this automatically when required,
913but when overriding the invoke callback this call comes handy.
914
915=item int ev_pending_count (loop)
916
917Returns the number of pending watchers - zero indicates that no watchers
918are pending.
919
920=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
921
922This overrides the invoke pending functionality of the loop: Instead of
923invoking all pending watchers when there are any, C<ev_run> will call
924this callback instead. This is useful, for example, when you want to
925invoke the actual watchers inside another context (another thread etc.).
926
927If you want to reset the callback, use C<ev_invoke_pending> as new
928callback.
929
930=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
931
932Sometimes you want to share the same loop between multiple threads. This
933can be done relatively simply by putting mutex_lock/unlock calls around
934each call to a libev function.
935
936However, C<ev_run> can run an indefinite time, so it is not feasible
937to wait for it to return. One way around this is to wake up the event
938loop via C<ev_break> and C<av_async_send>, another way is to set these
939I<release> and I<acquire> callbacks on the loop.
940
941When set, then C<release> will be called just before the thread is
942suspended waiting for new events, and C<acquire> is called just
943afterwards.
944
945Ideally, C<release> will just call your mutex_unlock function, and
946C<acquire> will just call the mutex_lock function again.
947
948While event loop modifications are allowed between invocations of
949C<release> and C<acquire> (that's their only purpose after all), no
950modifications done will affect the event loop, i.e. adding watchers will
951have no effect on the set of file descriptors being watched, or the time
952waited. Use an C<ev_async> watcher to wake up C<ev_run> when you want it
953to take note of any changes you made.
954
955In theory, threads executing C<ev_run> will be async-cancel safe between
956invocations of C<release> and C<acquire>.
957
958See also the locking example in the C<THREADS> section later in this
959document.
960
961=item ev_set_userdata (loop, void *data)
962
963=item ev_userdata (loop)
964
965Set and retrieve a single C<void *> associated with a loop. When
966C<ev_set_userdata> has never been called, then C<ev_userdata> returns
967C<0.>
968
969These two functions can be used to associate arbitrary data with a loop,
970and are intended solely for the C<invoke_pending_cb>, C<release> and
971C<acquire> callbacks described above, but of course can be (ab-)used for
972any other purpose as well.
973
795=item ev_loop_verify (loop) 974=item ev_verify (loop)
796 975
797This function only does something when C<EV_VERIFY> support has been 976This function only does something when C<EV_VERIFY> support has been
798compiled in, which is the default for non-minimal builds. It tries to go 977compiled in, which is the default for non-minimal builds. It tries to go
799through all internal structures and checks them for validity. If anything 978through all internal structures and checks them for validity. If anything
800is found to be inconsistent, it will print an error message to standard 979is found to be inconsistent, it will print an error message to standard
818become readable, you would create an C<ev_io> watcher for that: 997become readable, you would create an C<ev_io> watcher for that:
819 998
820 static void my_cb (struct ev_loop *loop, ev_io *w, int revents) 999 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
821 { 1000 {
822 ev_io_stop (w); 1001 ev_io_stop (w);
823 ev_unloop (loop, EVUNLOOP_ALL); 1002 ev_break (loop, EVBREAK_ALL);
824 } 1003 }
825 1004
826 struct ev_loop *loop = ev_default_loop (0); 1005 struct ev_loop *loop = ev_default_loop (0);
827 1006
828 ev_io stdin_watcher; 1007 ev_io stdin_watcher;
829 1008
830 ev_init (&stdin_watcher, my_cb); 1009 ev_init (&stdin_watcher, my_cb);
831 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 1010 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
832 ev_io_start (loop, &stdin_watcher); 1011 ev_io_start (loop, &stdin_watcher);
833 1012
834 ev_loop (loop, 0); 1013 ev_run (loop, 0);
835 1014
836As you can see, you are responsible for allocating the memory for your 1015As you can see, you are responsible for allocating the memory for your
837watcher structures (and it is I<usually> a bad idea to do this on the 1016watcher structures (and it is I<usually> a bad idea to do this on the
838stack). 1017stack).
839 1018
875=item C<EV_WRITE> 1054=item C<EV_WRITE>
876 1055
877The file descriptor in the C<ev_io> watcher has become readable and/or 1056The file descriptor in the C<ev_io> watcher has become readable and/or
878writable. 1057writable.
879 1058
880=item C<EV_TIMEOUT> 1059=item C<EV_TIMER>
881 1060
882The C<ev_timer> watcher has timed out. 1061The C<ev_timer> watcher has timed out.
883 1062
884=item C<EV_PERIODIC> 1063=item C<EV_PERIODIC>
885 1064
903 1082
904=item C<EV_PREPARE> 1083=item C<EV_PREPARE>
905 1084
906=item C<EV_CHECK> 1085=item C<EV_CHECK>
907 1086
908All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts 1087All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts
909to gather new events, and all C<ev_check> watchers are invoked just after 1088to gather new events, and all C<ev_check> watchers are invoked just after
910C<ev_loop> has gathered them, but before it invokes any callbacks for any 1089C<ev_run> has gathered them, but before it invokes any callbacks for any
911received events. Callbacks of both watcher types can start and stop as 1090received events. Callbacks of both watcher types can start and stop as
912many watchers as they want, and all of them will be taken into account 1091many watchers as they want, and all of them will be taken into account
913(for example, a C<ev_prepare> watcher might start an idle watcher to keep 1092(for example, a C<ev_prepare> watcher might start an idle watcher to keep
914C<ev_loop> from blocking). 1093C<ev_run> from blocking).
915 1094
916=item C<EV_EMBED> 1095=item C<EV_EMBED>
917 1096
918The embedded event loop specified in the C<ev_embed> watcher needs attention. 1097The embedded event loop specified in the C<ev_embed> watcher needs attention.
919 1098
923C<ev_fork>). 1102C<ev_fork>).
924 1103
925=item C<EV_ASYNC> 1104=item C<EV_ASYNC>
926 1105
927The given async watcher has been asynchronously notified (see C<ev_async>). 1106The given async watcher has been asynchronously notified (see C<ev_async>).
1107
1108=item C<EV_CUSTOM>
1109
1110Not ever sent (or otherwise used) by libev itself, but can be freely used
1111by libev users to signal watchers (e.g. via C<ev_feed_event>).
928 1112
929=item C<EV_ERROR> 1113=item C<EV_ERROR>
930 1114
931An unspecified error has occurred, the watcher has been stopped. This might 1115An unspecified error has occurred, the watcher has been stopped. This might
932happen because the watcher could not be properly started because libev 1116happen because the watcher could not be properly started because libev
970 1154
971 ev_io w; 1155 ev_io w;
972 ev_init (&w, my_cb); 1156 ev_init (&w, my_cb);
973 ev_io_set (&w, STDIN_FILENO, EV_READ); 1157 ev_io_set (&w, STDIN_FILENO, EV_READ);
974 1158
975=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1159=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
976 1160
977This macro initialises the type-specific parts of a watcher. You need to 1161This macro initialises the type-specific parts of a watcher. You need to
978call C<ev_init> at least once before you call this macro, but you can 1162call C<ev_init> at least once before you call this macro, but you can
979call C<ev_TYPE_set> any number of times. You must not, however, call this 1163call C<ev_TYPE_set> any number of times. You must not, however, call this
980macro on a watcher that is active (it can be pending, however, which is a 1164macro on a watcher that is active (it can be pending, however, which is a
993 1177
994Example: Initialise and set an C<ev_io> watcher in one step. 1178Example: Initialise and set an C<ev_io> watcher in one step.
995 1179
996 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1180 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
997 1181
998=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1182=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
999 1183
1000Starts (activates) the given watcher. Only active watchers will receive 1184Starts (activates) the given watcher. Only active watchers will receive
1001events. If the watcher is already active nothing will happen. 1185events. If the watcher is already active nothing will happen.
1002 1186
1003Example: Start the C<ev_io> watcher that is being abused as example in this 1187Example: Start the C<ev_io> watcher that is being abused as example in this
1004whole section. 1188whole section.
1005 1189
1006 ev_io_start (EV_DEFAULT_UC, &w); 1190 ev_io_start (EV_DEFAULT_UC, &w);
1007 1191
1008=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1192=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1009 1193
1010Stops the given watcher if active, and clears the pending status (whether 1194Stops the given watcher if active, and clears the pending status (whether
1011the watcher was active or not). 1195the watcher was active or not).
1012 1196
1013It is possible that stopped watchers are pending - for example, 1197It is possible that stopped watchers are pending - for example,
1038=item ev_cb_set (ev_TYPE *watcher, callback) 1222=item ev_cb_set (ev_TYPE *watcher, callback)
1039 1223
1040Change the callback. You can change the callback at virtually any time 1224Change the callback. You can change the callback at virtually any time
1041(modulo threads). 1225(modulo threads).
1042 1226
1043=item ev_set_priority (ev_TYPE *watcher, priority) 1227=item ev_set_priority (ev_TYPE *watcher, int priority)
1044 1228
1045=item int ev_priority (ev_TYPE *watcher) 1229=item int ev_priority (ev_TYPE *watcher)
1046 1230
1047Set and query the priority of the watcher. The priority is a small 1231Set and query the priority of the watcher. The priority is a small
1048integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1232integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1049(default: C<-2>). Pending watchers with higher priority will be invoked 1233(default: C<-2>). Pending watchers with higher priority will be invoked
1050before watchers with lower priority, but priority will not keep watchers 1234before watchers with lower priority, but priority will not keep watchers
1051from being executed (except for C<ev_idle> watchers). 1235from being executed (except for C<ev_idle> watchers).
1052 1236
1053This means that priorities are I<only> used for ordering callback
1054invocation after new events have been received. This is useful, for
1055example, to reduce latency after idling, or more often, to bind two
1056watchers on the same event and make sure one is called first.
1057
1058If you need to suppress invocation when higher priority events are pending 1237If you need to suppress invocation when higher priority events are pending
1059you need to look at C<ev_idle> watchers, which provide this functionality. 1238you need to look at C<ev_idle> watchers, which provide this functionality.
1060 1239
1061You I<must not> change the priority of a watcher as long as it is active or 1240You I<must not> change the priority of a watcher as long as it is active or
1062pending. 1241pending.
1063
1064The default priority used by watchers when no priority has been set is
1065always C<0>, which is supposed to not be too high and not be too low :).
1066 1242
1067Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1243Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1068fine, as long as you do not mind that the priority value you query might 1244fine, as long as you do not mind that the priority value you query might
1069or might not have been clamped to the valid range. 1245or might not have been clamped to the valid range.
1246
1247The default priority used by watchers when no priority has been set is
1248always C<0>, which is supposed to not be too high and not be too low :).
1249
1250See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1251priorities.
1070 1252
1071=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1253=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1072 1254
1073Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1255Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1074C<loop> nor C<revents> need to be valid as long as the watcher callback 1256C<loop> nor C<revents> need to be valid as long as the watcher callback
1081returns its C<revents> bitset (as if its callback was invoked). If the 1263returns its C<revents> bitset (as if its callback was invoked). If the
1082watcher isn't pending it does nothing and returns C<0>. 1264watcher isn't pending it does nothing and returns C<0>.
1083 1265
1084Sometimes it can be useful to "poll" a watcher instead of waiting for its 1266Sometimes it can be useful to "poll" a watcher instead of waiting for its
1085callback to be invoked, which can be accomplished with this function. 1267callback to be invoked, which can be accomplished with this function.
1268
1269=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1270
1271Feeds the given event set into the event loop, as if the specified event
1272had happened for the specified watcher (which must be a pointer to an
1273initialised but not necessarily started event watcher). Obviously you must
1274not free the watcher as long as it has pending events.
1275
1276Stopping the watcher, letting libev invoke it, or calling
1277C<ev_clear_pending> will clear the pending event, even if the watcher was
1278not started in the first place.
1279
1280See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1281functions that do not need a watcher.
1086 1282
1087=back 1283=back
1088 1284
1089 1285
1090=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1286=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1139 #include <stddef.h> 1335 #include <stddef.h>
1140 1336
1141 static void 1337 static void
1142 t1_cb (EV_P_ ev_timer *w, int revents) 1338 t1_cb (EV_P_ ev_timer *w, int revents)
1143 { 1339 {
1144 struct my_biggy big = (struct my_biggy * 1340 struct my_biggy big = (struct my_biggy *)
1145 (((char *)w) - offsetof (struct my_biggy, t1)); 1341 (((char *)w) - offsetof (struct my_biggy, t1));
1146 } 1342 }
1147 1343
1148 static void 1344 static void
1149 t2_cb (EV_P_ ev_timer *w, int revents) 1345 t2_cb (EV_P_ ev_timer *w, int revents)
1150 { 1346 {
1151 struct my_biggy big = (struct my_biggy * 1347 struct my_biggy big = (struct my_biggy *)
1152 (((char *)w) - offsetof (struct my_biggy, t2)); 1348 (((char *)w) - offsetof (struct my_biggy, t2));
1153 } 1349 }
1350
1351=head2 WATCHER PRIORITY MODELS
1352
1353Many event loops support I<watcher priorities>, which are usually small
1354integers that influence the ordering of event callback invocation
1355between watchers in some way, all else being equal.
1356
1357In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1358description for the more technical details such as the actual priority
1359range.
1360
1361There are two common ways how these these priorities are being interpreted
1362by event loops:
1363
1364In the more common lock-out model, higher priorities "lock out" invocation
1365of lower priority watchers, which means as long as higher priority
1366watchers receive events, lower priority watchers are not being invoked.
1367
1368The less common only-for-ordering model uses priorities solely to order
1369callback invocation within a single event loop iteration: Higher priority
1370watchers are invoked before lower priority ones, but they all get invoked
1371before polling for new events.
1372
1373Libev uses the second (only-for-ordering) model for all its watchers
1374except for idle watchers (which use the lock-out model).
1375
1376The rationale behind this is that implementing the lock-out model for
1377watchers is not well supported by most kernel interfaces, and most event
1378libraries will just poll for the same events again and again as long as
1379their callbacks have not been executed, which is very inefficient in the
1380common case of one high-priority watcher locking out a mass of lower
1381priority ones.
1382
1383Static (ordering) priorities are most useful when you have two or more
1384watchers handling the same resource: a typical usage example is having an
1385C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1386timeouts. Under load, data might be received while the program handles
1387other jobs, but since timers normally get invoked first, the timeout
1388handler will be executed before checking for data. In that case, giving
1389the timer a lower priority than the I/O watcher ensures that I/O will be
1390handled first even under adverse conditions (which is usually, but not
1391always, what you want).
1392
1393Since idle watchers use the "lock-out" model, meaning that idle watchers
1394will only be executed when no same or higher priority watchers have
1395received events, they can be used to implement the "lock-out" model when
1396required.
1397
1398For example, to emulate how many other event libraries handle priorities,
1399you can associate an C<ev_idle> watcher to each such watcher, and in
1400the normal watcher callback, you just start the idle watcher. The real
1401processing is done in the idle watcher callback. This causes libev to
1402continuously poll and process kernel event data for the watcher, but when
1403the lock-out case is known to be rare (which in turn is rare :), this is
1404workable.
1405
1406Usually, however, the lock-out model implemented that way will perform
1407miserably under the type of load it was designed to handle. In that case,
1408it might be preferable to stop the real watcher before starting the
1409idle watcher, so the kernel will not have to process the event in case
1410the actual processing will be delayed for considerable time.
1411
1412Here is an example of an I/O watcher that should run at a strictly lower
1413priority than the default, and which should only process data when no
1414other events are pending:
1415
1416 ev_idle idle; // actual processing watcher
1417 ev_io io; // actual event watcher
1418
1419 static void
1420 io_cb (EV_P_ ev_io *w, int revents)
1421 {
1422 // stop the I/O watcher, we received the event, but
1423 // are not yet ready to handle it.
1424 ev_io_stop (EV_A_ w);
1425
1426 // start the idle watcher to handle the actual event.
1427 // it will not be executed as long as other watchers
1428 // with the default priority are receiving events.
1429 ev_idle_start (EV_A_ &idle);
1430 }
1431
1432 static void
1433 idle_cb (EV_P_ ev_idle *w, int revents)
1434 {
1435 // actual processing
1436 read (STDIN_FILENO, ...);
1437
1438 // have to start the I/O watcher again, as
1439 // we have handled the event
1440 ev_io_start (EV_P_ &io);
1441 }
1442
1443 // initialisation
1444 ev_idle_init (&idle, idle_cb);
1445 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1446 ev_io_start (EV_DEFAULT_ &io);
1447
1448In the "real" world, it might also be beneficial to start a timer, so that
1449low-priority connections can not be locked out forever under load. This
1450enables your program to keep a lower latency for important connections
1451during short periods of high load, while not completely locking out less
1452important ones.
1154 1453
1155 1454
1156=head1 WATCHER TYPES 1455=head1 WATCHER TYPES
1157 1456
1158This section describes each watcher in detail, but will not repeat 1457This section describes each watcher in detail, but will not repeat
1184descriptors to non-blocking mode is also usually a good idea (but not 1483descriptors to non-blocking mode is also usually a good idea (but not
1185required if you know what you are doing). 1484required if you know what you are doing).
1186 1485
1187If you cannot use non-blocking mode, then force the use of a 1486If you cannot use non-blocking mode, then force the use of a
1188known-to-be-good backend (at the time of this writing, this includes only 1487known-to-be-good backend (at the time of this writing, this includes only
1189C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). 1488C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1489descriptors for which non-blocking operation makes no sense (such as
1490files) - libev doesn't guarantee any specific behaviour in that case.
1190 1491
1191Another thing you have to watch out for is that it is quite easy to 1492Another thing you have to watch out for is that it is quite easy to
1192receive "spurious" readiness notifications, that is your callback might 1493receive "spurious" readiness notifications, that is your callback might
1193be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1494be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1194because there is no data. Not only are some backends known to create a 1495because there is no data. Not only are some backends known to create a
1259 1560
1260So when you encounter spurious, unexplained daemon exits, make sure you 1561So when you encounter spurious, unexplained daemon exits, make sure you
1261ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1562ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1262somewhere, as that would have given you a big clue). 1563somewhere, as that would have given you a big clue).
1263 1564
1565=head3 The special problem of accept()ing when you can't
1566
1567Many implementations of the POSIX C<accept> function (for example,
1568found in post-2004 Linux) have the peculiar behaviour of not removing a
1569connection from the pending queue in all error cases.
1570
1571For example, larger servers often run out of file descriptors (because
1572of resource limits), causing C<accept> to fail with C<ENFILE> but not
1573rejecting the connection, leading to libev signalling readiness on
1574the next iteration again (the connection still exists after all), and
1575typically causing the program to loop at 100% CPU usage.
1576
1577Unfortunately, the set of errors that cause this issue differs between
1578operating systems, there is usually little the app can do to remedy the
1579situation, and no known thread-safe method of removing the connection to
1580cope with overload is known (to me).
1581
1582One of the easiest ways to handle this situation is to just ignore it
1583- when the program encounters an overload, it will just loop until the
1584situation is over. While this is a form of busy waiting, no OS offers an
1585event-based way to handle this situation, so it's the best one can do.
1586
1587A better way to handle the situation is to log any errors other than
1588C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1589messages, and continue as usual, which at least gives the user an idea of
1590what could be wrong ("raise the ulimit!"). For extra points one could stop
1591the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1592usage.
1593
1594If your program is single-threaded, then you could also keep a dummy file
1595descriptor for overload situations (e.g. by opening F</dev/null>), and
1596when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1597close that fd, and create a new dummy fd. This will gracefully refuse
1598clients under typical overload conditions.
1599
1600The last way to handle it is to simply log the error and C<exit>, as
1601is often done with C<malloc> failures, but this results in an easy
1602opportunity for a DoS attack.
1264 1603
1265=head3 Watcher-Specific Functions 1604=head3 Watcher-Specific Functions
1266 1605
1267=over 4 1606=over 4
1268 1607
1300 ... 1639 ...
1301 struct ev_loop *loop = ev_default_init (0); 1640 struct ev_loop *loop = ev_default_init (0);
1302 ev_io stdin_readable; 1641 ev_io stdin_readable;
1303 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1642 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1304 ev_io_start (loop, &stdin_readable); 1643 ev_io_start (loop, &stdin_readable);
1305 ev_loop (loop, 0); 1644 ev_run (loop, 0);
1306 1645
1307 1646
1308=head2 C<ev_timer> - relative and optionally repeating timeouts 1647=head2 C<ev_timer> - relative and optionally repeating timeouts
1309 1648
1310Timer watchers are simple relative timers that generate an event after a 1649Timer watchers are simple relative timers that generate an event after a
1315year, it will still time out after (roughly) one hour. "Roughly" because 1654year, it will still time out after (roughly) one hour. "Roughly" because
1316detecting time jumps is hard, and some inaccuracies are unavoidable (the 1655detecting time jumps is hard, and some inaccuracies are unavoidable (the
1317monotonic clock option helps a lot here). 1656monotonic clock option helps a lot here).
1318 1657
1319The callback is guaranteed to be invoked only I<after> its timeout has 1658The callback is guaranteed to be invoked only I<after> its timeout has
1320passed, but if multiple timers become ready during the same loop iteration 1659passed (not I<at>, so on systems with very low-resolution clocks this
1321then order of execution is undefined. 1660might introduce a small delay). If multiple timers become ready during the
1661same loop iteration then the ones with earlier time-out values are invoked
1662before ones of the same priority with later time-out values (but this is
1663no longer true when a callback calls C<ev_run> recursively).
1322 1664
1323=head3 Be smart about timeouts 1665=head3 Be smart about timeouts
1324 1666
1325Many real-world problems involve some kind of timeout, usually for error 1667Many real-world problems involve some kind of timeout, usually for error
1326recovery. A typical example is an HTTP request - if the other side hangs, 1668recovery. A typical example is an HTTP request - if the other side hangs,
1370C<after> argument to C<ev_timer_set>, and only ever use the C<repeat> 1712C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1371member and C<ev_timer_again>. 1713member and C<ev_timer_again>.
1372 1714
1373At start: 1715At start:
1374 1716
1375 ev_timer_init (timer, callback); 1717 ev_init (timer, callback);
1376 timer->repeat = 60.; 1718 timer->repeat = 60.;
1377 ev_timer_again (loop, timer); 1719 ev_timer_again (loop, timer);
1378 1720
1379Each time there is some activity: 1721Each time there is some activity:
1380 1722
1412 ev_tstamp timeout = last_activity + 60.; 1754 ev_tstamp timeout = last_activity + 60.;
1413 1755
1414 // if last_activity + 60. is older than now, we did time out 1756 // if last_activity + 60. is older than now, we did time out
1415 if (timeout < now) 1757 if (timeout < now)
1416 { 1758 {
1417 // timeout occured, take action 1759 // timeout occurred, take action
1418 } 1760 }
1419 else 1761 else
1420 { 1762 {
1421 // callback was invoked, but there was some activity, re-arm 1763 // callback was invoked, but there was some activity, re-arm
1422 // the watcher to fire in last_activity + 60, which is 1764 // the watcher to fire in last_activity + 60, which is
1442 1784
1443To start the timer, simply initialise the watcher and set C<last_activity> 1785To start the timer, simply initialise the watcher and set C<last_activity>
1444to the current time (meaning we just have some activity :), then call the 1786to the current time (meaning we just have some activity :), then call the
1445callback, which will "do the right thing" and start the timer: 1787callback, which will "do the right thing" and start the timer:
1446 1788
1447 ev_timer_init (timer, callback); 1789 ev_init (timer, callback);
1448 last_activity = ev_now (loop); 1790 last_activity = ev_now (loop);
1449 callback (loop, timer, EV_TIMEOUT); 1791 callback (loop, timer, EV_TIMER);
1450 1792
1451And when there is some activity, simply store the current time in 1793And when there is some activity, simply store the current time in
1452C<last_activity>, no libev calls at all: 1794C<last_activity>, no libev calls at all:
1453 1795
1454 last_actiivty = ev_now (loop); 1796 last_activity = ev_now (loop);
1455 1797
1456This technique is slightly more complex, but in most cases where the 1798This technique is slightly more complex, but in most cases where the
1457time-out is unlikely to be triggered, much more efficient. 1799time-out is unlikely to be triggered, much more efficient.
1458 1800
1459Changing the timeout is trivial as well (if it isn't hard-coded in the 1801Changing the timeout is trivial as well (if it isn't hard-coded in the
1497 1839
1498=head3 The special problem of time updates 1840=head3 The special problem of time updates
1499 1841
1500Establishing the current time is a costly operation (it usually takes at 1842Establishing the current time is a costly operation (it usually takes at
1501least two system calls): EV therefore updates its idea of the current 1843least two system calls): EV therefore updates its idea of the current
1502time only before and after C<ev_loop> collects new events, which causes a 1844time only before and after C<ev_run> collects new events, which causes a
1503growing difference between C<ev_now ()> and C<ev_time ()> when handling 1845growing difference between C<ev_now ()> and C<ev_time ()> when handling
1504lots of events in one iteration. 1846lots of events in one iteration.
1505 1847
1506The relative timeouts are calculated relative to the C<ev_now ()> 1848The relative timeouts are calculated relative to the C<ev_now ()>
1507time. This is usually the right thing as this timestamp refers to the time 1849time. This is usually the right thing as this timestamp refers to the time
1513 1855
1514If the event loop is suspended for a long time, you can also force an 1856If the event loop is suspended for a long time, you can also force an
1515update of the time returned by C<ev_now ()> by calling C<ev_now_update 1857update of the time returned by C<ev_now ()> by calling C<ev_now_update
1516()>. 1858()>.
1517 1859
1860=head3 The special problems of suspended animation
1861
1862When you leave the server world it is quite customary to hit machines that
1863can suspend/hibernate - what happens to the clocks during such a suspend?
1864
1865Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1866all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1867to run until the system is suspended, but they will not advance while the
1868system is suspended. That means, on resume, it will be as if the program
1869was frozen for a few seconds, but the suspend time will not be counted
1870towards C<ev_timer> when a monotonic clock source is used. The real time
1871clock advanced as expected, but if it is used as sole clocksource, then a
1872long suspend would be detected as a time jump by libev, and timers would
1873be adjusted accordingly.
1874
1875I would not be surprised to see different behaviour in different between
1876operating systems, OS versions or even different hardware.
1877
1878The other form of suspend (job control, or sending a SIGSTOP) will see a
1879time jump in the monotonic clocks and the realtime clock. If the program
1880is suspended for a very long time, and monotonic clock sources are in use,
1881then you can expect C<ev_timer>s to expire as the full suspension time
1882will be counted towards the timers. When no monotonic clock source is in
1883use, then libev will again assume a timejump and adjust accordingly.
1884
1885It might be beneficial for this latter case to call C<ev_suspend>
1886and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1887deterministic behaviour in this case (you can do nothing against
1888C<SIGSTOP>).
1889
1518=head3 Watcher-Specific Functions and Data Members 1890=head3 Watcher-Specific Functions and Data Members
1519 1891
1520=over 4 1892=over 4
1521 1893
1522=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1894=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1545If the timer is started but non-repeating, stop it (as if it timed out). 1917If the timer is started but non-repeating, stop it (as if it timed out).
1546 1918
1547If the timer is repeating, either start it if necessary (with the 1919If the timer is repeating, either start it if necessary (with the
1548C<repeat> value), or reset the running timer to the C<repeat> value. 1920C<repeat> value), or reset the running timer to the C<repeat> value.
1549 1921
1550This sounds a bit complicated, see "Be smart about timeouts", above, for a 1922This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1551usage example. 1923usage example.
1924
1925=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1926
1927Returns the remaining time until a timer fires. If the timer is active,
1928then this time is relative to the current event loop time, otherwise it's
1929the timeout value currently configured.
1930
1931That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1932C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1933will return C<4>. When the timer expires and is restarted, it will return
1934roughly C<7> (likely slightly less as callback invocation takes some time,
1935too), and so on.
1552 1936
1553=item ev_tstamp repeat [read-write] 1937=item ev_tstamp repeat [read-write]
1554 1938
1555The current C<repeat> value. Will be used each time the watcher times out 1939The current C<repeat> value. Will be used each time the watcher times out
1556or C<ev_timer_again> is called, and determines the next timeout (if any), 1940or C<ev_timer_again> is called, and determines the next timeout (if any),
1582 } 1966 }
1583 1967
1584 ev_timer mytimer; 1968 ev_timer mytimer;
1585 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1969 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1586 ev_timer_again (&mytimer); /* start timer */ 1970 ev_timer_again (&mytimer); /* start timer */
1587 ev_loop (loop, 0); 1971 ev_run (loop, 0);
1588 1972
1589 // and in some piece of code that gets executed on any "activity": 1973 // and in some piece of code that gets executed on any "activity":
1590 // reset the timeout to start ticking again at 10 seconds 1974 // reset the timeout to start ticking again at 10 seconds
1591 ev_timer_again (&mytimer); 1975 ev_timer_again (&mytimer);
1592 1976
1594=head2 C<ev_periodic> - to cron or not to cron? 1978=head2 C<ev_periodic> - to cron or not to cron?
1595 1979
1596Periodic watchers are also timers of a kind, but they are very versatile 1980Periodic watchers are also timers of a kind, but they are very versatile
1597(and unfortunately a bit complex). 1981(and unfortunately a bit complex).
1598 1982
1599Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1983Unlike C<ev_timer>, periodic watchers are not based on real time (or
1600but on wall clock time (absolute time). You can tell a periodic watcher 1984relative time, the physical time that passes) but on wall clock time
1601to trigger after some specific point in time. For example, if you tell a 1985(absolute time, the thing you can read on your calender or clock). The
1602periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 1986difference is that wall clock time can run faster or slower than real
1603+ 10.>, that is, an absolute time not a delay) and then reset your system 1987time, and time jumps are not uncommon (e.g. when you adjust your
1604clock to January of the previous year, then it will take more than year 1988wrist-watch).
1605to trigger the event (unlike an C<ev_timer>, which would still trigger
1606roughly 10 seconds later as it uses a relative timeout).
1607 1989
1990You can tell a periodic watcher to trigger after some specific point
1991in time: for example, if you tell a periodic watcher to trigger "in 10
1992seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1993not a delay) and then reset your system clock to January of the previous
1994year, then it will take a year or more to trigger the event (unlike an
1995C<ev_timer>, which would still trigger roughly 10 seconds after starting
1996it, as it uses a relative timeout).
1997
1608C<ev_periodic>s can also be used to implement vastly more complex timers, 1998C<ev_periodic> watchers can also be used to implement vastly more complex
1609such as triggering an event on each "midnight, local time", or other 1999timers, such as triggering an event on each "midnight, local time", or
1610complicated rules. 2000other complicated rules. This cannot be done with C<ev_timer> watchers, as
2001those cannot react to time jumps.
1611 2002
1612As with timers, the callback is guaranteed to be invoked only when the 2003As with timers, the callback is guaranteed to be invoked only when the
1613time (C<at>) has passed, but if multiple periodic timers become ready 2004point in time where it is supposed to trigger has passed. If multiple
1614during the same loop iteration, then order of execution is undefined. 2005timers become ready during the same loop iteration then the ones with
2006earlier time-out values are invoked before ones with later time-out values
2007(but this is no longer true when a callback calls C<ev_run> recursively).
1615 2008
1616=head3 Watcher-Specific Functions and Data Members 2009=head3 Watcher-Specific Functions and Data Members
1617 2010
1618=over 4 2011=over 4
1619 2012
1620=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 2013=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1621 2014
1622=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 2015=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1623 2016
1624Lots of arguments, lets sort it out... There are basically three modes of 2017Lots of arguments, let's sort it out... There are basically three modes of
1625operation, and we will explain them from simplest to most complex: 2018operation, and we will explain them from simplest to most complex:
1626 2019
1627=over 4 2020=over 4
1628 2021
1629=item * absolute timer (at = time, interval = reschedule_cb = 0) 2022=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1630 2023
1631In this configuration the watcher triggers an event after the wall clock 2024In this configuration the watcher triggers an event after the wall clock
1632time C<at> has passed. It will not repeat and will not adjust when a time 2025time C<offset> has passed. It will not repeat and will not adjust when a
1633jump occurs, that is, if it is to be run at January 1st 2011 then it will 2026time jump occurs, that is, if it is to be run at January 1st 2011 then it
1634only run when the system clock reaches or surpasses this time. 2027will be stopped and invoked when the system clock reaches or surpasses
2028this point in time.
1635 2029
1636=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 2030=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1637 2031
1638In this mode the watcher will always be scheduled to time out at the next 2032In this mode the watcher will always be scheduled to time out at the next
1639C<at + N * interval> time (for some integer N, which can also be negative) 2033C<offset + N * interval> time (for some integer N, which can also be
1640and then repeat, regardless of any time jumps. 2034negative) and then repeat, regardless of any time jumps. The C<offset>
2035argument is merely an offset into the C<interval> periods.
1641 2036
1642This can be used to create timers that do not drift with respect to the 2037This can be used to create timers that do not drift with respect to the
1643system clock, for example, here is a C<ev_periodic> that triggers each 2038system clock, for example, here is an C<ev_periodic> that triggers each
1644hour, on the hour: 2039hour, on the hour (with respect to UTC):
1645 2040
1646 ev_periodic_set (&periodic, 0., 3600., 0); 2041 ev_periodic_set (&periodic, 0., 3600., 0);
1647 2042
1648This doesn't mean there will always be 3600 seconds in between triggers, 2043This doesn't mean there will always be 3600 seconds in between triggers,
1649but only that the callback will be called when the system time shows a 2044but only that the callback will be called when the system time shows a
1650full hour (UTC), or more correctly, when the system time is evenly divisible 2045full hour (UTC), or more correctly, when the system time is evenly divisible
1651by 3600. 2046by 3600.
1652 2047
1653Another way to think about it (for the mathematically inclined) is that 2048Another way to think about it (for the mathematically inclined) is that
1654C<ev_periodic> will try to run the callback in this mode at the next possible 2049C<ev_periodic> will try to run the callback in this mode at the next possible
1655time where C<time = at (mod interval)>, regardless of any time jumps. 2050time where C<time = offset (mod interval)>, regardless of any time jumps.
1656 2051
1657For numerical stability it is preferable that the C<at> value is near 2052For numerical stability it is preferable that the C<offset> value is near
1658C<ev_now ()> (the current time), but there is no range requirement for 2053C<ev_now ()> (the current time), but there is no range requirement for
1659this value, and in fact is often specified as zero. 2054this value, and in fact is often specified as zero.
1660 2055
1661Note also that there is an upper limit to how often a timer can fire (CPU 2056Note also that there is an upper limit to how often a timer can fire (CPU
1662speed for example), so if C<interval> is very small then timing stability 2057speed for example), so if C<interval> is very small then timing stability
1663will of course deteriorate. Libev itself tries to be exact to be about one 2058will of course deteriorate. Libev itself tries to be exact to be about one
1664millisecond (if the OS supports it and the machine is fast enough). 2059millisecond (if the OS supports it and the machine is fast enough).
1665 2060
1666=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 2061=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1667 2062
1668In this mode the values for C<interval> and C<at> are both being 2063In this mode the values for C<interval> and C<offset> are both being
1669ignored. Instead, each time the periodic watcher gets scheduled, the 2064ignored. Instead, each time the periodic watcher gets scheduled, the
1670reschedule callback will be called with the watcher as first, and the 2065reschedule callback will be called with the watcher as first, and the
1671current time as second argument. 2066current time as second argument.
1672 2067
1673NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 2068NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1674ever, or make ANY event loop modifications whatsoever>. 2069or make ANY other event loop modifications whatsoever, unless explicitly
2070allowed by documentation here>.
1675 2071
1676If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 2072If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1677it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 2073it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1678only event loop modification you are allowed to do). 2074only event loop modification you are allowed to do).
1679 2075
1709a different time than the last time it was called (e.g. in a crond like 2105a different time than the last time it was called (e.g. in a crond like
1710program when the crontabs have changed). 2106program when the crontabs have changed).
1711 2107
1712=item ev_tstamp ev_periodic_at (ev_periodic *) 2108=item ev_tstamp ev_periodic_at (ev_periodic *)
1713 2109
1714When active, returns the absolute time that the watcher is supposed to 2110When active, returns the absolute time that the watcher is supposed
1715trigger next. 2111to trigger next. This is not the same as the C<offset> argument to
2112C<ev_periodic_set>, but indeed works even in interval and manual
2113rescheduling modes.
1716 2114
1717=item ev_tstamp offset [read-write] 2115=item ev_tstamp offset [read-write]
1718 2116
1719When repeating, this contains the offset value, otherwise this is the 2117When repeating, this contains the offset value, otherwise this is the
1720absolute point in time (the C<at> value passed to C<ev_periodic_set>). 2118absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
2119although libev might modify this value for better numerical stability).
1721 2120
1722Can be modified any time, but changes only take effect when the periodic 2121Can be modified any time, but changes only take effect when the periodic
1723timer fires or C<ev_periodic_again> is being called. 2122timer fires or C<ev_periodic_again> is being called.
1724 2123
1725=item ev_tstamp interval [read-write] 2124=item ev_tstamp interval [read-write]
1741Example: Call a callback every hour, or, more precisely, whenever the 2140Example: Call a callback every hour, or, more precisely, whenever the
1742system time is divisible by 3600. The callback invocation times have 2141system time is divisible by 3600. The callback invocation times have
1743potentially a lot of jitter, but good long-term stability. 2142potentially a lot of jitter, but good long-term stability.
1744 2143
1745 static void 2144 static void
1746 clock_cb (struct ev_loop *loop, ev_io *w, int revents) 2145 clock_cb (struct ev_loop *loop, ev_periodic *w, int revents)
1747 { 2146 {
1748 ... its now a full hour (UTC, or TAI or whatever your clock follows) 2147 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1749 } 2148 }
1750 2149
1751 ev_periodic hourly_tick; 2150 ev_periodic hourly_tick;
1777Signal watchers will trigger an event when the process receives a specific 2176Signal watchers will trigger an event when the process receives a specific
1778signal one or more times. Even though signals are very asynchronous, libev 2177signal one or more times. Even though signals are very asynchronous, libev
1779will try it's best to deliver signals synchronously, i.e. as part of the 2178will try it's best to deliver signals synchronously, i.e. as part of the
1780normal event processing, like any other event. 2179normal event processing, like any other event.
1781 2180
1782If you want signals asynchronously, just use C<sigaction> as you would 2181If you want signals to be delivered truly asynchronously, just use
1783do without libev and forget about sharing the signal. You can even use 2182C<sigaction> as you would do without libev and forget about sharing
1784C<ev_async> from a signal handler to synchronously wake up an event loop. 2183the signal. You can even use C<ev_async> from a signal handler to
2184synchronously wake up an event loop.
1785 2185
1786You can configure as many watchers as you like per signal. Only when the 2186You can configure as many watchers as you like for the same signal, but
2187only within the same loop, i.e. you can watch for C<SIGINT> in your
2188default loop and for C<SIGIO> in another loop, but you cannot watch for
2189C<SIGINT> in both the default loop and another loop at the same time. At
2190the moment, C<SIGCHLD> is permanently tied to the default loop.
2191
1787first watcher gets started will libev actually register a signal handler 2192When the first watcher gets started will libev actually register something
1788with the kernel (thus it coexists with your own signal handlers as long as 2193with the kernel (thus it coexists with your own signal handlers as long as
1789you don't register any with libev for the same signal). Similarly, when 2194you don't register any with libev for the same signal).
1790the last signal watcher for a signal is stopped, libev will reset the
1791signal handler to SIG_DFL (regardless of what it was set to before).
1792 2195
1793If possible and supported, libev will install its handlers with 2196If possible and supported, libev will install its handlers with
1794C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2197C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1795interrupted. If you have a problem with system calls getting interrupted by 2198not be unduly interrupted. If you have a problem with system calls getting
1796signals you can block all signals in an C<ev_check> watcher and unblock 2199interrupted by signals you can block all signals in an C<ev_check> watcher
1797them in an C<ev_prepare> watcher. 2200and unblock them in an C<ev_prepare> watcher.
2201
2202=head3 The special problem of inheritance over fork/execve/pthread_create
2203
2204Both the signal mask (C<sigprocmask>) and the signal disposition
2205(C<sigaction>) are unspecified after starting a signal watcher (and after
2206stopping it again), that is, libev might or might not block the signal,
2207and might or might not set or restore the installed signal handler.
2208
2209While this does not matter for the signal disposition (libev never
2210sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2211C<execve>), this matters for the signal mask: many programs do not expect
2212certain signals to be blocked.
2213
2214This means that before calling C<exec> (from the child) you should reset
2215the signal mask to whatever "default" you expect (all clear is a good
2216choice usually).
2217
2218The simplest way to ensure that the signal mask is reset in the child is
2219to install a fork handler with C<pthread_atfork> that resets it. That will
2220catch fork calls done by libraries (such as the libc) as well.
2221
2222In current versions of libev, the signal will not be blocked indefinitely
2223unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2224the window of opportunity for problems, it will not go away, as libev
2225I<has> to modify the signal mask, at least temporarily.
2226
2227So I can't stress this enough: I<If you do not reset your signal mask when
2228you expect it to be empty, you have a race condition in your code>. This
2229is not a libev-specific thing, this is true for most event libraries.
1798 2230
1799=head3 Watcher-Specific Functions and Data Members 2231=head3 Watcher-Specific Functions and Data Members
1800 2232
1801=over 4 2233=over 4
1802 2234
1818Example: Try to exit cleanly on SIGINT. 2250Example: Try to exit cleanly on SIGINT.
1819 2251
1820 static void 2252 static void
1821 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2253 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1822 { 2254 {
1823 ev_unloop (loop, EVUNLOOP_ALL); 2255 ev_break (loop, EVBREAK_ALL);
1824 } 2256 }
1825 2257
1826 ev_signal signal_watcher; 2258 ev_signal signal_watcher;
1827 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 2259 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1828 ev_signal_start (loop, &signal_watcher); 2260 ev_signal_start (loop, &signal_watcher);
1834some child status changes (most typically when a child of yours dies or 2266some child status changes (most typically when a child of yours dies or
1835exits). It is permissible to install a child watcher I<after> the child 2267exits). It is permissible to install a child watcher I<after> the child
1836has been forked (which implies it might have already exited), as long 2268has been forked (which implies it might have already exited), as long
1837as the event loop isn't entered (or is continued from a watcher), i.e., 2269as the event loop isn't entered (or is continued from a watcher), i.e.,
1838forking and then immediately registering a watcher for the child is fine, 2270forking and then immediately registering a watcher for the child is fine,
1839but forking and registering a watcher a few event loop iterations later is 2271but forking and registering a watcher a few event loop iterations later or
1840not. 2272in the next callback invocation is not.
1841 2273
1842Only the default event loop is capable of handling signals, and therefore 2274Only the default event loop is capable of handling signals, and therefore
1843you can only register child watchers in the default event loop. 2275you can only register child watchers in the default event loop.
1844 2276
2277Due to some design glitches inside libev, child watchers will always be
2278handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2279libev)
2280
1845=head3 Process Interaction 2281=head3 Process Interaction
1846 2282
1847Libev grabs C<SIGCHLD> as soon as the default event loop is 2283Libev grabs C<SIGCHLD> as soon as the default event loop is
1848initialised. This is necessary to guarantee proper behaviour even if 2284initialised. This is necessary to guarantee proper behaviour even if the
1849the first child watcher is started after the child exits. The occurrence 2285first child watcher is started after the child exits. The occurrence
1850of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2286of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1851synchronously as part of the event loop processing. Libev always reaps all 2287synchronously as part of the event loop processing. Libev always reaps all
1852children, even ones not watched. 2288children, even ones not watched.
1853 2289
1854=head3 Overriding the Built-In Processing 2290=head3 Overriding the Built-In Processing
1864=head3 Stopping the Child Watcher 2300=head3 Stopping the Child Watcher
1865 2301
1866Currently, the child watcher never gets stopped, even when the 2302Currently, the child watcher never gets stopped, even when the
1867child terminates, so normally one needs to stop the watcher in the 2303child terminates, so normally one needs to stop the watcher in the
1868callback. Future versions of libev might stop the watcher automatically 2304callback. Future versions of libev might stop the watcher automatically
1869when a child exit is detected. 2305when a child exit is detected (calling C<ev_child_stop> twice is not a
2306problem).
1870 2307
1871=head3 Watcher-Specific Functions and Data Members 2308=head3 Watcher-Specific Functions and Data Members
1872 2309
1873=over 4 2310=over 4
1874 2311
2010the process. The exception are C<ev_stat> watchers - those call C<stat 2447the process. The exception are C<ev_stat> watchers - those call C<stat
2011()>, which is a synchronous operation. 2448()>, which is a synchronous operation.
2012 2449
2013For local paths, this usually doesn't matter: unless the system is very 2450For local paths, this usually doesn't matter: unless the system is very
2014busy or the intervals between stat's are large, a stat call will be fast, 2451busy or the intervals between stat's are large, a stat call will be fast,
2015as the path data is suually in memory already (except when starting the 2452as the path data is usually in memory already (except when starting the
2016watcher). 2453watcher).
2017 2454
2018For networked file systems, calling C<stat ()> can block an indefinite 2455For networked file systems, calling C<stat ()> can block an indefinite
2019time due to network issues, and even under good conditions, a stat call 2456time due to network issues, and even under good conditions, a stat call
2020often takes multiple milliseconds. 2457often takes multiple milliseconds.
2177 2614
2178=head3 Watcher-Specific Functions and Data Members 2615=head3 Watcher-Specific Functions and Data Members
2179 2616
2180=over 4 2617=over 4
2181 2618
2182=item ev_idle_init (ev_signal *, callback) 2619=item ev_idle_init (ev_idle *, callback)
2183 2620
2184Initialises and configures the idle watcher - it has no parameters of any 2621Initialises and configures the idle watcher - it has no parameters of any
2185kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2622kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2186believe me. 2623believe me.
2187 2624
2200 // no longer anything immediate to do. 2637 // no longer anything immediate to do.
2201 } 2638 }
2202 2639
2203 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 2640 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2204 ev_idle_init (idle_watcher, idle_cb); 2641 ev_idle_init (idle_watcher, idle_cb);
2205 ev_idle_start (loop, idle_cb); 2642 ev_idle_start (loop, idle_watcher);
2206 2643
2207 2644
2208=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2645=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2209 2646
2210Prepare and check watchers are usually (but not always) used in pairs: 2647Prepare and check watchers are usually (but not always) used in pairs:
2211prepare watchers get invoked before the process blocks and check watchers 2648prepare watchers get invoked before the process blocks and check watchers
2212afterwards. 2649afterwards.
2213 2650
2214You I<must not> call C<ev_loop> or similar functions that enter 2651You I<must not> call C<ev_run> or similar functions that enter
2215the current event loop from either C<ev_prepare> or C<ev_check> 2652the current event loop from either C<ev_prepare> or C<ev_check>
2216watchers. Other loops than the current one are fine, however. The 2653watchers. Other loops than the current one are fine, however. The
2217rationale behind this is that you do not need to check for recursion in 2654rationale behind this is that you do not need to check for recursion in
2218those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2655those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
2219C<ev_check> so if you have one watcher of each kind they will always be 2656C<ev_check> so if you have one watcher of each kind they will always be
2303 struct pollfd fds [nfd]; 2740 struct pollfd fds [nfd];
2304 // actual code will need to loop here and realloc etc. 2741 // actual code will need to loop here and realloc etc.
2305 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2742 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2306 2743
2307 /* the callback is illegal, but won't be called as we stop during check */ 2744 /* the callback is illegal, but won't be called as we stop during check */
2308 ev_timer_init (&tw, 0, timeout * 1e-3); 2745 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2309 ev_timer_start (loop, &tw); 2746 ev_timer_start (loop, &tw);
2310 2747
2311 // create one ev_io per pollfd 2748 // create one ev_io per pollfd
2312 for (int i = 0; i < nfd; ++i) 2749 for (int i = 0; i < nfd; ++i)
2313 { 2750 {
2387 2824
2388 if (timeout >= 0) 2825 if (timeout >= 0)
2389 // create/start timer 2826 // create/start timer
2390 2827
2391 // poll 2828 // poll
2392 ev_loop (EV_A_ 0); 2829 ev_run (EV_A_ 0);
2393 2830
2394 // stop timer again 2831 // stop timer again
2395 if (timeout >= 0) 2832 if (timeout >= 0)
2396 ev_timer_stop (EV_A_ &to); 2833 ev_timer_stop (EV_A_ &to);
2397 2834
2426some fds have to be watched and handled very quickly (with low latency), 2863some fds have to be watched and handled very quickly (with low latency),
2427and even priorities and idle watchers might have too much overhead. In 2864and even priorities and idle watchers might have too much overhead. In
2428this case you would put all the high priority stuff in one loop and all 2865this case you would put all the high priority stuff in one loop and all
2429the rest in a second one, and embed the second one in the first. 2866the rest in a second one, and embed the second one in the first.
2430 2867
2431As long as the watcher is active, the callback will be invoked every time 2868As long as the watcher is active, the callback will be invoked every
2432there might be events pending in the embedded loop. The callback must then 2869time there might be events pending in the embedded loop. The callback
2433call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2870must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2434their callbacks (you could also start an idle watcher to give the embedded 2871sweep and invoke their callbacks (the callback doesn't need to invoke the
2435loop strictly lower priority for example). You can also set the callback 2872C<ev_embed_sweep> function directly, it could also start an idle watcher
2436to C<0>, in which case the embed watcher will automatically execute the 2873to give the embedded loop strictly lower priority for example).
2437embedded loop sweep.
2438 2874
2439As long as the watcher is started it will automatically handle events. The 2875You can also set the callback to C<0>, in which case the embed watcher
2440callback will be invoked whenever some events have been handled. You can 2876will automatically execute the embedded loop sweep whenever necessary.
2441set the callback to C<0> to avoid having to specify one if you are not
2442interested in that.
2443 2877
2444Also, there have not currently been made special provisions for forking: 2878Fork detection will be handled transparently while the C<ev_embed> watcher
2445when you fork, you not only have to call C<ev_loop_fork> on both loops, 2879is active, i.e., the embedded loop will automatically be forked when the
2446but you will also have to stop and restart any C<ev_embed> watchers 2880embedding loop forks. In other cases, the user is responsible for calling
2447yourself - but you can use a fork watcher to handle this automatically, 2881C<ev_loop_fork> on the embedded loop.
2448and future versions of libev might do just that.
2449 2882
2450Unfortunately, not all backends are embeddable: only the ones returned by 2883Unfortunately, not all backends are embeddable: only the ones returned by
2451C<ev_embeddable_backends> are, which, unfortunately, does not include any 2884C<ev_embeddable_backends> are, which, unfortunately, does not include any
2452portable one. 2885portable one.
2453 2886
2479if you do not want that, you need to temporarily stop the embed watcher). 2912if you do not want that, you need to temporarily stop the embed watcher).
2480 2913
2481=item ev_embed_sweep (loop, ev_embed *) 2914=item ev_embed_sweep (loop, ev_embed *)
2482 2915
2483Make a single, non-blocking sweep over the embedded loop. This works 2916Make a single, non-blocking sweep over the embedded loop. This works
2484similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 2917similarly to C<ev_run (embedded_loop, EVRUN_NOWAIT)>, but in the most
2485appropriate way for embedded loops. 2918appropriate way for embedded loops.
2486 2919
2487=item struct ev_loop *other [read-only] 2920=item struct ev_loop *other [read-only]
2488 2921
2489The embedded event loop. 2922The embedded event loop.
2547event loop blocks next and before C<ev_check> watchers are being called, 2980event loop blocks next and before C<ev_check> watchers are being called,
2548and only in the child after the fork. If whoever good citizen calling 2981and only in the child after the fork. If whoever good citizen calling
2549C<ev_default_fork> cheats and calls it in the wrong process, the fork 2982C<ev_default_fork> cheats and calls it in the wrong process, the fork
2550handlers will be invoked, too, of course. 2983handlers will be invoked, too, of course.
2551 2984
2985=head3 The special problem of life after fork - how is it possible?
2986
2987Most uses of C<fork()> consist of forking, then some simple calls to set
2988up/change the process environment, followed by a call to C<exec()>. This
2989sequence should be handled by libev without any problems.
2990
2991This changes when the application actually wants to do event handling
2992in the child, or both parent in child, in effect "continuing" after the
2993fork.
2994
2995The default mode of operation (for libev, with application help to detect
2996forks) is to duplicate all the state in the child, as would be expected
2997when I<either> the parent I<or> the child process continues.
2998
2999When both processes want to continue using libev, then this is usually the
3000wrong result. In that case, usually one process (typically the parent) is
3001supposed to continue with all watchers in place as before, while the other
3002process typically wants to start fresh, i.e. without any active watchers.
3003
3004The cleanest and most efficient way to achieve that with libev is to
3005simply create a new event loop, which of course will be "empty", and
3006use that for new watchers. This has the advantage of not touching more
3007memory than necessary, and thus avoiding the copy-on-write, and the
3008disadvantage of having to use multiple event loops (which do not support
3009signal watchers).
3010
3011When this is not possible, or you want to use the default loop for
3012other reasons, then in the process that wants to start "fresh", call
3013C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
3014the default loop will "orphan" (not stop) all registered watchers, so you
3015have to be careful not to execute code that modifies those watchers. Note
3016also that in that case, you have to re-register any signal watchers.
3017
2552=head3 Watcher-Specific Functions and Data Members 3018=head3 Watcher-Specific Functions and Data Members
2553 3019
2554=over 4 3020=over 4
2555 3021
2556=item ev_fork_init (ev_signal *, callback) 3022=item ev_fork_init (ev_signal *, callback)
2560believe me. 3026believe me.
2561 3027
2562=back 3028=back
2563 3029
2564 3030
2565=head2 C<ev_async> - how to wake up another event loop 3031=head2 C<ev_async> - how to wake up an event loop
2566 3032
2567In general, you cannot use an C<ev_loop> from multiple threads or other 3033In general, you cannot use an C<ev_run> from multiple threads or other
2568asynchronous sources such as signal handlers (as opposed to multiple event 3034asynchronous sources such as signal handlers (as opposed to multiple event
2569loops - those are of course safe to use in different threads). 3035loops - those are of course safe to use in different threads).
2570 3036
2571Sometimes, however, you need to wake up another event loop you do not 3037Sometimes, however, you need to wake up an event loop you do not control,
2572control, for example because it belongs to another thread. This is what 3038for example because it belongs to another thread. This is what C<ev_async>
2573C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you 3039watchers do: as long as the C<ev_async> watcher is active, you can signal
2574can signal it by calling C<ev_async_send>, which is thread- and signal 3040it by calling C<ev_async_send>, which is thread- and signal safe.
2575safe.
2576 3041
2577This functionality is very similar to C<ev_signal> watchers, as signals, 3042This functionality is very similar to C<ev_signal> watchers, as signals,
2578too, are asynchronous in nature, and signals, too, will be compressed 3043too, are asynchronous in nature, and signals, too, will be compressed
2579(i.e. the number of callback invocations may be less than the number of 3044(i.e. the number of callback invocations may be less than the number of
2580C<ev_async_sent> calls). 3045C<ev_async_sent> calls).
2585=head3 Queueing 3050=head3 Queueing
2586 3051
2587C<ev_async> does not support queueing of data in any way. The reason 3052C<ev_async> does not support queueing of data in any way. The reason
2588is that the author does not know of a simple (or any) algorithm for a 3053is that the author does not know of a simple (or any) algorithm for a
2589multiple-writer-single-reader queue that works in all cases and doesn't 3054multiple-writer-single-reader queue that works in all cases and doesn't
2590need elaborate support such as pthreads. 3055need elaborate support such as pthreads or unportable memory access
3056semantics.
2591 3057
2592That means that if you want to queue data, you have to provide your own 3058That means that if you want to queue data, you have to provide your own
2593queue. But at least I can tell you how to implement locking around your 3059queue. But at least I can tell you how to implement locking around your
2594queue: 3060queue:
2595 3061
2684an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3150an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2685C<ev_feed_event>, this call is safe to do from other threads, signal or 3151C<ev_feed_event>, this call is safe to do from other threads, signal or
2686similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 3152similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2687section below on what exactly this means). 3153section below on what exactly this means).
2688 3154
3155Note that, as with other watchers in libev, multiple events might get
3156compressed into a single callback invocation (another way to look at this
3157is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
3158reset when the event loop detects that).
3159
2689This call incurs the overhead of a system call only once per loop iteration, 3160This call incurs the overhead of a system call only once per event loop
2690so while the overhead might be noticeable, it doesn't apply to repeated 3161iteration, so while the overhead might be noticeable, it doesn't apply to
2691calls to C<ev_async_send>. 3162repeated calls to C<ev_async_send> for the same event loop.
2692 3163
2693=item bool = ev_async_pending (ev_async *) 3164=item bool = ev_async_pending (ev_async *)
2694 3165
2695Returns a non-zero value when C<ev_async_send> has been called on the 3166Returns a non-zero value when C<ev_async_send> has been called on the
2696watcher but the event has not yet been processed (or even noted) by the 3167watcher but the event has not yet been processed (or even noted) by the
2699C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 3170C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2700the loop iterates next and checks for the watcher to have become active, 3171the loop iterates next and checks for the watcher to have become active,
2701it will reset the flag again. C<ev_async_pending> can be used to very 3172it will reset the flag again. C<ev_async_pending> can be used to very
2702quickly check whether invoking the loop might be a good idea. 3173quickly check whether invoking the loop might be a good idea.
2703 3174
2704Not that this does I<not> check whether the watcher itself is pending, only 3175Not that this does I<not> check whether the watcher itself is pending,
2705whether it has been requested to make this watcher pending. 3176only whether it has been requested to make this watcher pending: there
3177is a time window between the event loop checking and resetting the async
3178notification, and the callback being invoked.
2706 3179
2707=back 3180=back
2708 3181
2709 3182
2710=head1 OTHER FUNCTIONS 3183=head1 OTHER FUNCTIONS
2727 3200
2728If C<timeout> is less than 0, then no timeout watcher will be 3201If C<timeout> is less than 0, then no timeout watcher will be
2729started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3202started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2730repeat = 0) will be started. C<0> is a valid timeout. 3203repeat = 0) will be started. C<0> is a valid timeout.
2731 3204
2732The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3205The callback has the type C<void (*cb)(int revents, void *arg)> and is
2733passed an C<revents> set like normal event callbacks (a combination of 3206passed an C<revents> set like normal event callbacks (a combination of
2734C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3207C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
2735value passed to C<ev_once>. Note that it is possible to receive I<both> 3208value passed to C<ev_once>. Note that it is possible to receive I<both>
2736a timeout and an io event at the same time - you probably should give io 3209a timeout and an io event at the same time - you probably should give io
2737events precedence. 3210events precedence.
2738 3211
2739Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3212Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2740 3213
2741 static void stdin_ready (int revents, void *arg) 3214 static void stdin_ready (int revents, void *arg)
2742 { 3215 {
2743 if (revents & EV_READ) 3216 if (revents & EV_READ)
2744 /* stdin might have data for us, joy! */; 3217 /* stdin might have data for us, joy! */;
2745 else if (revents & EV_TIMEOUT) 3218 else if (revents & EV_TIMER)
2746 /* doh, nothing entered */; 3219 /* doh, nothing entered */;
2747 } 3220 }
2748 3221
2749 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3222 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2750 3223
2751=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2752
2753Feeds the given event set into the event loop, as if the specified event
2754had happened for the specified watcher (which must be a pointer to an
2755initialised but not necessarily started event watcher).
2756
2757=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3224=item ev_feed_fd_event (loop, int fd, int revents)
2758 3225
2759Feed an event on the given fd, as if a file descriptor backend detected 3226Feed an event on the given fd, as if a file descriptor backend detected
2760the given events it. 3227the given events it.
2761 3228
2762=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3229=item ev_feed_signal_event (loop, int signum)
2763 3230
2764Feed an event as if the given signal occurred (C<loop> must be the default 3231Feed an event as if the given signal occurred (C<loop> must be the default
2765loop!). 3232loop!).
2766 3233
2767=back 3234=back
2847 3314
2848=over 4 3315=over 4
2849 3316
2850=item ev::TYPE::TYPE () 3317=item ev::TYPE::TYPE ()
2851 3318
2852=item ev::TYPE::TYPE (struct ev_loop *) 3319=item ev::TYPE::TYPE (loop)
2853 3320
2854=item ev::TYPE::~TYPE 3321=item ev::TYPE::~TYPE
2855 3322
2856The constructor (optionally) takes an event loop to associate the watcher 3323The constructor (optionally) takes an event loop to associate the watcher
2857with. If it is omitted, it will use C<EV_DEFAULT>. 3324with. If it is omitted, it will use C<EV_DEFAULT>.
2889 3356
2890 myclass obj; 3357 myclass obj;
2891 ev::io iow; 3358 ev::io iow;
2892 iow.set <myclass, &myclass::io_cb> (&obj); 3359 iow.set <myclass, &myclass::io_cb> (&obj);
2893 3360
3361=item w->set (object *)
3362
3363This is a variation of a method callback - leaving out the method to call
3364will default the method to C<operator ()>, which makes it possible to use
3365functor objects without having to manually specify the C<operator ()> all
3366the time. Incidentally, you can then also leave out the template argument
3367list.
3368
3369The C<operator ()> method prototype must be C<void operator ()(watcher &w,
3370int revents)>.
3371
3372See the method-C<set> above for more details.
3373
3374Example: use a functor object as callback.
3375
3376 struct myfunctor
3377 {
3378 void operator() (ev::io &w, int revents)
3379 {
3380 ...
3381 }
3382 }
3383
3384 myfunctor f;
3385
3386 ev::io w;
3387 w.set (&f);
3388
2894=item w->set<function> (void *data = 0) 3389=item w->set<function> (void *data = 0)
2895 3390
2896Also sets a callback, but uses a static method or plain function as 3391Also sets a callback, but uses a static method or plain function as
2897callback. The optional C<data> argument will be stored in the watcher's 3392callback. The optional C<data> argument will be stored in the watcher's
2898C<data> member and is free for you to use. 3393C<data> member and is free for you to use.
2904Example: Use a plain function as callback. 3399Example: Use a plain function as callback.
2905 3400
2906 static void io_cb (ev::io &w, int revents) { } 3401 static void io_cb (ev::io &w, int revents) { }
2907 iow.set <io_cb> (); 3402 iow.set <io_cb> ();
2908 3403
2909=item w->set (struct ev_loop *) 3404=item w->set (loop)
2910 3405
2911Associates a different C<struct ev_loop> with this watcher. You can only 3406Associates a different C<struct ev_loop> with this watcher. You can only
2912do this when the watcher is inactive (and not pending either). 3407do this when the watcher is inactive (and not pending either).
2913 3408
2914=item w->set ([arguments]) 3409=item w->set ([arguments])
2915 3410
2916Basically the same as C<ev_TYPE_set>, with the same arguments. Must be 3411Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
2917called at least once. Unlike the C counterpart, an active watcher gets 3412method or a suitable start method must be called at least once. Unlike the
2918automatically stopped and restarted when reconfiguring it with this 3413C counterpart, an active watcher gets automatically stopped and restarted
2919method. 3414when reconfiguring it with this method.
2920 3415
2921=item w->start () 3416=item w->start ()
2922 3417
2923Starts the watcher. Note that there is no C<loop> argument, as the 3418Starts the watcher. Note that there is no C<loop> argument, as the
2924constructor already stores the event loop. 3419constructor already stores the event loop.
2925 3420
3421=item w->start ([arguments])
3422
3423Instead of calling C<set> and C<start> methods separately, it is often
3424convenient to wrap them in one call. Uses the same type of arguments as
3425the configure C<set> method of the watcher.
3426
2926=item w->stop () 3427=item w->stop ()
2927 3428
2928Stops the watcher if it is active. Again, no C<loop> argument. 3429Stops the watcher if it is active. Again, no C<loop> argument.
2929 3430
2930=item w->again () (C<ev::timer>, C<ev::periodic> only) 3431=item w->again () (C<ev::timer>, C<ev::periodic> only)
2942 3443
2943=back 3444=back
2944 3445
2945=back 3446=back
2946 3447
2947Example: Define a class with an IO and idle watcher, start one of them in 3448Example: Define a class with two I/O and idle watchers, start the I/O
2948the constructor. 3449watchers in the constructor.
2949 3450
2950 class myclass 3451 class myclass
2951 { 3452 {
2952 ev::io io ; void io_cb (ev::io &w, int revents); 3453 ev::io io ; void io_cb (ev::io &w, int revents);
3454 ev::io2 io2 ; void io2_cb (ev::io &w, int revents);
2953 ev::idle idle; void idle_cb (ev::idle &w, int revents); 3455 ev::idle idle; void idle_cb (ev::idle &w, int revents);
2954 3456
2955 myclass (int fd) 3457 myclass (int fd)
2956 { 3458 {
2957 io .set <myclass, &myclass::io_cb > (this); 3459 io .set <myclass, &myclass::io_cb > (this);
3460 io2 .set <myclass, &myclass::io2_cb > (this);
2958 idle.set <myclass, &myclass::idle_cb> (this); 3461 idle.set <myclass, &myclass::idle_cb> (this);
2959 3462
2960 io.start (fd, ev::READ); 3463 io.set (fd, ev::WRITE); // configure the watcher
3464 io.start (); // start it whenever convenient
3465
3466 io2.start (fd, ev::READ); // set + start in one call
2961 } 3467 }
2962 }; 3468 };
2963 3469
2964 3470
2965=head1 OTHER LANGUAGE BINDINGS 3471=head1 OTHER LANGUAGE BINDINGS
2984L<http://software.schmorp.de/pkg/EV>. 3490L<http://software.schmorp.de/pkg/EV>.
2985 3491
2986=item Python 3492=item Python
2987 3493
2988Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3494Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2989seems to be quite complete and well-documented. Note, however, that the 3495seems to be quite complete and well-documented.
2990patch they require for libev is outright dangerous as it breaks the ABI
2991for everybody else, and therefore, should never be applied in an installed
2992libev (if python requires an incompatible ABI then it needs to embed
2993libev).
2994 3496
2995=item Ruby 3497=item Ruby
2996 3498
2997Tony Arcieri has written a ruby extension that offers access to a subset 3499Tony Arcieri has written a ruby extension that offers access to a subset
2998of the libev API and adds file handle abstractions, asynchronous DNS and 3500of the libev API and adds file handle abstractions, asynchronous DNS and
2999more on top of it. It can be found via gem servers. Its homepage is at 3501more on top of it. It can be found via gem servers. Its homepage is at
3000L<http://rev.rubyforge.org/>. 3502L<http://rev.rubyforge.org/>.
3001 3503
3504Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3505makes rev work even on mingw.
3506
3507=item Haskell
3508
3509A haskell binding to libev is available at
3510L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3511
3002=item D 3512=item D
3003 3513
3004Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3514Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3005be found at L<http://proj.llucax.com.ar/wiki/evd>. 3515be found at L<http://proj.llucax.com.ar/wiki/evd>.
3006 3516
3007=item Ocaml 3517=item Ocaml
3008 3518
3009Erkki Seppala has written Ocaml bindings for libev, to be found at 3519Erkki Seppala has written Ocaml bindings for libev, to be found at
3010L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3520L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3521
3522=item Lua
3523
3524Brian Maher has written a partial interface to libev for lua (at the
3525time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3526L<http://github.com/brimworks/lua-ev>.
3011 3527
3012=back 3528=back
3013 3529
3014 3530
3015=head1 MACRO MAGIC 3531=head1 MACRO MAGIC
3029loop argument"). The C<EV_A> form is used when this is the sole argument, 3545loop argument"). The C<EV_A> form is used when this is the sole argument,
3030C<EV_A_> is used when other arguments are following. Example: 3546C<EV_A_> is used when other arguments are following. Example:
3031 3547
3032 ev_unref (EV_A); 3548 ev_unref (EV_A);
3033 ev_timer_add (EV_A_ watcher); 3549 ev_timer_add (EV_A_ watcher);
3034 ev_loop (EV_A_ 0); 3550 ev_run (EV_A_ 0);
3035 3551
3036It assumes the variable C<loop> of type C<struct ev_loop *> is in scope, 3552It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
3037which is often provided by the following macro. 3553which is often provided by the following macro.
3038 3554
3039=item C<EV_P>, C<EV_P_> 3555=item C<EV_P>, C<EV_P_>
3079 } 3595 }
3080 3596
3081 ev_check check; 3597 ev_check check;
3082 ev_check_init (&check, check_cb); 3598 ev_check_init (&check, check_cb);
3083 ev_check_start (EV_DEFAULT_ &check); 3599 ev_check_start (EV_DEFAULT_ &check);
3084 ev_loop (EV_DEFAULT_ 0); 3600 ev_run (EV_DEFAULT_ 0);
3085 3601
3086=head1 EMBEDDING 3602=head1 EMBEDDING
3087 3603
3088Libev can (and often is) directly embedded into host 3604Libev can (and often is) directly embedded into host
3089applications. Examples of applications that embed it include the Deliantra 3605applications. Examples of applications that embed it include the Deliantra
3169 libev.m4 3685 libev.m4
3170 3686
3171=head2 PREPROCESSOR SYMBOLS/MACROS 3687=head2 PREPROCESSOR SYMBOLS/MACROS
3172 3688
3173Libev can be configured via a variety of preprocessor symbols you have to 3689Libev can be configured via a variety of preprocessor symbols you have to
3174define before including any of its files. The default in the absence of 3690define before including (or compiling) any of its files. The default in
3175autoconf is documented for every option. 3691the absence of autoconf is documented for every option.
3692
3693Symbols marked with "(h)" do not change the ABI, and can have different
3694values when compiling libev vs. including F<ev.h>, so it is permissible
3695to redefine them before including F<ev.h> without breaking compatibility
3696to a compiled library. All other symbols change the ABI, which means all
3697users of libev and the libev code itself must be compiled with compatible
3698settings.
3176 3699
3177=over 4 3700=over 4
3178 3701
3702=item EV_COMPAT3 (h)
3703
3704Backwards compatibility is a major concern for libev. This is why this
3705release of libev comes with wrappers for the functions and symbols that
3706have been renamed between libev version 3 and 4.
3707
3708You can disable these wrappers (to test compatibility with future
3709versions) by defining C<EV_COMPAT3> to C<0> when compiling your
3710sources. This has the additional advantage that you can drop the C<struct>
3711from C<struct ev_loop> declarations, as libev will provide an C<ev_loop>
3712typedef in that case.
3713
3714In some future version, the default for C<EV_COMPAT3> will become C<0>,
3715and in some even more future version the compatibility code will be
3716removed completely.
3717
3179=item EV_STANDALONE 3718=item EV_STANDALONE (h)
3180 3719
3181Must always be C<1> if you do not use autoconf configuration, which 3720Must always be C<1> if you do not use autoconf configuration, which
3182keeps libev from including F<config.h>, and it also defines dummy 3721keeps libev from including F<config.h>, and it also defines dummy
3183implementations for some libevent functions (such as logging, which is not 3722implementations for some libevent functions (such as logging, which is not
3184supported). It will also not define any of the structs usually found in 3723supported). It will also not define any of the structs usually found in
3185F<event.h> that are not directly supported by the libev core alone. 3724F<event.h> that are not directly supported by the libev core alone.
3186 3725
3726In standalone mode, libev will still try to automatically deduce the
3727configuration, but has to be more conservative.
3728
3187=item EV_USE_MONOTONIC 3729=item EV_USE_MONOTONIC
3188 3730
3189If defined to be C<1>, libev will try to detect the availability of the 3731If defined to be C<1>, libev will try to detect the availability of the
3190monotonic clock option at both compile time and runtime. Otherwise no use 3732monotonic clock option at both compile time and runtime. Otherwise no
3191of the monotonic clock option will be attempted. If you enable this, you 3733use of the monotonic clock option will be attempted. If you enable this,
3192usually have to link against librt or something similar. Enabling it when 3734you usually have to link against librt or something similar. Enabling it
3193the functionality isn't available is safe, though, although you have 3735when the functionality isn't available is safe, though, although you have
3194to make sure you link against any libraries where the C<clock_gettime> 3736to make sure you link against any libraries where the C<clock_gettime>
3195function is hiding in (often F<-lrt>). 3737function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3196 3738
3197=item EV_USE_REALTIME 3739=item EV_USE_REALTIME
3198 3740
3199If defined to be C<1>, libev will try to detect the availability of the 3741If defined to be C<1>, libev will try to detect the availability of the
3200real-time clock option at compile time (and assume its availability at 3742real-time clock option at compile time (and assume its availability
3201runtime if successful). Otherwise no use of the real-time clock option will 3743at runtime if successful). Otherwise no use of the real-time clock
3202be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3744option will be attempted. This effectively replaces C<gettimeofday>
3203(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3745by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3204note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3746correctness. See the note about libraries in the description of
3747C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3748C<EV_USE_CLOCK_SYSCALL>.
3749
3750=item EV_USE_CLOCK_SYSCALL
3751
3752If defined to be C<1>, libev will try to use a direct syscall instead
3753of calling the system-provided C<clock_gettime> function. This option
3754exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3755unconditionally pulls in C<libpthread>, slowing down single-threaded
3756programs needlessly. Using a direct syscall is slightly slower (in
3757theory), because no optimised vdso implementation can be used, but avoids
3758the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3759higher, as it simplifies linking (no need for C<-lrt>).
3205 3760
3206=item EV_USE_NANOSLEEP 3761=item EV_USE_NANOSLEEP
3207 3762
3208If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3763If defined to be C<1>, libev will assume that C<nanosleep ()> is available
3209and will use it for delays. Otherwise it will use C<select ()>. 3764and will use it for delays. Otherwise it will use C<select ()>.
3225 3780
3226=item EV_SELECT_USE_FD_SET 3781=item EV_SELECT_USE_FD_SET
3227 3782
3228If defined to C<1>, then the select backend will use the system C<fd_set> 3783If defined to C<1>, then the select backend will use the system C<fd_set>
3229structure. This is useful if libev doesn't compile due to a missing 3784structure. This is useful if libev doesn't compile due to a missing
3230C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on 3785C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
3231exotic systems. This usually limits the range of file descriptors to some 3786on exotic systems. This usually limits the range of file descriptors to
3232low limit such as 1024 or might have other limitations (winsocket only 3787some low limit such as 1024 or might have other limitations (winsocket
3233allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3788only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
3234influence the size of the C<fd_set> used. 3789configures the maximum size of the C<fd_set>.
3235 3790
3236=item EV_SELECT_IS_WINSOCKET 3791=item EV_SELECT_IS_WINSOCKET
3237 3792
3238When defined to C<1>, the select backend will assume that 3793When defined to C<1>, the select backend will assume that
3239select/socket/connect etc. don't understand file descriptors but 3794select/socket/connect etc. don't understand file descriptors but
3241be used is the winsock select). This means that it will call 3796be used is the winsock select). This means that it will call
3242C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3797C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3243it is assumed that all these functions actually work on fds, even 3798it is assumed that all these functions actually work on fds, even
3244on win32. Should not be defined on non-win32 platforms. 3799on win32. Should not be defined on non-win32 platforms.
3245 3800
3246=item EV_FD_TO_WIN32_HANDLE 3801=item EV_FD_TO_WIN32_HANDLE(fd)
3247 3802
3248If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3803If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3249file descriptors to socket handles. When not defining this symbol (the 3804file descriptors to socket handles. When not defining this symbol (the
3250default), then libev will call C<_get_osfhandle>, which is usually 3805default), then libev will call C<_get_osfhandle>, which is usually
3251correct. In some cases, programs use their own file descriptor management, 3806correct. In some cases, programs use their own file descriptor management,
3252in which case they can provide this function to map fds to socket handles. 3807in which case they can provide this function to map fds to socket handles.
3808
3809=item EV_WIN32_HANDLE_TO_FD(handle)
3810
3811If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3812using the standard C<_open_osfhandle> function. For programs implementing
3813their own fd to handle mapping, overwriting this function makes it easier
3814to do so. This can be done by defining this macro to an appropriate value.
3815
3816=item EV_WIN32_CLOSE_FD(fd)
3817
3818If programs implement their own fd to handle mapping on win32, then this
3819macro can be used to override the C<close> function, useful to unregister
3820file descriptors again. Note that the replacement function has to close
3821the underlying OS handle.
3253 3822
3254=item EV_USE_POLL 3823=item EV_USE_POLL
3255 3824
3256If defined to be C<1>, libev will compile in support for the C<poll>(2) 3825If defined to be C<1>, libev will compile in support for the C<poll>(2)
3257backend. Otherwise it will be enabled on non-win32 platforms. It 3826backend. Otherwise it will be enabled on non-win32 platforms. It
3304as well as for signal and thread safety in C<ev_async> watchers. 3873as well as for signal and thread safety in C<ev_async> watchers.
3305 3874
3306In the absence of this define, libev will use C<sig_atomic_t volatile> 3875In the absence of this define, libev will use C<sig_atomic_t volatile>
3307(from F<signal.h>), which is usually good enough on most platforms. 3876(from F<signal.h>), which is usually good enough on most platforms.
3308 3877
3309=item EV_H 3878=item EV_H (h)
3310 3879
3311The name of the F<ev.h> header file used to include it. The default if 3880The name of the F<ev.h> header file used to include it. The default if
3312undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3881undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3313used to virtually rename the F<ev.h> header file in case of conflicts. 3882used to virtually rename the F<ev.h> header file in case of conflicts.
3314 3883
3315=item EV_CONFIG_H 3884=item EV_CONFIG_H (h)
3316 3885
3317If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3886If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3318F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3887F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3319C<EV_H>, above. 3888C<EV_H>, above.
3320 3889
3321=item EV_EVENT_H 3890=item EV_EVENT_H (h)
3322 3891
3323Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3892Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3324of how the F<event.h> header can be found, the default is C<"event.h">. 3893of how the F<event.h> header can be found, the default is C<"event.h">.
3325 3894
3326=item EV_PROTOTYPES 3895=item EV_PROTOTYPES (h)
3327 3896
3328If defined to be C<0>, then F<ev.h> will not define any function 3897If defined to be C<0>, then F<ev.h> will not define any function
3329prototypes, but still define all the structs and other symbols. This is 3898prototypes, but still define all the structs and other symbols. This is
3330occasionally useful if you want to provide your own wrapper functions 3899occasionally useful if you want to provide your own wrapper functions
3331around libev functions. 3900around libev functions.
3353fine. 3922fine.
3354 3923
3355If your embedding application does not need any priorities, defining these 3924If your embedding application does not need any priorities, defining these
3356both to C<0> will save some memory and CPU. 3925both to C<0> will save some memory and CPU.
3357 3926
3358=item EV_PERIODIC_ENABLE 3927=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3928EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3929EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3359 3930
3360If undefined or defined to be C<1>, then periodic timers are supported. If 3931If undefined or defined to be C<1> (and the platform supports it), then
3361defined to be C<0>, then they are not. Disabling them saves a few kB of 3932the respective watcher type is supported. If defined to be C<0>, then it
3362code. 3933is not. Disabling watcher types mainly saves code size.
3363 3934
3364=item EV_IDLE_ENABLE 3935=item EV_FEATURES
3365
3366If undefined or defined to be C<1>, then idle watchers are supported. If
3367defined to be C<0>, then they are not. Disabling them saves a few kB of
3368code.
3369
3370=item EV_EMBED_ENABLE
3371
3372If undefined or defined to be C<1>, then embed watchers are supported. If
3373defined to be C<0>, then they are not. Embed watchers rely on most other
3374watcher types, which therefore must not be disabled.
3375
3376=item EV_STAT_ENABLE
3377
3378If undefined or defined to be C<1>, then stat watchers are supported. If
3379defined to be C<0>, then they are not.
3380
3381=item EV_FORK_ENABLE
3382
3383If undefined or defined to be C<1>, then fork watchers are supported. If
3384defined to be C<0>, then they are not.
3385
3386=item EV_ASYNC_ENABLE
3387
3388If undefined or defined to be C<1>, then async watchers are supported. If
3389defined to be C<0>, then they are not.
3390
3391=item EV_MINIMAL
3392 3936
3393If you need to shave off some kilobytes of code at the expense of some 3937If you need to shave off some kilobytes of code at the expense of some
3394speed, define this symbol to C<1>. Currently this is used to override some 3938speed (but with the full API), you can define this symbol to request
3395inlining decisions, saves roughly 30% code size on amd64. It also selects a 3939certain subsets of functionality. The default is to enable all features
3396much smaller 2-heap for timer management over the default 4-heap. 3940that can be enabled on the platform.
3941
3942A typical way to use this symbol is to define it to C<0> (or to a bitset
3943with some broad features you want) and then selectively re-enable
3944additional parts you want, for example if you want everything minimal,
3945but multiple event loop support, async and child watchers and the poll
3946backend, use this:
3947
3948 #define EV_FEATURES 0
3949 #define EV_MULTIPLICITY 1
3950 #define EV_USE_POLL 1
3951 #define EV_CHILD_ENABLE 1
3952 #define EV_ASYNC_ENABLE 1
3953
3954The actual value is a bitset, it can be a combination of the following
3955values:
3956
3957=over 4
3958
3959=item C<1> - faster/larger code
3960
3961Use larger code to speed up some operations.
3962
3963Currently this is used to override some inlining decisions (enlarging the
3964code size by roughly 30% on amd64).
3965
3966When optimising for size, use of compiler flags such as C<-Os> with
3967gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
3968assertions.
3969
3970=item C<2> - faster/larger data structures
3971
3972Replaces the small 2-heap for timer management by a faster 4-heap, larger
3973hash table sizes and so on. This will usually further increase code size
3974and can additionally have an effect on the size of data structures at
3975runtime.
3976
3977=item C<4> - full API configuration
3978
3979This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3980enables multiplicity (C<EV_MULTIPLICITY>=1).
3981
3982=item C<8> - full API
3983
3984This enables a lot of the "lesser used" API functions. See C<ev.h> for
3985details on which parts of the API are still available without this
3986feature, and do not complain if this subset changes over time.
3987
3988=item C<16> - enable all optional watcher types
3989
3990Enables all optional watcher types. If you want to selectively enable
3991only some watcher types other than I/O and timers (e.g. prepare,
3992embed, async, child...) you can enable them manually by defining
3993C<EV_watchertype_ENABLE> to C<1> instead.
3994
3995=item C<32> - enable all backends
3996
3997This enables all backends - without this feature, you need to enable at
3998least one backend manually (C<EV_USE_SELECT> is a good choice).
3999
4000=item C<64> - enable OS-specific "helper" APIs
4001
4002Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
4003default.
4004
4005=back
4006
4007Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
4008reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
4009code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
4010watchers, timers and monotonic clock support.
4011
4012With an intelligent-enough linker (gcc+binutils are intelligent enough
4013when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
4014your program might be left out as well - a binary starting a timer and an
4015I/O watcher then might come out at only 5Kb.
4016
4017=item EV_AVOID_STDIO
4018
4019If this is set to C<1> at compiletime, then libev will avoid using stdio
4020functions (printf, scanf, perror etc.). This will increase the code size
4021somewhat, but if your program doesn't otherwise depend on stdio and your
4022libc allows it, this avoids linking in the stdio library which is quite
4023big.
4024
4025Note that error messages might become less precise when this option is
4026enabled.
4027
4028=item EV_NSIG
4029
4030The highest supported signal number, +1 (or, the number of
4031signals): Normally, libev tries to deduce the maximum number of signals
4032automatically, but sometimes this fails, in which case it can be
4033specified. Also, using a lower number than detected (C<32> should be
4034good for about any system in existence) can save some memory, as libev
4035statically allocates some 12-24 bytes per signal number.
3397 4036
3398=item EV_PID_HASHSIZE 4037=item EV_PID_HASHSIZE
3399 4038
3400C<ev_child> watchers use a small hash table to distribute workload by 4039C<ev_child> watchers use a small hash table to distribute workload by
3401pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 4040pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3402than enough. If you need to manage thousands of children you might want to 4041usually more than enough. If you need to manage thousands of children you
3403increase this value (I<must> be a power of two). 4042might want to increase this value (I<must> be a power of two).
3404 4043
3405=item EV_INOTIFY_HASHSIZE 4044=item EV_INOTIFY_HASHSIZE
3406 4045
3407C<ev_stat> watchers use a small hash table to distribute workload by 4046C<ev_stat> watchers use a small hash table to distribute workload by
3408inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4047inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3409usually more than enough. If you need to manage thousands of C<ev_stat> 4048disabled), usually more than enough. If you need to manage thousands of
3410watchers you might want to increase this value (I<must> be a power of 4049C<ev_stat> watchers you might want to increase this value (I<must> be a
3411two). 4050power of two).
3412 4051
3413=item EV_USE_4HEAP 4052=item EV_USE_4HEAP
3414 4053
3415Heaps are not very cache-efficient. To improve the cache-efficiency of the 4054Heaps are not very cache-efficient. To improve the cache-efficiency of the
3416timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4055timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3417to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4056to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3418faster performance with many (thousands) of watchers. 4057faster performance with many (thousands) of watchers.
3419 4058
3420The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4059The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3421(disabled). 4060will be C<0>.
3422 4061
3423=item EV_HEAP_CACHE_AT 4062=item EV_HEAP_CACHE_AT
3424 4063
3425Heaps are not very cache-efficient. To improve the cache-efficiency of the 4064Heaps are not very cache-efficient. To improve the cache-efficiency of the
3426timer and periodics heaps, libev can cache the timestamp (I<at>) within 4065timer and periodics heaps, libev can cache the timestamp (I<at>) within
3427the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4066the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3428which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4067which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3429but avoids random read accesses on heap changes. This improves performance 4068but avoids random read accesses on heap changes. This improves performance
3430noticeably with many (hundreds) of watchers. 4069noticeably with many (hundreds) of watchers.
3431 4070
3432The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4071The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3433(disabled). 4072will be C<0>.
3434 4073
3435=item EV_VERIFY 4074=item EV_VERIFY
3436 4075
3437Controls how much internal verification (see C<ev_loop_verify ()>) will 4076Controls how much internal verification (see C<ev_verify ()>) will
3438be done: If set to C<0>, no internal verification code will be compiled 4077be done: If set to C<0>, no internal verification code will be compiled
3439in. If set to C<1>, then verification code will be compiled in, but not 4078in. If set to C<1>, then verification code will be compiled in, but not
3440called. If set to C<2>, then the internal verification code will be 4079called. If set to C<2>, then the internal verification code will be
3441called once per loop, which can slow down libev. If set to C<3>, then the 4080called once per loop, which can slow down libev. If set to C<3>, then the
3442verification code will be called very frequently, which will slow down 4081verification code will be called very frequently, which will slow down
3443libev considerably. 4082libev considerably.
3444 4083
3445The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4084The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3446C<0>. 4085will be C<0>.
3447 4086
3448=item EV_COMMON 4087=item EV_COMMON
3449 4088
3450By default, all watchers have a C<void *data> member. By redefining 4089By default, all watchers have a C<void *data> member. By redefining
3451this macro to a something else you can include more and other types of 4090this macro to something else you can include more and other types of
3452members. You have to define it each time you include one of the files, 4091members. You have to define it each time you include one of the files,
3453though, and it must be identical each time. 4092though, and it must be identical each time.
3454 4093
3455For example, the perl EV module uses something like this: 4094For example, the perl EV module uses something like this:
3456 4095
3509file. 4148file.
3510 4149
3511The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4150The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3512that everybody includes and which overrides some configure choices: 4151that everybody includes and which overrides some configure choices:
3513 4152
3514 #define EV_MINIMAL 1 4153 #define EV_FEATURES 8
3515 #define EV_USE_POLL 0 4154 #define EV_USE_SELECT 1
3516 #define EV_MULTIPLICITY 0
3517 #define EV_PERIODIC_ENABLE 0 4155 #define EV_PREPARE_ENABLE 1
4156 #define EV_IDLE_ENABLE 1
3518 #define EV_STAT_ENABLE 0 4157 #define EV_SIGNAL_ENABLE 1
3519 #define EV_FORK_ENABLE 0 4158 #define EV_CHILD_ENABLE 1
4159 #define EV_USE_STDEXCEPT 0
3520 #define EV_CONFIG_H <config.h> 4160 #define EV_CONFIG_H <config.h>
3521 #define EV_MINPRI 0
3522 #define EV_MAXPRI 0
3523 4161
3524 #include "ev++.h" 4162 #include "ev++.h"
3525 4163
3526And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4164And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3527 4165
3587default loop and triggering an C<ev_async> watcher from the default loop 4225default loop and triggering an C<ev_async> watcher from the default loop
3588watcher callback into the event loop interested in the signal. 4226watcher callback into the event loop interested in the signal.
3589 4227
3590=back 4228=back
3591 4229
4230=head4 THREAD LOCKING EXAMPLE
4231
4232Here is a fictitious example of how to run an event loop in a different
4233thread than where callbacks are being invoked and watchers are
4234created/added/removed.
4235
4236For a real-world example, see the C<EV::Loop::Async> perl module,
4237which uses exactly this technique (which is suited for many high-level
4238languages).
4239
4240The example uses a pthread mutex to protect the loop data, a condition
4241variable to wait for callback invocations, an async watcher to notify the
4242event loop thread and an unspecified mechanism to wake up the main thread.
4243
4244First, you need to associate some data with the event loop:
4245
4246 typedef struct {
4247 mutex_t lock; /* global loop lock */
4248 ev_async async_w;
4249 thread_t tid;
4250 cond_t invoke_cv;
4251 } userdata;
4252
4253 void prepare_loop (EV_P)
4254 {
4255 // for simplicity, we use a static userdata struct.
4256 static userdata u;
4257
4258 ev_async_init (&u->async_w, async_cb);
4259 ev_async_start (EV_A_ &u->async_w);
4260
4261 pthread_mutex_init (&u->lock, 0);
4262 pthread_cond_init (&u->invoke_cv, 0);
4263
4264 // now associate this with the loop
4265 ev_set_userdata (EV_A_ u);
4266 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4267 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4268
4269 // then create the thread running ev_loop
4270 pthread_create (&u->tid, 0, l_run, EV_A);
4271 }
4272
4273The callback for the C<ev_async> watcher does nothing: the watcher is used
4274solely to wake up the event loop so it takes notice of any new watchers
4275that might have been added:
4276
4277 static void
4278 async_cb (EV_P_ ev_async *w, int revents)
4279 {
4280 // just used for the side effects
4281 }
4282
4283The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4284protecting the loop data, respectively.
4285
4286 static void
4287 l_release (EV_P)
4288 {
4289 userdata *u = ev_userdata (EV_A);
4290 pthread_mutex_unlock (&u->lock);
4291 }
4292
4293 static void
4294 l_acquire (EV_P)
4295 {
4296 userdata *u = ev_userdata (EV_A);
4297 pthread_mutex_lock (&u->lock);
4298 }
4299
4300The event loop thread first acquires the mutex, and then jumps straight
4301into C<ev_run>:
4302
4303 void *
4304 l_run (void *thr_arg)
4305 {
4306 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4307
4308 l_acquire (EV_A);
4309 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4310 ev_run (EV_A_ 0);
4311 l_release (EV_A);
4312
4313 return 0;
4314 }
4315
4316Instead of invoking all pending watchers, the C<l_invoke> callback will
4317signal the main thread via some unspecified mechanism (signals? pipe
4318writes? C<Async::Interrupt>?) and then waits until all pending watchers
4319have been called (in a while loop because a) spurious wakeups are possible
4320and b) skipping inter-thread-communication when there are no pending
4321watchers is very beneficial):
4322
4323 static void
4324 l_invoke (EV_P)
4325 {
4326 userdata *u = ev_userdata (EV_A);
4327
4328 while (ev_pending_count (EV_A))
4329 {
4330 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4331 pthread_cond_wait (&u->invoke_cv, &u->lock);
4332 }
4333 }
4334
4335Now, whenever the main thread gets told to invoke pending watchers, it
4336will grab the lock, call C<ev_invoke_pending> and then signal the loop
4337thread to continue:
4338
4339 static void
4340 real_invoke_pending (EV_P)
4341 {
4342 userdata *u = ev_userdata (EV_A);
4343
4344 pthread_mutex_lock (&u->lock);
4345 ev_invoke_pending (EV_A);
4346 pthread_cond_signal (&u->invoke_cv);
4347 pthread_mutex_unlock (&u->lock);
4348 }
4349
4350Whenever you want to start/stop a watcher or do other modifications to an
4351event loop, you will now have to lock:
4352
4353 ev_timer timeout_watcher;
4354 userdata *u = ev_userdata (EV_A);
4355
4356 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4357
4358 pthread_mutex_lock (&u->lock);
4359 ev_timer_start (EV_A_ &timeout_watcher);
4360 ev_async_send (EV_A_ &u->async_w);
4361 pthread_mutex_unlock (&u->lock);
4362
4363Note that sending the C<ev_async> watcher is required because otherwise
4364an event loop currently blocking in the kernel will have no knowledge
4365about the newly added timer. By waking up the loop it will pick up any new
4366watchers in the next event loop iteration.
4367
3592=head3 COROUTINES 4368=head3 COROUTINES
3593 4369
3594Libev is very accommodating to coroutines ("cooperative threads"): 4370Libev is very accommodating to coroutines ("cooperative threads"):
3595libev fully supports nesting calls to its functions from different 4371libev fully supports nesting calls to its functions from different
3596coroutines (e.g. you can call C<ev_loop> on the same loop from two 4372coroutines (e.g. you can call C<ev_run> on the same loop from two
3597different coroutines, and switch freely between both coroutines running the 4373different coroutines, and switch freely between both coroutines running
3598loop, as long as you don't confuse yourself). The only exception is that 4374the loop, as long as you don't confuse yourself). The only exception is
3599you must not do this from C<ev_periodic> reschedule callbacks. 4375that you must not do this from C<ev_periodic> reschedule callbacks.
3600 4376
3601Care has been taken to ensure that libev does not keep local state inside 4377Care has been taken to ensure that libev does not keep local state inside
3602C<ev_loop>, and other calls do not usually allow for coroutine switches as 4378C<ev_run>, and other calls do not usually allow for coroutine switches as
3603they do not call any callbacks. 4379they do not call any callbacks.
3604 4380
3605=head2 COMPILER WARNINGS 4381=head2 COMPILER WARNINGS
3606 4382
3607Depending on your compiler and compiler settings, you might get no or a 4383Depending on your compiler and compiler settings, you might get no or a
3618maintainable. 4394maintainable.
3619 4395
3620And of course, some compiler warnings are just plain stupid, or simply 4396And of course, some compiler warnings are just plain stupid, or simply
3621wrong (because they don't actually warn about the condition their message 4397wrong (because they don't actually warn about the condition their message
3622seems to warn about). For example, certain older gcc versions had some 4398seems to warn about). For example, certain older gcc versions had some
3623warnings that resulted an extreme number of false positives. These have 4399warnings that resulted in an extreme number of false positives. These have
3624been fixed, but some people still insist on making code warn-free with 4400been fixed, but some people still insist on making code warn-free with
3625such buggy versions. 4401such buggy versions.
3626 4402
3627While libev is written to generate as few warnings as possible, 4403While libev is written to generate as few warnings as possible,
3628"warn-free" code is not a goal, and it is recommended not to build libev 4404"warn-free" code is not a goal, and it is recommended not to build libev
3664I suggest using suppression lists. 4440I suggest using suppression lists.
3665 4441
3666 4442
3667=head1 PORTABILITY NOTES 4443=head1 PORTABILITY NOTES
3668 4444
4445=head2 GNU/LINUX 32 BIT LIMITATIONS
4446
4447GNU/Linux is the only common platform that supports 64 bit file/large file
4448interfaces but I<disables> them by default.
4449
4450That means that libev compiled in the default environment doesn't support
4451files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
4452
4453Unfortunately, many programs try to work around this GNU/Linux issue
4454by enabling the large file API, which makes them incompatible with the
4455standard libev compiled for their system.
4456
4457Likewise, libev cannot enable the large file API itself as this would
4458suddenly make it incompatible to the default compile time environment,
4459i.e. all programs not using special compile switches.
4460
4461=head2 OS/X AND DARWIN BUGS
4462
4463The whole thing is a bug if you ask me - basically any system interface
4464you touch is broken, whether it is locales, poll, kqueue or even the
4465OpenGL drivers.
4466
4467=head3 C<kqueue> is buggy
4468
4469The kqueue syscall is broken in all known versions - most versions support
4470only sockets, many support pipes.
4471
4472Libev tries to work around this by not using C<kqueue> by default on
4473this rotten platform, but of course you can still ask for it when creating
4474a loop.
4475
4476=head3 C<poll> is buggy
4477
4478Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4479implementation by something calling C<kqueue> internally around the 10.5.6
4480release, so now C<kqueue> I<and> C<poll> are broken.
4481
4482Libev tries to work around this by not using C<poll> by default on
4483this rotten platform, but of course you can still ask for it when creating
4484a loop.
4485
4486=head3 C<select> is buggy
4487
4488All that's left is C<select>, and of course Apple found a way to fuck this
4489one up as well: On OS/X, C<select> actively limits the number of file
4490descriptors you can pass in to 1024 - your program suddenly crashes when
4491you use more.
4492
4493There is an undocumented "workaround" for this - defining
4494C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
4495work on OS/X.
4496
4497=head2 SOLARIS PROBLEMS AND WORKAROUNDS
4498
4499=head3 C<errno> reentrancy
4500
4501The default compile environment on Solaris is unfortunately so
4502thread-unsafe that you can't even use components/libraries compiled
4503without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
4504isn't defined by default.
4505
4506If you want to use libev in threaded environments you have to make sure
4507it's compiled with C<_REENTRANT> defined.
4508
4509=head3 Event port backend
4510
4511The scalable event interface for Solaris is called "event ports". Unfortunately,
4512this mechanism is very buggy. If you run into high CPU usage, your program
4513freezes or you get a large number of spurious wakeups, make sure you have
4514all the relevant and latest kernel patches applied. No, I don't know which
4515ones, but there are multiple ones.
4516
4517If you can't get it to work, you can try running the program by setting
4518the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
4519C<select> backends.
4520
4521=head2 AIX POLL BUG
4522
4523AIX unfortunately has a broken C<poll.h> header. Libev works around
4524this by trying to avoid the poll backend altogether (i.e. it's not even
4525compiled in), which normally isn't a big problem as C<select> works fine
4526with large bitsets, and AIX is dead anyway.
4527
3669=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4528=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4529
4530=head3 General issues
3670 4531
3671Win32 doesn't support any of the standards (e.g. POSIX) that libev 4532Win32 doesn't support any of the standards (e.g. POSIX) that libev
3672requires, and its I/O model is fundamentally incompatible with the POSIX 4533requires, and its I/O model is fundamentally incompatible with the POSIX
3673model. Libev still offers limited functionality on this platform in 4534model. Libev still offers limited functionality on this platform in
3674the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4535the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3675descriptors. This only applies when using Win32 natively, not when using 4536descriptors. This only applies when using Win32 natively, not when using
3676e.g. cygwin. 4537e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4538as every compielr comes with a slightly differently broken/incompatible
4539environment.
3677 4540
3678Lifting these limitations would basically require the full 4541Lifting these limitations would basically require the full
3679re-implementation of the I/O system. If you are into these kinds of 4542re-implementation of the I/O system. If you are into this kind of thing,
3680things, then note that glib does exactly that for you in a very portable 4543then note that glib does exactly that for you in a very portable way (note
3681way (note also that glib is the slowest event library known to man). 4544also that glib is the slowest event library known to man).
3682 4545
3683There is no supported compilation method available on windows except 4546There is no supported compilation method available on windows except
3684embedding it into other applications. 4547embedding it into other applications.
4548
4549Sensible signal handling is officially unsupported by Microsoft - libev
4550tries its best, but under most conditions, signals will simply not work.
3685 4551
3686Not a libev limitation but worth mentioning: windows apparently doesn't 4552Not a libev limitation but worth mentioning: windows apparently doesn't
3687accept large writes: instead of resulting in a partial write, windows will 4553accept large writes: instead of resulting in a partial write, windows will
3688either accept everything or return C<ENOBUFS> if the buffer is too large, 4554either accept everything or return C<ENOBUFS> if the buffer is too large,
3689so make sure you only write small amounts into your sockets (less than a 4555so make sure you only write small amounts into your sockets (less than a
3694the abysmal performance of winsockets, using a large number of sockets 4560the abysmal performance of winsockets, using a large number of sockets
3695is not recommended (and not reasonable). If your program needs to use 4561is not recommended (and not reasonable). If your program needs to use
3696more than a hundred or so sockets, then likely it needs to use a totally 4562more than a hundred or so sockets, then likely it needs to use a totally
3697different implementation for windows, as libev offers the POSIX readiness 4563different implementation for windows, as libev offers the POSIX readiness
3698notification model, which cannot be implemented efficiently on windows 4564notification model, which cannot be implemented efficiently on windows
3699(Microsoft monopoly games). 4565(due to Microsoft monopoly games).
3700 4566
3701A typical way to use libev under windows is to embed it (see the embedding 4567A typical way to use libev under windows is to embed it (see the embedding
3702section for details) and use the following F<evwrap.h> header file instead 4568section for details) and use the following F<evwrap.h> header file instead
3703of F<ev.h>: 4569of F<ev.h>:
3704 4570
3711you do I<not> compile the F<ev.c> or any other embedded source files!): 4577you do I<not> compile the F<ev.c> or any other embedded source files!):
3712 4578
3713 #include "evwrap.h" 4579 #include "evwrap.h"
3714 #include "ev.c" 4580 #include "ev.c"
3715 4581
3716=over 4
3717
3718=item The winsocket select function 4582=head3 The winsocket C<select> function
3719 4583
3720The winsocket C<select> function doesn't follow POSIX in that it 4584The winsocket C<select> function doesn't follow POSIX in that it
3721requires socket I<handles> and not socket I<file descriptors> (it is 4585requires socket I<handles> and not socket I<file descriptors> (it is
3722also extremely buggy). This makes select very inefficient, and also 4586also extremely buggy). This makes select very inefficient, and also
3723requires a mapping from file descriptors to socket handles (the Microsoft 4587requires a mapping from file descriptors to socket handles (the Microsoft
3732 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 4596 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3733 4597
3734Note that winsockets handling of fd sets is O(n), so you can easily get a 4598Note that winsockets handling of fd sets is O(n), so you can easily get a
3735complexity in the O(n²) range when using win32. 4599complexity in the O(n²) range when using win32.
3736 4600
3737=item Limited number of file descriptors 4601=head3 Limited number of file descriptors
3738 4602
3739Windows has numerous arbitrary (and low) limits on things. 4603Windows has numerous arbitrary (and low) limits on things.
3740 4604
3741Early versions of winsocket's select only supported waiting for a maximum 4605Early versions of winsocket's select only supported waiting for a maximum
3742of C<64> handles (probably owning to the fact that all windows kernels 4606of C<64> handles (probably owning to the fact that all windows kernels
3743can only wait for C<64> things at the same time internally; Microsoft 4607can only wait for C<64> things at the same time internally; Microsoft
3744recommends spawning a chain of threads and wait for 63 handles and the 4608recommends spawning a chain of threads and wait for 63 handles and the
3745previous thread in each. Great). 4609previous thread in each. Sounds great!).
3746 4610
3747Newer versions support more handles, but you need to define C<FD_SETSIZE> 4611Newer versions support more handles, but you need to define C<FD_SETSIZE>
3748to some high number (e.g. C<2048>) before compiling the winsocket select 4612to some high number (e.g. C<2048>) before compiling the winsocket select
3749call (which might be in libev or elsewhere, for example, perl does its own 4613call (which might be in libev or elsewhere, for example, perl and many
3750select emulation on windows). 4614other interpreters do their own select emulation on windows).
3751 4615
3752Another limit is the number of file descriptors in the Microsoft runtime 4616Another limit is the number of file descriptors in the Microsoft runtime
3753libraries, which by default is C<64> (there must be a hidden I<64> fetish 4617libraries, which by default is C<64> (there must be a hidden I<64>
3754or something like this inside Microsoft). You can increase this by calling 4618fetish or something like this inside Microsoft). You can increase this
3755C<_setmaxstdio>, which can increase this limit to C<2048> (another 4619by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3756arbitrary limit), but is broken in many versions of the Microsoft runtime 4620(another arbitrary limit), but is broken in many versions of the Microsoft
3757libraries.
3758
3759This might get you to about C<512> or C<2048> sockets (depending on 4621runtime libraries. This might get you to about C<512> or C<2048> sockets
3760windows version and/or the phase of the moon). To get more, you need to 4622(depending on windows version and/or the phase of the moon). To get more,
3761wrap all I/O functions and provide your own fd management, but the cost of 4623you need to wrap all I/O functions and provide your own fd management, but
3762calling select (O(n²)) will likely make this unworkable. 4624the cost of calling select (O(n²)) will likely make this unworkable.
3763
3764=back
3765 4625
3766=head2 PORTABILITY REQUIREMENTS 4626=head2 PORTABILITY REQUIREMENTS
3767 4627
3768In addition to a working ISO-C implementation and of course the 4628In addition to a working ISO-C implementation and of course the
3769backend-specific APIs, libev relies on a few additional extensions: 4629backend-specific APIs, libev relies on a few additional extensions:
3808watchers. 4668watchers.
3809 4669
3810=item C<double> must hold a time value in seconds with enough accuracy 4670=item C<double> must hold a time value in seconds with enough accuracy
3811 4671
3812The type C<double> is used to represent timestamps. It is required to 4672The type C<double> is used to represent timestamps. It is required to
3813have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4673have at least 51 bits of mantissa (and 9 bits of exponent), which is
3814enough for at least into the year 4000. This requirement is fulfilled by 4674good enough for at least into the year 4000 with millisecond accuracy
4675(the design goal for libev). This requirement is overfulfilled by
3815implementations implementing IEEE 754 (basically all existing ones). 4676implementations using IEEE 754, which is basically all existing ones. With
4677IEEE 754 doubles, you get microsecond accuracy until at least 2200.
3816 4678
3817=back 4679=back
3818 4680
3819If you know of other additional requirements drop me a note. 4681If you know of other additional requirements drop me a note.
3820 4682
3888involves iterating over all running async watchers or all signal numbers. 4750involves iterating over all running async watchers or all signal numbers.
3889 4751
3890=back 4752=back
3891 4753
3892 4754
4755=head1 PORTING FROM LIBEV 3.X TO 4.X
4756
4757The major version 4 introduced some minor incompatible changes to the API.
4758
4759At the moment, the C<ev.h> header file tries to implement superficial
4760compatibility, so most programs should still compile. Those might be
4761removed in later versions of libev, so better update early than late.
4762
4763=over 4
4764
4765=item function/symbol renames
4766
4767A number of functions and symbols have been renamed:
4768
4769 ev_loop => ev_run
4770 EVLOOP_NONBLOCK => EVRUN_NOWAIT
4771 EVLOOP_ONESHOT => EVRUN_ONCE
4772
4773 ev_unloop => ev_break
4774 EVUNLOOP_CANCEL => EVBREAK_CANCEL
4775 EVUNLOOP_ONE => EVBREAK_ONE
4776 EVUNLOOP_ALL => EVBREAK_ALL
4777
4778 EV_TIMEOUT => EV_TIMER
4779
4780 ev_loop_count => ev_iteration
4781 ev_loop_depth => ev_depth
4782 ev_loop_verify => ev_verify
4783
4784Most functions working on C<struct ev_loop> objects don't have an
4785C<ev_loop_> prefix, so it was removed; C<ev_loop>, C<ev_unloop> and
4786associated constants have been renamed to not collide with the C<struct
4787ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
4788as all other watcher types. Note that C<ev_loop_fork> is still called
4789C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
4790typedef.
4791
4792=item C<EV_COMPAT3> backwards compatibility mechanism
4793
4794The backward compatibility mechanism can be controlled by
4795C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
4796section.
4797
4798=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4799
4800The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4801mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4802and work, but the library code will of course be larger.
4803
4804=back
4805
4806
4807=head1 GLOSSARY
4808
4809=over 4
4810
4811=item active
4812
4813A watcher is active as long as it has been started (has been attached to
4814an event loop) but not yet stopped (disassociated from the event loop).
4815
4816=item application
4817
4818In this document, an application is whatever is using libev.
4819
4820=item callback
4821
4822The address of a function that is called when some event has been
4823detected. Callbacks are being passed the event loop, the watcher that
4824received the event, and the actual event bitset.
4825
4826=item callback invocation
4827
4828The act of calling the callback associated with a watcher.
4829
4830=item event
4831
4832A change of state of some external event, such as data now being available
4833for reading on a file descriptor, time having passed or simply not having
4834any other events happening anymore.
4835
4836In libev, events are represented as single bits (such as C<EV_READ> or
4837C<EV_TIMER>).
4838
4839=item event library
4840
4841A software package implementing an event model and loop.
4842
4843=item event loop
4844
4845An entity that handles and processes external events and converts them
4846into callback invocations.
4847
4848=item event model
4849
4850The model used to describe how an event loop handles and processes
4851watchers and events.
4852
4853=item pending
4854
4855A watcher is pending as soon as the corresponding event has been detected,
4856and stops being pending as soon as the watcher will be invoked or its
4857pending status is explicitly cleared by the application.
4858
4859A watcher can be pending, but not active. Stopping a watcher also clears
4860its pending status.
4861
4862=item real time
4863
4864The physical time that is observed. It is apparently strictly monotonic :)
4865
4866=item wall-clock time
4867
4868The time and date as shown on clocks. Unlike real time, it can actually
4869be wrong and jump forwards and backwards, e.g. when the you adjust your
4870clock.
4871
4872=item watcher
4873
4874A data structure that describes interest in certain events. Watchers need
4875to be started (attached to an event loop) before they can receive events.
4876
4877=item watcher invocation
4878
4879The act of calling the callback associated with a watcher.
4880
4881=back
4882
3893=head1 AUTHOR 4883=head1 AUTHOR
3894 4884
3895Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 4885Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3896 4886

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines