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

Comparing libev/ev.pod (file contents):
Revision 1.203 by root, Sun Oct 26 00:52:51 2008 UTC vs.
Revision 1.249 by root, Wed Jul 8 04:29:31 2009 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
108name C<loop> (which is always of type C<ev_loop *>) will not have 122name C<loop> (which is always of type C<ev_loop *>) will not have
109this argument. 123this argument.
110 124
111=head2 TIME REPRESENTATION 125=head2 TIME REPRESENTATION
112 126
113Libev represents time as a single floating point number, representing the 127Libev represents time as a single floating point number, representing
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 128the (fractional) number of seconds since the (POSIX) epoch (somewhere
115the beginning of 1970, details are complicated, don't ask). This type is 129near 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 130type 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 131aliases 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 132on 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 133component C<stamp> might indicate, it is also used for time differences
120throughout libev. 134throughout libev.
121 135
122=head1 ERROR HANDLING 136=head1 ERROR HANDLING
123 137
298If you don't know what event loop to use, use the one returned from this 312If you don't know what event loop to use, use the one returned from this
299function. 313function.
300 314
301Note that this function is I<not> thread-safe, so if you want to use it 315Note that this function is I<not> thread-safe, so if you want to use it
302from multiple threads, you have to lock (note also that this is unlikely, 316from multiple threads, you have to lock (note also that this is unlikely,
303as loops cannot bes hared easily between threads anyway). 317as loops cannot be shared easily between threads anyway).
304 318
305The default loop is the only loop that can handle C<ev_signal> and 319The default loop is the only loop that can handle C<ev_signal> and
306C<ev_child> watchers, and to do this, it always registers a handler 320C<ev_child> watchers, and to do this, it always registers a handler
307for C<SIGCHLD>. If this is a problem for your application you can either 321for C<SIGCHLD>. If this is a problem for your application you can either
308create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 322create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
384=item C<EVBACKEND_EPOLL> (value 4, Linux) 398=item C<EVBACKEND_EPOLL> (value 4, Linux)
385 399
386For few fds, this backend is a bit little slower than poll and select, 400For few fds, this backend is a bit little slower than poll and select,
387but it scales phenomenally better. While poll and select usually scale 401but 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), 402like O(total_fds) where n is the total number of fds (or the highest fd),
389epoll scales either O(1) or O(active_fds). The epoll design has a number 403epoll scales either O(1) or O(active_fds).
390of shortcomings, such as silently dropping events in some hard-to-detect 404
391cases and requiring a system call per fd change, no fork support and bad 405The epoll mechanism deserves honorable mention as the most misdesigned
392support for dup. 406of the more advanced event mechanisms: mere annoyances include silently
407dropping file descriptors, requiring a system call per change per file
408descriptor (and unnecessary guessing of parameters), problems with dup and
409so on. The biggest issue is fork races, however - if a program forks then
410I<both> parent and child process have to recreate the epoll set, which can
411take considerable time (one syscall per file descriptor) and is of course
412hard to detect.
413
414Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
415of course I<doesn't>, and epoll just loves to report events for totally
416I<different> file descriptors (even already closed ones, so one cannot
417even remove them from the set) than registered in the set (especially
418on SMP systems). Libev tries to counter these spurious notifications by
419employing an additional generation counter and comparing that against the
420events to filter out spurious ones, recreating the set when required.
393 421
394While stopping, setting and starting an I/O watcher in the same iteration 422While stopping, setting and starting an I/O watcher in the same iteration
395will result in some caching, there is still a system call per such incident 423will result in some caching, there is still a system call per such
396(because the fd could point to a different file description now), so its 424incident (because the same I<file descriptor> could point to a different
397best to avoid that. Also, C<dup ()>'ed file descriptors might not work 425I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
398very well if you register events for both fds. 426file descriptors might not work very well if you register events for both
399 427file descriptors.
400Please note that epoll sometimes generates spurious notifications, so you
401need to use non-blocking I/O or other means to avoid blocking when no data
402(or space) is available.
403 428
404Best performance from this backend is achieved by not unregistering all 429Best performance from this backend is achieved by not unregistering all
405watchers for a file descriptor until it has been closed, if possible, 430watchers for a file descriptor until it has been closed, if possible,
406i.e. keep at least one watcher active per fd at all times. Stopping and 431i.e. keep at least one watcher active per fd at all times. Stopping and
407starting a watcher (without re-setting it) also usually doesn't cause 432starting a watcher (without re-setting it) also usually doesn't cause
408extra overhead. 433extra overhead. A fork can both result in spurious notifications as well
434as in libev having to destroy and recreate the epoll object, which can
435take considerable time and thus should be avoided.
436
437All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
438faster than epoll for maybe up to a hundred file descriptors, depending on
439the usage. So sad.
409 440
410While nominally embeddable in other event loops, this feature is broken in 441While nominally embeddable in other event loops, this feature is broken in
411all kernel versions tested so far. 442all kernel versions tested so far.
412 443
413This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 444This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
414C<EVBACKEND_POLL>. 445C<EVBACKEND_POLL>.
415 446
416=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 447=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
417 448
418Kqueue deserves special mention, as at the time of this writing, it was 449Kqueue deserves special mention, as at the time of this writing, it
419broken on all BSDs except NetBSD (usually it doesn't work reliably with 450was broken on all BSDs except NetBSD (usually it doesn't work reliably
420anything but sockets and pipes, except on Darwin, where of course it's 451with anything but sockets and pipes, except on Darwin, where of course
421completely useless). For this reason it's not being "auto-detected" unless 452it's completely useless). Unlike epoll, however, whose brokenness
422you explicitly specify it in the flags (i.e. using C<EVBACKEND_KQUEUE>) or 453is by design, these kqueue bugs can (and eventually will) be fixed
423libev was compiled on a known-to-be-good (-enough) system like NetBSD. 454without API changes to existing programs. For this reason it's not being
455"auto-detected" unless you explicitly specify it in the flags (i.e. using
456C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
457system like NetBSD.
424 458
425You still can embed kqueue into a normal poll or select backend and use it 459You still can embed kqueue into a normal poll or select backend and use it
426only for sockets (after having made sure that sockets work with kqueue on 460only for sockets (after having made sure that sockets work with kqueue on
427the target platform). See C<ev_embed> watchers for more info. 461the target platform). See C<ev_embed> watchers for more info.
428 462
429It scales in the same way as the epoll backend, but the interface to the 463It scales in the same way as the epoll backend, but the interface to the
430kernel is more efficient (which says nothing about its actual speed, of 464kernel is more efficient (which says nothing about its actual speed, of
431course). While stopping, setting and starting an I/O watcher does never 465course). While stopping, setting and starting an I/O watcher does never
432cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 466cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
433two event changes per incident. Support for C<fork ()> is very bad and it 467two event changes per incident. Support for C<fork ()> is very bad (but
434drops fds silently in similarly hard-to-detect cases. 468sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
469cases
435 470
436This backend usually performs well under most conditions. 471This backend usually performs well under most conditions.
437 472
438While nominally embeddable in other event loops, this doesn't work 473While nominally embeddable in other event loops, this doesn't work
439everywhere, so you might need to test for this. And since it is broken 474everywhere, so you might need to test for this. And since it is broken
440almost everywhere, you should only use it when you have a lot of sockets 475almost everywhere, you should only use it when you have a lot of sockets
441(for which it usually works), by embedding it into another event loop 476(for which it usually works), by embedding it into another event loop
442(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it, 477(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
443using it only for sockets. 478also broken on OS X)) and, did I mention it, using it only for sockets.
444 479
445This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 480This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
446C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with 481C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
447C<NOTE_EOF>. 482C<NOTE_EOF>.
448 483
468might perform better. 503might perform better.
469 504
470On the positive side, with the exception of the spurious readiness 505On the positive side, with the exception of the spurious readiness
471notifications, this backend actually performed fully to specification 506notifications, this backend actually performed fully to specification
472in all tests and is fully embeddable, which is a rare feat among the 507in all tests and is fully embeddable, which is a rare feat among the
473OS-specific backends. 508OS-specific backends (I vastly prefer correctness over speed hacks).
474 509
475This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 510This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
476C<EVBACKEND_POLL>. 511C<EVBACKEND_POLL>.
477 512
478=item C<EVBACKEND_ALL> 513=item C<EVBACKEND_ALL>
586 621
587This value can sometimes be useful as a generation counter of sorts (it 622This value can sometimes be useful as a generation counter of sorts (it
588"ticks" the number of loop iterations), as it roughly corresponds with 623"ticks" the number of loop iterations), as it roughly corresponds with
589C<ev_prepare> and C<ev_check> calls. 624C<ev_prepare> and C<ev_check> calls.
590 625
626=item unsigned int ev_loop_depth (loop)
627
628Returns the number of times C<ev_loop> was entered minus the number of
629times C<ev_loop> was exited, in other words, the recursion depth.
630
631Outside C<ev_loop>, this number is zero. In a callback, this number is
632C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
633in which case it is higher.
634
635Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
636etc.), doesn't count as exit.
637
591=item unsigned int ev_backend (loop) 638=item unsigned int ev_backend (loop)
592 639
593Returns one of the C<EVBACKEND_*> flags indicating the event backend in 640Returns one of the C<EVBACKEND_*> flags indicating the event backend in
594use. 641use.
595 642
609 656
610This function is rarely useful, but when some event callback runs for a 657This function is rarely useful, but when some event callback runs for a
611very long time without entering the event loop, updating libev's idea of 658very long time without entering the event loop, updating libev's idea of
612the current time is a good idea. 659the current time is a good idea.
613 660
614See also "The special problem of time updates" in the C<ev_timer> section. 661See also L<The special problem of time updates> in the C<ev_timer> section.
662
663=item ev_suspend (loop)
664
665=item ev_resume (loop)
666
667These two functions suspend and resume a loop, for use when the loop is
668not used for a while and timeouts should not be processed.
669
670A typical use case would be an interactive program such as a game: When
671the user presses C<^Z> to suspend the game and resumes it an hour later it
672would be best to handle timeouts as if no time had actually passed while
673the program was suspended. This can be achieved by calling C<ev_suspend>
674in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
675C<ev_resume> directly afterwards to resume timer processing.
676
677Effectively, all C<ev_timer> watchers will be delayed by the time spend
678between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
679will be rescheduled (that is, they will lose any events that would have
680occured while suspended).
681
682After calling C<ev_suspend> you B<must not> call I<any> function on the
683given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
684without a previous call to C<ev_suspend>.
685
686Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
687event loop time (see C<ev_now_update>).
615 688
616=item ev_loop (loop, int flags) 689=item ev_loop (loop, int flags)
617 690
618Finally, this is it, the event handler. This function usually is called 691Finally, this is it, the event handler. This function usually is called
619after you initialised all your watchers and you want to start handling 692after you initialised all your watchers and you want to start handling
635the loop. 708the loop.
636 709
637A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 710A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
638necessary) and will handle those and any already outstanding ones. It 711necessary) and will handle those and any already outstanding ones. It
639will block your process until at least one new event arrives (which could 712will block your process until at least one new event arrives (which could
640be an event internal to libev itself, so there is no guarentee that a 713be an event internal to libev itself, so there is no guarantee that a
641user-registered callback will be called), and will return after one 714user-registered callback will be called), and will return after one
642iteration of the loop. 715iteration of the loop.
643 716
644This is useful if you are waiting for some external event in conjunction 717This is useful if you are waiting for some external event in conjunction
645with something not expressible using other libev watchers (i.e. "roll your 718with something not expressible using other libev watchers (i.e. "roll your
703 776
704If you have a watcher you never unregister that should not keep C<ev_loop> 777If you have a watcher you never unregister that should not keep C<ev_loop>
705from returning, call ev_unref() after starting, and ev_ref() before 778from returning, call ev_unref() after starting, and ev_ref() before
706stopping it. 779stopping it.
707 780
708As an example, libev itself uses this for its internal signal pipe: It is 781As an example, libev itself uses this for its internal signal pipe: It
709not visible to the libev user and should not keep C<ev_loop> from exiting 782is not visible to the libev user and should not keep C<ev_loop> from
710if no event watchers registered by it are active. It is also an excellent 783exiting if no event watchers registered by it are active. It is also an
711way to do this for generic recurring timers or from within third-party 784excellent way to do this for generic recurring timers or from within
712libraries. Just remember to I<unref after start> and I<ref before stop> 785third-party libraries. Just remember to I<unref after start> and I<ref
713(but only if the watcher wasn't active before, or was active before, 786before stop> (but only if the watcher wasn't active before, or was active
714respectively). 787before, respectively. Note also that libev might stop watchers itself
788(e.g. non-repeating timers) in which case you have to C<ev_ref>
789in the callback).
715 790
716Example: Create a signal watcher, but keep it from keeping C<ev_loop> 791Example: Create a signal watcher, but keep it from keeping C<ev_loop>
717running when nothing else is active. 792running when nothing else is active.
718 793
719 ev_signal exitsig; 794 ev_signal exitsig;
748 823
749By setting a higher I<io collect interval> you allow libev to spend more 824By setting a higher I<io collect interval> you allow libev to spend more
750time collecting I/O events, so you can handle more events per iteration, 825time collecting I/O events, so you can handle more events per iteration,
751at the cost of increasing latency. Timeouts (both C<ev_periodic> and 826at the cost of increasing latency. Timeouts (both C<ev_periodic> and
752C<ev_timer>) will be not affected. Setting this to a non-null value will 827C<ev_timer>) will be not affected. Setting this to a non-null value will
753introduce an additional C<ev_sleep ()> call into most loop iterations. 828introduce an additional C<ev_sleep ()> call into most loop iterations. The
829sleep time ensures that libev will not poll for I/O events more often then
830once per this interval, on average.
754 831
755Likewise, by setting a higher I<timeout collect interval> you allow libev 832Likewise, by setting a higher I<timeout collect interval> you allow libev
756to spend more time collecting timeouts, at the expense of increased 833to spend more time collecting timeouts, at the expense of increased
757latency/jitter/inexactness (the watcher callback will be called 834latency/jitter/inexactness (the watcher callback will be called
758later). C<ev_io> watchers will not be affected. Setting this to a non-null 835later). C<ev_io> watchers will not be affected. Setting this to a non-null
760 837
761Many (busy) programs can usually benefit by setting the I/O collect 838Many (busy) programs can usually benefit by setting the I/O collect
762interval to a value near C<0.1> or so, which is often enough for 839interval to a value near C<0.1> or so, which is often enough for
763interactive servers (of course not for games), likewise for timeouts. It 840interactive servers (of course not for games), likewise for timeouts. It
764usually doesn't make much sense to set it to a lower value than C<0.01>, 841usually doesn't make much sense to set it to a lower value than C<0.01>,
765as this approaches the timing granularity of most systems. 842as this approaches the timing granularity of most systems. Note that if
843you do transactions with the outside world and you can't increase the
844parallelity, then this setting will limit your transaction rate (if you
845need to poll once per transaction and the I/O collect interval is 0.01,
846then you can't do more than 100 transations per second).
766 847
767Setting the I<timeout collect interval> can improve the opportunity for 848Setting the I<timeout collect interval> can improve the opportunity for
768saving power, as the program will "bundle" timer callback invocations that 849saving power, as the program will "bundle" timer callback invocations that
769are "near" in time together, by delaying some, thus reducing the number of 850are "near" in time together, by delaying some, thus reducing the number of
770times the process sleeps and wakes up again. Another useful technique to 851times the process sleeps and wakes up again. Another useful technique to
771reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure 852reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
772they fire on, say, one-second boundaries only. 853they fire on, say, one-second boundaries only.
854
855Example: we only need 0.1s timeout granularity, and we wish not to poll
856more often than 100 times per second:
857
858 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
859 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
773 860
774=item ev_loop_verify (loop) 861=item ev_loop_verify (loop)
775 862
776This function only does something when C<EV_VERIFY> support has been 863This function only does something when C<EV_VERIFY> support has been
777compiled in, which is the default for non-minimal builds. It tries to go 864compiled in, which is the default for non-minimal builds. It tries to go
903 990
904=item C<EV_ASYNC> 991=item C<EV_ASYNC>
905 992
906The given async watcher has been asynchronously notified (see C<ev_async>). 993The given async watcher has been asynchronously notified (see C<ev_async>).
907 994
995=item C<EV_CUSTOM>
996
997Not ever sent (or otherwise used) by libev itself, but can be freely used
998by libev users to signal watchers (e.g. via C<ev_feed_event>).
999
908=item C<EV_ERROR> 1000=item C<EV_ERROR>
909 1001
910An unspecified error has occurred, the watcher has been stopped. This might 1002An unspecified error has occurred, the watcher has been stopped. This might
911happen because the watcher could not be properly started because libev 1003happen because the watcher could not be properly started because libev
912ran out of memory, a file descriptor was found to be closed or any other 1004ran out of memory, a file descriptor was found to be closed or any other
1027integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1119integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1028(default: C<-2>). Pending watchers with higher priority will be invoked 1120(default: C<-2>). Pending watchers with higher priority will be invoked
1029before watchers with lower priority, but priority will not keep watchers 1121before watchers with lower priority, but priority will not keep watchers
1030from being executed (except for C<ev_idle> watchers). 1122from being executed (except for C<ev_idle> watchers).
1031 1123
1032This means that priorities are I<only> used for ordering callback
1033invocation after new events have been received. This is useful, for
1034example, to reduce latency after idling, or more often, to bind two
1035watchers on the same event and make sure one is called first.
1036
1037If you need to suppress invocation when higher priority events are pending 1124If you need to suppress invocation when higher priority events are pending
1038you need to look at C<ev_idle> watchers, which provide this functionality. 1125you need to look at C<ev_idle> watchers, which provide this functionality.
1039 1126
1040You I<must not> change the priority of a watcher as long as it is active or 1127You I<must not> change the priority of a watcher as long as it is active or
1041pending. 1128pending.
1042
1043The default priority used by watchers when no priority has been set is
1044always C<0>, which is supposed to not be too high and not be too low :).
1045 1129
1046Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1130Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1047fine, as long as you do not mind that the priority value you query might 1131fine, as long as you do not mind that the priority value you query might
1048or might not have been clamped to the valid range. 1132or might not have been clamped to the valid range.
1133
1134The default priority used by watchers when no priority has been set is
1135always C<0>, which is supposed to not be too high and not be too low :).
1136
1137See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1138priorities.
1049 1139
1050=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1140=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1051 1141
1052Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1142Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1053C<loop> nor C<revents> need to be valid as long as the watcher callback 1143C<loop> nor C<revents> need to be valid as long as the watcher callback
1118 #include <stddef.h> 1208 #include <stddef.h>
1119 1209
1120 static void 1210 static void
1121 t1_cb (EV_P_ ev_timer *w, int revents) 1211 t1_cb (EV_P_ ev_timer *w, int revents)
1122 { 1212 {
1123 struct my_biggy big = (struct my_biggy * 1213 struct my_biggy big = (struct my_biggy *)
1124 (((char *)w) - offsetof (struct my_biggy, t1)); 1214 (((char *)w) - offsetof (struct my_biggy, t1));
1125 } 1215 }
1126 1216
1127 static void 1217 static void
1128 t2_cb (EV_P_ ev_timer *w, int revents) 1218 t2_cb (EV_P_ ev_timer *w, int revents)
1129 { 1219 {
1130 struct my_biggy big = (struct my_biggy * 1220 struct my_biggy big = (struct my_biggy *)
1131 (((char *)w) - offsetof (struct my_biggy, t2)); 1221 (((char *)w) - offsetof (struct my_biggy, t2));
1132 } 1222 }
1223
1224=head2 WATCHER PRIORITY MODELS
1225
1226Many event loops support I<watcher priorities>, which are usually small
1227integers that influence the ordering of event callback invocation
1228between watchers in some way, all else being equal.
1229
1230In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1231description for the more technical details such as the actual priority
1232range.
1233
1234There are two common ways how these these priorities are being interpreted
1235by event loops:
1236
1237In the more common lock-out model, higher priorities "lock out" invocation
1238of lower priority watchers, which means as long as higher priority
1239watchers receive events, lower priority watchers are not being invoked.
1240
1241The less common only-for-ordering model uses priorities solely to order
1242callback invocation within a single event loop iteration: Higher priority
1243watchers are invoked before lower priority ones, but they all get invoked
1244before polling for new events.
1245
1246Libev uses the second (only-for-ordering) model for all its watchers
1247except for idle watchers (which use the lock-out model).
1248
1249The rationale behind this is that implementing the lock-out model for
1250watchers is not well supported by most kernel interfaces, and most event
1251libraries will just poll for the same events again and again as long as
1252their callbacks have not been executed, which is very inefficient in the
1253common case of one high-priority watcher locking out a mass of lower
1254priority ones.
1255
1256Static (ordering) priorities are most useful when you have two or more
1257watchers handling the same resource: a typical usage example is having an
1258C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1259timeouts. Under load, data might be received while the program handles
1260other jobs, but since timers normally get invoked first, the timeout
1261handler will be executed before checking for data. In that case, giving
1262the timer a lower priority than the I/O watcher ensures that I/O will be
1263handled first even under adverse conditions (which is usually, but not
1264always, what you want).
1265
1266Since idle watchers use the "lock-out" model, meaning that idle watchers
1267will only be executed when no same or higher priority watchers have
1268received events, they can be used to implement the "lock-out" model when
1269required.
1270
1271For example, to emulate how many other event libraries handle priorities,
1272you can associate an C<ev_idle> watcher to each such watcher, and in
1273the normal watcher callback, you just start the idle watcher. The real
1274processing is done in the idle watcher callback. This causes libev to
1275continously poll and process kernel event data for the watcher, but when
1276the lock-out case is known to be rare (which in turn is rare :), this is
1277workable.
1278
1279Usually, however, the lock-out model implemented that way will perform
1280miserably under the type of load it was designed to handle. In that case,
1281it might be preferable to stop the real watcher before starting the
1282idle watcher, so the kernel will not have to process the event in case
1283the actual processing will be delayed for considerable time.
1284
1285Here is an example of an I/O watcher that should run at a strictly lower
1286priority than the default, and which should only process data when no
1287other events are pending:
1288
1289 ev_idle idle; // actual processing watcher
1290 ev_io io; // actual event watcher
1291
1292 static void
1293 io_cb (EV_P_ ev_io *w, int revents)
1294 {
1295 // stop the I/O watcher, we received the event, but
1296 // are not yet ready to handle it.
1297 ev_io_stop (EV_A_ w);
1298
1299 // start the idle watcher to ahndle the actual event.
1300 // it will not be executed as long as other watchers
1301 // with the default priority are receiving events.
1302 ev_idle_start (EV_A_ &idle);
1303 }
1304
1305 static void
1306 idle_cb (EV_P_ ev_idle *w, int revents)
1307 {
1308 // actual processing
1309 read (STDIN_FILENO, ...);
1310
1311 // have to start the I/O watcher again, as
1312 // we have handled the event
1313 ev_io_start (EV_P_ &io);
1314 }
1315
1316 // initialisation
1317 ev_idle_init (&idle, idle_cb);
1318 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1319 ev_io_start (EV_DEFAULT_ &io);
1320
1321In the "real" world, it might also be beneficial to start a timer, so that
1322low-priority connections can not be locked out forever under load. This
1323enables your program to keep a lower latency for important connections
1324during short periods of high load, while not completely locking out less
1325important ones.
1133 1326
1134 1327
1135=head1 WATCHER TYPES 1328=head1 WATCHER TYPES
1136 1329
1137This section describes each watcher in detail, but will not repeat 1330This section describes each watcher in detail, but will not repeat
1163descriptors to non-blocking mode is also usually a good idea (but not 1356descriptors to non-blocking mode is also usually a good idea (but not
1164required if you know what you are doing). 1357required if you know what you are doing).
1165 1358
1166If you cannot use non-blocking mode, then force the use of a 1359If you cannot use non-blocking mode, then force the use of a
1167known-to-be-good backend (at the time of this writing, this includes only 1360known-to-be-good backend (at the time of this writing, this includes only
1168C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). 1361C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1362descriptors for which non-blocking operation makes no sense (such as
1363files) - libev doesn't guarentee any specific behaviour in that case.
1169 1364
1170Another thing you have to watch out for is that it is quite easy to 1365Another thing you have to watch out for is that it is quite easy to
1171receive "spurious" readiness notifications, that is your callback might 1366receive "spurious" readiness notifications, that is your callback might
1172be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1367be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1173because there is no data. Not only are some backends known to create a 1368because there is no data. Not only are some backends known to create a
1294year, it will still time out after (roughly) one hour. "Roughly" because 1489year, it will still time out after (roughly) one hour. "Roughly" because
1295detecting time jumps is hard, and some inaccuracies are unavoidable (the 1490detecting time jumps is hard, and some inaccuracies are unavoidable (the
1296monotonic clock option helps a lot here). 1491monotonic clock option helps a lot here).
1297 1492
1298The callback is guaranteed to be invoked only I<after> its timeout has 1493The callback is guaranteed to be invoked only I<after> its timeout has
1299passed, but if multiple timers become ready during the same loop iteration 1494passed (not I<at>, so on systems with very low-resolution clocks this
1300then order of execution is undefined. 1495might introduce a small delay). If multiple timers become ready during the
1496same loop iteration then the ones with earlier time-out values are invoked
1497before ones of the same priority with later time-out values (but this is
1498no longer true when a callback calls C<ev_loop> recursively).
1301 1499
1302=head3 Be smart about timeouts 1500=head3 Be smart about timeouts
1303 1501
1304Many real-world problems involve some kind of timeout, usually for error 1502Many real-world problems involve some kind of timeout, usually for error
1305recovery. A typical example is an HTTP request - if the other side hangs, 1503recovery. A typical example is an HTTP request - if the other side hangs,
1349C<after> argument to C<ev_timer_set>, and only ever use the C<repeat> 1547C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1350member and C<ev_timer_again>. 1548member and C<ev_timer_again>.
1351 1549
1352At start: 1550At start:
1353 1551
1354 ev_timer_init (timer, callback); 1552 ev_init (timer, callback);
1355 timer->repeat = 60.; 1553 timer->repeat = 60.;
1356 ev_timer_again (loop, timer); 1554 ev_timer_again (loop, timer);
1357 1555
1358Each time there is some activity: 1556Each time there is some activity:
1359 1557
1398 else 1596 else
1399 { 1597 {
1400 // callback was invoked, but there was some activity, re-arm 1598 // callback was invoked, but there was some activity, re-arm
1401 // the watcher to fire in last_activity + 60, which is 1599 // the watcher to fire in last_activity + 60, which is
1402 // guaranteed to be in the future, so "again" is positive: 1600 // guaranteed to be in the future, so "again" is positive:
1403 w->again = timeout - now; 1601 w->repeat = timeout - now;
1404 ev_timer_again (EV_A_ w); 1602 ev_timer_again (EV_A_ w);
1405 } 1603 }
1406 } 1604 }
1407 1605
1408To summarise the callback: first calculate the real timeout (defined 1606To summarise the callback: first calculate the real timeout (defined
1421 1619
1422To start the timer, simply initialise the watcher and set C<last_activity> 1620To start the timer, simply initialise the watcher and set C<last_activity>
1423to the current time (meaning we just have some activity :), then call the 1621to the current time (meaning we just have some activity :), then call the
1424callback, which will "do the right thing" and start the timer: 1622callback, which will "do the right thing" and start the timer:
1425 1623
1426 ev_timer_init (timer, callback); 1624 ev_init (timer, callback);
1427 last_activity = ev_now (loop); 1625 last_activity = ev_now (loop);
1428 callback (loop, timer, EV_TIMEOUT); 1626 callback (loop, timer, EV_TIMEOUT);
1429 1627
1430And when there is some activity, simply store the current time in 1628And when there is some activity, simply store the current time in
1431C<last_activity>, no libev calls at all: 1629C<last_activity>, no libev calls at all:
1524If the timer is started but non-repeating, stop it (as if it timed out). 1722If the timer is started but non-repeating, stop it (as if it timed out).
1525 1723
1526If the timer is repeating, either start it if necessary (with the 1724If the timer is repeating, either start it if necessary (with the
1527C<repeat> value), or reset the running timer to the C<repeat> value. 1725C<repeat> value), or reset the running timer to the C<repeat> value.
1528 1726
1529This sounds a bit complicated, see "Be smart about timeouts", above, for a 1727This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1530usage example. 1728usage example.
1531 1729
1532=item ev_tstamp repeat [read-write] 1730=item ev_tstamp repeat [read-write]
1533 1731
1534The current C<repeat> value. Will be used each time the watcher times out 1732The current C<repeat> value. Will be used each time the watcher times out
1573=head2 C<ev_periodic> - to cron or not to cron? 1771=head2 C<ev_periodic> - to cron or not to cron?
1574 1772
1575Periodic watchers are also timers of a kind, but they are very versatile 1773Periodic watchers are also timers of a kind, but they are very versatile
1576(and unfortunately a bit complex). 1774(and unfortunately a bit complex).
1577 1775
1578Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1776Unlike C<ev_timer>, periodic watchers are not based on real time (or
1579but on wall clock time (absolute time). You can tell a periodic watcher 1777relative time, the physical time that passes) but on wall clock time
1580to trigger after some specific point in time. For example, if you tell a 1778(absolute time, the thing you can read on your calender or clock). The
1581periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 1779difference is that wall clock time can run faster or slower than real
1582+ 10.>, that is, an absolute time not a delay) and then reset your system 1780time, and time jumps are not uncommon (e.g. when you adjust your
1583clock to January of the previous year, then it will take more than year 1781wrist-watch).
1584to trigger the event (unlike an C<ev_timer>, which would still trigger
1585roughly 10 seconds later as it uses a relative timeout).
1586 1782
1783You can tell a periodic watcher to trigger after some specific point
1784in time: for example, if you tell a periodic watcher to trigger "in 10
1785seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1786not a delay) and then reset your system clock to January of the previous
1787year, then it will take a year or more to trigger the event (unlike an
1788C<ev_timer>, which would still trigger roughly 10 seconds after starting
1789it, as it uses a relative timeout).
1790
1587C<ev_periodic>s can also be used to implement vastly more complex timers, 1791C<ev_periodic> watchers can also be used to implement vastly more complex
1588such as triggering an event on each "midnight, local time", or other 1792timers, such as triggering an event on each "midnight, local time", or
1589complicated rules. 1793other complicated rules. This cannot be done with C<ev_timer> watchers, as
1794those cannot react to time jumps.
1590 1795
1591As with timers, the callback is guaranteed to be invoked only when the 1796As with timers, the callback is guaranteed to be invoked only when the
1592time (C<at>) has passed, but if multiple periodic timers become ready 1797point in time where it is supposed to trigger has passed. If multiple
1593during the same loop iteration, then order of execution is undefined. 1798timers become ready during the same loop iteration then the ones with
1799earlier time-out values are invoked before ones with later time-out values
1800(but this is no longer true when a callback calls C<ev_loop> recursively).
1594 1801
1595=head3 Watcher-Specific Functions and Data Members 1802=head3 Watcher-Specific Functions and Data Members
1596 1803
1597=over 4 1804=over 4
1598 1805
1599=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1806=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1600 1807
1601=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1808=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1602 1809
1603Lots of arguments, lets sort it out... There are basically three modes of 1810Lots of arguments, let's sort it out... There are basically three modes of
1604operation, and we will explain them from simplest to most complex: 1811operation, and we will explain them from simplest to most complex:
1605 1812
1606=over 4 1813=over 4
1607 1814
1608=item * absolute timer (at = time, interval = reschedule_cb = 0) 1815=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1609 1816
1610In this configuration the watcher triggers an event after the wall clock 1817In this configuration the watcher triggers an event after the wall clock
1611time C<at> has passed. It will not repeat and will not adjust when a time 1818time C<offset> has passed. It will not repeat and will not adjust when a
1612jump occurs, that is, if it is to be run at January 1st 2011 then it will 1819time jump occurs, that is, if it is to be run at January 1st 2011 then it
1613only run when the system clock reaches or surpasses this time. 1820will be stopped and invoked when the system clock reaches or surpasses
1821this point in time.
1614 1822
1615=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1823=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1616 1824
1617In this mode the watcher will always be scheduled to time out at the next 1825In this mode the watcher will always be scheduled to time out at the next
1618C<at + N * interval> time (for some integer N, which can also be negative) 1826C<offset + N * interval> time (for some integer N, which can also be
1619and then repeat, regardless of any time jumps. 1827negative) and then repeat, regardless of any time jumps. The C<offset>
1828argument is merely an offset into the C<interval> periods.
1620 1829
1621This can be used to create timers that do not drift with respect to the 1830This can be used to create timers that do not drift with respect to the
1622system clock, for example, here is a C<ev_periodic> that triggers each 1831system clock, for example, here is an C<ev_periodic> that triggers each
1623hour, on the hour: 1832hour, on the hour (with respect to UTC):
1624 1833
1625 ev_periodic_set (&periodic, 0., 3600., 0); 1834 ev_periodic_set (&periodic, 0., 3600., 0);
1626 1835
1627This doesn't mean there will always be 3600 seconds in between triggers, 1836This doesn't mean there will always be 3600 seconds in between triggers,
1628but only that the callback will be called when the system time shows a 1837but only that the callback will be called when the system time shows a
1629full hour (UTC), or more correctly, when the system time is evenly divisible 1838full hour (UTC), or more correctly, when the system time is evenly divisible
1630by 3600. 1839by 3600.
1631 1840
1632Another way to think about it (for the mathematically inclined) is that 1841Another way to think about it (for the mathematically inclined) is that
1633C<ev_periodic> will try to run the callback in this mode at the next possible 1842C<ev_periodic> will try to run the callback in this mode at the next possible
1634time where C<time = at (mod interval)>, regardless of any time jumps. 1843time where C<time = offset (mod interval)>, regardless of any time jumps.
1635 1844
1636For numerical stability it is preferable that the C<at> value is near 1845For numerical stability it is preferable that the C<offset> value is near
1637C<ev_now ()> (the current time), but there is no range requirement for 1846C<ev_now ()> (the current time), but there is no range requirement for
1638this value, and in fact is often specified as zero. 1847this value, and in fact is often specified as zero.
1639 1848
1640Note also that there is an upper limit to how often a timer can fire (CPU 1849Note also that there is an upper limit to how often a timer can fire (CPU
1641speed for example), so if C<interval> is very small then timing stability 1850speed for example), so if C<interval> is very small then timing stability
1642will of course deteriorate. Libev itself tries to be exact to be about one 1851will of course deteriorate. Libev itself tries to be exact to be about one
1643millisecond (if the OS supports it and the machine is fast enough). 1852millisecond (if the OS supports it and the machine is fast enough).
1644 1853
1645=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1854=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1646 1855
1647In this mode the values for C<interval> and C<at> are both being 1856In this mode the values for C<interval> and C<offset> are both being
1648ignored. Instead, each time the periodic watcher gets scheduled, the 1857ignored. Instead, each time the periodic watcher gets scheduled, the
1649reschedule callback will be called with the watcher as first, and the 1858reschedule callback will be called with the watcher as first, and the
1650current time as second argument. 1859current time as second argument.
1651 1860
1652NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1861NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1653ever, or make ANY event loop modifications whatsoever>. 1862or make ANY other event loop modifications whatsoever, unless explicitly
1863allowed by documentation here>.
1654 1864
1655If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1865If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1656it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1866it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1657only event loop modification you are allowed to do). 1867only event loop modification you are allowed to do).
1658 1868
1688a different time than the last time it was called (e.g. in a crond like 1898a different time than the last time it was called (e.g. in a crond like
1689program when the crontabs have changed). 1899program when the crontabs have changed).
1690 1900
1691=item ev_tstamp ev_periodic_at (ev_periodic *) 1901=item ev_tstamp ev_periodic_at (ev_periodic *)
1692 1902
1693When active, returns the absolute time that the watcher is supposed to 1903When active, returns the absolute time that the watcher is supposed
1694trigger next. 1904to trigger next. This is not the same as the C<offset> argument to
1905C<ev_periodic_set>, but indeed works even in interval and manual
1906rescheduling modes.
1695 1907
1696=item ev_tstamp offset [read-write] 1908=item ev_tstamp offset [read-write]
1697 1909
1698When repeating, this contains the offset value, otherwise this is the 1910When repeating, this contains the offset value, otherwise this is the
1699absolute point in time (the C<at> value passed to C<ev_periodic_set>). 1911absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
1912although libev might modify this value for better numerical stability).
1700 1913
1701Can be modified any time, but changes only take effect when the periodic 1914Can be modified any time, but changes only take effect when the periodic
1702timer fires or C<ev_periodic_again> is being called. 1915timer fires or C<ev_periodic_again> is being called.
1703 1916
1704=item ev_tstamp interval [read-write] 1917=item ev_tstamp interval [read-write]
1813some child status changes (most typically when a child of yours dies or 2026some child status changes (most typically when a child of yours dies or
1814exits). It is permissible to install a child watcher I<after> the child 2027exits). It is permissible to install a child watcher I<after> the child
1815has been forked (which implies it might have already exited), as long 2028has been forked (which implies it might have already exited), as long
1816as the event loop isn't entered (or is continued from a watcher), i.e., 2029as the event loop isn't entered (or is continued from a watcher), i.e.,
1817forking and then immediately registering a watcher for the child is fine, 2030forking and then immediately registering a watcher for the child is fine,
1818but forking and registering a watcher a few event loop iterations later is 2031but forking and registering a watcher a few event loop iterations later or
1819not. 2032in the next callback invocation is not.
1820 2033
1821Only the default event loop is capable of handling signals, and therefore 2034Only the default event loop is capable of handling signals, and therefore
1822you can only register child watchers in the default event loop. 2035you can only register child watchers in the default event loop.
2036
2037Due to some design glitches inside libev, child watchers will always be
2038handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2039libev)
1823 2040
1824=head3 Process Interaction 2041=head3 Process Interaction
1825 2042
1826Libev grabs C<SIGCHLD> as soon as the default event loop is 2043Libev grabs C<SIGCHLD> as soon as the default event loop is
1827initialised. This is necessary to guarantee proper behaviour even if 2044initialised. This is necessary to guarantee proper behaviour even if
1910 2127
1911 2128
1912=head2 C<ev_stat> - did the file attributes just change? 2129=head2 C<ev_stat> - did the file attributes just change?
1913 2130
1914This watches a file system path for attribute changes. That is, it calls 2131This watches a file system path for attribute changes. That is, it calls
1915C<stat> regularly (or when the OS says it changed) and sees if it changed 2132C<stat> on that path in regular intervals (or when the OS says it changed)
1916compared to the last time, invoking the callback if it did. 2133and sees if it changed compared to the last time, invoking the callback if
2134it did.
1917 2135
1918The path does not need to exist: changing from "path exists" to "path does 2136The path does not need to exist: changing from "path exists" to "path does
1919not exist" is a status change like any other. The condition "path does 2137not exist" is a status change like any other. The condition "path does not
1920not exist" is signified by the C<st_nlink> field being zero (which is 2138exist" (or more correctly "path cannot be stat'ed") is signified by the
1921otherwise always forced to be at least one) and all the other fields of 2139C<st_nlink> field being zero (which is otherwise always forced to be at
1922the stat buffer having unspecified contents. 2140least one) and all the other fields of the stat buffer having unspecified
2141contents.
1923 2142
1924The path I<should> be absolute and I<must not> end in a slash. If it is 2143The path I<must not> end in a slash or contain special components such as
2144C<.> or C<..>. The path I<should> be absolute: If it is relative and
1925relative and your working directory changes, the behaviour is undefined. 2145your working directory changes, then the behaviour is undefined.
1926 2146
1927Since there is no standard kernel interface to do this, the portable 2147Since there is no portable change notification interface available, the
1928implementation simply calls C<stat (2)> regularly on the path to see if 2148portable implementation simply calls C<stat(2)> regularly on the path
1929it changed somehow. You can specify a recommended polling interval for 2149to see if it changed somehow. You can specify a recommended polling
1930this case. If you specify a polling interval of C<0> (highly recommended!) 2150interval for this case. If you specify a polling interval of C<0> (highly
1931then a I<suitable, unspecified default> value will be used (which 2151recommended!) then a I<suitable, unspecified default> value will be used
1932you can expect to be around five seconds, although this might change 2152(which you can expect to be around five seconds, although this might
1933dynamically). Libev will also impose a minimum interval which is currently 2153change dynamically). Libev will also impose a minimum interval which is
1934around C<0.1>, but thats usually overkill. 2154currently around C<0.1>, but that's usually overkill.
1935 2155
1936This watcher type is not meant for massive numbers of stat watchers, 2156This watcher type is not meant for massive numbers of stat watchers,
1937as even with OS-supported change notifications, this can be 2157as even with OS-supported change notifications, this can be
1938resource-intensive. 2158resource-intensive.
1939 2159
1940At the time of this writing, the only OS-specific interface implemented 2160At the time of this writing, the only OS-specific interface implemented
1941is the Linux inotify interface (implementing kqueue support is left as 2161is the Linux inotify interface (implementing kqueue support is left as an
1942an exercise for the reader. Note, however, that the author sees no way 2162exercise for the reader. Note, however, that the author sees no way of
1943of implementing C<ev_stat> semantics with kqueue). 2163implementing C<ev_stat> semantics with kqueue, except as a hint).
1944 2164
1945=head3 ABI Issues (Largefile Support) 2165=head3 ABI Issues (Largefile Support)
1946 2166
1947Libev by default (unless the user overrides this) uses the default 2167Libev by default (unless the user overrides this) uses the default
1948compilation environment, which means that on systems with large file 2168compilation environment, which means that on systems with large file
1949support disabled by default, you get the 32 bit version of the stat 2169support disabled by default, you get the 32 bit version of the stat
1950structure. When using the library from programs that change the ABI to 2170structure. When using the library from programs that change the ABI to
1951use 64 bit file offsets the programs will fail. In that case you have to 2171use 64 bit file offsets the programs will fail. In that case you have to
1952compile libev with the same flags to get binary compatibility. This is 2172compile libev with the same flags to get binary compatibility. This is
1953obviously the case with any flags that change the ABI, but the problem is 2173obviously the case with any flags that change the ABI, but the problem is
1954most noticeably disabled with ev_stat and large file support. 2174most noticeably displayed with ev_stat and large file support.
1955 2175
1956The solution for this is to lobby your distribution maker to make large 2176The solution for this is to lobby your distribution maker to make large
1957file interfaces available by default (as e.g. FreeBSD does) and not 2177file interfaces available by default (as e.g. FreeBSD does) and not
1958optional. Libev cannot simply switch on large file support because it has 2178optional. Libev cannot simply switch on large file support because it has
1959to exchange stat structures with application programs compiled using the 2179to exchange stat structures with application programs compiled using the
1960default compilation environment. 2180default compilation environment.
1961 2181
1962=head3 Inotify and Kqueue 2182=head3 Inotify and Kqueue
1963 2183
1964When C<inotify (7)> support has been compiled into libev (generally 2184When C<inotify (7)> support has been compiled into libev and present at
1965only available with Linux 2.6.25 or above due to bugs in earlier 2185runtime, it will be used to speed up change detection where possible. The
1966implementations) and present at runtime, it will be used to speed up 2186inotify descriptor will be created lazily when the first C<ev_stat>
1967change detection where possible. The inotify descriptor will be created 2187watcher is being started.
1968lazily when the first C<ev_stat> watcher is being started.
1969 2188
1970Inotify presence does not change the semantics of C<ev_stat> watchers 2189Inotify presence does not change the semantics of C<ev_stat> watchers
1971except that changes might be detected earlier, and in some cases, to avoid 2190except that changes might be detected earlier, and in some cases, to avoid
1972making regular C<stat> calls. Even in the presence of inotify support 2191making regular C<stat> calls. Even in the presence of inotify support
1973there are many cases where libev has to resort to regular C<stat> polling, 2192there are many cases where libev has to resort to regular C<stat> polling,
1974but as long as the path exists, libev usually gets away without polling. 2193but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
2194many bugs), the path exists (i.e. stat succeeds), and the path resides on
2195a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2196xfs are fully working) libev usually gets away without polling.
1975 2197
1976There is no support for kqueue, as apparently it cannot be used to 2198There is no support for kqueue, as apparently it cannot be used to
1977implement this functionality, due to the requirement of having a file 2199implement this functionality, due to the requirement of having a file
1978descriptor open on the object at all times, and detecting renames, unlinks 2200descriptor open on the object at all times, and detecting renames, unlinks
1979etc. is difficult. 2201etc. is difficult.
1980 2202
2203=head3 C<stat ()> is a synchronous operation
2204
2205Libev doesn't normally do any kind of I/O itself, and so is not blocking
2206the process. The exception are C<ev_stat> watchers - those call C<stat
2207()>, which is a synchronous operation.
2208
2209For local paths, this usually doesn't matter: unless the system is very
2210busy or the intervals between stat's are large, a stat call will be fast,
2211as the path data is usually in memory already (except when starting the
2212watcher).
2213
2214For networked file systems, calling C<stat ()> can block an indefinite
2215time due to network issues, and even under good conditions, a stat call
2216often takes multiple milliseconds.
2217
2218Therefore, it is best to avoid using C<ev_stat> watchers on networked
2219paths, although this is fully supported by libev.
2220
1981=head3 The special problem of stat time resolution 2221=head3 The special problem of stat time resolution
1982 2222
1983The C<stat ()> system call only supports full-second resolution portably, and 2223The C<stat ()> system call only supports full-second resolution portably,
1984even on systems where the resolution is higher, most file systems still 2224and even on systems where the resolution is higher, most file systems
1985only support whole seconds. 2225still only support whole seconds.
1986 2226
1987That means that, if the time is the only thing that changes, you can 2227That means that, if the time is the only thing that changes, you can
1988easily miss updates: on the first update, C<ev_stat> detects a change and 2228easily miss updates: on the first update, C<ev_stat> detects a change and
1989calls your callback, which does something. When there is another update 2229calls your callback, which does something. When there is another update
1990within the same second, C<ev_stat> will be unable to detect unless the 2230within the same second, C<ev_stat> will be unable to detect unless the
2133 2373
2134=head3 Watcher-Specific Functions and Data Members 2374=head3 Watcher-Specific Functions and Data Members
2135 2375
2136=over 4 2376=over 4
2137 2377
2138=item ev_idle_init (ev_signal *, callback) 2378=item ev_idle_init (ev_idle *, callback)
2139 2379
2140Initialises and configures the idle watcher - it has no parameters of any 2380Initialises and configures the idle watcher - it has no parameters of any
2141kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2381kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2142believe me. 2382believe me.
2143 2383
2156 // no longer anything immediate to do. 2396 // no longer anything immediate to do.
2157 } 2397 }
2158 2398
2159 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 2399 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2160 ev_idle_init (idle_watcher, idle_cb); 2400 ev_idle_init (idle_watcher, idle_cb);
2161 ev_idle_start (loop, idle_cb); 2401 ev_idle_start (loop, idle_watcher);
2162 2402
2163 2403
2164=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2404=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2165 2405
2166Prepare and check watchers are usually (but not always) used in pairs: 2406Prepare and check watchers are usually (but not always) used in pairs:
2259 struct pollfd fds [nfd]; 2499 struct pollfd fds [nfd];
2260 // actual code will need to loop here and realloc etc. 2500 // actual code will need to loop here and realloc etc.
2261 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2501 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2262 2502
2263 /* the callback is illegal, but won't be called as we stop during check */ 2503 /* the callback is illegal, but won't be called as we stop during check */
2264 ev_timer_init (&tw, 0, timeout * 1e-3); 2504 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2265 ev_timer_start (loop, &tw); 2505 ev_timer_start (loop, &tw);
2266 2506
2267 // create one ev_io per pollfd 2507 // create one ev_io per pollfd
2268 for (int i = 0; i < nfd; ++i) 2508 for (int i = 0; i < nfd; ++i)
2269 { 2509 {
2382some fds have to be watched and handled very quickly (with low latency), 2622some fds have to be watched and handled very quickly (with low latency),
2383and even priorities and idle watchers might have too much overhead. In 2623and even priorities and idle watchers might have too much overhead. In
2384this case you would put all the high priority stuff in one loop and all 2624this case you would put all the high priority stuff in one loop and all
2385the rest in a second one, and embed the second one in the first. 2625the rest in a second one, and embed the second one in the first.
2386 2626
2387As long as the watcher is active, the callback will be invoked every time 2627As long as the watcher is active, the callback will be invoked every
2388there might be events pending in the embedded loop. The callback must then 2628time there might be events pending in the embedded loop. The callback
2389call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2629must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2390their callbacks (you could also start an idle watcher to give the embedded 2630sweep and invoke their callbacks (the callback doesn't need to invoke the
2391loop strictly lower priority for example). You can also set the callback 2631C<ev_embed_sweep> function directly, it could also start an idle watcher
2392to C<0>, in which case the embed watcher will automatically execute the 2632to give the embedded loop strictly lower priority for example).
2393embedded loop sweep.
2394 2633
2395As long as the watcher is started it will automatically handle events. The 2634You can also set the callback to C<0>, in which case the embed watcher
2396callback will be invoked whenever some events have been handled. You can 2635will automatically execute the embedded loop sweep whenever necessary.
2397set the callback to C<0> to avoid having to specify one if you are not
2398interested in that.
2399 2636
2400Also, there have not currently been made special provisions for forking: 2637Fork detection will be handled transparently while the C<ev_embed> watcher
2401when you fork, you not only have to call C<ev_loop_fork> on both loops, 2638is active, i.e., the embedded loop will automatically be forked when the
2402but you will also have to stop and restart any C<ev_embed> watchers 2639embedding loop forks. In other cases, the user is responsible for calling
2403yourself - but you can use a fork watcher to handle this automatically, 2640C<ev_loop_fork> on the embedded loop.
2404and future versions of libev might do just that.
2405 2641
2406Unfortunately, not all backends are embeddable: only the ones returned by 2642Unfortunately, not all backends are embeddable: only the ones returned by
2407C<ev_embeddable_backends> are, which, unfortunately, does not include any 2643C<ev_embeddable_backends> are, which, unfortunately, does not include any
2408portable one. 2644portable one.
2409 2645
2503event loop blocks next and before C<ev_check> watchers are being called, 2739event loop blocks next and before C<ev_check> watchers are being called,
2504and only in the child after the fork. If whoever good citizen calling 2740and only in the child after the fork. If whoever good citizen calling
2505C<ev_default_fork> cheats and calls it in the wrong process, the fork 2741C<ev_default_fork> cheats and calls it in the wrong process, the fork
2506handlers will be invoked, too, of course. 2742handlers will be invoked, too, of course.
2507 2743
2744=head3 The special problem of life after fork - how is it possible?
2745
2746Most uses of C<fork()> consist of forking, then some simple calls to ste
2747up/change the process environment, followed by a call to C<exec()>. This
2748sequence should be handled by libev without any problems.
2749
2750This changes when the application actually wants to do event handling
2751in the child, or both parent in child, in effect "continuing" after the
2752fork.
2753
2754The default mode of operation (for libev, with application help to detect
2755forks) is to duplicate all the state in the child, as would be expected
2756when I<either> the parent I<or> the child process continues.
2757
2758When both processes want to continue using libev, then this is usually the
2759wrong result. In that case, usually one process (typically the parent) is
2760supposed to continue with all watchers in place as before, while the other
2761process typically wants to start fresh, i.e. without any active watchers.
2762
2763The cleanest and most efficient way to achieve that with libev is to
2764simply create a new event loop, which of course will be "empty", and
2765use that for new watchers. This has the advantage of not touching more
2766memory than necessary, and thus avoiding the copy-on-write, and the
2767disadvantage of having to use multiple event loops (which do not support
2768signal watchers).
2769
2770When this is not possible, or you want to use the default loop for
2771other reasons, then in the process that wants to start "fresh", call
2772C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
2773the default loop will "orphan" (not stop) all registered watchers, so you
2774have to be careful not to execute code that modifies those watchers. Note
2775also that in that case, you have to re-register any signal watchers.
2776
2508=head3 Watcher-Specific Functions and Data Members 2777=head3 Watcher-Specific Functions and Data Members
2509 2778
2510=over 4 2779=over 4
2511 2780
2512=item ev_fork_init (ev_signal *, callback) 2781=item ev_fork_init (ev_signal *, callback)
2629=over 4 2898=over 4
2630 2899
2631=item ev_async_init (ev_async *, callback) 2900=item ev_async_init (ev_async *, callback)
2632 2901
2633Initialises and configures the async watcher - it has no parameters of any 2902Initialises and configures the async watcher - it has no parameters of any
2634kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 2903kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2635trust me. 2904trust me.
2636 2905
2637=item ev_async_send (loop, ev_async *) 2906=item ev_async_send (loop, ev_async *)
2638 2907
2639Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2908Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2640an C<EV_ASYNC> event on the watcher into the event loop. Unlike 2909an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2641C<ev_feed_event>, this call is safe to do from other threads, signal or 2910C<ev_feed_event>, this call is safe to do from other threads, signal or
2642similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 2911similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2643section below on what exactly this means). 2912section below on what exactly this means).
2644 2913
2914Note that, as with other watchers in libev, multiple events might get
2915compressed into a single callback invocation (another way to look at this
2916is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
2917reset when the event loop detects that).
2918
2645This call incurs the overhead of a system call only once per loop iteration, 2919This call incurs the overhead of a system call only once per event loop
2646so while the overhead might be noticeable, it doesn't apply to repeated 2920iteration, so while the overhead might be noticeable, it doesn't apply to
2647calls to C<ev_async_send>. 2921repeated calls to C<ev_async_send> for the same event loop.
2648 2922
2649=item bool = ev_async_pending (ev_async *) 2923=item bool = ev_async_pending (ev_async *)
2650 2924
2651Returns a non-zero value when C<ev_async_send> has been called on the 2925Returns a non-zero value when C<ev_async_send> has been called on the
2652watcher but the event has not yet been processed (or even noted) by the 2926watcher but the event has not yet been processed (or even noted) by the
2655C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 2929C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2656the loop iterates next and checks for the watcher to have become active, 2930the loop iterates next and checks for the watcher to have become active,
2657it will reset the flag again. C<ev_async_pending> can be used to very 2931it will reset the flag again. C<ev_async_pending> can be used to very
2658quickly check whether invoking the loop might be a good idea. 2932quickly check whether invoking the loop might be a good idea.
2659 2933
2660Not that this does I<not> check whether the watcher itself is pending, only 2934Not that this does I<not> check whether the watcher itself is pending,
2661whether it has been requested to make this watcher pending. 2935only whether it has been requested to make this watcher pending: there
2936is a time window between the event loop checking and resetting the async
2937notification, and the callback being invoked.
2662 2938
2663=back 2939=back
2664 2940
2665 2941
2666=head1 OTHER FUNCTIONS 2942=head1 OTHER FUNCTIONS
2845 3121
2846 myclass obj; 3122 myclass obj;
2847 ev::io iow; 3123 ev::io iow;
2848 iow.set <myclass, &myclass::io_cb> (&obj); 3124 iow.set <myclass, &myclass::io_cb> (&obj);
2849 3125
3126=item w->set (object *)
3127
3128This is an B<experimental> feature that might go away in a future version.
3129
3130This is a variation of a method callback - leaving out the method to call
3131will default the method to C<operator ()>, which makes it possible to use
3132functor objects without having to manually specify the C<operator ()> all
3133the time. Incidentally, you can then also leave out the template argument
3134list.
3135
3136The C<operator ()> method prototype must be C<void operator ()(watcher &w,
3137int revents)>.
3138
3139See the method-C<set> above for more details.
3140
3141Example: use a functor object as callback.
3142
3143 struct myfunctor
3144 {
3145 void operator() (ev::io &w, int revents)
3146 {
3147 ...
3148 }
3149 }
3150
3151 myfunctor f;
3152
3153 ev::io w;
3154 w.set (&f);
3155
2850=item w->set<function> (void *data = 0) 3156=item w->set<function> (void *data = 0)
2851 3157
2852Also sets a callback, but uses a static method or plain function as 3158Also sets a callback, but uses a static method or plain function as
2853callback. The optional C<data> argument will be stored in the watcher's 3159callback. The optional C<data> argument will be stored in the watcher's
2854C<data> member and is free for you to use. 3160C<data> member and is free for you to use.
2940L<http://software.schmorp.de/pkg/EV>. 3246L<http://software.schmorp.de/pkg/EV>.
2941 3247
2942=item Python 3248=item Python
2943 3249
2944Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3250Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2945seems to be quite complete and well-documented. Note, however, that the 3251seems to be quite complete and well-documented.
2946patch they require for libev is outright dangerous as it breaks the ABI
2947for everybody else, and therefore, should never be applied in an installed
2948libev (if python requires an incompatible ABI then it needs to embed
2949libev).
2950 3252
2951=item Ruby 3253=item Ruby
2952 3254
2953Tony Arcieri has written a ruby extension that offers access to a subset 3255Tony Arcieri has written a ruby extension that offers access to a subset
2954of the libev API and adds file handle abstractions, asynchronous DNS and 3256of the libev API and adds file handle abstractions, asynchronous DNS and
2955more on top of it. It can be found via gem servers. Its homepage is at 3257more on top of it. It can be found via gem servers. Its homepage is at
2956L<http://rev.rubyforge.org/>. 3258L<http://rev.rubyforge.org/>.
3259
3260Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3261makes rev work even on mingw.
3262
3263=item Haskell
3264
3265A haskell binding to libev is available at
3266L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
2957 3267
2958=item D 3268=item D
2959 3269
2960Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3270Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2961be found at L<http://proj.llucax.com.ar/wiki/evd>. 3271be found at L<http://proj.llucax.com.ar/wiki/evd>.
3072 3382
3073 #define EV_STANDALONE 1 3383 #define EV_STANDALONE 1
3074 #include "ev.h" 3384 #include "ev.h"
3075 3385
3076Both header files and implementation files can be compiled with a C++ 3386Both header files and implementation files can be compiled with a C++
3077compiler (at least, thats a stated goal, and breakage will be treated 3387compiler (at least, that's a stated goal, and breakage will be treated
3078as a bug). 3388as a bug).
3079 3389
3080You need the following files in your source tree, or in a directory 3390You need the following files in your source tree, or in a directory
3081in your include path (e.g. in libev/ when using -Ilibev): 3391in your include path (e.g. in libev/ when using -Ilibev):
3082 3392
3138keeps libev from including F<config.h>, and it also defines dummy 3448keeps libev from including F<config.h>, and it also defines dummy
3139implementations for some libevent functions (such as logging, which is not 3449implementations for some libevent functions (such as logging, which is not
3140supported). It will also not define any of the structs usually found in 3450supported). It will also not define any of the structs usually found in
3141F<event.h> that are not directly supported by the libev core alone. 3451F<event.h> that are not directly supported by the libev core alone.
3142 3452
3453In stanbdalone mode, libev will still try to automatically deduce the
3454configuration, but has to be more conservative.
3455
3143=item EV_USE_MONOTONIC 3456=item EV_USE_MONOTONIC
3144 3457
3145If defined to be C<1>, libev will try to detect the availability of the 3458If defined to be C<1>, libev will try to detect the availability of the
3146monotonic clock option at both compile time and runtime. Otherwise no use 3459monotonic clock option at both compile time and runtime. Otherwise no
3147of the monotonic clock option will be attempted. If you enable this, you 3460use of the monotonic clock option will be attempted. If you enable this,
3148usually have to link against librt or something similar. Enabling it when 3461you usually have to link against librt or something similar. Enabling it
3149the functionality isn't available is safe, though, although you have 3462when the functionality isn't available is safe, though, although you have
3150to make sure you link against any libraries where the C<clock_gettime> 3463to make sure you link against any libraries where the C<clock_gettime>
3151function is hiding in (often F<-lrt>). 3464function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3152 3465
3153=item EV_USE_REALTIME 3466=item EV_USE_REALTIME
3154 3467
3155If defined to be C<1>, libev will try to detect the availability of the 3468If defined to be C<1>, libev will try to detect the availability of the
3156real-time clock option at compile time (and assume its availability at 3469real-time clock option at compile time (and assume its availability
3157runtime if successful). Otherwise no use of the real-time clock option will 3470at runtime if successful). Otherwise no use of the real-time clock
3158be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3471option will be attempted. This effectively replaces C<gettimeofday>
3159(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3472by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3160note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3473correctness. See the note about libraries in the description of
3474C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3475C<EV_USE_CLOCK_SYSCALL>.
3476
3477=item EV_USE_CLOCK_SYSCALL
3478
3479If defined to be C<1>, libev will try to use a direct syscall instead
3480of calling the system-provided C<clock_gettime> function. This option
3481exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3482unconditionally pulls in C<libpthread>, slowing down single-threaded
3483programs needlessly. Using a direct syscall is slightly slower (in
3484theory), because no optimised vdso implementation can be used, but avoids
3485the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3486higher, as it simplifies linking (no need for C<-lrt>).
3161 3487
3162=item EV_USE_NANOSLEEP 3488=item EV_USE_NANOSLEEP
3163 3489
3164If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3490If defined to be C<1>, libev will assume that C<nanosleep ()> is available
3165and will use it for delays. Otherwise it will use C<select ()>. 3491and will use it for delays. Otherwise it will use C<select ()>.
3181 3507
3182=item EV_SELECT_USE_FD_SET 3508=item EV_SELECT_USE_FD_SET
3183 3509
3184If defined to C<1>, then the select backend will use the system C<fd_set> 3510If defined to C<1>, then the select backend will use the system C<fd_set>
3185structure. This is useful if libev doesn't compile due to a missing 3511structure. This is useful if libev doesn't compile due to a missing
3186C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on 3512C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
3187exotic systems. This usually limits the range of file descriptors to some 3513on exotic systems. This usually limits the range of file descriptors to
3188low limit such as 1024 or might have other limitations (winsocket only 3514some low limit such as 1024 or might have other limitations (winsocket
3189allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3515only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
3190influence the size of the C<fd_set> used. 3516configures the maximum size of the C<fd_set>.
3191 3517
3192=item EV_SELECT_IS_WINSOCKET 3518=item EV_SELECT_IS_WINSOCKET
3193 3519
3194When defined to C<1>, the select backend will assume that 3520When defined to C<1>, the select backend will assume that
3195select/socket/connect etc. don't understand file descriptors but 3521select/socket/connect etc. don't understand file descriptors but
3554loop, as long as you don't confuse yourself). The only exception is that 3880loop, as long as you don't confuse yourself). The only exception is that
3555you must not do this from C<ev_periodic> reschedule callbacks. 3881you must not do this from C<ev_periodic> reschedule callbacks.
3556 3882
3557Care has been taken to ensure that libev does not keep local state inside 3883Care has been taken to ensure that libev does not keep local state inside
3558C<ev_loop>, and other calls do not usually allow for coroutine switches as 3884C<ev_loop>, and other calls do not usually allow for coroutine switches as
3559they do not clal any callbacks. 3885they do not call any callbacks.
3560 3886
3561=head2 COMPILER WARNINGS 3887=head2 COMPILER WARNINGS
3562 3888
3563Depending on your compiler and compiler settings, you might get no or a 3889Depending on your compiler and compiler settings, you might get no or a
3564lot of warnings when compiling libev code. Some people are apparently 3890lot of warnings when compiling libev code. Some people are apparently
3598 ==2274== definitely lost: 0 bytes in 0 blocks. 3924 ==2274== definitely lost: 0 bytes in 0 blocks.
3599 ==2274== possibly lost: 0 bytes in 0 blocks. 3925 ==2274== possibly lost: 0 bytes in 0 blocks.
3600 ==2274== still reachable: 256 bytes in 1 blocks. 3926 ==2274== still reachable: 256 bytes in 1 blocks.
3601 3927
3602Then there is no memory leak, just as memory accounted to global variables 3928Then there is no memory leak, just as memory accounted to global variables
3603is not a memleak - the memory is still being refernced, and didn't leak. 3929is not a memleak - the memory is still being referenced, and didn't leak.
3604 3930
3605Similarly, under some circumstances, valgrind might report kernel bugs 3931Similarly, under some circumstances, valgrind might report kernel bugs
3606as if it were a bug in libev (e.g. in realloc or in the poll backend, 3932as if it were a bug in libev (e.g. in realloc or in the poll backend,
3607although an acceptable workaround has been found here), or it might be 3933although an acceptable workaround has been found here), or it might be
3608confused. 3934confused.
3637way (note also that glib is the slowest event library known to man). 3963way (note also that glib is the slowest event library known to man).
3638 3964
3639There is no supported compilation method available on windows except 3965There is no supported compilation method available on windows except
3640embedding it into other applications. 3966embedding it into other applications.
3641 3967
3968Sensible signal handling is officially unsupported by Microsoft - libev
3969tries its best, but under most conditions, signals will simply not work.
3970
3642Not a libev limitation but worth mentioning: windows apparently doesn't 3971Not a libev limitation but worth mentioning: windows apparently doesn't
3643accept large writes: instead of resulting in a partial write, windows will 3972accept large writes: instead of resulting in a partial write, windows will
3644either accept everything or return C<ENOBUFS> if the buffer is too large, 3973either accept everything or return C<ENOBUFS> if the buffer is too large,
3645so make sure you only write small amounts into your sockets (less than a 3974so make sure you only write small amounts into your sockets (less than a
3646megabyte seems safe, but this apparently depends on the amount of memory 3975megabyte seems safe, but this apparently depends on the amount of memory
3650the abysmal performance of winsockets, using a large number of sockets 3979the abysmal performance of winsockets, using a large number of sockets
3651is not recommended (and not reasonable). If your program needs to use 3980is not recommended (and not reasonable). If your program needs to use
3652more than a hundred or so sockets, then likely it needs to use a totally 3981more than a hundred or so sockets, then likely it needs to use a totally
3653different implementation for windows, as libev offers the POSIX readiness 3982different implementation for windows, as libev offers the POSIX readiness
3654notification model, which cannot be implemented efficiently on windows 3983notification model, which cannot be implemented efficiently on windows
3655(Microsoft monopoly games). 3984(due to Microsoft monopoly games).
3656 3985
3657A typical way to use libev under windows is to embed it (see the embedding 3986A typical way to use libev under windows is to embed it (see the embedding
3658section for details) and use the following F<evwrap.h> header file instead 3987section for details) and use the following F<evwrap.h> header file instead
3659of F<ev.h>: 3988of F<ev.h>:
3660 3989
3696 4025
3697Early versions of winsocket's select only supported waiting for a maximum 4026Early versions of winsocket's select only supported waiting for a maximum
3698of C<64> handles (probably owning to the fact that all windows kernels 4027of C<64> handles (probably owning to the fact that all windows kernels
3699can only wait for C<64> things at the same time internally; Microsoft 4028can only wait for C<64> things at the same time internally; Microsoft
3700recommends spawning a chain of threads and wait for 63 handles and the 4029recommends spawning a chain of threads and wait for 63 handles and the
3701previous thread in each. Great). 4030previous thread in each. Sounds great!).
3702 4031
3703Newer versions support more handles, but you need to define C<FD_SETSIZE> 4032Newer versions support more handles, but you need to define C<FD_SETSIZE>
3704to some high number (e.g. C<2048>) before compiling the winsocket select 4033to some high number (e.g. C<2048>) before compiling the winsocket select
3705call (which might be in libev or elsewhere, for example, perl does its own 4034call (which might be in libev or elsewhere, for example, perl and many
3706select emulation on windows). 4035other interpreters do their own select emulation on windows).
3707 4036
3708Another limit is the number of file descriptors in the Microsoft runtime 4037Another limit is the number of file descriptors in the Microsoft runtime
3709libraries, which by default is C<64> (there must be a hidden I<64> fetish 4038libraries, which by default is C<64> (there must be a hidden I<64>
3710or something like this inside Microsoft). You can increase this by calling 4039fetish or something like this inside Microsoft). You can increase this
3711C<_setmaxstdio>, which can increase this limit to C<2048> (another 4040by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3712arbitrary limit), but is broken in many versions of the Microsoft runtime 4041(another arbitrary limit), but is broken in many versions of the Microsoft
3713libraries.
3714
3715This might get you to about C<512> or C<2048> sockets (depending on 4042runtime libraries. This might get you to about C<512> or C<2048> sockets
3716windows version and/or the phase of the moon). To get more, you need to 4043(depending on windows version and/or the phase of the moon). To get more,
3717wrap all I/O functions and provide your own fd management, but the cost of 4044you need to wrap all I/O functions and provide your own fd management, but
3718calling select (O(n²)) will likely make this unworkable. 4045the cost of calling select (O(n²)) will likely make this unworkable.
3719 4046
3720=back 4047=back
3721 4048
3722=head2 PORTABILITY REQUIREMENTS 4049=head2 PORTABILITY REQUIREMENTS
3723 4050
3766=item C<double> must hold a time value in seconds with enough accuracy 4093=item C<double> must hold a time value in seconds with enough accuracy
3767 4094
3768The type C<double> is used to represent timestamps. It is required to 4095The type C<double> is used to represent timestamps. It is required to
3769have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4096have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3770enough for at least into the year 4000. This requirement is fulfilled by 4097enough for at least into the year 4000. This requirement is fulfilled by
3771implementations implementing IEEE 754 (basically all existing ones). 4098implementations implementing IEEE 754, which is basically all existing
4099ones. With IEEE 754 doubles, you get microsecond accuracy until at least
41002200.
3772 4101
3773=back 4102=back
3774 4103
3775If you know of other additional requirements drop me a note. 4104If you know of other additional requirements drop me a note.
3776 4105
3844involves iterating over all running async watchers or all signal numbers. 4173involves iterating over all running async watchers or all signal numbers.
3845 4174
3846=back 4175=back
3847 4176
3848 4177
4178=head1 GLOSSARY
4179
4180=over 4
4181
4182=item active
4183
4184A watcher is active as long as it has been started (has been attached to
4185an event loop) but not yet stopped (disassociated from the event loop).
4186
4187=item application
4188
4189In this document, an application is whatever is using libev.
4190
4191=item callback
4192
4193The address of a function that is called when some event has been
4194detected. Callbacks are being passed the event loop, the watcher that
4195received the event, and the actual event bitset.
4196
4197=item callback invocation
4198
4199The act of calling the callback associated with a watcher.
4200
4201=item event
4202
4203A change of state of some external event, such as data now being available
4204for reading on a file descriptor, time having passed or simply not having
4205any other events happening anymore.
4206
4207In libev, events are represented as single bits (such as C<EV_READ> or
4208C<EV_TIMEOUT>).
4209
4210=item event library
4211
4212A software package implementing an event model and loop.
4213
4214=item event loop
4215
4216An entity that handles and processes external events and converts them
4217into callback invocations.
4218
4219=item event model
4220
4221The model used to describe how an event loop handles and processes
4222watchers and events.
4223
4224=item pending
4225
4226A watcher is pending as soon as the corresponding event has been detected,
4227and stops being pending as soon as the watcher will be invoked or its
4228pending status is explicitly cleared by the application.
4229
4230A watcher can be pending, but not active. Stopping a watcher also clears
4231its pending status.
4232
4233=item real time
4234
4235The physical time that is observed. It is apparently strictly monotonic :)
4236
4237=item wall-clock time
4238
4239The time and date as shown on clocks. Unlike real time, it can actually
4240be wrong and jump forwards and backwards, e.g. when the you adjust your
4241clock.
4242
4243=item watcher
4244
4245A data structure that describes interest in certain events. Watchers need
4246to be started (attached to an event loop) before they can receive events.
4247
4248=item watcher invocation
4249
4250The act of calling the callback associated with a watcher.
4251
4252=back
4253
3849=head1 AUTHOR 4254=head1 AUTHOR
3850 4255
3851Marc Lehmann <libev@schmorp.de>. 4256Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3852 4257

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines