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.292 by sf-exg, Mon Mar 22 09:57:01 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;
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);
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
80Familarity 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 (somewhere
115the beginning of 1970, details are complicated, don't ask). This type is 130near the beginning of 1970, details are complicated, don't ask). This
116called C<ev_tstamp>, which is what you should use too. It usually aliases 131type is called C<ev_tstamp>, which is what you should use too. It usually
117to the C<double> type in C, and when you need to do any calculations on 132aliases to the C<double> type in C. When you need to do any calculations
118it, you should treat it as some floating point value. Unlike the name 133on it, you should treat it as some floating point value. Unlike the name
119component C<stamp> might indicate, it is also used for time differences 134component C<stamp> might indicate, it is also used for time differences
120throughout libev. 135throughout libev.
121 136
122=head1 ERROR HANDLING 137=head1 ERROR HANDLING
123 138
330useful to try out specific backends to test their performance, or to work 345useful to try out specific backends to test their performance, or to work
331around bugs. 346around bugs.
332 347
333=item C<EVFLAG_FORKCHECK> 348=item C<EVFLAG_FORKCHECK>
334 349
335Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 350Instead 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 351make libev check for a fork in each iteration by enabling this flag.
337enabling this flag.
338 352
339This works by calling C<getpid ()> on every iteration of the loop, 353This 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 354and 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 355iterations 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 356GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
348flag. 362flag.
349 363
350This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 364This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
351environment variable. 365environment variable.
352 366
367=item C<EVFLAG_NOINOTIFY>
368
369When this flag is specified, then libev will not attempt to use the
370I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
371testing, this flag can be useful to conserve inotify file descriptors, as
372otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
373
374=item C<EVFLAG_SIGNALFD>
375
376When this flag is specified, then libev will attempt to use the
377I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
378delivers signals synchronously, which makes it both faster and might make
379it possible to get the queued signal data. It can also simplify signal
380handling with threads, as long as you properly block signals in your
381threads that are not interested in handling them.
382
383Signalfd will not be used by default as this changes your signal mask, and
384there are a lot of shoddy libraries and programs (glib's threadpool for
385example) that can't properly initialise their signal masks.
386
353=item C<EVBACKEND_SELECT> (value 1, portable select backend) 387=item C<EVBACKEND_SELECT> (value 1, portable select backend)
354 388
355This is your standard select(2) backend. Not I<completely> standard, as 389This 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, 390libev 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 391but if that fails, expect a fairly low limit on the number of fds when
380 414
381This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 415This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
382C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 416C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
383 417
384=item C<EVBACKEND_EPOLL> (value 4, Linux) 418=item C<EVBACKEND_EPOLL> (value 4, Linux)
419
420Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
421kernels).
385 422
386For few fds, this backend is a bit little slower than poll and select, 423For few fds, this backend is a bit little slower than poll and select,
387but it scales phenomenally better. While poll and select usually scale 424but 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), 425like O(total_fds) where n is the total number of fds (or the highest fd),
389epoll scales either O(1) or O(active_fds). 426epoll scales either O(1) or O(active_fds).
458 495
459While nominally embeddable in other event loops, this doesn't work 496While nominally embeddable in other event loops, this doesn't work
460everywhere, so you might need to test for this. And since it is broken 497everywhere, 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 498almost 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 499(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, 500(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
464using it only for sockets. 501also broken on OS X)) and, did I mention it, using it only for sockets.
465 502
466This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 503This 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 504C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
468C<NOTE_EOF>. 505C<NOTE_EOF>.
469 506
504 541
505It is definitely not recommended to use this flag. 542It is definitely not recommended to use this flag.
506 543
507=back 544=back
508 545
509If one or more of these are or'ed into the flags value, then only these 546If 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 547then only these backends will be tried (in the reverse order as listed
511specified, all backends in C<ev_recommended_backends ()> will be tried. 548here). If none are specified, all backends in C<ev_recommended_backends
549()> will be tried.
512 550
513Example: This is the most typical usage. 551Example: This is the most typical usage.
514 552
515 if (!ev_default_loop (0)) 553 if (!ev_default_loop (0))
516 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 554 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
528 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 566 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
529 567
530=item struct ev_loop *ev_loop_new (unsigned int flags) 568=item struct ev_loop *ev_loop_new (unsigned int flags)
531 569
532Similar to C<ev_default_loop>, but always creates a new event loop that is 570Similar 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 571always 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 572
537Note that this function I<is> thread-safe, and the recommended way to use 573Note 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 574libev with threads is indeed to create one loop per thread, and using the
539default loop in the "main" or "initial" thread. 575default loop in the "main" or "initial" thread.
540 576
541Example: Try to create a event loop that uses epoll and nothing else. 577Example: Try to create a event loop that uses epoll and nothing else.
542 578
544 if (!epoller) 580 if (!epoller)
545 fatal ("no epoll found here, maybe it hides under your chair"); 581 fatal ("no epoll found here, maybe it hides under your chair");
546 582
547=item ev_default_destroy () 583=item ev_default_destroy ()
548 584
549Destroys the default loop again (frees all memory and kernel state 585Destroys the default loop (frees all memory and kernel state etc.). None
550etc.). None of the active event watchers will be stopped in the normal 586of 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 587e.g. C<ev_is_active> might still return true. It is your responsibility to
552responsibility to either stop all watchers cleanly yourself I<before> 588either stop all watchers cleanly yourself I<before> calling this function,
553calling this function, or cope with the fact afterwards (which is usually 589or 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 590can just ignore the watchers and/or C<free ()> them for example).
555for example).
556 591
557Note that certain global state, such as signal state (and installed signal 592Note that certain global state, such as signal state (and installed signal
558handlers), will not be freed by this function, and related watchers (such 593handlers), will not be freed by this function, and related watchers (such
559as signal and child watchers) would need to be stopped manually. 594as signal and child watchers) would need to be stopped manually.
560 595
561In general it is not advisable to call this function except in the 596In 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 597rare 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 598pipe fds. If you need dynamically allocated loops it is better to use
564C<ev_loop_new> and C<ev_loop_destroy>). 599C<ev_loop_new> and C<ev_loop_destroy>.
565 600
566=item ev_loop_destroy (loop) 601=item ev_loop_destroy (loop)
567 602
568Like C<ev_default_destroy>, but destroys an event loop created by an 603Like C<ev_default_destroy>, but destroys an event loop created by an
569earlier call to C<ev_loop_new>. 604earlier call to C<ev_loop_new>.
575name, you can call it anytime, but it makes most sense after forking, in 610name, 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 611the 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 612sense). 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. 613functions, and it will only take effect at the next C<ev_loop> iteration.
579 614
615Again, you I<have> to call it on I<any> loop that you want to re-use after
616a fork, I<even if you do not plan to use the loop in the parent>. This is
617because some kernel interfaces *cough* I<kqueue> *cough* do funny things
618during fork.
619
580On the other hand, you only need to call this function in the child 620On 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 621process if and only if you want to use the event loop in the child. If you
582you just fork+exec, you don't have to call it at all. 622just fork+exec or create a new loop in the child, you don't have to call
623it at all.
583 624
584The function itself is quite fast and it's usually not a problem to call 625The 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 626it just in case after a fork. To make this easy, the function will fit in
586quite nicely into a call to C<pthread_atfork>: 627quite nicely into a call to C<pthread_atfork>:
587 628
589 630
590=item ev_loop_fork (loop) 631=item ev_loop_fork (loop)
591 632
592Like C<ev_default_fork>, but acts on an event loop created by 633Like 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 634C<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 635after fork that you want to re-use in the child, and how you keep track of
595entirely your own problem. 636them is entirely your own problem.
596 637
597=item int ev_is_default_loop (loop) 638=item int ev_is_default_loop (loop)
598 639
599Returns true when the given loop is, in fact, the default loop, and false 640Returns true when the given loop is, in fact, the default loop, and false
600otherwise. 641otherwise.
601 642
602=item unsigned int ev_loop_count (loop) 643=item unsigned int ev_iteration (loop)
603 644
604Returns the count of loop iterations for the loop, which is identical to 645Returns the current iteration count for the loop, which is identical to
605the number of times libev did poll for new events. It starts at C<0> and 646the number of times libev did poll for new events. It starts at C<0> and
606happily wraps around with enough iterations. 647happily wraps around with enough iterations.
607 648
608This value can sometimes be useful as a generation counter of sorts (it 649This value can sometimes be useful as a generation counter of sorts (it
609"ticks" the number of loop iterations), as it roughly corresponds with 650"ticks" the number of loop iterations), as it roughly corresponds with
610C<ev_prepare> and C<ev_check> calls. 651C<ev_prepare> and C<ev_check> calls - and is incremented between the
652prepare and check phases.
653
654=item unsigned int ev_depth (loop)
655
656Returns the number of times C<ev_loop> was entered minus the number of
657times C<ev_loop> was exited, in other words, the recursion depth.
658
659Outside C<ev_loop>, this number is zero. In a callback, this number is
660C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
661in which case it is higher.
662
663Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
664etc.), doesn't count as "exit" - consider this as a hint to avoid such
665ungentleman behaviour unless it's really convenient.
611 666
612=item unsigned int ev_backend (loop) 667=item unsigned int ev_backend (loop)
613 668
614Returns one of the C<EVBACKEND_*> flags indicating the event backend in 669Returns one of the C<EVBACKEND_*> flags indicating the event backend in
615use. 670use.
630 685
631This function is rarely useful, but when some event callback runs for a 686This 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 687very long time without entering the event loop, updating libev's idea of
633the current time is a good idea. 688the current time is a good idea.
634 689
635See also "The special problem of time updates" in the C<ev_timer> section. 690See also L<The special problem of time updates> in the C<ev_timer> section.
691
692=item ev_suspend (loop)
693
694=item ev_resume (loop)
695
696These two functions suspend and resume a loop, for use when the loop is
697not used for a while and timeouts should not be processed.
698
699A typical use case would be an interactive program such as a game: When
700the user presses C<^Z> to suspend the game and resumes it an hour later it
701would be best to handle timeouts as if no time had actually passed while
702the program was suspended. This can be achieved by calling C<ev_suspend>
703in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
704C<ev_resume> directly afterwards to resume timer processing.
705
706Effectively, all C<ev_timer> watchers will be delayed by the time spend
707between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
708will be rescheduled (that is, they will lose any events that would have
709occured while suspended).
710
711After calling C<ev_suspend> you B<must not> call I<any> function on the
712given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
713without a previous call to C<ev_suspend>.
714
715Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
716event loop time (see C<ev_now_update>).
636 717
637=item ev_loop (loop, int flags) 718=item ev_loop (loop, int flags)
638 719
639Finally, this is it, the event handler. This function usually is called 720Finally, this is it, the event handler. This function usually is called
640after you initialised all your watchers and you want to start handling 721after you have initialised all your watchers and you want to start
641events. 722handling events.
642 723
643If the flags argument is specified as C<0>, it will not return until 724If the flags argument is specified as C<0>, it will not return until
644either no event watchers are active anymore or C<ev_unloop> was called. 725either no event watchers are active anymore or C<ev_unloop> was called.
645 726
646Please note that an explicit C<ev_unloop> is usually better than 727Please note that an explicit C<ev_unloop> is usually better than
720 801
721Ref/unref can be used to add or remove a reference count on the event 802Ref/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 803loop: Every watcher keeps one reference, and as long as the reference
723count is nonzero, C<ev_loop> will not return on its own. 804count is nonzero, C<ev_loop> will not return on its own.
724 805
725If you have a watcher you never unregister that should not keep C<ev_loop> 806This is useful when you have a watcher that you never intend to
726from returning, call ev_unref() after starting, and ev_ref() before 807unregister, but that nevertheless should not keep C<ev_loop> from
808returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
727stopping it. 809before stopping it.
728 810
729As an example, libev itself uses this for its internal signal pipe: It is 811As 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 812is not visible to the libev user and should not keep C<ev_loop> from
731if no event watchers registered by it are active. It is also an excellent 813exiting 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 814excellent way to do this for generic recurring timers or from within
733libraries. Just remember to I<unref after start> and I<ref before stop> 815third-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, 816before stop> (but only if the watcher wasn't active before, or was active
735respectively). 817before, respectively. Note also that libev might stop watchers itself
818(e.g. non-repeating timers) in which case you have to C<ev_ref>
819in the callback).
736 820
737Example: Create a signal watcher, but keep it from keeping C<ev_loop> 821Example: Create a signal watcher, but keep it from keeping C<ev_loop>
738running when nothing else is active. 822running when nothing else is active.
739 823
740 ev_signal exitsig; 824 ev_signal exitsig;
769 853
770By setting a higher I<io collect interval> you allow libev to spend more 854By 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, 855time collecting I/O events, so you can handle more events per iteration,
772at the cost of increasing latency. Timeouts (both C<ev_periodic> and 856at 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 857C<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. 858introduce an additional C<ev_sleep ()> call into most loop iterations. The
859sleep time ensures that libev will not poll for I/O events more often then
860once per this interval, on average.
775 861
776Likewise, by setting a higher I<timeout collect interval> you allow libev 862Likewise, by setting a higher I<timeout collect interval> you allow libev
777to spend more time collecting timeouts, at the expense of increased 863to spend more time collecting timeouts, at the expense of increased
778latency/jitter/inexactness (the watcher callback will be called 864latency/jitter/inexactness (the watcher callback will be called
779later). C<ev_io> watchers will not be affected. Setting this to a non-null 865later). C<ev_io> watchers will not be affected. Setting this to a non-null
781 867
782Many (busy) programs can usually benefit by setting the I/O collect 868Many (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 869interval 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 870interactive 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>, 871usually 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. 872as this approaches the timing granularity of most systems. Note that if
873you do transactions with the outside world and you can't increase the
874parallelity, then this setting will limit your transaction rate (if you
875need to poll once per transaction and the I/O collect interval is 0.01,
876then you can't do more than 100 transations per second).
787 877
788Setting the I<timeout collect interval> can improve the opportunity for 878Setting the I<timeout collect interval> can improve the opportunity for
789saving power, as the program will "bundle" timer callback invocations that 879saving power, as the program will "bundle" timer callback invocations that
790are "near" in time together, by delaying some, thus reducing the number of 880are "near" in time together, by delaying some, thus reducing the number of
791times the process sleeps and wakes up again. Another useful technique to 881times 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 882reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
793they fire on, say, one-second boundaries only. 883they fire on, say, one-second boundaries only.
794 884
885Example: we only need 0.1s timeout granularity, and we wish not to poll
886more often than 100 times per second:
887
888 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
889 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
890
891=item ev_invoke_pending (loop)
892
893This call will simply invoke all pending watchers while resetting their
894pending state. Normally, C<ev_loop> does this automatically when required,
895but when overriding the invoke callback this call comes handy.
896
897=item int ev_pending_count (loop)
898
899Returns the number of pending watchers - zero indicates that no watchers
900are pending.
901
902=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
903
904This overrides the invoke pending functionality of the loop: Instead of
905invoking all pending watchers when there are any, C<ev_loop> will call
906this callback instead. This is useful, for example, when you want to
907invoke the actual watchers inside another context (another thread etc.).
908
909If you want to reset the callback, use C<ev_invoke_pending> as new
910callback.
911
912=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
913
914Sometimes you want to share the same loop between multiple threads. This
915can be done relatively simply by putting mutex_lock/unlock calls around
916each call to a libev function.
917
918However, C<ev_loop> can run an indefinite time, so it is not feasible to
919wait for it to return. One way around this is to wake up the loop via
920C<ev_unloop> and C<av_async_send>, another way is to set these I<release>
921and I<acquire> callbacks on the loop.
922
923When set, then C<release> will be called just before the thread is
924suspended waiting for new events, and C<acquire> is called just
925afterwards.
926
927Ideally, C<release> will just call your mutex_unlock function, and
928C<acquire> will just call the mutex_lock function again.
929
930While event loop modifications are allowed between invocations of
931C<release> and C<acquire> (that's their only purpose after all), no
932modifications done will affect the event loop, i.e. adding watchers will
933have no effect on the set of file descriptors being watched, or the time
934waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
935to take note of any changes you made.
936
937In theory, threads executing C<ev_loop> will be async-cancel safe between
938invocations of C<release> and C<acquire>.
939
940See also the locking example in the C<THREADS> section later in this
941document.
942
943=item ev_set_userdata (loop, void *data)
944
945=item ev_userdata (loop)
946
947Set and retrieve a single C<void *> associated with a loop. When
948C<ev_set_userdata> has never been called, then C<ev_userdata> returns
949C<0.>
950
951These two functions can be used to associate arbitrary data with a loop,
952and are intended solely for the C<invoke_pending_cb>, C<release> and
953C<acquire> callbacks described above, but of course can be (ab-)used for
954any other purpose as well.
955
795=item ev_loop_verify (loop) 956=item ev_loop_verify (loop)
796 957
797This function only does something when C<EV_VERIFY> support has been 958This 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 959compiled in, which is the default for non-minimal builds. It tries to go
799through all internal structures and checks them for validity. If anything 960through all internal structures and checks them for validity. If anything
875=item C<EV_WRITE> 1036=item C<EV_WRITE>
876 1037
877The file descriptor in the C<ev_io> watcher has become readable and/or 1038The file descriptor in the C<ev_io> watcher has become readable and/or
878writable. 1039writable.
879 1040
880=item C<EV_TIMEOUT> 1041=item C<EV_TIMER>
881 1042
882The C<ev_timer> watcher has timed out. 1043The C<ev_timer> watcher has timed out.
883 1044
884=item C<EV_PERIODIC> 1045=item C<EV_PERIODIC>
885 1046
924 1085
925=item C<EV_ASYNC> 1086=item C<EV_ASYNC>
926 1087
927The given async watcher has been asynchronously notified (see C<ev_async>). 1088The given async watcher has been asynchronously notified (see C<ev_async>).
928 1089
1090=item C<EV_CUSTOM>
1091
1092Not ever sent (or otherwise used) by libev itself, but can be freely used
1093by libev users to signal watchers (e.g. via C<ev_feed_event>).
1094
929=item C<EV_ERROR> 1095=item C<EV_ERROR>
930 1096
931An unspecified error has occurred, the watcher has been stopped. This might 1097An unspecified error has occurred, the watcher has been stopped. This might
932happen because the watcher could not be properly started because libev 1098happen because the watcher could not be properly started because libev
933ran out of memory, a file descriptor was found to be closed or any other 1099ran out of memory, a file descriptor was found to be closed or any other
970 1136
971 ev_io w; 1137 ev_io w;
972 ev_init (&w, my_cb); 1138 ev_init (&w, my_cb);
973 ev_io_set (&w, STDIN_FILENO, EV_READ); 1139 ev_io_set (&w, STDIN_FILENO, EV_READ);
974 1140
975=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1141=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
976 1142
977This macro initialises the type-specific parts of a watcher. You need to 1143This 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 1144call 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 1145call 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 1146macro on a watcher that is active (it can be pending, however, which is a
993 1159
994Example: Initialise and set an C<ev_io> watcher in one step. 1160Example: Initialise and set an C<ev_io> watcher in one step.
995 1161
996 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1162 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
997 1163
998=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1164=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
999 1165
1000Starts (activates) the given watcher. Only active watchers will receive 1166Starts (activates) the given watcher. Only active watchers will receive
1001events. If the watcher is already active nothing will happen. 1167events. If the watcher is already active nothing will happen.
1002 1168
1003Example: Start the C<ev_io> watcher that is being abused as example in this 1169Example: Start the C<ev_io> watcher that is being abused as example in this
1004whole section. 1170whole section.
1005 1171
1006 ev_io_start (EV_DEFAULT_UC, &w); 1172 ev_io_start (EV_DEFAULT_UC, &w);
1007 1173
1008=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1174=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1009 1175
1010Stops the given watcher if active, and clears the pending status (whether 1176Stops the given watcher if active, and clears the pending status (whether
1011the watcher was active or not). 1177the watcher was active or not).
1012 1178
1013It is possible that stopped watchers are pending - for example, 1179It is possible that stopped watchers are pending - for example,
1038=item ev_cb_set (ev_TYPE *watcher, callback) 1204=item ev_cb_set (ev_TYPE *watcher, callback)
1039 1205
1040Change the callback. You can change the callback at virtually any time 1206Change the callback. You can change the callback at virtually any time
1041(modulo threads). 1207(modulo threads).
1042 1208
1043=item ev_set_priority (ev_TYPE *watcher, priority) 1209=item ev_set_priority (ev_TYPE *watcher, int priority)
1044 1210
1045=item int ev_priority (ev_TYPE *watcher) 1211=item int ev_priority (ev_TYPE *watcher)
1046 1212
1047Set and query the priority of the watcher. The priority is a small 1213Set and query the priority of the watcher. The priority is a small
1048integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1214integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1049(default: C<-2>). Pending watchers with higher priority will be invoked 1215(default: C<-2>). Pending watchers with higher priority will be invoked
1050before watchers with lower priority, but priority will not keep watchers 1216before watchers with lower priority, but priority will not keep watchers
1051from being executed (except for C<ev_idle> watchers). 1217from being executed (except for C<ev_idle> watchers).
1052 1218
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 1219If you need to suppress invocation when higher priority events are pending
1059you need to look at C<ev_idle> watchers, which provide this functionality. 1220you need to look at C<ev_idle> watchers, which provide this functionality.
1060 1221
1061You I<must not> change the priority of a watcher as long as it is active or 1222You I<must not> change the priority of a watcher as long as it is active or
1062pending. 1223pending.
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 1224
1067Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1225Setting 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 1226fine, as long as you do not mind that the priority value you query might
1069or might not have been clamped to the valid range. 1227or might not have been clamped to the valid range.
1228
1229The default priority used by watchers when no priority has been set is
1230always C<0>, which is supposed to not be too high and not be too low :).
1231
1232See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1233priorities.
1070 1234
1071=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1235=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1072 1236
1073Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1237Invoke 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 1238C<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 1245returns its C<revents> bitset (as if its callback was invoked). If the
1082watcher isn't pending it does nothing and returns C<0>. 1246watcher isn't pending it does nothing and returns C<0>.
1083 1247
1084Sometimes it can be useful to "poll" a watcher instead of waiting for its 1248Sometimes it can be useful to "poll" a watcher instead of waiting for its
1085callback to be invoked, which can be accomplished with this function. 1249callback to be invoked, which can be accomplished with this function.
1250
1251=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1252
1253Feeds the given event set into the event loop, as if the specified event
1254had happened for the specified watcher (which must be a pointer to an
1255initialised but not necessarily started event watcher). Obviously you must
1256not free the watcher as long as it has pending events.
1257
1258Stopping the watcher, letting libev invoke it, or calling
1259C<ev_clear_pending> will clear the pending event, even if the watcher was
1260not started in the first place.
1261
1262See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1263functions that do not need a watcher.
1086 1264
1087=back 1265=back
1088 1266
1089 1267
1090=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1268=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1139 #include <stddef.h> 1317 #include <stddef.h>
1140 1318
1141 static void 1319 static void
1142 t1_cb (EV_P_ ev_timer *w, int revents) 1320 t1_cb (EV_P_ ev_timer *w, int revents)
1143 { 1321 {
1144 struct my_biggy big = (struct my_biggy * 1322 struct my_biggy big = (struct my_biggy *)
1145 (((char *)w) - offsetof (struct my_biggy, t1)); 1323 (((char *)w) - offsetof (struct my_biggy, t1));
1146 } 1324 }
1147 1325
1148 static void 1326 static void
1149 t2_cb (EV_P_ ev_timer *w, int revents) 1327 t2_cb (EV_P_ ev_timer *w, int revents)
1150 { 1328 {
1151 struct my_biggy big = (struct my_biggy * 1329 struct my_biggy big = (struct my_biggy *)
1152 (((char *)w) - offsetof (struct my_biggy, t2)); 1330 (((char *)w) - offsetof (struct my_biggy, t2));
1153 } 1331 }
1332
1333=head2 WATCHER PRIORITY MODELS
1334
1335Many event loops support I<watcher priorities>, which are usually small
1336integers that influence the ordering of event callback invocation
1337between watchers in some way, all else being equal.
1338
1339In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1340description for the more technical details such as the actual priority
1341range.
1342
1343There are two common ways how these these priorities are being interpreted
1344by event loops:
1345
1346In the more common lock-out model, higher priorities "lock out" invocation
1347of lower priority watchers, which means as long as higher priority
1348watchers receive events, lower priority watchers are not being invoked.
1349
1350The less common only-for-ordering model uses priorities solely to order
1351callback invocation within a single event loop iteration: Higher priority
1352watchers are invoked before lower priority ones, but they all get invoked
1353before polling for new events.
1354
1355Libev uses the second (only-for-ordering) model for all its watchers
1356except for idle watchers (which use the lock-out model).
1357
1358The rationale behind this is that implementing the lock-out model for
1359watchers is not well supported by most kernel interfaces, and most event
1360libraries will just poll for the same events again and again as long as
1361their callbacks have not been executed, which is very inefficient in the
1362common case of one high-priority watcher locking out a mass of lower
1363priority ones.
1364
1365Static (ordering) priorities are most useful when you have two or more
1366watchers handling the same resource: a typical usage example is having an
1367C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1368timeouts. Under load, data might be received while the program handles
1369other jobs, but since timers normally get invoked first, the timeout
1370handler will be executed before checking for data. In that case, giving
1371the timer a lower priority than the I/O watcher ensures that I/O will be
1372handled first even under adverse conditions (which is usually, but not
1373always, what you want).
1374
1375Since idle watchers use the "lock-out" model, meaning that idle watchers
1376will only be executed when no same or higher priority watchers have
1377received events, they can be used to implement the "lock-out" model when
1378required.
1379
1380For example, to emulate how many other event libraries handle priorities,
1381you can associate an C<ev_idle> watcher to each such watcher, and in
1382the normal watcher callback, you just start the idle watcher. The real
1383processing is done in the idle watcher callback. This causes libev to
1384continously poll and process kernel event data for the watcher, but when
1385the lock-out case is known to be rare (which in turn is rare :), this is
1386workable.
1387
1388Usually, however, the lock-out model implemented that way will perform
1389miserably under the type of load it was designed to handle. In that case,
1390it might be preferable to stop the real watcher before starting the
1391idle watcher, so the kernel will not have to process the event in case
1392the actual processing will be delayed for considerable time.
1393
1394Here is an example of an I/O watcher that should run at a strictly lower
1395priority than the default, and which should only process data when no
1396other events are pending:
1397
1398 ev_idle idle; // actual processing watcher
1399 ev_io io; // actual event watcher
1400
1401 static void
1402 io_cb (EV_P_ ev_io *w, int revents)
1403 {
1404 // stop the I/O watcher, we received the event, but
1405 // are not yet ready to handle it.
1406 ev_io_stop (EV_A_ w);
1407
1408 // start the idle watcher to ahndle the actual event.
1409 // it will not be executed as long as other watchers
1410 // with the default priority are receiving events.
1411 ev_idle_start (EV_A_ &idle);
1412 }
1413
1414 static void
1415 idle_cb (EV_P_ ev_idle *w, int revents)
1416 {
1417 // actual processing
1418 read (STDIN_FILENO, ...);
1419
1420 // have to start the I/O watcher again, as
1421 // we have handled the event
1422 ev_io_start (EV_P_ &io);
1423 }
1424
1425 // initialisation
1426 ev_idle_init (&idle, idle_cb);
1427 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1428 ev_io_start (EV_DEFAULT_ &io);
1429
1430In the "real" world, it might also be beneficial to start a timer, so that
1431low-priority connections can not be locked out forever under load. This
1432enables your program to keep a lower latency for important connections
1433during short periods of high load, while not completely locking out less
1434important ones.
1154 1435
1155 1436
1156=head1 WATCHER TYPES 1437=head1 WATCHER TYPES
1157 1438
1158This section describes each watcher in detail, but will not repeat 1439This section describes each watcher in detail, but will not repeat
1184descriptors to non-blocking mode is also usually a good idea (but not 1465descriptors to non-blocking mode is also usually a good idea (but not
1185required if you know what you are doing). 1466required if you know what you are doing).
1186 1467
1187If you cannot use non-blocking mode, then force the use of a 1468If 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 1469known-to-be-good backend (at the time of this writing, this includes only
1189C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). 1470C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1471descriptors for which non-blocking operation makes no sense (such as
1472files) - libev doesn't guarentee any specific behaviour in that case.
1190 1473
1191Another thing you have to watch out for is that it is quite easy to 1474Another thing you have to watch out for is that it is quite easy to
1192receive "spurious" readiness notifications, that is your callback might 1475receive "spurious" readiness notifications, that is your callback might
1193be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1476be 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 1477because there is no data. Not only are some backends known to create a
1259 1542
1260So when you encounter spurious, unexplained daemon exits, make sure you 1543So when you encounter spurious, unexplained daemon exits, make sure you
1261ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1544ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1262somewhere, as that would have given you a big clue). 1545somewhere, as that would have given you a big clue).
1263 1546
1547=head3 The special problem of accept()ing when you can't
1548
1549Many implementations of the POSIX C<accept> function (for example,
1550found in post-2004 Linux) have the peculiar behaviour of not removing a
1551connection from the pending queue in all error cases.
1552
1553For example, larger servers often run out of file descriptors (because
1554of resource limits), causing C<accept> to fail with C<ENFILE> but not
1555rejecting the connection, leading to libev signalling readiness on
1556the next iteration again (the connection still exists after all), and
1557typically causing the program to loop at 100% CPU usage.
1558
1559Unfortunately, the set of errors that cause this issue differs between
1560operating systems, there is usually little the app can do to remedy the
1561situation, and no known thread-safe method of removing the connection to
1562cope with overload is known (to me).
1563
1564One of the easiest ways to handle this situation is to just ignore it
1565- when the program encounters an overload, it will just loop until the
1566situation is over. While this is a form of busy waiting, no OS offers an
1567event-based way to handle this situation, so it's the best one can do.
1568
1569A better way to handle the situation is to log any errors other than
1570C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1571messages, and continue as usual, which at least gives the user an idea of
1572what could be wrong ("raise the ulimit!"). For extra points one could stop
1573the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1574usage.
1575
1576If your program is single-threaded, then you could also keep a dummy file
1577descriptor for overload situations (e.g. by opening F</dev/null>), and
1578when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1579close that fd, and create a new dummy fd. This will gracefully refuse
1580clients under typical overload conditions.
1581
1582The last way to handle it is to simply log the error and C<exit>, as
1583is often done with C<malloc> failures, but this results in an easy
1584opportunity for a DoS attack.
1264 1585
1265=head3 Watcher-Specific Functions 1586=head3 Watcher-Specific Functions
1266 1587
1267=over 4 1588=over 4
1268 1589
1315year, it will still time out after (roughly) one hour. "Roughly" because 1636year, it will still time out after (roughly) one hour. "Roughly" because
1316detecting time jumps is hard, and some inaccuracies are unavoidable (the 1637detecting time jumps is hard, and some inaccuracies are unavoidable (the
1317monotonic clock option helps a lot here). 1638monotonic clock option helps a lot here).
1318 1639
1319The callback is guaranteed to be invoked only I<after> its timeout has 1640The callback is guaranteed to be invoked only I<after> its timeout has
1320passed, but if multiple timers become ready during the same loop iteration 1641passed (not I<at>, so on systems with very low-resolution clocks this
1321then order of execution is undefined. 1642might introduce a small delay). If multiple timers become ready during the
1643same loop iteration then the ones with earlier time-out values are invoked
1644before ones of the same priority with later time-out values (but this is
1645no longer true when a callback calls C<ev_loop> recursively).
1322 1646
1323=head3 Be smart about timeouts 1647=head3 Be smart about timeouts
1324 1648
1325Many real-world problems involve some kind of timeout, usually for error 1649Many real-world problems involve some kind of timeout, usually for error
1326recovery. A typical example is an HTTP request - if the other side hangs, 1650recovery. 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> 1694C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1371member and C<ev_timer_again>. 1695member and C<ev_timer_again>.
1372 1696
1373At start: 1697At start:
1374 1698
1375 ev_timer_init (timer, callback); 1699 ev_init (timer, callback);
1376 timer->repeat = 60.; 1700 timer->repeat = 60.;
1377 ev_timer_again (loop, timer); 1701 ev_timer_again (loop, timer);
1378 1702
1379Each time there is some activity: 1703Each time there is some activity:
1380 1704
1442 1766
1443To start the timer, simply initialise the watcher and set C<last_activity> 1767To 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 1768to the current time (meaning we just have some activity :), then call the
1445callback, which will "do the right thing" and start the timer: 1769callback, which will "do the right thing" and start the timer:
1446 1770
1447 ev_timer_init (timer, callback); 1771 ev_init (timer, callback);
1448 last_activity = ev_now (loop); 1772 last_activity = ev_now (loop);
1449 callback (loop, timer, EV_TIMEOUT); 1773 callback (loop, timer, EV_TIMER);
1450 1774
1451And when there is some activity, simply store the current time in 1775And when there is some activity, simply store the current time in
1452C<last_activity>, no libev calls at all: 1776C<last_activity>, no libev calls at all:
1453 1777
1454 last_actiivty = ev_now (loop); 1778 last_actiivty = ev_now (loop);
1513 1837
1514If the event loop is suspended for a long time, you can also force an 1838If 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 1839update of the time returned by C<ev_now ()> by calling C<ev_now_update
1516()>. 1840()>.
1517 1841
1842=head3 The special problems of suspended animation
1843
1844When you leave the server world it is quite customary to hit machines that
1845can suspend/hibernate - what happens to the clocks during such a suspend?
1846
1847Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1848all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1849to run until the system is suspended, but they will not advance while the
1850system is suspended. That means, on resume, it will be as if the program
1851was frozen for a few seconds, but the suspend time will not be counted
1852towards C<ev_timer> when a monotonic clock source is used. The real time
1853clock advanced as expected, but if it is used as sole clocksource, then a
1854long suspend would be detected as a time jump by libev, and timers would
1855be adjusted accordingly.
1856
1857I would not be surprised to see different behaviour in different between
1858operating systems, OS versions or even different hardware.
1859
1860The other form of suspend (job control, or sending a SIGSTOP) will see a
1861time jump in the monotonic clocks and the realtime clock. If the program
1862is suspended for a very long time, and monotonic clock sources are in use,
1863then you can expect C<ev_timer>s to expire as the full suspension time
1864will be counted towards the timers. When no monotonic clock source is in
1865use, then libev will again assume a timejump and adjust accordingly.
1866
1867It might be beneficial for this latter case to call C<ev_suspend>
1868and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1869deterministic behaviour in this case (you can do nothing against
1870C<SIGSTOP>).
1871
1518=head3 Watcher-Specific Functions and Data Members 1872=head3 Watcher-Specific Functions and Data Members
1519 1873
1520=over 4 1874=over 4
1521 1875
1522=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1876=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). 1899If the timer is started but non-repeating, stop it (as if it timed out).
1546 1900
1547If the timer is repeating, either start it if necessary (with the 1901If the timer is repeating, either start it if necessary (with the
1548C<repeat> value), or reset the running timer to the C<repeat> value. 1902C<repeat> value), or reset the running timer to the C<repeat> value.
1549 1903
1550This sounds a bit complicated, see "Be smart about timeouts", above, for a 1904This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1551usage example. 1905usage example.
1906
1907=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1908
1909Returns the remaining time until a timer fires. If the timer is active,
1910then this time is relative to the current event loop time, otherwise it's
1911the timeout value currently configured.
1912
1913That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1914C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1915will return C<4>. When the timer expires and is restarted, it will return
1916roughly C<7> (likely slightly less as callback invocation takes some time,
1917too), and so on.
1552 1918
1553=item ev_tstamp repeat [read-write] 1919=item ev_tstamp repeat [read-write]
1554 1920
1555The current C<repeat> value. Will be used each time the watcher times out 1921The 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), 1922or C<ev_timer_again> is called, and determines the next timeout (if any),
1594=head2 C<ev_periodic> - to cron or not to cron? 1960=head2 C<ev_periodic> - to cron or not to cron?
1595 1961
1596Periodic watchers are also timers of a kind, but they are very versatile 1962Periodic watchers are also timers of a kind, but they are very versatile
1597(and unfortunately a bit complex). 1963(and unfortunately a bit complex).
1598 1964
1599Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1965Unlike 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 1966relative 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 1967(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 () 1968difference 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 1969time, 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 1970wrist-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 1971
1972You can tell a periodic watcher to trigger after some specific point
1973in time: for example, if you tell a periodic watcher to trigger "in 10
1974seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1975not a delay) and then reset your system clock to January of the previous
1976year, then it will take a year or more to trigger the event (unlike an
1977C<ev_timer>, which would still trigger roughly 10 seconds after starting
1978it, as it uses a relative timeout).
1979
1608C<ev_periodic>s can also be used to implement vastly more complex timers, 1980C<ev_periodic> watchers can also be used to implement vastly more complex
1609such as triggering an event on each "midnight, local time", or other 1981timers, such as triggering an event on each "midnight, local time", or
1610complicated rules. 1982other complicated rules. This cannot be done with C<ev_timer> watchers, as
1983those cannot react to time jumps.
1611 1984
1612As with timers, the callback is guaranteed to be invoked only when the 1985As with timers, the callback is guaranteed to be invoked only when the
1613time (C<at>) has passed, but if multiple periodic timers become ready 1986point in time where it is supposed to trigger has passed. If multiple
1614during the same loop iteration, then order of execution is undefined. 1987timers become ready during the same loop iteration then the ones with
1988earlier time-out values are invoked before ones with later time-out values
1989(but this is no longer true when a callback calls C<ev_loop> recursively).
1615 1990
1616=head3 Watcher-Specific Functions and Data Members 1991=head3 Watcher-Specific Functions and Data Members
1617 1992
1618=over 4 1993=over 4
1619 1994
1620=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1995=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1621 1996
1622=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1997=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1623 1998
1624Lots of arguments, lets sort it out... There are basically three modes of 1999Lots of arguments, let's sort it out... There are basically three modes of
1625operation, and we will explain them from simplest to most complex: 2000operation, and we will explain them from simplest to most complex:
1626 2001
1627=over 4 2002=over 4
1628 2003
1629=item * absolute timer (at = time, interval = reschedule_cb = 0) 2004=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1630 2005
1631In this configuration the watcher triggers an event after the wall clock 2006In 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 2007time 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 2008time 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. 2009will be stopped and invoked when the system clock reaches or surpasses
2010this point in time.
1635 2011
1636=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 2012=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1637 2013
1638In this mode the watcher will always be scheduled to time out at the next 2014In 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) 2015C<offset + N * interval> time (for some integer N, which can also be
1640and then repeat, regardless of any time jumps. 2016negative) and then repeat, regardless of any time jumps. The C<offset>
2017argument is merely an offset into the C<interval> periods.
1641 2018
1642This can be used to create timers that do not drift with respect to the 2019This 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 2020system clock, for example, here is an C<ev_periodic> that triggers each
1644hour, on the hour: 2021hour, on the hour (with respect to UTC):
1645 2022
1646 ev_periodic_set (&periodic, 0., 3600., 0); 2023 ev_periodic_set (&periodic, 0., 3600., 0);
1647 2024
1648This doesn't mean there will always be 3600 seconds in between triggers, 2025This 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 2026but 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 2027full hour (UTC), or more correctly, when the system time is evenly divisible
1651by 3600. 2028by 3600.
1652 2029
1653Another way to think about it (for the mathematically inclined) is that 2030Another 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 2031C<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. 2032time where C<time = offset (mod interval)>, regardless of any time jumps.
1656 2033
1657For numerical stability it is preferable that the C<at> value is near 2034For 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 2035C<ev_now ()> (the current time), but there is no range requirement for
1659this value, and in fact is often specified as zero. 2036this value, and in fact is often specified as zero.
1660 2037
1661Note also that there is an upper limit to how often a timer can fire (CPU 2038Note 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 2039speed 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 2040will 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). 2041millisecond (if the OS supports it and the machine is fast enough).
1665 2042
1666=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 2043=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1667 2044
1668In this mode the values for C<interval> and C<at> are both being 2045In this mode the values for C<interval> and C<offset> are both being
1669ignored. Instead, each time the periodic watcher gets scheduled, the 2046ignored. Instead, each time the periodic watcher gets scheduled, the
1670reschedule callback will be called with the watcher as first, and the 2047reschedule callback will be called with the watcher as first, and the
1671current time as second argument. 2048current time as second argument.
1672 2049
1673NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 2050NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1674ever, or make ANY event loop modifications whatsoever>. 2051or make ANY other event loop modifications whatsoever, unless explicitly
2052allowed by documentation here>.
1675 2053
1676If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 2054If 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 2055it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1678only event loop modification you are allowed to do). 2056only event loop modification you are allowed to do).
1679 2057
1709a different time than the last time it was called (e.g. in a crond like 2087a different time than the last time it was called (e.g. in a crond like
1710program when the crontabs have changed). 2088program when the crontabs have changed).
1711 2089
1712=item ev_tstamp ev_periodic_at (ev_periodic *) 2090=item ev_tstamp ev_periodic_at (ev_periodic *)
1713 2091
1714When active, returns the absolute time that the watcher is supposed to 2092When active, returns the absolute time that the watcher is supposed
1715trigger next. 2093to trigger next. This is not the same as the C<offset> argument to
2094C<ev_periodic_set>, but indeed works even in interval and manual
2095rescheduling modes.
1716 2096
1717=item ev_tstamp offset [read-write] 2097=item ev_tstamp offset [read-write]
1718 2098
1719When repeating, this contains the offset value, otherwise this is the 2099When repeating, this contains the offset value, otherwise this is the
1720absolute point in time (the C<at> value passed to C<ev_periodic_set>). 2100absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
2101although libev might modify this value for better numerical stability).
1721 2102
1722Can be modified any time, but changes only take effect when the periodic 2103Can be modified any time, but changes only take effect when the periodic
1723timer fires or C<ev_periodic_again> is being called. 2104timer fires or C<ev_periodic_again> is being called.
1724 2105
1725=item ev_tstamp interval [read-write] 2106=item ev_tstamp interval [read-write]
1777Signal watchers will trigger an event when the process receives a specific 2158Signal watchers will trigger an event when the process receives a specific
1778signal one or more times. Even though signals are very asynchronous, libev 2159signal 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 2160will try it's best to deliver signals synchronously, i.e. as part of the
1780normal event processing, like any other event. 2161normal event processing, like any other event.
1781 2162
1782If you want signals asynchronously, just use C<sigaction> as you would 2163If you want signals to be delivered truly asynchronously, just use
1783do without libev and forget about sharing the signal. You can even use 2164C<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. 2165the signal. You can even use C<ev_async> from a signal handler to
2166synchronously wake up an event loop.
1785 2167
1786You can configure as many watchers as you like per signal. Only when the 2168You can configure as many watchers as you like for the same signal, but
2169only within the same loop, i.e. you can watch for C<SIGINT> in your
2170default loop and for C<SIGIO> in another loop, but you cannot watch for
2171C<SIGINT> in both the default loop and another loop at the same time. At
2172the moment, C<SIGCHLD> is permanently tied to the default loop.
2173
1787first watcher gets started will libev actually register a signal handler 2174When the first watcher gets started will libev actually register something
1788with the kernel (thus it coexists with your own signal handlers as long as 2175with 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 2176you 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 2177
1793If possible and supported, libev will install its handlers with 2178If possible and supported, libev will install its handlers with
1794C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2179C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1795interrupted. If you have a problem with system calls getting interrupted by 2180not 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 2181interrupted by signals you can block all signals in an C<ev_check> watcher
1797them in an C<ev_prepare> watcher. 2182and unblock them in an C<ev_prepare> watcher.
2183
2184=head3 The special problem of inheritance over fork/execve/pthread_create
2185
2186Both the signal mask (C<sigprocmask>) and the signal disposition
2187(C<sigaction>) are unspecified after starting a signal watcher (and after
2188stopping it again), that is, libev might or might not block the signal,
2189and might or might not set or restore the installed signal handler.
2190
2191While this does not matter for the signal disposition (libev never
2192sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2193C<execve>), this matters for the signal mask: many programs do not expect
2194certain signals to be blocked.
2195
2196This means that before calling C<exec> (from the child) you should reset
2197the signal mask to whatever "default" you expect (all clear is a good
2198choice usually).
2199
2200The simplest way to ensure that the signal mask is reset in the child is
2201to install a fork handler with C<pthread_atfork> that resets it. That will
2202catch fork calls done by libraries (such as the libc) as well.
2203
2204In current versions of libev, the signal will not be blocked indefinitely
2205unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2206the window of opportunity for problems, it will not go away, as libev
2207I<has> to modify the signal mask, at least temporarily.
2208
2209So I can't stress this enough: I<If you do not reset your signal mask when
2210you expect it to be empty, you have a race condition in your code>. This
2211is not a libev-specific thing, this is true for most event libraries.
1798 2212
1799=head3 Watcher-Specific Functions and Data Members 2213=head3 Watcher-Specific Functions and Data Members
1800 2214
1801=over 4 2215=over 4
1802 2216
1834some child status changes (most typically when a child of yours dies or 2248some 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 2249exits). It is permissible to install a child watcher I<after> the child
1836has been forked (which implies it might have already exited), as long 2250has 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., 2251as 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, 2252forking and then immediately registering a watcher for the child is fine,
1839but forking and registering a watcher a few event loop iterations later is 2253but forking and registering a watcher a few event loop iterations later or
1840not. 2254in the next callback invocation is not.
1841 2255
1842Only the default event loop is capable of handling signals, and therefore 2256Only the default event loop is capable of handling signals, and therefore
1843you can only register child watchers in the default event loop. 2257you can only register child watchers in the default event loop.
1844 2258
2259Due to some design glitches inside libev, child watchers will always be
2260handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2261libev)
2262
1845=head3 Process Interaction 2263=head3 Process Interaction
1846 2264
1847Libev grabs C<SIGCHLD> as soon as the default event loop is 2265Libev grabs C<SIGCHLD> as soon as the default event loop is
1848initialised. This is necessary to guarantee proper behaviour even if 2266initialised. This is necessary to guarantee proper behaviour even if the
1849the first child watcher is started after the child exits. The occurrence 2267first child watcher is started after the child exits. The occurrence
1850of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2268of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1851synchronously as part of the event loop processing. Libev always reaps all 2269synchronously as part of the event loop processing. Libev always reaps all
1852children, even ones not watched. 2270children, even ones not watched.
1853 2271
1854=head3 Overriding the Built-In Processing 2272=head3 Overriding the Built-In Processing
1864=head3 Stopping the Child Watcher 2282=head3 Stopping the Child Watcher
1865 2283
1866Currently, the child watcher never gets stopped, even when the 2284Currently, the child watcher never gets stopped, even when the
1867child terminates, so normally one needs to stop the watcher in the 2285child terminates, so normally one needs to stop the watcher in the
1868callback. Future versions of libev might stop the watcher automatically 2286callback. Future versions of libev might stop the watcher automatically
1869when a child exit is detected. 2287when a child exit is detected (calling C<ev_child_stop> twice is not a
2288problem).
1870 2289
1871=head3 Watcher-Specific Functions and Data Members 2290=head3 Watcher-Specific Functions and Data Members
1872 2291
1873=over 4 2292=over 4
1874 2293
2010the process. The exception are C<ev_stat> watchers - those call C<stat 2429the process. The exception are C<ev_stat> watchers - those call C<stat
2011()>, which is a synchronous operation. 2430()>, which is a synchronous operation.
2012 2431
2013For local paths, this usually doesn't matter: unless the system is very 2432For 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, 2433busy 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 2434as the path data is usually in memory already (except when starting the
2016watcher). 2435watcher).
2017 2436
2018For networked file systems, calling C<stat ()> can block an indefinite 2437For networked file systems, calling C<stat ()> can block an indefinite
2019time due to network issues, and even under good conditions, a stat call 2438time due to network issues, and even under good conditions, a stat call
2020often takes multiple milliseconds. 2439often takes multiple milliseconds.
2177 2596
2178=head3 Watcher-Specific Functions and Data Members 2597=head3 Watcher-Specific Functions and Data Members
2179 2598
2180=over 4 2599=over 4
2181 2600
2182=item ev_idle_init (ev_signal *, callback) 2601=item ev_idle_init (ev_idle *, callback)
2183 2602
2184Initialises and configures the idle watcher - it has no parameters of any 2603Initialises 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, 2604kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2186believe me. 2605believe me.
2187 2606
2200 // no longer anything immediate to do. 2619 // no longer anything immediate to do.
2201 } 2620 }
2202 2621
2203 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 2622 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2204 ev_idle_init (idle_watcher, idle_cb); 2623 ev_idle_init (idle_watcher, idle_cb);
2205 ev_idle_start (loop, idle_cb); 2624 ev_idle_start (loop, idle_watcher);
2206 2625
2207 2626
2208=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2627=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2209 2628
2210Prepare and check watchers are usually (but not always) used in pairs: 2629Prepare and check watchers are usually (but not always) used in pairs:
2303 struct pollfd fds [nfd]; 2722 struct pollfd fds [nfd];
2304 // actual code will need to loop here and realloc etc. 2723 // actual code will need to loop here and realloc etc.
2305 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2724 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2306 2725
2307 /* the callback is illegal, but won't be called as we stop during check */ 2726 /* the callback is illegal, but won't be called as we stop during check */
2308 ev_timer_init (&tw, 0, timeout * 1e-3); 2727 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2309 ev_timer_start (loop, &tw); 2728 ev_timer_start (loop, &tw);
2310 2729
2311 // create one ev_io per pollfd 2730 // create one ev_io per pollfd
2312 for (int i = 0; i < nfd; ++i) 2731 for (int i = 0; i < nfd; ++i)
2313 { 2732 {
2426some fds have to be watched and handled very quickly (with low latency), 2845some fds have to be watched and handled very quickly (with low latency),
2427and even priorities and idle watchers might have too much overhead. In 2846and 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 2847this 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. 2848the rest in a second one, and embed the second one in the first.
2430 2849
2431As long as the watcher is active, the callback will be invoked every time 2850As 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 2851time 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 2852must 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 2853sweep and invoke their callbacks (the callback doesn't need to invoke the
2435loop strictly lower priority for example). You can also set the callback 2854C<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 2855to give the embedded loop strictly lower priority for example).
2437embedded loop sweep.
2438 2856
2439As long as the watcher is started it will automatically handle events. The 2857You 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 2858will 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 2859
2444Also, there have not currently been made special provisions for forking: 2860Fork 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, 2861is 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 2862embedding loop forks. In other cases, the user is responsible for calling
2447yourself - but you can use a fork watcher to handle this automatically, 2863C<ev_loop_fork> on the embedded loop.
2448and future versions of libev might do just that.
2449 2864
2450Unfortunately, not all backends are embeddable: only the ones returned by 2865Unfortunately, not all backends are embeddable: only the ones returned by
2451C<ev_embeddable_backends> are, which, unfortunately, does not include any 2866C<ev_embeddable_backends> are, which, unfortunately, does not include any
2452portable one. 2867portable one.
2453 2868
2547event loop blocks next and before C<ev_check> watchers are being called, 2962event 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 2963and 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 2964C<ev_default_fork> cheats and calls it in the wrong process, the fork
2550handlers will be invoked, too, of course. 2965handlers will be invoked, too, of course.
2551 2966
2967=head3 The special problem of life after fork - how is it possible?
2968
2969Most uses of C<fork()> consist of forking, then some simple calls to ste
2970up/change the process environment, followed by a call to C<exec()>. This
2971sequence should be handled by libev without any problems.
2972
2973This changes when the application actually wants to do event handling
2974in the child, or both parent in child, in effect "continuing" after the
2975fork.
2976
2977The default mode of operation (for libev, with application help to detect
2978forks) is to duplicate all the state in the child, as would be expected
2979when I<either> the parent I<or> the child process continues.
2980
2981When both processes want to continue using libev, then this is usually the
2982wrong result. In that case, usually one process (typically the parent) is
2983supposed to continue with all watchers in place as before, while the other
2984process typically wants to start fresh, i.e. without any active watchers.
2985
2986The cleanest and most efficient way to achieve that with libev is to
2987simply create a new event loop, which of course will be "empty", and
2988use that for new watchers. This has the advantage of not touching more
2989memory than necessary, and thus avoiding the copy-on-write, and the
2990disadvantage of having to use multiple event loops (which do not support
2991signal watchers).
2992
2993When this is not possible, or you want to use the default loop for
2994other reasons, then in the process that wants to start "fresh", call
2995C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
2996the default loop will "orphan" (not stop) all registered watchers, so you
2997have to be careful not to execute code that modifies those watchers. Note
2998also that in that case, you have to re-register any signal watchers.
2999
2552=head3 Watcher-Specific Functions and Data Members 3000=head3 Watcher-Specific Functions and Data Members
2553 3001
2554=over 4 3002=over 4
2555 3003
2556=item ev_fork_init (ev_signal *, callback) 3004=item ev_fork_init (ev_signal *, callback)
2585=head3 Queueing 3033=head3 Queueing
2586 3034
2587C<ev_async> does not support queueing of data in any way. The reason 3035C<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 3036is 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 3037multiple-writer-single-reader queue that works in all cases and doesn't
2590need elaborate support such as pthreads. 3038need elaborate support such as pthreads or unportable memory access
3039semantics.
2591 3040
2592That means that if you want to queue data, you have to provide your own 3041That 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 3042queue. But at least I can tell you how to implement locking around your
2594queue: 3043queue:
2595 3044
2684an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3133an 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 3134C<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 3135similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2687section below on what exactly this means). 3136section below on what exactly this means).
2688 3137
3138Note that, as with other watchers in libev, multiple events might get
3139compressed into a single callback invocation (another way to look at this
3140is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
3141reset when the event loop detects that).
3142
2689This call incurs the overhead of a system call only once per loop iteration, 3143This 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 3144iteration, so while the overhead might be noticeable, it doesn't apply to
2691calls to C<ev_async_send>. 3145repeated calls to C<ev_async_send> for the same event loop.
2692 3146
2693=item bool = ev_async_pending (ev_async *) 3147=item bool = ev_async_pending (ev_async *)
2694 3148
2695Returns a non-zero value when C<ev_async_send> has been called on the 3149Returns 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 3150watcher 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 3153C<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, 3154the 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 3155it 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. 3156quickly check whether invoking the loop might be a good idea.
2703 3157
2704Not that this does I<not> check whether the watcher itself is pending, only 3158Not that this does I<not> check whether the watcher itself is pending,
2705whether it has been requested to make this watcher pending. 3159only whether it has been requested to make this watcher pending: there
3160is a time window between the event loop checking and resetting the async
3161notification, and the callback being invoked.
2706 3162
2707=back 3163=back
2708 3164
2709 3165
2710=head1 OTHER FUNCTIONS 3166=head1 OTHER FUNCTIONS
2727 3183
2728If C<timeout> is less than 0, then no timeout watcher will be 3184If C<timeout> is less than 0, then no timeout watcher will be
2729started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3185started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2730repeat = 0) will be started. C<0> is a valid timeout. 3186repeat = 0) will be started. C<0> is a valid timeout.
2731 3187
2732The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3188The 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 3189passed 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> 3190C<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> 3191value 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 3192a timeout and an io event at the same time - you probably should give io
2737events precedence. 3193events precedence.
2738 3194
2739Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3195Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2740 3196
2741 static void stdin_ready (int revents, void *arg) 3197 static void stdin_ready (int revents, void *arg)
2742 { 3198 {
2743 if (revents & EV_READ) 3199 if (revents & EV_READ)
2744 /* stdin might have data for us, joy! */; 3200 /* stdin might have data for us, joy! */;
2745 else if (revents & EV_TIMEOUT) 3201 else if (revents & EV_TIMER)
2746 /* doh, nothing entered */; 3202 /* doh, nothing entered */;
2747 } 3203 }
2748 3204
2749 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3205 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2750 3206
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) 3207=item ev_feed_fd_event (loop, int fd, int revents)
2758 3208
2759Feed an event on the given fd, as if a file descriptor backend detected 3209Feed an event on the given fd, as if a file descriptor backend detected
2760the given events it. 3210the given events it.
2761 3211
2762=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3212=item ev_feed_signal_event (loop, int signum)
2763 3213
2764Feed an event as if the given signal occurred (C<loop> must be the default 3214Feed an event as if the given signal occurred (C<loop> must be the default
2765loop!). 3215loop!).
2766 3216
2767=back 3217=back
2847 3297
2848=over 4 3298=over 4
2849 3299
2850=item ev::TYPE::TYPE () 3300=item ev::TYPE::TYPE ()
2851 3301
2852=item ev::TYPE::TYPE (struct ev_loop *) 3302=item ev::TYPE::TYPE (loop)
2853 3303
2854=item ev::TYPE::~TYPE 3304=item ev::TYPE::~TYPE
2855 3305
2856The constructor (optionally) takes an event loop to associate the watcher 3306The constructor (optionally) takes an event loop to associate the watcher
2857with. If it is omitted, it will use C<EV_DEFAULT>. 3307with. If it is omitted, it will use C<EV_DEFAULT>.
2889 3339
2890 myclass obj; 3340 myclass obj;
2891 ev::io iow; 3341 ev::io iow;
2892 iow.set <myclass, &myclass::io_cb> (&obj); 3342 iow.set <myclass, &myclass::io_cb> (&obj);
2893 3343
3344=item w->set (object *)
3345
3346This is an B<experimental> feature that might go away in a future version.
3347
3348This is a variation of a method callback - leaving out the method to call
3349will default the method to C<operator ()>, which makes it possible to use
3350functor objects without having to manually specify the C<operator ()> all
3351the time. Incidentally, you can then also leave out the template argument
3352list.
3353
3354The C<operator ()> method prototype must be C<void operator ()(watcher &w,
3355int revents)>.
3356
3357See the method-C<set> above for more details.
3358
3359Example: use a functor object as callback.
3360
3361 struct myfunctor
3362 {
3363 void operator() (ev::io &w, int revents)
3364 {
3365 ...
3366 }
3367 }
3368
3369 myfunctor f;
3370
3371 ev::io w;
3372 w.set (&f);
3373
2894=item w->set<function> (void *data = 0) 3374=item w->set<function> (void *data = 0)
2895 3375
2896Also sets a callback, but uses a static method or plain function as 3376Also 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 3377callback. The optional C<data> argument will be stored in the watcher's
2898C<data> member and is free for you to use. 3378C<data> member and is free for you to use.
2904Example: Use a plain function as callback. 3384Example: Use a plain function as callback.
2905 3385
2906 static void io_cb (ev::io &w, int revents) { } 3386 static void io_cb (ev::io &w, int revents) { }
2907 iow.set <io_cb> (); 3387 iow.set <io_cb> ();
2908 3388
2909=item w->set (struct ev_loop *) 3389=item w->set (loop)
2910 3390
2911Associates a different C<struct ev_loop> with this watcher. You can only 3391Associates a different C<struct ev_loop> with this watcher. You can only
2912do this when the watcher is inactive (and not pending either). 3392do this when the watcher is inactive (and not pending either).
2913 3393
2914=item w->set ([arguments]) 3394=item w->set ([arguments])
2984L<http://software.schmorp.de/pkg/EV>. 3464L<http://software.schmorp.de/pkg/EV>.
2985 3465
2986=item Python 3466=item Python
2987 3467
2988Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3468Python 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 3469seems 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 3470
2995=item Ruby 3471=item Ruby
2996 3472
2997Tony Arcieri has written a ruby extension that offers access to a subset 3473Tony Arcieri has written a ruby extension that offers access to a subset
2998of the libev API and adds file handle abstractions, asynchronous DNS and 3474of 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 3475more on top of it. It can be found via gem servers. Its homepage is at
3000L<http://rev.rubyforge.org/>. 3476L<http://rev.rubyforge.org/>.
3001 3477
3478Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3479makes rev work even on mingw.
3480
3481=item Haskell
3482
3483A haskell binding to libev is available at
3484L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3485
3002=item D 3486=item D
3003 3487
3004Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3488Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3005be found at L<http://proj.llucax.com.ar/wiki/evd>. 3489be found at L<http://proj.llucax.com.ar/wiki/evd>.
3006 3490
3007=item Ocaml 3491=item Ocaml
3008 3492
3009Erkki Seppala has written Ocaml bindings for libev, to be found at 3493Erkki Seppala has written Ocaml bindings for libev, to be found at
3010L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3494L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3495
3496=item Lua
3497
3498Brian Maher has written a partial interface to libev for lua (at the
3499time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3500L<http://github.com/brimworks/lua-ev>.
3011 3501
3012=back 3502=back
3013 3503
3014 3504
3015=head1 MACRO MAGIC 3505=head1 MACRO MAGIC
3169 libev.m4 3659 libev.m4
3170 3660
3171=head2 PREPROCESSOR SYMBOLS/MACROS 3661=head2 PREPROCESSOR SYMBOLS/MACROS
3172 3662
3173Libev can be configured via a variety of preprocessor symbols you have to 3663Libev 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 3664define before including (or compiling) any of its files. The default in
3175autoconf is documented for every option. 3665the absence of autoconf is documented for every option.
3666
3667Symbols marked with "(h)" do not change the ABI, and can have different
3668values when compiling libev vs. including F<ev.h>, so it is permissible
3669to redefine them before including F<ev.h> without breaking compatibility
3670to a compiled library. All other symbols change the ABI, which means all
3671users of libev and the libev code itself must be compiled with compatible
3672settings.
3176 3673
3177=over 4 3674=over 4
3178 3675
3179=item EV_STANDALONE 3676=item EV_STANDALONE (h)
3180 3677
3181Must always be C<1> if you do not use autoconf configuration, which 3678Must always be C<1> if you do not use autoconf configuration, which
3182keeps libev from including F<config.h>, and it also defines dummy 3679keeps libev from including F<config.h>, and it also defines dummy
3183implementations for some libevent functions (such as logging, which is not 3680implementations for some libevent functions (such as logging, which is not
3184supported). It will also not define any of the structs usually found in 3681supported). 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. 3682F<event.h> that are not directly supported by the libev core alone.
3186 3683
3684In standalone mode, libev will still try to automatically deduce the
3685configuration, but has to be more conservative.
3686
3187=item EV_USE_MONOTONIC 3687=item EV_USE_MONOTONIC
3188 3688
3189If defined to be C<1>, libev will try to detect the availability of the 3689If 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 3690monotonic clock option at both compile time and runtime. Otherwise no
3191of the monotonic clock option will be attempted. If you enable this, you 3691use of the monotonic clock option will be attempted. If you enable this,
3192usually have to link against librt or something similar. Enabling it when 3692you usually have to link against librt or something similar. Enabling it
3193the functionality isn't available is safe, though, although you have 3693when the functionality isn't available is safe, though, although you have
3194to make sure you link against any libraries where the C<clock_gettime> 3694to make sure you link against any libraries where the C<clock_gettime>
3195function is hiding in (often F<-lrt>). 3695function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3196 3696
3197=item EV_USE_REALTIME 3697=item EV_USE_REALTIME
3198 3698
3199If defined to be C<1>, libev will try to detect the availability of the 3699If 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 3700real-time clock option at compile time (and assume its availability
3201runtime if successful). Otherwise no use of the real-time clock option will 3701at runtime if successful). Otherwise no use of the real-time clock
3202be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3702option will be attempted. This effectively replaces C<gettimeofday>
3203(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3703by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3204note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3704correctness. See the note about libraries in the description of
3705C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3706C<EV_USE_CLOCK_SYSCALL>.
3707
3708=item EV_USE_CLOCK_SYSCALL
3709
3710If defined to be C<1>, libev will try to use a direct syscall instead
3711of calling the system-provided C<clock_gettime> function. This option
3712exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3713unconditionally pulls in C<libpthread>, slowing down single-threaded
3714programs needlessly. Using a direct syscall is slightly slower (in
3715theory), because no optimised vdso implementation can be used, but avoids
3716the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3717higher, as it simplifies linking (no need for C<-lrt>).
3205 3718
3206=item EV_USE_NANOSLEEP 3719=item EV_USE_NANOSLEEP
3207 3720
3208If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3721If 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 ()>. 3722and will use it for delays. Otherwise it will use C<select ()>.
3225 3738
3226=item EV_SELECT_USE_FD_SET 3739=item EV_SELECT_USE_FD_SET
3227 3740
3228If defined to C<1>, then the select backend will use the system C<fd_set> 3741If 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 3742structure. 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 3743C<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 3744on exotic systems. This usually limits the range of file descriptors to
3232low limit such as 1024 or might have other limitations (winsocket only 3745some low limit such as 1024 or might have other limitations (winsocket
3233allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3746only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
3234influence the size of the C<fd_set> used. 3747configures the maximum size of the C<fd_set>.
3235 3748
3236=item EV_SELECT_IS_WINSOCKET 3749=item EV_SELECT_IS_WINSOCKET
3237 3750
3238When defined to C<1>, the select backend will assume that 3751When defined to C<1>, the select backend will assume that
3239select/socket/connect etc. don't understand file descriptors but 3752select/socket/connect etc. don't understand file descriptors but
3241be used is the winsock select). This means that it will call 3754be 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, 3755C<_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 3756it is assumed that all these functions actually work on fds, even
3244on win32. Should not be defined on non-win32 platforms. 3757on win32. Should not be defined on non-win32 platforms.
3245 3758
3246=item EV_FD_TO_WIN32_HANDLE 3759=item EV_FD_TO_WIN32_HANDLE(fd)
3247 3760
3248If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3761If 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 3762file descriptors to socket handles. When not defining this symbol (the
3250default), then libev will call C<_get_osfhandle>, which is usually 3763default), then libev will call C<_get_osfhandle>, which is usually
3251correct. In some cases, programs use their own file descriptor management, 3764correct. In some cases, programs use their own file descriptor management,
3252in which case they can provide this function to map fds to socket handles. 3765in which case they can provide this function to map fds to socket handles.
3766
3767=item EV_WIN32_HANDLE_TO_FD(handle)
3768
3769If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3770using the standard C<_open_osfhandle> function. For programs implementing
3771their own fd to handle mapping, overwriting this function makes it easier
3772to do so. This can be done by defining this macro to an appropriate value.
3773
3774=item EV_WIN32_CLOSE_FD(fd)
3775
3776If programs implement their own fd to handle mapping on win32, then this
3777macro can be used to override the C<close> function, useful to unregister
3778file descriptors again. Note that the replacement function has to close
3779the underlying OS handle.
3253 3780
3254=item EV_USE_POLL 3781=item EV_USE_POLL
3255 3782
3256If defined to be C<1>, libev will compile in support for the C<poll>(2) 3783If 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 3784backend. Otherwise it will be enabled on non-win32 platforms. It
3304as well as for signal and thread safety in C<ev_async> watchers. 3831as well as for signal and thread safety in C<ev_async> watchers.
3305 3832
3306In the absence of this define, libev will use C<sig_atomic_t volatile> 3833In 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. 3834(from F<signal.h>), which is usually good enough on most platforms.
3308 3835
3309=item EV_H 3836=item EV_H (h)
3310 3837
3311The name of the F<ev.h> header file used to include it. The default if 3838The 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 3839undefined 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. 3840used to virtually rename the F<ev.h> header file in case of conflicts.
3314 3841
3315=item EV_CONFIG_H 3842=item EV_CONFIG_H (h)
3316 3843
3317If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3844If 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 3845F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3319C<EV_H>, above. 3846C<EV_H>, above.
3320 3847
3321=item EV_EVENT_H 3848=item EV_EVENT_H (h)
3322 3849
3323Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3850Similarly 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">. 3851of how the F<event.h> header can be found, the default is C<"event.h">.
3325 3852
3326=item EV_PROTOTYPES 3853=item EV_PROTOTYPES (h)
3327 3854
3328If defined to be C<0>, then F<ev.h> will not define any function 3855If 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 3856prototypes, but still define all the structs and other symbols. This is
3330occasionally useful if you want to provide your own wrapper functions 3857occasionally useful if you want to provide your own wrapper functions
3331around libev functions. 3858around libev functions.
3353fine. 3880fine.
3354 3881
3355If your embedding application does not need any priorities, defining these 3882If your embedding application does not need any priorities, defining these
3356both to C<0> will save some memory and CPU. 3883both to C<0> will save some memory and CPU.
3357 3884
3358=item EV_PERIODIC_ENABLE 3885=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3886EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3887EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3359 3888
3360If undefined or defined to be C<1>, then periodic timers are supported. If 3889If 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 3890the respective watcher type is supported. If defined to be C<0>, then it
3362code. 3891is not. Disabling watcher types mainly saves codesize.
3363 3892
3364=item EV_IDLE_ENABLE 3893=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 3894
3393If you need to shave off some kilobytes of code at the expense of some 3895If 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 3896speed (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 3897certain subsets of functionality. The default is to enable all features
3396much smaller 2-heap for timer management over the default 4-heap. 3898that can be enabled on the platform.
3899
3900A typical way to use this symbol is to define it to C<0> (or to a bitset
3901with some broad features you want) and then selectively re-enable
3902additional parts you want, for example if you want everything minimal,
3903but multiple event loop support, async and child watchers and the poll
3904backend, use this:
3905
3906 #define EV_FEATURES 0
3907 #define EV_MULTIPLICITY 1
3908 #define EV_USE_POLL 1
3909 #define EV_CHILD_ENABLE 1
3910 #define EV_ASYNC_ENABLE 1
3911
3912The actual value is a bitset, it can be a combination of the following
3913values:
3914
3915=over 4
3916
3917=item C<1> - faster/larger code
3918
3919Use larger code to speed up some operations.
3920
3921Currently this is used to override some inlining decisions (enlarging the roughly
392230% code size on amd64.
3923
3924When optimising for size, use of compiler flags such as C<-Os> with
3925gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3926assertions.
3927
3928=item C<2> - faster/larger data structures
3929
3930Replaces the small 2-heap for timer management by a faster 4-heap, larger
3931hash table sizes and so on. This will usually further increase codesize
3932and can additionally have an effect on the size of data structures at
3933runtime.
3934
3935=item C<4> - full API configuration
3936
3937This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3938enables multiplicity (C<EV_MULTIPLICITY>=1).
3939
3940=item C<8> - full API
3941
3942This enables a lot of the "lesser used" API functions. See C<ev.h> for
3943details on which parts of the API are still available without this
3944feature, and do not complain if this subset changes over time.
3945
3946=item C<16> - enable all optional watcher types
3947
3948Enables all optional watcher types. If you want to selectively enable
3949only some watcher types other than I/O and timers (e.g. prepare,
3950embed, async, child...) you can enable them manually by defining
3951C<EV_watchertype_ENABLE> to C<1> instead.
3952
3953=item C<32> - enable all backends
3954
3955This enables all backends - without this feature, you need to enable at
3956least one backend manually (C<EV_USE_SELECT> is a good choice).
3957
3958=item C<64> - enable OS-specific "helper" APIs
3959
3960Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3961default.
3962
3963=back
3964
3965Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3966reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3967code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3968watchers, timers and monotonic clock support.
3969
3970With an intelligent-enough linker (gcc+binutils are intelligent enough
3971when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3972your program might be left out as well - a binary starting a timer and an
3973I/O watcher then might come out at only 5Kb.
3974
3975=item EV_AVOID_STDIO
3976
3977If this is set to C<1> at compiletime, then libev will avoid using stdio
3978functions (printf, scanf, perror etc.). This will increase the codesize
3979somewhat, but if your program doesn't otherwise depend on stdio and your
3980libc allows it, this avoids linking in the stdio library which is quite
3981big.
3982
3983Note that error messages might become less precise when this option is
3984enabled.
3985
3986=item EV_NSIG
3987
3988The highest supported signal number, +1 (or, the number of
3989signals): Normally, libev tries to deduce the maximum number of signals
3990automatically, but sometimes this fails, in which case it can be
3991specified. Also, using a lower number than detected (C<32> should be
3992good for about any system in existance) can save some memory, as libev
3993statically allocates some 12-24 bytes per signal number.
3397 3994
3398=item EV_PID_HASHSIZE 3995=item EV_PID_HASHSIZE
3399 3996
3400C<ev_child> watchers use a small hash table to distribute workload by 3997C<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 3998pid. 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 3999usually more than enough. If you need to manage thousands of children you
3403increase this value (I<must> be a power of two). 4000might want to increase this value (I<must> be a power of two).
3404 4001
3405=item EV_INOTIFY_HASHSIZE 4002=item EV_INOTIFY_HASHSIZE
3406 4003
3407C<ev_stat> watchers use a small hash table to distribute workload by 4004C<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>), 4005inotify 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> 4006disabled), 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 4007C<ev_stat> watchers you might want to increase this value (I<must> be a
3411two). 4008power of two).
3412 4009
3413=item EV_USE_4HEAP 4010=item EV_USE_4HEAP
3414 4011
3415Heaps are not very cache-efficient. To improve the cache-efficiency of the 4012Heaps 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 4013timer 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 4014to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3418faster performance with many (thousands) of watchers. 4015faster performance with many (thousands) of watchers.
3419 4016
3420The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4017The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3421(disabled). 4018will be C<0>.
3422 4019
3423=item EV_HEAP_CACHE_AT 4020=item EV_HEAP_CACHE_AT
3424 4021
3425Heaps are not very cache-efficient. To improve the cache-efficiency of the 4022Heaps are not very cache-efficient. To improve the cache-efficiency of the
3426timer and periodics heaps, libev can cache the timestamp (I<at>) within 4023timer 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>), 4024the 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, 4025which 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 4026but avoids random read accesses on heap changes. This improves performance
3430noticeably with many (hundreds) of watchers. 4027noticeably with many (hundreds) of watchers.
3431 4028
3432The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4029The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3433(disabled). 4030will be C<0>.
3434 4031
3435=item EV_VERIFY 4032=item EV_VERIFY
3436 4033
3437Controls how much internal verification (see C<ev_loop_verify ()>) will 4034Controls how much internal verification (see C<ev_loop_verify ()>) will
3438be done: If set to C<0>, no internal verification code will be compiled 4035be done: If set to C<0>, no internal verification code will be compiled
3440called. If set to C<2>, then the internal verification code will be 4037called. 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 4038called 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 4039verification code will be called very frequently, which will slow down
3443libev considerably. 4040libev considerably.
3444 4041
3445The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4042The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3446C<0>. 4043will be C<0>.
3447 4044
3448=item EV_COMMON 4045=item EV_COMMON
3449 4046
3450By default, all watchers have a C<void *data> member. By redefining 4047By 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 4048this macro to a something else you can include more and other types of
3509file. 4106file.
3510 4107
3511The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4108The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3512that everybody includes and which overrides some configure choices: 4109that everybody includes and which overrides some configure choices:
3513 4110
3514 #define EV_MINIMAL 1 4111 #define EV_FEATURES 8
3515 #define EV_USE_POLL 0 4112 #define EV_USE_SELECT 1
3516 #define EV_MULTIPLICITY 0
3517 #define EV_PERIODIC_ENABLE 0 4113 #define EV_PREPARE_ENABLE 1
4114 #define EV_IDLE_ENABLE 1
3518 #define EV_STAT_ENABLE 0 4115 #define EV_SIGNAL_ENABLE 1
3519 #define EV_FORK_ENABLE 0 4116 #define EV_CHILD_ENABLE 1
4117 #define EV_USE_STDEXCEPT 0
3520 #define EV_CONFIG_H <config.h> 4118 #define EV_CONFIG_H <config.h>
3521 #define EV_MINPRI 0
3522 #define EV_MAXPRI 0
3523 4119
3524 #include "ev++.h" 4120 #include "ev++.h"
3525 4121
3526And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4122And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3527 4123
3587default loop and triggering an C<ev_async> watcher from the default loop 4183default loop and triggering an C<ev_async> watcher from the default loop
3588watcher callback into the event loop interested in the signal. 4184watcher callback into the event loop interested in the signal.
3589 4185
3590=back 4186=back
3591 4187
4188=head4 THREAD LOCKING EXAMPLE
4189
4190Here is a fictitious example of how to run an event loop in a different
4191thread than where callbacks are being invoked and watchers are
4192created/added/removed.
4193
4194For a real-world example, see the C<EV::Loop::Async> perl module,
4195which uses exactly this technique (which is suited for many high-level
4196languages).
4197
4198The example uses a pthread mutex to protect the loop data, a condition
4199variable to wait for callback invocations, an async watcher to notify the
4200event loop thread and an unspecified mechanism to wake up the main thread.
4201
4202First, you need to associate some data with the event loop:
4203
4204 typedef struct {
4205 mutex_t lock; /* global loop lock */
4206 ev_async async_w;
4207 thread_t tid;
4208 cond_t invoke_cv;
4209 } userdata;
4210
4211 void prepare_loop (EV_P)
4212 {
4213 // for simplicity, we use a static userdata struct.
4214 static userdata u;
4215
4216 ev_async_init (&u->async_w, async_cb);
4217 ev_async_start (EV_A_ &u->async_w);
4218
4219 pthread_mutex_init (&u->lock, 0);
4220 pthread_cond_init (&u->invoke_cv, 0);
4221
4222 // now associate this with the loop
4223 ev_set_userdata (EV_A_ u);
4224 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4225 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4226
4227 // then create the thread running ev_loop
4228 pthread_create (&u->tid, 0, l_run, EV_A);
4229 }
4230
4231The callback for the C<ev_async> watcher does nothing: the watcher is used
4232solely to wake up the event loop so it takes notice of any new watchers
4233that might have been added:
4234
4235 static void
4236 async_cb (EV_P_ ev_async *w, int revents)
4237 {
4238 // just used for the side effects
4239 }
4240
4241The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4242protecting the loop data, respectively.
4243
4244 static void
4245 l_release (EV_P)
4246 {
4247 userdata *u = ev_userdata (EV_A);
4248 pthread_mutex_unlock (&u->lock);
4249 }
4250
4251 static void
4252 l_acquire (EV_P)
4253 {
4254 userdata *u = ev_userdata (EV_A);
4255 pthread_mutex_lock (&u->lock);
4256 }
4257
4258The event loop thread first acquires the mutex, and then jumps straight
4259into C<ev_loop>:
4260
4261 void *
4262 l_run (void *thr_arg)
4263 {
4264 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4265
4266 l_acquire (EV_A);
4267 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4268 ev_loop (EV_A_ 0);
4269 l_release (EV_A);
4270
4271 return 0;
4272 }
4273
4274Instead of invoking all pending watchers, the C<l_invoke> callback will
4275signal the main thread via some unspecified mechanism (signals? pipe
4276writes? C<Async::Interrupt>?) and then waits until all pending watchers
4277have been called (in a while loop because a) spurious wakeups are possible
4278and b) skipping inter-thread-communication when there are no pending
4279watchers is very beneficial):
4280
4281 static void
4282 l_invoke (EV_P)
4283 {
4284 userdata *u = ev_userdata (EV_A);
4285
4286 while (ev_pending_count (EV_A))
4287 {
4288 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4289 pthread_cond_wait (&u->invoke_cv, &u->lock);
4290 }
4291 }
4292
4293Now, whenever the main thread gets told to invoke pending watchers, it
4294will grab the lock, call C<ev_invoke_pending> and then signal the loop
4295thread to continue:
4296
4297 static void
4298 real_invoke_pending (EV_P)
4299 {
4300 userdata *u = ev_userdata (EV_A);
4301
4302 pthread_mutex_lock (&u->lock);
4303 ev_invoke_pending (EV_A);
4304 pthread_cond_signal (&u->invoke_cv);
4305 pthread_mutex_unlock (&u->lock);
4306 }
4307
4308Whenever you want to start/stop a watcher or do other modifications to an
4309event loop, you will now have to lock:
4310
4311 ev_timer timeout_watcher;
4312 userdata *u = ev_userdata (EV_A);
4313
4314 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4315
4316 pthread_mutex_lock (&u->lock);
4317 ev_timer_start (EV_A_ &timeout_watcher);
4318 ev_async_send (EV_A_ &u->async_w);
4319 pthread_mutex_unlock (&u->lock);
4320
4321Note that sending the C<ev_async> watcher is required because otherwise
4322an event loop currently blocking in the kernel will have no knowledge
4323about the newly added timer. By waking up the loop it will pick up any new
4324watchers in the next event loop iteration.
4325
3592=head3 COROUTINES 4326=head3 COROUTINES
3593 4327
3594Libev is very accommodating to coroutines ("cooperative threads"): 4328Libev is very accommodating to coroutines ("cooperative threads"):
3595libev fully supports nesting calls to its functions from different 4329libev fully supports nesting calls to its functions from different
3596coroutines (e.g. you can call C<ev_loop> on the same loop from two 4330coroutines (e.g. you can call C<ev_loop> on the same loop from two
3597different coroutines, and switch freely between both coroutines running the 4331different coroutines, and switch freely between both coroutines running
3598loop, as long as you don't confuse yourself). The only exception is that 4332the loop, as long as you don't confuse yourself). The only exception is
3599you must not do this from C<ev_periodic> reschedule callbacks. 4333that you must not do this from C<ev_periodic> reschedule callbacks.
3600 4334
3601Care has been taken to ensure that libev does not keep local state inside 4335Care 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 4336C<ev_loop>, and other calls do not usually allow for coroutine switches as
3603they do not call any callbacks. 4337they do not call any callbacks.
3604 4338
3681way (note also that glib is the slowest event library known to man). 4415way (note also that glib is the slowest event library known to man).
3682 4416
3683There is no supported compilation method available on windows except 4417There is no supported compilation method available on windows except
3684embedding it into other applications. 4418embedding it into other applications.
3685 4419
4420Sensible signal handling is officially unsupported by Microsoft - libev
4421tries its best, but under most conditions, signals will simply not work.
4422
3686Not a libev limitation but worth mentioning: windows apparently doesn't 4423Not a libev limitation but worth mentioning: windows apparently doesn't
3687accept large writes: instead of resulting in a partial write, windows will 4424accept large writes: instead of resulting in a partial write, windows will
3688either accept everything or return C<ENOBUFS> if the buffer is too large, 4425either 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 4426so make sure you only write small amounts into your sockets (less than a
3690megabyte seems safe, but this apparently depends on the amount of memory 4427megabyte seems safe, but this apparently depends on the amount of memory
3694the abysmal performance of winsockets, using a large number of sockets 4431the abysmal performance of winsockets, using a large number of sockets
3695is not recommended (and not reasonable). If your program needs to use 4432is 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 4433more than a hundred or so sockets, then likely it needs to use a totally
3697different implementation for windows, as libev offers the POSIX readiness 4434different implementation for windows, as libev offers the POSIX readiness
3698notification model, which cannot be implemented efficiently on windows 4435notification model, which cannot be implemented efficiently on windows
3699(Microsoft monopoly games). 4436(due to Microsoft monopoly games).
3700 4437
3701A typical way to use libev under windows is to embed it (see the embedding 4438A 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 4439section for details) and use the following F<evwrap.h> header file instead
3703of F<ev.h>: 4440of F<ev.h>:
3704 4441
3740 4477
3741Early versions of winsocket's select only supported waiting for a maximum 4478Early versions of winsocket's select only supported waiting for a maximum
3742of C<64> handles (probably owning to the fact that all windows kernels 4479of 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 4480can 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 4481recommends spawning a chain of threads and wait for 63 handles and the
3745previous thread in each. Great). 4482previous thread in each. Sounds great!).
3746 4483
3747Newer versions support more handles, but you need to define C<FD_SETSIZE> 4484Newer 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 4485to 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 4486call (which might be in libev or elsewhere, for example, perl and many
3750select emulation on windows). 4487other interpreters do their own select emulation on windows).
3751 4488
3752Another limit is the number of file descriptors in the Microsoft runtime 4489Another 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 4490libraries, 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 4491fetish or something like this inside Microsoft). You can increase this
3755C<_setmaxstdio>, which can increase this limit to C<2048> (another 4492by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3756arbitrary limit), but is broken in many versions of the Microsoft runtime 4493(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 4494runtime 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 4495(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 4496you need to wrap all I/O functions and provide your own fd management, but
3762calling select (O(n²)) will likely make this unworkable. 4497the cost of calling select (O(n²)) will likely make this unworkable.
3763 4498
3764=back 4499=back
3765 4500
3766=head2 PORTABILITY REQUIREMENTS 4501=head2 PORTABILITY REQUIREMENTS
3767 4502
3810=item C<double> must hold a time value in seconds with enough accuracy 4545=item C<double> must hold a time value in seconds with enough accuracy
3811 4546
3812The type C<double> is used to represent timestamps. It is required to 4547The 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 4548have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3814enough for at least into the year 4000. This requirement is fulfilled by 4549enough for at least into the year 4000. This requirement is fulfilled by
3815implementations implementing IEEE 754 (basically all existing ones). 4550implementations implementing IEEE 754, which is basically all existing
4551ones. With IEEE 754 doubles, you get microsecond accuracy until at least
45522200.
3816 4553
3817=back 4554=back
3818 4555
3819If you know of other additional requirements drop me a note. 4556If you know of other additional requirements drop me a note.
3820 4557
3888involves iterating over all running async watchers or all signal numbers. 4625involves iterating over all running async watchers or all signal numbers.
3889 4626
3890=back 4627=back
3891 4628
3892 4629
4630=head1 PORTING FROM LIBEV 3.X TO 4.X
4631
4632The major version 4 introduced some minor incompatible changes to the API.
4633
4634At the moment, the C<ev.h> header file tries to implement superficial
4635compatibility, so most programs should still compile. Those might be
4636removed in later versions of libev, so better update early than late.
4637
4638=over 4
4639
4640=item C<ev_loop_count> renamed to C<ev_iteration>
4641
4642=item C<ev_loop_depth> renamed to C<ev_depth>
4643
4644=item C<ev_loop_verify> renamed to C<ev_verify>
4645
4646Most functions working on C<struct ev_loop> objects don't have an
4647C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
4648still called C<ev_loop_fork> because it would otherwise clash with the
4649C<ev_fork> typedef.
4650
4651=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
4652
4653This is a simple rename - all other watcher types use their name
4654as revents flag, and now C<ev_timer> does, too.
4655
4656Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4657and continue to be present for the forseeable future, so this is mostly a
4658documentation change.
4659
4660=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4661
4662The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4663mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4664and work, but the library code will of course be larger.
4665
4666=back
4667
4668
4669=head1 GLOSSARY
4670
4671=over 4
4672
4673=item active
4674
4675A watcher is active as long as it has been started (has been attached to
4676an event loop) but not yet stopped (disassociated from the event loop).
4677
4678=item application
4679
4680In this document, an application is whatever is using libev.
4681
4682=item callback
4683
4684The address of a function that is called when some event has been
4685detected. Callbacks are being passed the event loop, the watcher that
4686received the event, and the actual event bitset.
4687
4688=item callback invocation
4689
4690The act of calling the callback associated with a watcher.
4691
4692=item event
4693
4694A change of state of some external event, such as data now being available
4695for reading on a file descriptor, time having passed or simply not having
4696any other events happening anymore.
4697
4698In libev, events are represented as single bits (such as C<EV_READ> or
4699C<EV_TIMER>).
4700
4701=item event library
4702
4703A software package implementing an event model and loop.
4704
4705=item event loop
4706
4707An entity that handles and processes external events and converts them
4708into callback invocations.
4709
4710=item event model
4711
4712The model used to describe how an event loop handles and processes
4713watchers and events.
4714
4715=item pending
4716
4717A watcher is pending as soon as the corresponding event has been detected,
4718and stops being pending as soon as the watcher will be invoked or its
4719pending status is explicitly cleared by the application.
4720
4721A watcher can be pending, but not active. Stopping a watcher also clears
4722its pending status.
4723
4724=item real time
4725
4726The physical time that is observed. It is apparently strictly monotonic :)
4727
4728=item wall-clock time
4729
4730The time and date as shown on clocks. Unlike real time, it can actually
4731be wrong and jump forwards and backwards, e.g. when the you adjust your
4732clock.
4733
4734=item watcher
4735
4736A data structure that describes interest in certain events. Watchers need
4737to be started (attached to an event loop) before they can receive events.
4738
4739=item watcher invocation
4740
4741The act of calling the callback associated with a watcher.
4742
4743=back
4744
3893=head1 AUTHOR 4745=head1 AUTHOR
3894 4746
3895Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 4747Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3896 4748

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines