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

Comparing libev/ev.pod (file contents):
Revision 1.212 by root, Mon Nov 3 15:13:53 2008 UTC vs.
Revision 1.265 by root, Wed Aug 26 17:11:42 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
84=head2 FEATURES 98=head2 FEATURES
85 99
86Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
87BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
88for file descriptor events (C<ev_io>), the Linux C<inotify> interface 102for file descriptor events (C<ev_io>), the Linux C<inotify> interface
89(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 103(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
90with customised rescheduling (C<ev_periodic>), synchronous signals 104inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
91(C<ev_signal>), process status change events (C<ev_child>), and event 105timers (C<ev_timer>), absolute timers with customised rescheduling
92watchers dealing with the event loop mechanism itself (C<ev_idle>, 106(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
93C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 107change events (C<ev_child>), and event watchers dealing with the event
94file watchers (C<ev_stat>) and even limited support for fork events 108loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
95(C<ev_fork>). 109C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
110limited support for fork events (C<ev_fork>).
96 111
97It also is quite fast (see this 112It also is quite fast (see this
98L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 113L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
99for example). 114for example).
100 115
108name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<ev_loop *>) will not have
109this argument. 124this argument.
110 125
111=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
112 127
113Libev represents time as a single floating point number, representing the 128Libev represents time as a single floating point number, representing
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 129the (fractional) number of seconds since the (POSIX) epoch (somewhere
115the beginning of 1970, details are complicated, don't ask). This type is 130near the beginning of 1970, details are complicated, don't ask). This
116called C<ev_tstamp>, which is what you should use too. It usually aliases 131type is called C<ev_tstamp>, which is what you should use too. It usually
117to the C<double> type in C, and when you need to do any calculations on 132aliases to the C<double> type in C. When you need to do any calculations
118it, you should treat it as some floating point value. Unlike the name 133on it, you should treat it as some floating point value. Unlike the name
119component C<stamp> might indicate, it is also used for time differences 134component C<stamp> might indicate, it is also used for time differences
120throughout libev. 135throughout libev.
121 136
122=head1 ERROR HANDLING 137=head1 ERROR HANDLING
123 138
347forget about forgetting to tell libev about forking) when you use this 362forget about forgetting to tell libev about forking) when you use this
348flag. 363flag.
349 364
350This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 365This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
351environment variable. 366environment variable.
367
368=item C<EVFLAG_NOINOTIFY>
369
370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374
375=item C<EVFLAG_NOSIGNALFD>
376
377When this flag is specified, then libev will not attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is
379probably only useful to work around any bugs in libev. Consequently, this
380flag might go away once the signalfd functionality is considered stable,
381so it's useful mostly in environment variables and not in program code.
352 382
353=item C<EVBACKEND_SELECT> (value 1, portable select backend) 383=item C<EVBACKEND_SELECT> (value 1, portable select backend)
354 384
355This is your standard select(2) backend. Not I<completely> standard, as 385This is your standard select(2) backend. Not I<completely> standard, as
356libev tries to roll its own fd_set with no limits on the number of fds, 386libev tries to roll its own fd_set with no limits on the number of fds,
417i.e. keep at least one watcher active per fd at all times. Stopping and 447i.e. keep at least one watcher active per fd at all times. Stopping and
418starting a watcher (without re-setting it) also usually doesn't cause 448starting a watcher (without re-setting it) also usually doesn't cause
419extra overhead. A fork can both result in spurious notifications as well 449extra overhead. A fork can both result in spurious notifications as well
420as in libev having to destroy and recreate the epoll object, which can 450as in libev having to destroy and recreate the epoll object, which can
421take considerable time and thus should be avoided. 451take considerable time and thus should be avoided.
452
453All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
454faster than epoll for maybe up to a hundred file descriptors, depending on
455the usage. So sad.
422 456
423While nominally embeddable in other event loops, this feature is broken in 457While nominally embeddable in other event loops, this feature is broken in
424all kernel versions tested so far. 458all kernel versions tested so far.
425 459
426This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 460This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
454 488
455While nominally embeddable in other event loops, this doesn't work 489While nominally embeddable in other event loops, this doesn't work
456everywhere, so you might need to test for this. And since it is broken 490everywhere, so you might need to test for this. And since it is broken
457almost everywhere, you should only use it when you have a lot of sockets 491almost everywhere, you should only use it when you have a lot of sockets
458(for which it usually works), by embedding it into another event loop 492(for which it usually works), by embedding it into another event loop
459(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it, 493(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
460using it only for sockets. 494also broken on OS X)) and, did I mention it, using it only for sockets.
461 495
462This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 496This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
463C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with 497C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
464C<NOTE_EOF>. 498C<NOTE_EOF>.
465 499
500 534
501It is definitely not recommended to use this flag. 535It is definitely not recommended to use this flag.
502 536
503=back 537=back
504 538
505If one or more of these are or'ed into the flags value, then only these 539If one or more of the backend flags are or'ed into the flags value,
506backends will be tried (in the reverse order as listed here). If none are 540then only these backends will be tried (in the reverse order as listed
507specified, all backends in C<ev_recommended_backends ()> will be tried. 541here). If none are specified, all backends in C<ev_recommended_backends
542()> will be tried.
508 543
509Example: This is the most typical usage. 544Example: This is the most typical usage.
510 545
511 if (!ev_default_loop (0)) 546 if (!ev_default_loop (0))
512 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 547 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
603 638
604This value can sometimes be useful as a generation counter of sorts (it 639This value can sometimes be useful as a generation counter of sorts (it
605"ticks" the number of loop iterations), as it roughly corresponds with 640"ticks" the number of loop iterations), as it roughly corresponds with
606C<ev_prepare> and C<ev_check> calls. 641C<ev_prepare> and C<ev_check> calls.
607 642
643=item unsigned int ev_loop_depth (loop)
644
645Returns the number of times C<ev_loop> was entered minus the number of
646times C<ev_loop> was exited, in other words, the recursion depth.
647
648Outside C<ev_loop>, this number is zero. In a callback, this number is
649C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
650in which case it is higher.
651
652Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
653etc.), doesn't count as exit.
654
608=item unsigned int ev_backend (loop) 655=item unsigned int ev_backend (loop)
609 656
610Returns one of the C<EVBACKEND_*> flags indicating the event backend in 657Returns one of the C<EVBACKEND_*> flags indicating the event backend in
611use. 658use.
612 659
626 673
627This function is rarely useful, but when some event callback runs for a 674This function is rarely useful, but when some event callback runs for a
628very long time without entering the event loop, updating libev's idea of 675very long time without entering the event loop, updating libev's idea of
629the current time is a good idea. 676the current time is a good idea.
630 677
631See also "The special problem of time updates" in the C<ev_timer> section. 678See also L<The special problem of time updates> in the C<ev_timer> section.
679
680=item ev_suspend (loop)
681
682=item ev_resume (loop)
683
684These two functions suspend and resume a loop, for use when the loop is
685not used for a while and timeouts should not be processed.
686
687A typical use case would be an interactive program such as a game: When
688the user presses C<^Z> to suspend the game and resumes it an hour later it
689would be best to handle timeouts as if no time had actually passed while
690the program was suspended. This can be achieved by calling C<ev_suspend>
691in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
692C<ev_resume> directly afterwards to resume timer processing.
693
694Effectively, all C<ev_timer> watchers will be delayed by the time spend
695between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
696will be rescheduled (that is, they will lose any events that would have
697occured while suspended).
698
699After calling C<ev_suspend> you B<must not> call I<any> function on the
700given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
701without a previous call to C<ev_suspend>.
702
703Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
704event loop time (see C<ev_now_update>).
632 705
633=item ev_loop (loop, int flags) 706=item ev_loop (loop, int flags)
634 707
635Finally, this is it, the event handler. This function usually is called 708Finally, this is it, the event handler. This function usually is called
636after you initialised all your watchers and you want to start handling 709after you initialised all your watchers and you want to start handling
720 793
721If you have a watcher you never unregister that should not keep C<ev_loop> 794If you have a watcher you never unregister that should not keep C<ev_loop>
722from returning, call ev_unref() after starting, and ev_ref() before 795from returning, call ev_unref() after starting, and ev_ref() before
723stopping it. 796stopping it.
724 797
725As an example, libev itself uses this for its internal signal pipe: It is 798As an example, libev itself uses this for its internal signal pipe: It
726not visible to the libev user and should not keep C<ev_loop> from exiting 799is not visible to the libev user and should not keep C<ev_loop> from
727if no event watchers registered by it are active. It is also an excellent 800exiting if no event watchers registered by it are active. It is also an
728way to do this for generic recurring timers or from within third-party 801excellent way to do this for generic recurring timers or from within
729libraries. Just remember to I<unref after start> and I<ref before stop> 802third-party libraries. Just remember to I<unref after start> and I<ref
730(but only if the watcher wasn't active before, or was active before, 803before stop> (but only if the watcher wasn't active before, or was active
731respectively). 804before, respectively. Note also that libev might stop watchers itself
805(e.g. non-repeating timers) in which case you have to C<ev_ref>
806in the callback).
732 807
733Example: Create a signal watcher, but keep it from keeping C<ev_loop> 808Example: Create a signal watcher, but keep it from keeping C<ev_loop>
734running when nothing else is active. 809running when nothing else is active.
735 810
736 ev_signal exitsig; 811 ev_signal exitsig;
765 840
766By setting a higher I<io collect interval> you allow libev to spend more 841By setting a higher I<io collect interval> you allow libev to spend more
767time collecting I/O events, so you can handle more events per iteration, 842time collecting I/O events, so you can handle more events per iteration,
768at the cost of increasing latency. Timeouts (both C<ev_periodic> and 843at the cost of increasing latency. Timeouts (both C<ev_periodic> and
769C<ev_timer>) will be not affected. Setting this to a non-null value will 844C<ev_timer>) will be not affected. Setting this to a non-null value will
770introduce an additional C<ev_sleep ()> call into most loop iterations. 845introduce an additional C<ev_sleep ()> call into most loop iterations. The
846sleep time ensures that libev will not poll for I/O events more often then
847once per this interval, on average.
771 848
772Likewise, by setting a higher I<timeout collect interval> you allow libev 849Likewise, by setting a higher I<timeout collect interval> you allow libev
773to spend more time collecting timeouts, at the expense of increased 850to spend more time collecting timeouts, at the expense of increased
774latency/jitter/inexactness (the watcher callback will be called 851latency/jitter/inexactness (the watcher callback will be called
775later). C<ev_io> watchers will not be affected. Setting this to a non-null 852later). C<ev_io> watchers will not be affected. Setting this to a non-null
777 854
778Many (busy) programs can usually benefit by setting the I/O collect 855Many (busy) programs can usually benefit by setting the I/O collect
779interval to a value near C<0.1> or so, which is often enough for 856interval to a value near C<0.1> or so, which is often enough for
780interactive servers (of course not for games), likewise for timeouts. It 857interactive servers (of course not for games), likewise for timeouts. It
781usually doesn't make much sense to set it to a lower value than C<0.01>, 858usually doesn't make much sense to set it to a lower value than C<0.01>,
782as this approaches the timing granularity of most systems. 859as this approaches the timing granularity of most systems. Note that if
860you do transactions with the outside world and you can't increase the
861parallelity, then this setting will limit your transaction rate (if you
862need to poll once per transaction and the I/O collect interval is 0.01,
863then you can't do more than 100 transations per second).
783 864
784Setting the I<timeout collect interval> can improve the opportunity for 865Setting the I<timeout collect interval> can improve the opportunity for
785saving power, as the program will "bundle" timer callback invocations that 866saving power, as the program will "bundle" timer callback invocations that
786are "near" in time together, by delaying some, thus reducing the number of 867are "near" in time together, by delaying some, thus reducing the number of
787times the process sleeps and wakes up again. Another useful technique to 868times the process sleeps and wakes up again. Another useful technique to
788reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure 869reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
789they fire on, say, one-second boundaries only. 870they fire on, say, one-second boundaries only.
871
872Example: we only need 0.1s timeout granularity, and we wish not to poll
873more often than 100 times per second:
874
875 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
876 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
877
878=item ev_invoke_pending (loop)
879
880This call will simply invoke all pending watchers while resetting their
881pending state. Normally, C<ev_loop> does this automatically when required,
882but when overriding the invoke callback this call comes handy.
883
884=item int ev_pending_count (loop)
885
886Returns the number of pending watchers - zero indicates that no watchers
887are pending.
888
889=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
890
891This overrides the invoke pending functionality of the loop: Instead of
892invoking all pending watchers when there are any, C<ev_loop> will call
893this callback instead. This is useful, for example, when you want to
894invoke the actual watchers inside another context (another thread etc.).
895
896If you want to reset the callback, use C<ev_invoke_pending> as new
897callback.
898
899=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
900
901Sometimes you want to share the same loop between multiple threads. This
902can be done relatively simply by putting mutex_lock/unlock calls around
903each call to a libev function.
904
905However, C<ev_loop> can run an indefinite time, so it is not feasible to
906wait for it to return. One way around this is to wake up the loop via
907C<ev_unloop> and C<av_async_send>, another way is to set these I<release>
908and I<acquire> callbacks on the loop.
909
910When set, then C<release> will be called just before the thread is
911suspended waiting for new events, and C<acquire> is called just
912afterwards.
913
914Ideally, C<release> will just call your mutex_unlock function, and
915C<acquire> will just call the mutex_lock function again.
916
917While event loop modifications are allowed between invocations of
918C<release> and C<acquire> (that's their only purpose after all), no
919modifications done will affect the event loop, i.e. adding watchers will
920have no effect on the set of file descriptors being watched, or the time
921waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it
922to take note of any changes you made.
923
924In theory, threads executing C<ev_loop> will be async-cancel safe between
925invocations of C<release> and C<acquire>.
926
927See also the locking example in the C<THREADS> section later in this
928document.
929
930=item ev_set_userdata (loop, void *data)
931
932=item ev_userdata (loop)
933
934Set and retrieve a single C<void *> associated with a loop. When
935C<ev_set_userdata> has never been called, then C<ev_userdata> returns
936C<0.>
937
938These two functions can be used to associate arbitrary data with a loop,
939and are intended solely for the C<invoke_pending_cb>, C<release> and
940C<acquire> callbacks described above, but of course can be (ab-)used for
941any other purpose as well.
790 942
791=item ev_loop_verify (loop) 943=item ev_loop_verify (loop)
792 944
793This function only does something when C<EV_VERIFY> support has been 945This function only does something when C<EV_VERIFY> support has been
794compiled in, which is the default for non-minimal builds. It tries to go 946compiled in, which is the default for non-minimal builds. It tries to go
920 1072
921=item C<EV_ASYNC> 1073=item C<EV_ASYNC>
922 1074
923The given async watcher has been asynchronously notified (see C<ev_async>). 1075The given async watcher has been asynchronously notified (see C<ev_async>).
924 1076
1077=item C<EV_CUSTOM>
1078
1079Not ever sent (or otherwise used) by libev itself, but can be freely used
1080by libev users to signal watchers (e.g. via C<ev_feed_event>).
1081
925=item C<EV_ERROR> 1082=item C<EV_ERROR>
926 1083
927An unspecified error has occurred, the watcher has been stopped. This might 1084An unspecified error has occurred, the watcher has been stopped. This might
928happen because the watcher could not be properly started because libev 1085happen because the watcher could not be properly started because libev
929ran out of memory, a file descriptor was found to be closed or any other 1086ran out of memory, a file descriptor was found to be closed or any other
1044integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1201integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1045(default: C<-2>). Pending watchers with higher priority will be invoked 1202(default: C<-2>). Pending watchers with higher priority will be invoked
1046before watchers with lower priority, but priority will not keep watchers 1203before watchers with lower priority, but priority will not keep watchers
1047from being executed (except for C<ev_idle> watchers). 1204from being executed (except for C<ev_idle> watchers).
1048 1205
1049This means that priorities are I<only> used for ordering callback
1050invocation after new events have been received. This is useful, for
1051example, to reduce latency after idling, or more often, to bind two
1052watchers on the same event and make sure one is called first.
1053
1054If you need to suppress invocation when higher priority events are pending 1206If you need to suppress invocation when higher priority events are pending
1055you need to look at C<ev_idle> watchers, which provide this functionality. 1207you need to look at C<ev_idle> watchers, which provide this functionality.
1056 1208
1057You I<must not> change the priority of a watcher as long as it is active or 1209You I<must not> change the priority of a watcher as long as it is active or
1058pending. 1210pending.
1059
1060The default priority used by watchers when no priority has been set is
1061always C<0>, which is supposed to not be too high and not be too low :).
1062 1211
1063Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1212Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1064fine, as long as you do not mind that the priority value you query might 1213fine, as long as you do not mind that the priority value you query might
1065or might not have been clamped to the valid range. 1214or might not have been clamped to the valid range.
1215
1216The default priority used by watchers when no priority has been set is
1217always C<0>, which is supposed to not be too high and not be too low :).
1218
1219See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1220priorities.
1066 1221
1067=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1222=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1068 1223
1069Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1224Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1070C<loop> nor C<revents> need to be valid as long as the watcher callback 1225C<loop> nor C<revents> need to be valid as long as the watcher callback
1135 #include <stddef.h> 1290 #include <stddef.h>
1136 1291
1137 static void 1292 static void
1138 t1_cb (EV_P_ ev_timer *w, int revents) 1293 t1_cb (EV_P_ ev_timer *w, int revents)
1139 { 1294 {
1140 struct my_biggy big = (struct my_biggy * 1295 struct my_biggy big = (struct my_biggy *)
1141 (((char *)w) - offsetof (struct my_biggy, t1)); 1296 (((char *)w) - offsetof (struct my_biggy, t1));
1142 } 1297 }
1143 1298
1144 static void 1299 static void
1145 t2_cb (EV_P_ ev_timer *w, int revents) 1300 t2_cb (EV_P_ ev_timer *w, int revents)
1146 { 1301 {
1147 struct my_biggy big = (struct my_biggy * 1302 struct my_biggy big = (struct my_biggy *)
1148 (((char *)w) - offsetof (struct my_biggy, t2)); 1303 (((char *)w) - offsetof (struct my_biggy, t2));
1149 } 1304 }
1305
1306=head2 WATCHER PRIORITY MODELS
1307
1308Many event loops support I<watcher priorities>, which are usually small
1309integers that influence the ordering of event callback invocation
1310between watchers in some way, all else being equal.
1311
1312In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1313description for the more technical details such as the actual priority
1314range.
1315
1316There are two common ways how these these priorities are being interpreted
1317by event loops:
1318
1319In the more common lock-out model, higher priorities "lock out" invocation
1320of lower priority watchers, which means as long as higher priority
1321watchers receive events, lower priority watchers are not being invoked.
1322
1323The less common only-for-ordering model uses priorities solely to order
1324callback invocation within a single event loop iteration: Higher priority
1325watchers are invoked before lower priority ones, but they all get invoked
1326before polling for new events.
1327
1328Libev uses the second (only-for-ordering) model for all its watchers
1329except for idle watchers (which use the lock-out model).
1330
1331The rationale behind this is that implementing the lock-out model for
1332watchers is not well supported by most kernel interfaces, and most event
1333libraries will just poll for the same events again and again as long as
1334their callbacks have not been executed, which is very inefficient in the
1335common case of one high-priority watcher locking out a mass of lower
1336priority ones.
1337
1338Static (ordering) priorities are most useful when you have two or more
1339watchers handling the same resource: a typical usage example is having an
1340C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1341timeouts. Under load, data might be received while the program handles
1342other jobs, but since timers normally get invoked first, the timeout
1343handler will be executed before checking for data. In that case, giving
1344the timer a lower priority than the I/O watcher ensures that I/O will be
1345handled first even under adverse conditions (which is usually, but not
1346always, what you want).
1347
1348Since idle watchers use the "lock-out" model, meaning that idle watchers
1349will only be executed when no same or higher priority watchers have
1350received events, they can be used to implement the "lock-out" model when
1351required.
1352
1353For example, to emulate how many other event libraries handle priorities,
1354you can associate an C<ev_idle> watcher to each such watcher, and in
1355the normal watcher callback, you just start the idle watcher. The real
1356processing is done in the idle watcher callback. This causes libev to
1357continously poll and process kernel event data for the watcher, but when
1358the lock-out case is known to be rare (which in turn is rare :), this is
1359workable.
1360
1361Usually, however, the lock-out model implemented that way will perform
1362miserably under the type of load it was designed to handle. In that case,
1363it might be preferable to stop the real watcher before starting the
1364idle watcher, so the kernel will not have to process the event in case
1365the actual processing will be delayed for considerable time.
1366
1367Here is an example of an I/O watcher that should run at a strictly lower
1368priority than the default, and which should only process data when no
1369other events are pending:
1370
1371 ev_idle idle; // actual processing watcher
1372 ev_io io; // actual event watcher
1373
1374 static void
1375 io_cb (EV_P_ ev_io *w, int revents)
1376 {
1377 // stop the I/O watcher, we received the event, but
1378 // are not yet ready to handle it.
1379 ev_io_stop (EV_A_ w);
1380
1381 // start the idle watcher to ahndle the actual event.
1382 // it will not be executed as long as other watchers
1383 // with the default priority are receiving events.
1384 ev_idle_start (EV_A_ &idle);
1385 }
1386
1387 static void
1388 idle_cb (EV_P_ ev_idle *w, int revents)
1389 {
1390 // actual processing
1391 read (STDIN_FILENO, ...);
1392
1393 // have to start the I/O watcher again, as
1394 // we have handled the event
1395 ev_io_start (EV_P_ &io);
1396 }
1397
1398 // initialisation
1399 ev_idle_init (&idle, idle_cb);
1400 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1401 ev_io_start (EV_DEFAULT_ &io);
1402
1403In the "real" world, it might also be beneficial to start a timer, so that
1404low-priority connections can not be locked out forever under load. This
1405enables your program to keep a lower latency for important connections
1406during short periods of high load, while not completely locking out less
1407important ones.
1150 1408
1151 1409
1152=head1 WATCHER TYPES 1410=head1 WATCHER TYPES
1153 1411
1154This section describes each watcher in detail, but will not repeat 1412This section describes each watcher in detail, but will not repeat
1180descriptors to non-blocking mode is also usually a good idea (but not 1438descriptors to non-blocking mode is also usually a good idea (but not
1181required if you know what you are doing). 1439required if you know what you are doing).
1182 1440
1183If you cannot use non-blocking mode, then force the use of a 1441If you cannot use non-blocking mode, then force the use of a
1184known-to-be-good backend (at the time of this writing, this includes only 1442known-to-be-good backend (at the time of this writing, this includes only
1185C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). 1443C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1444descriptors for which non-blocking operation makes no sense (such as
1445files) - libev doesn't guarentee any specific behaviour in that case.
1186 1446
1187Another thing you have to watch out for is that it is quite easy to 1447Another thing you have to watch out for is that it is quite easy to
1188receive "spurious" readiness notifications, that is your callback might 1448receive "spurious" readiness notifications, that is your callback might
1189be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1449be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1190because there is no data. Not only are some backends known to create a 1450because there is no data. Not only are some backends known to create a
1311year, it will still time out after (roughly) one hour. "Roughly" because 1571year, it will still time out after (roughly) one hour. "Roughly" because
1312detecting time jumps is hard, and some inaccuracies are unavoidable (the 1572detecting time jumps is hard, and some inaccuracies are unavoidable (the
1313monotonic clock option helps a lot here). 1573monotonic clock option helps a lot here).
1314 1574
1315The callback is guaranteed to be invoked only I<after> its timeout has 1575The callback is guaranteed to be invoked only I<after> its timeout has
1316passed, but if multiple timers become ready during the same loop iteration 1576passed (not I<at>, so on systems with very low-resolution clocks this
1317then order of execution is undefined. 1577might introduce a small delay). If multiple timers become ready during the
1578same loop iteration then the ones with earlier time-out values are invoked
1579before ones of the same priority with later time-out values (but this is
1580no longer true when a callback calls C<ev_loop> recursively).
1318 1581
1319=head3 Be smart about timeouts 1582=head3 Be smart about timeouts
1320 1583
1321Many real-world problems involve some kind of timeout, usually for error 1584Many real-world problems involve some kind of timeout, usually for error
1322recovery. A typical example is an HTTP request - if the other side hangs, 1585recovery. A typical example is an HTTP request - if the other side hangs,
1366C<after> argument to C<ev_timer_set>, and only ever use the C<repeat> 1629C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1367member and C<ev_timer_again>. 1630member and C<ev_timer_again>.
1368 1631
1369At start: 1632At start:
1370 1633
1371 ev_timer_init (timer, callback); 1634 ev_init (timer, callback);
1372 timer->repeat = 60.; 1635 timer->repeat = 60.;
1373 ev_timer_again (loop, timer); 1636 ev_timer_again (loop, timer);
1374 1637
1375Each time there is some activity: 1638Each time there is some activity:
1376 1639
1415 else 1678 else
1416 { 1679 {
1417 // callback was invoked, but there was some activity, re-arm 1680 // callback was invoked, but there was some activity, re-arm
1418 // the watcher to fire in last_activity + 60, which is 1681 // the watcher to fire in last_activity + 60, which is
1419 // guaranteed to be in the future, so "again" is positive: 1682 // guaranteed to be in the future, so "again" is positive:
1420 w->again = timeout - now; 1683 w->repeat = timeout - now;
1421 ev_timer_again (EV_A_ w); 1684 ev_timer_again (EV_A_ w);
1422 } 1685 }
1423 } 1686 }
1424 1687
1425To summarise the callback: first calculate the real timeout (defined 1688To summarise the callback: first calculate the real timeout (defined
1438 1701
1439To start the timer, simply initialise the watcher and set C<last_activity> 1702To start the timer, simply initialise the watcher and set C<last_activity>
1440to the current time (meaning we just have some activity :), then call the 1703to the current time (meaning we just have some activity :), then call the
1441callback, which will "do the right thing" and start the timer: 1704callback, which will "do the right thing" and start the timer:
1442 1705
1443 ev_timer_init (timer, callback); 1706 ev_init (timer, callback);
1444 last_activity = ev_now (loop); 1707 last_activity = ev_now (loop);
1445 callback (loop, timer, EV_TIMEOUT); 1708 callback (loop, timer, EV_TIMEOUT);
1446 1709
1447And when there is some activity, simply store the current time in 1710And when there is some activity, simply store the current time in
1448C<last_activity>, no libev calls at all: 1711C<last_activity>, no libev calls at all:
1509 1772
1510If the event loop is suspended for a long time, you can also force an 1773If the event loop is suspended for a long time, you can also force an
1511update of the time returned by C<ev_now ()> by calling C<ev_now_update 1774update of the time returned by C<ev_now ()> by calling C<ev_now_update
1512()>. 1775()>.
1513 1776
1777=head3 The special problems of suspended animation
1778
1779When you leave the server world it is quite customary to hit machines that
1780can suspend/hibernate - what happens to the clocks during such a suspend?
1781
1782Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1783all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1784to run until the system is suspended, but they will not advance while the
1785system is suspended. That means, on resume, it will be as if the program
1786was frozen for a few seconds, but the suspend time will not be counted
1787towards C<ev_timer> when a monotonic clock source is used. The real time
1788clock advanced as expected, but if it is used as sole clocksource, then a
1789long suspend would be detected as a time jump by libev, and timers would
1790be adjusted accordingly.
1791
1792I would not be surprised to see different behaviour in different between
1793operating systems, OS versions or even different hardware.
1794
1795The other form of suspend (job control, or sending a SIGSTOP) will see a
1796time jump in the monotonic clocks and the realtime clock. If the program
1797is suspended for a very long time, and monotonic clock sources are in use,
1798then you can expect C<ev_timer>s to expire as the full suspension time
1799will be counted towards the timers. When no monotonic clock source is in
1800use, then libev will again assume a timejump and adjust accordingly.
1801
1802It might be beneficial for this latter case to call C<ev_suspend>
1803and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1804deterministic behaviour in this case (you can do nothing against
1805C<SIGSTOP>).
1806
1514=head3 Watcher-Specific Functions and Data Members 1807=head3 Watcher-Specific Functions and Data Members
1515 1808
1516=over 4 1809=over 4
1517 1810
1518=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1811=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1541If the timer is started but non-repeating, stop it (as if it timed out). 1834If the timer is started but non-repeating, stop it (as if it timed out).
1542 1835
1543If the timer is repeating, either start it if necessary (with the 1836If the timer is repeating, either start it if necessary (with the
1544C<repeat> value), or reset the running timer to the C<repeat> value. 1837C<repeat> value), or reset the running timer to the C<repeat> value.
1545 1838
1546This sounds a bit complicated, see "Be smart about timeouts", above, for a 1839This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1547usage example. 1840usage example.
1841
1842=item ev_timer_remaining (loop, ev_timer *)
1843
1844Returns the remaining time until a timer fires. If the timer is active,
1845then this time is relative to the current event loop time, otherwise it's
1846the timeout value currently configured.
1847
1848That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1849C<5>. When the timer is started and one second passes, C<ev_timer_remain>
1850will return C<4>. When the timer expires and is restarted, it will return
1851roughly C<7> (likely slightly less as callback invocation takes some time,
1852too), and so on.
1548 1853
1549=item ev_tstamp repeat [read-write] 1854=item ev_tstamp repeat [read-write]
1550 1855
1551The current C<repeat> value. Will be used each time the watcher times out 1856The current C<repeat> value. Will be used each time the watcher times out
1552or C<ev_timer_again> is called, and determines the next timeout (if any), 1857or C<ev_timer_again> is called, and determines the next timeout (if any),
1590=head2 C<ev_periodic> - to cron or not to cron? 1895=head2 C<ev_periodic> - to cron or not to cron?
1591 1896
1592Periodic watchers are also timers of a kind, but they are very versatile 1897Periodic watchers are also timers of a kind, but they are very versatile
1593(and unfortunately a bit complex). 1898(and unfortunately a bit complex).
1594 1899
1595Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1900Unlike C<ev_timer>, periodic watchers are not based on real time (or
1596but on wall clock time (absolute time). You can tell a periodic watcher 1901relative time, the physical time that passes) but on wall clock time
1597to trigger after some specific point in time. For example, if you tell a 1902(absolute time, the thing you can read on your calender or clock). The
1598periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 1903difference is that wall clock time can run faster or slower than real
1599+ 10.>, that is, an absolute time not a delay) and then reset your system 1904time, and time jumps are not uncommon (e.g. when you adjust your
1600clock to January of the previous year, then it will take more than year 1905wrist-watch).
1601to trigger the event (unlike an C<ev_timer>, which would still trigger
1602roughly 10 seconds later as it uses a relative timeout).
1603 1906
1907You can tell a periodic watcher to trigger after some specific point
1908in time: for example, if you tell a periodic watcher to trigger "in 10
1909seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1910not a delay) and then reset your system clock to January of the previous
1911year, then it will take a year or more to trigger the event (unlike an
1912C<ev_timer>, which would still trigger roughly 10 seconds after starting
1913it, as it uses a relative timeout).
1914
1604C<ev_periodic>s can also be used to implement vastly more complex timers, 1915C<ev_periodic> watchers can also be used to implement vastly more complex
1605such as triggering an event on each "midnight, local time", or other 1916timers, such as triggering an event on each "midnight, local time", or
1606complicated rules. 1917other complicated rules. This cannot be done with C<ev_timer> watchers, as
1918those cannot react to time jumps.
1607 1919
1608As with timers, the callback is guaranteed to be invoked only when the 1920As with timers, the callback is guaranteed to be invoked only when the
1609time (C<at>) has passed, but if multiple periodic timers become ready 1921point in time where it is supposed to trigger has passed. If multiple
1610during the same loop iteration, then order of execution is undefined. 1922timers become ready during the same loop iteration then the ones with
1923earlier time-out values are invoked before ones with later time-out values
1924(but this is no longer true when a callback calls C<ev_loop> recursively).
1611 1925
1612=head3 Watcher-Specific Functions and Data Members 1926=head3 Watcher-Specific Functions and Data Members
1613 1927
1614=over 4 1928=over 4
1615 1929
1616=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1930=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1617 1931
1618=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1932=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1619 1933
1620Lots of arguments, lets sort it out... There are basically three modes of 1934Lots of arguments, let's sort it out... There are basically three modes of
1621operation, and we will explain them from simplest to most complex: 1935operation, and we will explain them from simplest to most complex:
1622 1936
1623=over 4 1937=over 4
1624 1938
1625=item * absolute timer (at = time, interval = reschedule_cb = 0) 1939=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1626 1940
1627In this configuration the watcher triggers an event after the wall clock 1941In this configuration the watcher triggers an event after the wall clock
1628time C<at> has passed. It will not repeat and will not adjust when a time 1942time C<offset> has passed. It will not repeat and will not adjust when a
1629jump occurs, that is, if it is to be run at January 1st 2011 then it will 1943time jump occurs, that is, if it is to be run at January 1st 2011 then it
1630only run when the system clock reaches or surpasses this time. 1944will be stopped and invoked when the system clock reaches or surpasses
1945this point in time.
1631 1946
1632=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1947=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1633 1948
1634In this mode the watcher will always be scheduled to time out at the next 1949In this mode the watcher will always be scheduled to time out at the next
1635C<at + N * interval> time (for some integer N, which can also be negative) 1950C<offset + N * interval> time (for some integer N, which can also be
1636and then repeat, regardless of any time jumps. 1951negative) and then repeat, regardless of any time jumps. The C<offset>
1952argument is merely an offset into the C<interval> periods.
1637 1953
1638This can be used to create timers that do not drift with respect to the 1954This can be used to create timers that do not drift with respect to the
1639system clock, for example, here is a C<ev_periodic> that triggers each 1955system clock, for example, here is an C<ev_periodic> that triggers each
1640hour, on the hour: 1956hour, on the hour (with respect to UTC):
1641 1957
1642 ev_periodic_set (&periodic, 0., 3600., 0); 1958 ev_periodic_set (&periodic, 0., 3600., 0);
1643 1959
1644This doesn't mean there will always be 3600 seconds in between triggers, 1960This doesn't mean there will always be 3600 seconds in between triggers,
1645but only that the callback will be called when the system time shows a 1961but only that the callback will be called when the system time shows a
1646full hour (UTC), or more correctly, when the system time is evenly divisible 1962full hour (UTC), or more correctly, when the system time is evenly divisible
1647by 3600. 1963by 3600.
1648 1964
1649Another way to think about it (for the mathematically inclined) is that 1965Another way to think about it (for the mathematically inclined) is that
1650C<ev_periodic> will try to run the callback in this mode at the next possible 1966C<ev_periodic> will try to run the callback in this mode at the next possible
1651time where C<time = at (mod interval)>, regardless of any time jumps. 1967time where C<time = offset (mod interval)>, regardless of any time jumps.
1652 1968
1653For numerical stability it is preferable that the C<at> value is near 1969For numerical stability it is preferable that the C<offset> value is near
1654C<ev_now ()> (the current time), but there is no range requirement for 1970C<ev_now ()> (the current time), but there is no range requirement for
1655this value, and in fact is often specified as zero. 1971this value, and in fact is often specified as zero.
1656 1972
1657Note also that there is an upper limit to how often a timer can fire (CPU 1973Note also that there is an upper limit to how often a timer can fire (CPU
1658speed for example), so if C<interval> is very small then timing stability 1974speed for example), so if C<interval> is very small then timing stability
1659will of course deteriorate. Libev itself tries to be exact to be about one 1975will of course deteriorate. Libev itself tries to be exact to be about one
1660millisecond (if the OS supports it and the machine is fast enough). 1976millisecond (if the OS supports it and the machine is fast enough).
1661 1977
1662=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1978=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1663 1979
1664In this mode the values for C<interval> and C<at> are both being 1980In this mode the values for C<interval> and C<offset> are both being
1665ignored. Instead, each time the periodic watcher gets scheduled, the 1981ignored. Instead, each time the periodic watcher gets scheduled, the
1666reschedule callback will be called with the watcher as first, and the 1982reschedule callback will be called with the watcher as first, and the
1667current time as second argument. 1983current time as second argument.
1668 1984
1669NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1985NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1670ever, or make ANY event loop modifications whatsoever>. 1986or make ANY other event loop modifications whatsoever, unless explicitly
1987allowed by documentation here>.
1671 1988
1672If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1989If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1673it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1990it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1674only event loop modification you are allowed to do). 1991only event loop modification you are allowed to do).
1675 1992
1705a different time than the last time it was called (e.g. in a crond like 2022a different time than the last time it was called (e.g. in a crond like
1706program when the crontabs have changed). 2023program when the crontabs have changed).
1707 2024
1708=item ev_tstamp ev_periodic_at (ev_periodic *) 2025=item ev_tstamp ev_periodic_at (ev_periodic *)
1709 2026
1710When active, returns the absolute time that the watcher is supposed to 2027When active, returns the absolute time that the watcher is supposed
1711trigger next. 2028to trigger next. This is not the same as the C<offset> argument to
2029C<ev_periodic_set>, but indeed works even in interval and manual
2030rescheduling modes.
1712 2031
1713=item ev_tstamp offset [read-write] 2032=item ev_tstamp offset [read-write]
1714 2033
1715When repeating, this contains the offset value, otherwise this is the 2034When repeating, this contains the offset value, otherwise this is the
1716absolute point in time (the C<at> value passed to C<ev_periodic_set>). 2035absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
2036although libev might modify this value for better numerical stability).
1717 2037
1718Can be modified any time, but changes only take effect when the periodic 2038Can be modified any time, but changes only take effect when the periodic
1719timer fires or C<ev_periodic_again> is being called. 2039timer fires or C<ev_periodic_again> is being called.
1720 2040
1721=item ev_tstamp interval [read-write] 2041=item ev_tstamp interval [read-write]
1773Signal watchers will trigger an event when the process receives a specific 2093Signal watchers will trigger an event when the process receives a specific
1774signal one or more times. Even though signals are very asynchronous, libev 2094signal one or more times. Even though signals are very asynchronous, libev
1775will try it's best to deliver signals synchronously, i.e. as part of the 2095will try it's best to deliver signals synchronously, i.e. as part of the
1776normal event processing, like any other event. 2096normal event processing, like any other event.
1777 2097
1778If you want signals asynchronously, just use C<sigaction> as you would 2098If you want signals to be delivered truly asynchronously, just use
1779do without libev and forget about sharing the signal. You can even use 2099C<sigaction> as you would do without libev and forget about sharing
1780C<ev_async> from a signal handler to synchronously wake up an event loop. 2100the signal. You can even use C<ev_async> from a signal handler to
2101synchronously wake up an event loop.
1781 2102
1782You can configure as many watchers as you like per signal. Only when the 2103You can configure as many watchers as you like for the same signal, but
2104only within the same loop, i.e. you can watch for C<SIGINT> in your
2105default loop and for C<SIGIO> in another loop, but you cannot watch for
2106C<SIGINT> in both the default loop and another loop at the same time. At
2107the moment, C<SIGCHLD> is permanently tied to the default loop.
2108
1783first watcher gets started will libev actually register a signal handler 2109When the first watcher gets started will libev actually register something
1784with the kernel (thus it coexists with your own signal handlers as long as 2110with the kernel (thus it coexists with your own signal handlers as long as
1785you don't register any with libev for the same signal). Similarly, when 2111you don't register any with libev for the same signal).
1786the last signal watcher for a signal is stopped, libev will reset the
1787signal handler to SIG_DFL (regardless of what it was set to before).
1788 2112
1789If possible and supported, libev will install its handlers with 2113If possible and supported, libev will install its handlers with
1790C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2114C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1791interrupted. If you have a problem with system calls getting interrupted by 2115not be unduly interrupted. If you have a problem with system calls getting
1792signals you can block all signals in an C<ev_check> watcher and unblock 2116interrupted by signals you can block all signals in an C<ev_check> watcher
1793them in an C<ev_prepare> watcher. 2117and unblock them in an C<ev_prepare> watcher.
2118
2119=head3 The special problem of inheritance over execve
2120
2121Both the signal mask (C<sigprocmask>) and the signal disposition
2122(C<sigaction>) are unspecified after starting a signal watcher (and after
2123stopping it again), that is, libev might or might not block the signal,
2124and might or might not set or restore the installed signal handler.
2125
2126While this does not matter for the signal disposition (libev never
2127sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2128C<execve>), this matters for the signal mask: many programs do not expect
2129many signals to be blocked.
2130
2131This means that before calling C<exec> (from the child) you should reset
2132the signal mask to whatever "default" you expect (all clear is a good
2133choice usually).
1794 2134
1795=head3 Watcher-Specific Functions and Data Members 2135=head3 Watcher-Specific Functions and Data Members
1796 2136
1797=over 4 2137=over 4
1798 2138
1830some child status changes (most typically when a child of yours dies or 2170some child status changes (most typically when a child of yours dies or
1831exits). It is permissible to install a child watcher I<after> the child 2171exits). It is permissible to install a child watcher I<after> the child
1832has been forked (which implies it might have already exited), as long 2172has been forked (which implies it might have already exited), as long
1833as the event loop isn't entered (or is continued from a watcher), i.e., 2173as the event loop isn't entered (or is continued from a watcher), i.e.,
1834forking and then immediately registering a watcher for the child is fine, 2174forking and then immediately registering a watcher for the child is fine,
1835but forking and registering a watcher a few event loop iterations later is 2175but forking and registering a watcher a few event loop iterations later or
1836not. 2176in the next callback invocation is not.
1837 2177
1838Only the default event loop is capable of handling signals, and therefore 2178Only the default event loop is capable of handling signals, and therefore
1839you can only register child watchers in the default event loop. 2179you can only register child watchers in the default event loop.
1840 2180
2181Due to some design glitches inside libev, child watchers will always be
2182handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2183libev)
2184
1841=head3 Process Interaction 2185=head3 Process Interaction
1842 2186
1843Libev grabs C<SIGCHLD> as soon as the default event loop is 2187Libev grabs C<SIGCHLD> as soon as the default event loop is
1844initialised. This is necessary to guarantee proper behaviour even if 2188initialised. This is necessary to guarantee proper behaviour even if the
1845the first child watcher is started after the child exits. The occurrence 2189first child watcher is started after the child exits. The occurrence
1846of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2190of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1847synchronously as part of the event loop processing. Libev always reaps all 2191synchronously as part of the event loop processing. Libev always reaps all
1848children, even ones not watched. 2192children, even ones not watched.
1849 2193
1850=head3 Overriding the Built-In Processing 2194=head3 Overriding the Built-In Processing
1860=head3 Stopping the Child Watcher 2204=head3 Stopping the Child Watcher
1861 2205
1862Currently, the child watcher never gets stopped, even when the 2206Currently, the child watcher never gets stopped, even when the
1863child terminates, so normally one needs to stop the watcher in the 2207child terminates, so normally one needs to stop the watcher in the
1864callback. Future versions of libev might stop the watcher automatically 2208callback. Future versions of libev might stop the watcher automatically
1865when a child exit is detected. 2209when a child exit is detected (calling C<ev_child_stop> twice is not a
2210problem).
1866 2211
1867=head3 Watcher-Specific Functions and Data Members 2212=head3 Watcher-Specific Functions and Data Members
1868 2213
1869=over 4 2214=over 4
1870 2215
2006the process. The exception are C<ev_stat> watchers - those call C<stat 2351the process. The exception are C<ev_stat> watchers - those call C<stat
2007()>, which is a synchronous operation. 2352()>, which is a synchronous operation.
2008 2353
2009For local paths, this usually doesn't matter: unless the system is very 2354For local paths, this usually doesn't matter: unless the system is very
2010busy or the intervals between stat's are large, a stat call will be fast, 2355busy or the intervals between stat's are large, a stat call will be fast,
2011as the path data is suually in memory already (except when starting the 2356as the path data is usually in memory already (except when starting the
2012watcher). 2357watcher).
2013 2358
2014For networked file systems, calling C<stat ()> can block an indefinite 2359For networked file systems, calling C<stat ()> can block an indefinite
2015time due to network issues, and even under good conditions, a stat call 2360time due to network issues, and even under good conditions, a stat call
2016often takes multiple milliseconds. 2361often takes multiple milliseconds.
2173 2518
2174=head3 Watcher-Specific Functions and Data Members 2519=head3 Watcher-Specific Functions and Data Members
2175 2520
2176=over 4 2521=over 4
2177 2522
2178=item ev_idle_init (ev_signal *, callback) 2523=item ev_idle_init (ev_idle *, callback)
2179 2524
2180Initialises and configures the idle watcher - it has no parameters of any 2525Initialises and configures the idle watcher - it has no parameters of any
2181kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2526kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2182believe me. 2527believe me.
2183 2528
2196 // no longer anything immediate to do. 2541 // no longer anything immediate to do.
2197 } 2542 }
2198 2543
2199 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 2544 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2200 ev_idle_init (idle_watcher, idle_cb); 2545 ev_idle_init (idle_watcher, idle_cb);
2201 ev_idle_start (loop, idle_cb); 2546 ev_idle_start (loop, idle_watcher);
2202 2547
2203 2548
2204=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2549=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2205 2550
2206Prepare and check watchers are usually (but not always) used in pairs: 2551Prepare and check watchers are usually (but not always) used in pairs:
2299 struct pollfd fds [nfd]; 2644 struct pollfd fds [nfd];
2300 // actual code will need to loop here and realloc etc. 2645 // actual code will need to loop here and realloc etc.
2301 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2646 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2302 2647
2303 /* the callback is illegal, but won't be called as we stop during check */ 2648 /* the callback is illegal, but won't be called as we stop during check */
2304 ev_timer_init (&tw, 0, timeout * 1e-3); 2649 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2305 ev_timer_start (loop, &tw); 2650 ev_timer_start (loop, &tw);
2306 2651
2307 // create one ev_io per pollfd 2652 // create one ev_io per pollfd
2308 for (int i = 0; i < nfd; ++i) 2653 for (int i = 0; i < nfd; ++i)
2309 { 2654 {
2422some fds have to be watched and handled very quickly (with low latency), 2767some fds have to be watched and handled very quickly (with low latency),
2423and even priorities and idle watchers might have too much overhead. In 2768and even priorities and idle watchers might have too much overhead. In
2424this case you would put all the high priority stuff in one loop and all 2769this case you would put all the high priority stuff in one loop and all
2425the rest in a second one, and embed the second one in the first. 2770the rest in a second one, and embed the second one in the first.
2426 2771
2427As long as the watcher is active, the callback will be invoked every time 2772As long as the watcher is active, the callback will be invoked every
2428there might be events pending in the embedded loop. The callback must then 2773time there might be events pending in the embedded loop. The callback
2429call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2774must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2430their callbacks (you could also start an idle watcher to give the embedded 2775sweep and invoke their callbacks (the callback doesn't need to invoke the
2431loop strictly lower priority for example). You can also set the callback 2776C<ev_embed_sweep> function directly, it could also start an idle watcher
2432to C<0>, in which case the embed watcher will automatically execute the 2777to give the embedded loop strictly lower priority for example).
2433embedded loop sweep.
2434 2778
2435As long as the watcher is started it will automatically handle events. The 2779You can also set the callback to C<0>, in which case the embed watcher
2436callback will be invoked whenever some events have been handled. You can 2780will automatically execute the embedded loop sweep whenever necessary.
2437set the callback to C<0> to avoid having to specify one if you are not
2438interested in that.
2439 2781
2440Also, there have not currently been made special provisions for forking: 2782Fork detection will be handled transparently while the C<ev_embed> watcher
2441when you fork, you not only have to call C<ev_loop_fork> on both loops, 2783is active, i.e., the embedded loop will automatically be forked when the
2442but you will also have to stop and restart any C<ev_embed> watchers 2784embedding loop forks. In other cases, the user is responsible for calling
2443yourself - but you can use a fork watcher to handle this automatically, 2785C<ev_loop_fork> on the embedded loop.
2444and future versions of libev might do just that.
2445 2786
2446Unfortunately, not all backends are embeddable: only the ones returned by 2787Unfortunately, not all backends are embeddable: only the ones returned by
2447C<ev_embeddable_backends> are, which, unfortunately, does not include any 2788C<ev_embeddable_backends> are, which, unfortunately, does not include any
2448portable one. 2789portable one.
2449 2790
2543event loop blocks next and before C<ev_check> watchers are being called, 2884event loop blocks next and before C<ev_check> watchers are being called,
2544and only in the child after the fork. If whoever good citizen calling 2885and only in the child after the fork. If whoever good citizen calling
2545C<ev_default_fork> cheats and calls it in the wrong process, the fork 2886C<ev_default_fork> cheats and calls it in the wrong process, the fork
2546handlers will be invoked, too, of course. 2887handlers will be invoked, too, of course.
2547 2888
2889=head3 The special problem of life after fork - how is it possible?
2890
2891Most uses of C<fork()> consist of forking, then some simple calls to ste
2892up/change the process environment, followed by a call to C<exec()>. This
2893sequence should be handled by libev without any problems.
2894
2895This changes when the application actually wants to do event handling
2896in the child, or both parent in child, in effect "continuing" after the
2897fork.
2898
2899The default mode of operation (for libev, with application help to detect
2900forks) is to duplicate all the state in the child, as would be expected
2901when I<either> the parent I<or> the child process continues.
2902
2903When both processes want to continue using libev, then this is usually the
2904wrong result. In that case, usually one process (typically the parent) is
2905supposed to continue with all watchers in place as before, while the other
2906process typically wants to start fresh, i.e. without any active watchers.
2907
2908The cleanest and most efficient way to achieve that with libev is to
2909simply create a new event loop, which of course will be "empty", and
2910use that for new watchers. This has the advantage of not touching more
2911memory than necessary, and thus avoiding the copy-on-write, and the
2912disadvantage of having to use multiple event loops (which do not support
2913signal watchers).
2914
2915When this is not possible, or you want to use the default loop for
2916other reasons, then in the process that wants to start "fresh", call
2917C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
2918the default loop will "orphan" (not stop) all registered watchers, so you
2919have to be careful not to execute code that modifies those watchers. Note
2920also that in that case, you have to re-register any signal watchers.
2921
2548=head3 Watcher-Specific Functions and Data Members 2922=head3 Watcher-Specific Functions and Data Members
2549 2923
2550=over 4 2924=over 4
2551 2925
2552=item ev_fork_init (ev_signal *, callback) 2926=item ev_fork_init (ev_signal *, callback)
2680an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3054an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2681C<ev_feed_event>, this call is safe to do from other threads, signal or 3055C<ev_feed_event>, this call is safe to do from other threads, signal or
2682similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 3056similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2683section below on what exactly this means). 3057section below on what exactly this means).
2684 3058
3059Note that, as with other watchers in libev, multiple events might get
3060compressed into a single callback invocation (another way to look at this
3061is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
3062reset when the event loop detects that).
3063
2685This call incurs the overhead of a system call only once per loop iteration, 3064This call incurs the overhead of a system call only once per event loop
2686so while the overhead might be noticeable, it doesn't apply to repeated 3065iteration, so while the overhead might be noticeable, it doesn't apply to
2687calls to C<ev_async_send>. 3066repeated calls to C<ev_async_send> for the same event loop.
2688 3067
2689=item bool = ev_async_pending (ev_async *) 3068=item bool = ev_async_pending (ev_async *)
2690 3069
2691Returns a non-zero value when C<ev_async_send> has been called on the 3070Returns a non-zero value when C<ev_async_send> has been called on the
2692watcher but the event has not yet been processed (or even noted) by the 3071watcher but the event has not yet been processed (or even noted) by the
2695C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 3074C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2696the loop iterates next and checks for the watcher to have become active, 3075the loop iterates next and checks for the watcher to have become active,
2697it will reset the flag again. C<ev_async_pending> can be used to very 3076it will reset the flag again. C<ev_async_pending> can be used to very
2698quickly check whether invoking the loop might be a good idea. 3077quickly check whether invoking the loop might be a good idea.
2699 3078
2700Not that this does I<not> check whether the watcher itself is pending, only 3079Not that this does I<not> check whether the watcher itself is pending,
2701whether it has been requested to make this watcher pending. 3080only whether it has been requested to make this watcher pending: there
3081is a time window between the event loop checking and resetting the async
3082notification, and the callback being invoked.
2702 3083
2703=back 3084=back
2704 3085
2705 3086
2706=head1 OTHER FUNCTIONS 3087=head1 OTHER FUNCTIONS
2885 3266
2886 myclass obj; 3267 myclass obj;
2887 ev::io iow; 3268 ev::io iow;
2888 iow.set <myclass, &myclass::io_cb> (&obj); 3269 iow.set <myclass, &myclass::io_cb> (&obj);
2889 3270
3271=item w->set (object *)
3272
3273This is an B<experimental> feature that might go away in a future version.
3274
3275This is a variation of a method callback - leaving out the method to call
3276will default the method to C<operator ()>, which makes it possible to use
3277functor objects without having to manually specify the C<operator ()> all
3278the time. Incidentally, you can then also leave out the template argument
3279list.
3280
3281The C<operator ()> method prototype must be C<void operator ()(watcher &w,
3282int revents)>.
3283
3284See the method-C<set> above for more details.
3285
3286Example: use a functor object as callback.
3287
3288 struct myfunctor
3289 {
3290 void operator() (ev::io &w, int revents)
3291 {
3292 ...
3293 }
3294 }
3295
3296 myfunctor f;
3297
3298 ev::io w;
3299 w.set (&f);
3300
2890=item w->set<function> (void *data = 0) 3301=item w->set<function> (void *data = 0)
2891 3302
2892Also sets a callback, but uses a static method or plain function as 3303Also sets a callback, but uses a static method or plain function as
2893callback. The optional C<data> argument will be stored in the watcher's 3304callback. The optional C<data> argument will be stored in the watcher's
2894C<data> member and is free for you to use. 3305C<data> member and is free for you to use.
2980L<http://software.schmorp.de/pkg/EV>. 3391L<http://software.schmorp.de/pkg/EV>.
2981 3392
2982=item Python 3393=item Python
2983 3394
2984Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3395Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2985seems to be quite complete and well-documented. Note, however, that the 3396seems to be quite complete and well-documented.
2986patch they require for libev is outright dangerous as it breaks the ABI
2987for everybody else, and therefore, should never be applied in an installed
2988libev (if python requires an incompatible ABI then it needs to embed
2989libev).
2990 3397
2991=item Ruby 3398=item Ruby
2992 3399
2993Tony Arcieri has written a ruby extension that offers access to a subset 3400Tony Arcieri has written a ruby extension that offers access to a subset
2994of the libev API and adds file handle abstractions, asynchronous DNS and 3401of the libev API and adds file handle abstractions, asynchronous DNS and
2995more on top of it. It can be found via gem servers. Its homepage is at 3402more on top of it. It can be found via gem servers. Its homepage is at
2996L<http://rev.rubyforge.org/>. 3403L<http://rev.rubyforge.org/>.
2997 3404
3405Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3406makes rev work even on mingw.
3407
3408=item Haskell
3409
3410A haskell binding to libev is available at
3411L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3412
2998=item D 3413=item D
2999 3414
3000Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3415Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3001be found at L<http://proj.llucax.com.ar/wiki/evd>. 3416be found at L<http://proj.llucax.com.ar/wiki/evd>.
3002 3417
3003=item Ocaml 3418=item Ocaml
3004 3419
3005Erkki Seppala has written Ocaml bindings for libev, to be found at 3420Erkki Seppala has written Ocaml bindings for libev, to be found at
3006L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3421L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3422
3423=item Lua
3424
3425Brian Maher has written a partial interface to libev
3426for lua (only C<ev_io> and C<ev_timer>), to be found at
3427L<http://github.com/brimworks/lua-ev>.
3007 3428
3008=back 3429=back
3009 3430
3010 3431
3011=head1 MACRO MAGIC 3432=head1 MACRO MAGIC
3178keeps libev from including F<config.h>, and it also defines dummy 3599keeps libev from including F<config.h>, and it also defines dummy
3179implementations for some libevent functions (such as logging, which is not 3600implementations for some libevent functions (such as logging, which is not
3180supported). It will also not define any of the structs usually found in 3601supported). It will also not define any of the structs usually found in
3181F<event.h> that are not directly supported by the libev core alone. 3602F<event.h> that are not directly supported by the libev core alone.
3182 3603
3604In standalone mode, libev will still try to automatically deduce the
3605configuration, but has to be more conservative.
3606
3183=item EV_USE_MONOTONIC 3607=item EV_USE_MONOTONIC
3184 3608
3185If defined to be C<1>, libev will try to detect the availability of the 3609If defined to be C<1>, libev will try to detect the availability of the
3186monotonic clock option at both compile time and runtime. Otherwise no use 3610monotonic clock option at both compile time and runtime. Otherwise no
3187of the monotonic clock option will be attempted. If you enable this, you 3611use of the monotonic clock option will be attempted. If you enable this,
3188usually have to link against librt or something similar. Enabling it when 3612you usually have to link against librt or something similar. Enabling it
3189the functionality isn't available is safe, though, although you have 3613when the functionality isn't available is safe, though, although you have
3190to make sure you link against any libraries where the C<clock_gettime> 3614to make sure you link against any libraries where the C<clock_gettime>
3191function is hiding in (often F<-lrt>). 3615function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3192 3616
3193=item EV_USE_REALTIME 3617=item EV_USE_REALTIME
3194 3618
3195If defined to be C<1>, libev will try to detect the availability of the 3619If defined to be C<1>, libev will try to detect the availability of the
3196real-time clock option at compile time (and assume its availability at 3620real-time clock option at compile time (and assume its availability
3197runtime if successful). Otherwise no use of the real-time clock option will 3621at runtime if successful). Otherwise no use of the real-time clock
3198be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3622option will be attempted. This effectively replaces C<gettimeofday>
3199(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3623by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3200note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3624correctness. See the note about libraries in the description of
3625C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3626C<EV_USE_CLOCK_SYSCALL>.
3627
3628=item EV_USE_CLOCK_SYSCALL
3629
3630If defined to be C<1>, libev will try to use a direct syscall instead
3631of calling the system-provided C<clock_gettime> function. This option
3632exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3633unconditionally pulls in C<libpthread>, slowing down single-threaded
3634programs needlessly. Using a direct syscall is slightly slower (in
3635theory), because no optimised vdso implementation can be used, but avoids
3636the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3637higher, as it simplifies linking (no need for C<-lrt>).
3201 3638
3202=item EV_USE_NANOSLEEP 3639=item EV_USE_NANOSLEEP
3203 3640
3204If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3641If defined to be C<1>, libev will assume that C<nanosleep ()> is available
3205and will use it for delays. Otherwise it will use C<select ()>. 3642and will use it for delays. Otherwise it will use C<select ()>.
3221 3658
3222=item EV_SELECT_USE_FD_SET 3659=item EV_SELECT_USE_FD_SET
3223 3660
3224If defined to C<1>, then the select backend will use the system C<fd_set> 3661If defined to C<1>, then the select backend will use the system C<fd_set>
3225structure. This is useful if libev doesn't compile due to a missing 3662structure. This is useful if libev doesn't compile due to a missing
3226C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on 3663C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
3227exotic systems. This usually limits the range of file descriptors to some 3664on exotic systems. This usually limits the range of file descriptors to
3228low limit such as 1024 or might have other limitations (winsocket only 3665some low limit such as 1024 or might have other limitations (winsocket
3229allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3666only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
3230influence the size of the C<fd_set> used. 3667configures the maximum size of the C<fd_set>.
3231 3668
3232=item EV_SELECT_IS_WINSOCKET 3669=item EV_SELECT_IS_WINSOCKET
3233 3670
3234When defined to C<1>, the select backend will assume that 3671When defined to C<1>, the select backend will assume that
3235select/socket/connect etc. don't understand file descriptors but 3672select/socket/connect etc. don't understand file descriptors but
3237be used is the winsock select). This means that it will call 3674be used is the winsock select). This means that it will call
3238C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3675C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3239it is assumed that all these functions actually work on fds, even 3676it is assumed that all these functions actually work on fds, even
3240on win32. Should not be defined on non-win32 platforms. 3677on win32. Should not be defined on non-win32 platforms.
3241 3678
3242=item EV_FD_TO_WIN32_HANDLE 3679=item EV_FD_TO_WIN32_HANDLE(fd)
3243 3680
3244If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3681If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3245file descriptors to socket handles. When not defining this symbol (the 3682file descriptors to socket handles. When not defining this symbol (the
3246default), then libev will call C<_get_osfhandle>, which is usually 3683default), then libev will call C<_get_osfhandle>, which is usually
3247correct. In some cases, programs use their own file descriptor management, 3684correct. In some cases, programs use their own file descriptor management,
3248in which case they can provide this function to map fds to socket handles. 3685in which case they can provide this function to map fds to socket handles.
3686
3687=item EV_WIN32_HANDLE_TO_FD(handle)
3688
3689If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3690using the standard C<_open_osfhandle> function. For programs implementing
3691their own fd to handle mapping, overwriting this function makes it easier
3692to do so. This can be done by defining this macro to an appropriate value.
3693
3694=item EV_WIN32_CLOSE_FD(fd)
3695
3696If programs implement their own fd to handle mapping on win32, then this
3697macro can be used to override the C<close> function, useful to unregister
3698file descriptors again. Note that the replacement function has to close
3699the underlying OS handle.
3249 3700
3250=item EV_USE_POLL 3701=item EV_USE_POLL
3251 3702
3252If defined to be C<1>, libev will compile in support for the C<poll>(2) 3703If defined to be C<1>, libev will compile in support for the C<poll>(2)
3253backend. Otherwise it will be enabled on non-win32 platforms. It 3704backend. Otherwise it will be enabled on non-win32 platforms. It
3385defined to be C<0>, then they are not. 3836defined to be C<0>, then they are not.
3386 3837
3387=item EV_MINIMAL 3838=item EV_MINIMAL
3388 3839
3389If you need to shave off some kilobytes of code at the expense of some 3840If you need to shave off some kilobytes of code at the expense of some
3390speed, define this symbol to C<1>. Currently this is used to override some 3841speed (but with the full API), define this symbol to C<1>. Currently this
3391inlining decisions, saves roughly 30% code size on amd64. It also selects a 3842is used to override some inlining decisions, saves roughly 30% code size
3392much smaller 2-heap for timer management over the default 4-heap. 3843on amd64. It also selects a much smaller 2-heap for timer management over
3844the default 4-heap.
3845
3846You can save even more by disabling watcher types you do not need
3847and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
3848(C<-DNDEBUG>) will usually reduce code size a lot.
3849
3850Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3851provide a bare-bones event library. See C<ev.h> for details on what parts
3852of the API are still available, and do not complain if this subset changes
3853over time.
3854
3855=item EV_NSIG
3856
3857The highest supported signal number, +1 (or, the number of
3858signals): Normally, libev tries to deduce the maximum number of signals
3859automatically, but sometimes this fails, in which case it can be
3860specified. Also, using a lower number than detected (C<32> should be
3861good for about any system in existance) can save some memory, as libev
3862statically allocates some 12-24 bytes per signal number.
3393 3863
3394=item EV_PID_HASHSIZE 3864=item EV_PID_HASHSIZE
3395 3865
3396C<ev_child> watchers use a small hash table to distribute workload by 3866C<ev_child> watchers use a small hash table to distribute workload by
3397pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3867pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
3583default loop and triggering an C<ev_async> watcher from the default loop 4053default loop and triggering an C<ev_async> watcher from the default loop
3584watcher callback into the event loop interested in the signal. 4054watcher callback into the event loop interested in the signal.
3585 4055
3586=back 4056=back
3587 4057
4058=head4 THREAD LOCKING EXAMPLE
4059
4060Here is a fictitious example of how to run an event loop in a different
4061thread than where callbacks are being invoked and watchers are
4062created/added/removed.
4063
4064For a real-world example, see the C<EV::Loop::Async> perl module,
4065which uses exactly this technique (which is suited for many high-level
4066languages).
4067
4068The example uses a pthread mutex to protect the loop data, a condition
4069variable to wait for callback invocations, an async watcher to notify the
4070event loop thread and an unspecified mechanism to wake up the main thread.
4071
4072First, you need to associate some data with the event loop:
4073
4074 typedef struct {
4075 mutex_t lock; /* global loop lock */
4076 ev_async async_w;
4077 thread_t tid;
4078 cond_t invoke_cv;
4079 } userdata;
4080
4081 void prepare_loop (EV_P)
4082 {
4083 // for simplicity, we use a static userdata struct.
4084 static userdata u;
4085
4086 ev_async_init (&u->async_w, async_cb);
4087 ev_async_start (EV_A_ &u->async_w);
4088
4089 pthread_mutex_init (&u->lock, 0);
4090 pthread_cond_init (&u->invoke_cv, 0);
4091
4092 // now associate this with the loop
4093 ev_set_userdata (EV_A_ u);
4094 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4095 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4096
4097 // then create the thread running ev_loop
4098 pthread_create (&u->tid, 0, l_run, EV_A);
4099 }
4100
4101The callback for the C<ev_async> watcher does nothing: the watcher is used
4102solely to wake up the event loop so it takes notice of any new watchers
4103that might have been added:
4104
4105 static void
4106 async_cb (EV_P_ ev_async *w, int revents)
4107 {
4108 // just used for the side effects
4109 }
4110
4111The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4112protecting the loop data, respectively.
4113
4114 static void
4115 l_release (EV_P)
4116 {
4117 userdata *u = ev_userdata (EV_A);
4118 pthread_mutex_unlock (&u->lock);
4119 }
4120
4121 static void
4122 l_acquire (EV_P)
4123 {
4124 userdata *u = ev_userdata (EV_A);
4125 pthread_mutex_lock (&u->lock);
4126 }
4127
4128The event loop thread first acquires the mutex, and then jumps straight
4129into C<ev_loop>:
4130
4131 void *
4132 l_run (void *thr_arg)
4133 {
4134 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4135
4136 l_acquire (EV_A);
4137 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4138 ev_loop (EV_A_ 0);
4139 l_release (EV_A);
4140
4141 return 0;
4142 }
4143
4144Instead of invoking all pending watchers, the C<l_invoke> callback will
4145signal the main thread via some unspecified mechanism (signals? pipe
4146writes? C<Async::Interrupt>?) and then waits until all pending watchers
4147have been called (in a while loop because a) spurious wakeups are possible
4148and b) skipping inter-thread-communication when there are no pending
4149watchers is very beneficial):
4150
4151 static void
4152 l_invoke (EV_P)
4153 {
4154 userdata *u = ev_userdata (EV_A);
4155
4156 while (ev_pending_count (EV_A))
4157 {
4158 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4159 pthread_cond_wait (&u->invoke_cv, &u->lock);
4160 }
4161 }
4162
4163Now, whenever the main thread gets told to invoke pending watchers, it
4164will grab the lock, call C<ev_invoke_pending> and then signal the loop
4165thread to continue:
4166
4167 static void
4168 real_invoke_pending (EV_P)
4169 {
4170 userdata *u = ev_userdata (EV_A);
4171
4172 pthread_mutex_lock (&u->lock);
4173 ev_invoke_pending (EV_A);
4174 pthread_cond_signal (&u->invoke_cv);
4175 pthread_mutex_unlock (&u->lock);
4176 }
4177
4178Whenever you want to start/stop a watcher or do other modifications to an
4179event loop, you will now have to lock:
4180
4181 ev_timer timeout_watcher;
4182 userdata *u = ev_userdata (EV_A);
4183
4184 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4185
4186 pthread_mutex_lock (&u->lock);
4187 ev_timer_start (EV_A_ &timeout_watcher);
4188 ev_async_send (EV_A_ &u->async_w);
4189 pthread_mutex_unlock (&u->lock);
4190
4191Note that sending the C<ev_async> watcher is required because otherwise
4192an event loop currently blocking in the kernel will have no knowledge
4193about the newly added timer. By waking up the loop it will pick up any new
4194watchers in the next event loop iteration.
4195
3588=head3 COROUTINES 4196=head3 COROUTINES
3589 4197
3590Libev is very accommodating to coroutines ("cooperative threads"): 4198Libev is very accommodating to coroutines ("cooperative threads"):
3591libev fully supports nesting calls to its functions from different 4199libev fully supports nesting calls to its functions from different
3592coroutines (e.g. you can call C<ev_loop> on the same loop from two 4200coroutines (e.g. you can call C<ev_loop> on the same loop from two
3593different coroutines, and switch freely between both coroutines running the 4201different coroutines, and switch freely between both coroutines running
3594loop, as long as you don't confuse yourself). The only exception is that 4202the loop, as long as you don't confuse yourself). The only exception is
3595you must not do this from C<ev_periodic> reschedule callbacks. 4203that you must not do this from C<ev_periodic> reschedule callbacks.
3596 4204
3597Care has been taken to ensure that libev does not keep local state inside 4205Care has been taken to ensure that libev does not keep local state inside
3598C<ev_loop>, and other calls do not usually allow for coroutine switches as 4206C<ev_loop>, and other calls do not usually allow for coroutine switches as
3599they do not call any callbacks. 4207they do not call any callbacks.
3600 4208
3677way (note also that glib is the slowest event library known to man). 4285way (note also that glib is the slowest event library known to man).
3678 4286
3679There is no supported compilation method available on windows except 4287There is no supported compilation method available on windows except
3680embedding it into other applications. 4288embedding it into other applications.
3681 4289
4290Sensible signal handling is officially unsupported by Microsoft - libev
4291tries its best, but under most conditions, signals will simply not work.
4292
3682Not a libev limitation but worth mentioning: windows apparently doesn't 4293Not a libev limitation but worth mentioning: windows apparently doesn't
3683accept large writes: instead of resulting in a partial write, windows will 4294accept large writes: instead of resulting in a partial write, windows will
3684either accept everything or return C<ENOBUFS> if the buffer is too large, 4295either accept everything or return C<ENOBUFS> if the buffer is too large,
3685so make sure you only write small amounts into your sockets (less than a 4296so make sure you only write small amounts into your sockets (less than a
3686megabyte seems safe, but this apparently depends on the amount of memory 4297megabyte seems safe, but this apparently depends on the amount of memory
3690the abysmal performance of winsockets, using a large number of sockets 4301the abysmal performance of winsockets, using a large number of sockets
3691is not recommended (and not reasonable). If your program needs to use 4302is not recommended (and not reasonable). If your program needs to use
3692more than a hundred or so sockets, then likely it needs to use a totally 4303more than a hundred or so sockets, then likely it needs to use a totally
3693different implementation for windows, as libev offers the POSIX readiness 4304different implementation for windows, as libev offers the POSIX readiness
3694notification model, which cannot be implemented efficiently on windows 4305notification model, which cannot be implemented efficiently on windows
3695(Microsoft monopoly games). 4306(due to Microsoft monopoly games).
3696 4307
3697A typical way to use libev under windows is to embed it (see the embedding 4308A typical way to use libev under windows is to embed it (see the embedding
3698section for details) and use the following F<evwrap.h> header file instead 4309section for details) and use the following F<evwrap.h> header file instead
3699of F<ev.h>: 4310of F<ev.h>:
3700 4311
3736 4347
3737Early versions of winsocket's select only supported waiting for a maximum 4348Early versions of winsocket's select only supported waiting for a maximum
3738of C<64> handles (probably owning to the fact that all windows kernels 4349of C<64> handles (probably owning to the fact that all windows kernels
3739can only wait for C<64> things at the same time internally; Microsoft 4350can only wait for C<64> things at the same time internally; Microsoft
3740recommends spawning a chain of threads and wait for 63 handles and the 4351recommends spawning a chain of threads and wait for 63 handles and the
3741previous thread in each. Great). 4352previous thread in each. Sounds great!).
3742 4353
3743Newer versions support more handles, but you need to define C<FD_SETSIZE> 4354Newer versions support more handles, but you need to define C<FD_SETSIZE>
3744to some high number (e.g. C<2048>) before compiling the winsocket select 4355to some high number (e.g. C<2048>) before compiling the winsocket select
3745call (which might be in libev or elsewhere, for example, perl does its own 4356call (which might be in libev or elsewhere, for example, perl and many
3746select emulation on windows). 4357other interpreters do their own select emulation on windows).
3747 4358
3748Another limit is the number of file descriptors in the Microsoft runtime 4359Another limit is the number of file descriptors in the Microsoft runtime
3749libraries, which by default is C<64> (there must be a hidden I<64> fetish 4360libraries, which by default is C<64> (there must be a hidden I<64>
3750or something like this inside Microsoft). You can increase this by calling 4361fetish or something like this inside Microsoft). You can increase this
3751C<_setmaxstdio>, which can increase this limit to C<2048> (another 4362by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3752arbitrary limit), but is broken in many versions of the Microsoft runtime 4363(another arbitrary limit), but is broken in many versions of the Microsoft
3753libraries.
3754
3755This might get you to about C<512> or C<2048> sockets (depending on 4364runtime libraries. This might get you to about C<512> or C<2048> sockets
3756windows version and/or the phase of the moon). To get more, you need to 4365(depending on windows version and/or the phase of the moon). To get more,
3757wrap all I/O functions and provide your own fd management, but the cost of 4366you need to wrap all I/O functions and provide your own fd management, but
3758calling select (O(n²)) will likely make this unworkable. 4367the cost of calling select (O(n²)) will likely make this unworkable.
3759 4368
3760=back 4369=back
3761 4370
3762=head2 PORTABILITY REQUIREMENTS 4371=head2 PORTABILITY REQUIREMENTS
3763 4372
3806=item C<double> must hold a time value in seconds with enough accuracy 4415=item C<double> must hold a time value in seconds with enough accuracy
3807 4416
3808The type C<double> is used to represent timestamps. It is required to 4417The type C<double> is used to represent timestamps. It is required to
3809have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4418have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3810enough for at least into the year 4000. This requirement is fulfilled by 4419enough for at least into the year 4000. This requirement is fulfilled by
3811implementations implementing IEEE 754 (basically all existing ones). 4420implementations implementing IEEE 754, which is basically all existing
4421ones. With IEEE 754 doubles, you get microsecond accuracy until at least
44222200.
3812 4423
3813=back 4424=back
3814 4425
3815If you know of other additional requirements drop me a note. 4426If you know of other additional requirements drop me a note.
3816 4427
3884involves iterating over all running async watchers or all signal numbers. 4495involves iterating over all running async watchers or all signal numbers.
3885 4496
3886=back 4497=back
3887 4498
3888 4499
4500=head1 GLOSSARY
4501
4502=over 4
4503
4504=item active
4505
4506A watcher is active as long as it has been started (has been attached to
4507an event loop) but not yet stopped (disassociated from the event loop).
4508
4509=item application
4510
4511In this document, an application is whatever is using libev.
4512
4513=item callback
4514
4515The address of a function that is called when some event has been
4516detected. Callbacks are being passed the event loop, the watcher that
4517received the event, and the actual event bitset.
4518
4519=item callback invocation
4520
4521The act of calling the callback associated with a watcher.
4522
4523=item event
4524
4525A change of state of some external event, such as data now being available
4526for reading on a file descriptor, time having passed or simply not having
4527any other events happening anymore.
4528
4529In libev, events are represented as single bits (such as C<EV_READ> or
4530C<EV_TIMEOUT>).
4531
4532=item event library
4533
4534A software package implementing an event model and loop.
4535
4536=item event loop
4537
4538An entity that handles and processes external events and converts them
4539into callback invocations.
4540
4541=item event model
4542
4543The model used to describe how an event loop handles and processes
4544watchers and events.
4545
4546=item pending
4547
4548A watcher is pending as soon as the corresponding event has been detected,
4549and stops being pending as soon as the watcher will be invoked or its
4550pending status is explicitly cleared by the application.
4551
4552A watcher can be pending, but not active. Stopping a watcher also clears
4553its pending status.
4554
4555=item real time
4556
4557The physical time that is observed. It is apparently strictly monotonic :)
4558
4559=item wall-clock time
4560
4561The time and date as shown on clocks. Unlike real time, it can actually
4562be wrong and jump forwards and backwards, e.g. when the you adjust your
4563clock.
4564
4565=item watcher
4566
4567A data structure that describes interest in certain events. Watchers need
4568to be started (attached to an event loop) before they can receive events.
4569
4570=item watcher invocation
4571
4572The act of calling the callback associated with a watcher.
4573
4574=back
4575
3889=head1 AUTHOR 4576=head1 AUTHOR
3890 4577
3891Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 4578Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3892 4579

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines