--- libev/ev.pod 2008/06/03 03:48:10 1.166 +++ libev/ev.pod 2008/07/08 09:49:15 1.171 @@ -606,21 +606,22 @@ - Before the first iteration, call any pending watchers. * If EVFLAG_FORKCHECK was used, check for a fork. - - If a fork was detected, queue and call all fork watchers. + - If a fork was detected (by any means), queue and call all fork watchers. - Queue and call all prepare watchers. - - If we have been forked, recreate the kernel state. + - If we have been forked, detach and recreate the kernel state + as to not disturb the other process. - Update the kernel state with all outstanding changes. - - Update the "event loop time". + - Update the "event loop time" (ev_now ()). - Calculate for how long to sleep or block, if at all (active idle watchers, EVLOOP_NONBLOCK or not having any active watchers at all will result in not sleeping). - Sleep if the I/O and timer collect interval say so. - Block the process, waiting for any events. - Queue all outstanding I/O (fd) events. - - Update the "event loop time" and do time jump handling. + - Update the "event loop time" (ev_now ()), and do time jump adjustments. - Queue all outstanding timers. - Queue all outstanding periodics. - - If no events are pending now, queue all idle watchers. + - Unless any events are pending now, queue all idle watchers. - Queue all check watchers. - Call all queued watchers in reverse order (i.e. check watchers first). Signals and child watchers are implemented as I/O watchers, and will @@ -635,7 +636,7 @@ ... queue jobs here, make sure they register event watchers as long ... as they still have work to do (even an idle watcher will do..) ev_loop (my_loop, 0); - ... jobs done. yeah! + ... jobs done or somebody called unloop. yeah! =item ev_unloop (loop, how) @@ -681,12 +682,14 @@ =item ev_set_timeout_collect_interval (loop, ev_tstamp interval) These advanced functions influence the time that libev will spend waiting -for events. Both are by default C<0>, meaning that libev will try to -invoke timer/periodic callbacks and I/O callbacks with minimum latency. +for events. Both time intervals are by default C<0>, meaning that libev +will try to invoke timer/periodic callbacks and I/O callbacks with minimum +latency. Setting these to a higher value (the C I be >= C<0>) -allows libev to delay invocation of I/O and timer/periodic callbacks to -increase efficiency of loop iterations. +allows libev to delay invocation of I/O and timer/periodic callbacks +to increase efficiency of loop iterations (or to increase power-saving +opportunities). The background is that sometimes your program runs just fast enough to handle one (or very few) event(s) per loop iteration. While this makes @@ -712,6 +715,13 @@ usually doesn't make much sense to set it to a lower value than C<0.01>, as this approaches the timing granularity of most systems. +Setting the I can improve the opportunity for +saving power, as the program will "bundle" timer callback invocations that +are "near" in time together, by delaying some, thus reducing the number of +times the process sleeps and wakes up again. Another useful technique to +reduce iterations/wake-ups is to use C watchers and make sure +they fire on, say, one-second boundaries only. + =item ev_loop_verify (loop) This function only does something when C support has been @@ -1664,13 +1674,19 @@ =head3 ABI Issues (Largefile Support) Libev by default (unless the user overrides this) uses the default -compilation environment, which means that on systems with optionally -disabled large file support, you get the 32 bit version of the stat +compilation environment, which means that on systems with large file +support disabled by default, you get the 32 bit version of the stat structure. When using the library from programs that change the ABI to use 64 bit file offsets the programs will fail. In that case you have to compile libev with the same flags to get binary compatibility. This is obviously the case with any flags that change the ABI, but the problem is -most noticeably with ev_stat and large file support. +most noticeably disabled with ev_stat and large file support. + +The solution for this is to lobby your distribution maker to make large +file interfaces available by default (as e.g. FreeBSD does) and not +optional. Libev cannot simply switch on large file support because it has +to exchange stat structures with application programs compiled using the +default compilation environment. =head3 Inotify @@ -3184,8 +3200,9 @@ thread ever is inside a call at any point in time, e.g. by using a mutex per loop). -If you want to know which design is best for your problem, then I cannot -help you but by giving some generic advice: +If you want to know which design (one loop, locking, or multiple loops +without or something else still) is best for your problem, then I cannot +help you. I can give some generic advice however: =over 4 @@ -3328,6 +3345,21 @@ notification model, which cannot be implemented efficiently on windows (Microsoft monopoly games). +A typical way to use libev under windows is to embed it (see the embedding +section for details) and use the following F header file instead +of F: + + #define EV_STANDALONE /* keeps ev from requiring config.h */ + #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ + + #include "ev.h" + +And compile the following F file into your project (make sure +you do I compile the F or any other embedded soruce files!): + + #include "evwrap.h" + #include "ev.c" + =over 4 =item The winsocket select function @@ -3335,7 +3367,8 @@ The winsocket C