… | |
… | |
604 | |
604 | |
605 | Here are the gory details of what C<ev_loop> does: |
605 | Here are the gory details of what C<ev_loop> does: |
606 | |
606 | |
607 | - Before the first iteration, call any pending watchers. |
607 | - Before the first iteration, call any pending watchers. |
608 | * If EVFLAG_FORKCHECK was used, check for a fork. |
608 | * If EVFLAG_FORKCHECK was used, check for a fork. |
609 | - If a fork was detected, queue and call all fork watchers. |
609 | - If a fork was detected (by any means), queue and call all fork watchers. |
610 | - Queue and call all prepare watchers. |
610 | - Queue and call all prepare watchers. |
611 | - If we have been forked, recreate the kernel state. |
611 | - If we have been forked, detach and recreate the kernel state |
|
|
612 | as to not disturb the other process. |
612 | - Update the kernel state with all outstanding changes. |
613 | - Update the kernel state with all outstanding changes. |
613 | - Update the "event loop time". |
614 | - Update the "event loop time" (ev_now ()). |
614 | - Calculate for how long to sleep or block, if at all |
615 | - Calculate for how long to sleep or block, if at all |
615 | (active idle watchers, EVLOOP_NONBLOCK or not having |
616 | (active idle watchers, EVLOOP_NONBLOCK or not having |
616 | any active watchers at all will result in not sleeping). |
617 | any active watchers at all will result in not sleeping). |
617 | - Sleep if the I/O and timer collect interval say so. |
618 | - Sleep if the I/O and timer collect interval say so. |
618 | - Block the process, waiting for any events. |
619 | - Block the process, waiting for any events. |
619 | - Queue all outstanding I/O (fd) events. |
620 | - Queue all outstanding I/O (fd) events. |
620 | - Update the "event loop time" and do time jump handling. |
621 | - Update the "event loop time" (ev_now ()), and do time jump adjustments. |
621 | - Queue all outstanding timers. |
622 | - Queue all outstanding timers. |
622 | - Queue all outstanding periodics. |
623 | - Queue all outstanding periodics. |
623 | - If no events are pending now, queue all idle watchers. |
624 | - Unless any events are pending now, queue all idle watchers. |
624 | - Queue all check watchers. |
625 | - Queue all check watchers. |
625 | - Call all queued watchers in reverse order (i.e. check watchers first). |
626 | - Call all queued watchers in reverse order (i.e. check watchers first). |
626 | Signals and child watchers are implemented as I/O watchers, and will |
627 | Signals and child watchers are implemented as I/O watchers, and will |
627 | be handled here by queueing them when their watcher gets executed. |
628 | be handled here by queueing them when their watcher gets executed. |
628 | - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
629 | - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
… | |
… | |
633 | anymore. |
634 | anymore. |
634 | |
635 | |
635 | ... queue jobs here, make sure they register event watchers as long |
636 | ... queue jobs here, make sure they register event watchers as long |
636 | ... as they still have work to do (even an idle watcher will do..) |
637 | ... as they still have work to do (even an idle watcher will do..) |
637 | ev_loop (my_loop, 0); |
638 | ev_loop (my_loop, 0); |
638 | ... jobs done. yeah! |
639 | ... jobs done or somebody called unloop. yeah! |
639 | |
640 | |
640 | =item ev_unloop (loop, how) |
641 | =item ev_unloop (loop, how) |
641 | |
642 | |
642 | Can be used to make a call to C<ev_loop> return early (but only after it |
643 | Can be used to make a call to C<ev_loop> return early (but only after it |
643 | has processed all outstanding events). The C<how> argument must be either |
644 | has processed all outstanding events). The C<how> argument must be either |
… | |
… | |
679 | =item ev_set_io_collect_interval (loop, ev_tstamp interval) |
680 | =item ev_set_io_collect_interval (loop, ev_tstamp interval) |
680 | |
681 | |
681 | =item ev_set_timeout_collect_interval (loop, ev_tstamp interval) |
682 | =item ev_set_timeout_collect_interval (loop, ev_tstamp interval) |
682 | |
683 | |
683 | These advanced functions influence the time that libev will spend waiting |
684 | These advanced functions influence the time that libev will spend waiting |
684 | for events. Both are by default C<0>, meaning that libev will try to |
685 | for events. Both time intervals are by default C<0>, meaning that libev |
685 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
686 | will try to invoke timer/periodic callbacks and I/O callbacks with minimum |
|
|
687 | latency. |
686 | |
688 | |
687 | Setting these to a higher value (the C<interval> I<must> be >= C<0>) |
689 | Setting these to a higher value (the C<interval> I<must> be >= C<0>) |
688 | allows libev to delay invocation of I/O and timer/periodic callbacks to |
690 | allows libev to delay invocation of I/O and timer/periodic callbacks |
689 | increase efficiency of loop iterations. |
691 | to increase efficiency of loop iterations (or to increase power-saving |
|
|
692 | opportunities). |
690 | |
693 | |
691 | The background is that sometimes your program runs just fast enough to |
694 | The background is that sometimes your program runs just fast enough to |
692 | handle one (or very few) event(s) per loop iteration. While this makes |
695 | handle one (or very few) event(s) per loop iteration. While this makes |
693 | the program responsive, it also wastes a lot of CPU time to poll for new |
696 | the program responsive, it also wastes a lot of CPU time to poll for new |
694 | events, especially with backends like C<select ()> which have a high |
697 | events, especially with backends like C<select ()> which have a high |
… | |
… | |
709 | Many (busy) programs can usually benefit by setting the I/O collect |
712 | Many (busy) programs can usually benefit by setting the I/O collect |
710 | interval to a value near C<0.1> or so, which is often enough for |
713 | interval to a value near C<0.1> or so, which is often enough for |
711 | interactive servers (of course not for games), likewise for timeouts. It |
714 | interactive servers (of course not for games), likewise for timeouts. It |
712 | usually doesn't make much sense to set it to a lower value than C<0.01>, |
715 | usually doesn't make much sense to set it to a lower value than C<0.01>, |
713 | as this approaches the timing granularity of most systems. |
716 | as this approaches the timing granularity of most systems. |
|
|
717 | |
|
|
718 | Setting the I<timeout collect interval> can improve the opportunity for |
|
|
719 | saving power, as the program will "bundle" timer callback invocations that |
|
|
720 | are "near" in time together, by delaying some, thus reducing the number of |
|
|
721 | times the process sleeps and wakes up again. Another useful technique to |
|
|
722 | reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure |
|
|
723 | they fire on, say, one-second boundaries only. |
714 | |
724 | |
715 | =item ev_loop_verify (loop) |
725 | =item ev_loop_verify (loop) |
716 | |
726 | |
717 | This function only does something when C<EV_VERIFY> support has been |
727 | This function only does something when C<EV_VERIFY> support has been |
718 | compiled in. It tries to go through all internal structures and checks |
728 | compiled in. It tries to go through all internal structures and checks |
… | |
… | |
1124 | C<EVBACKEND_POLL>. |
1134 | C<EVBACKEND_POLL>. |
1125 | |
1135 | |
1126 | =head3 The special problem of SIGPIPE |
1136 | =head3 The special problem of SIGPIPE |
1127 | |
1137 | |
1128 | While not really specific to libev, it is easy to forget about SIGPIPE: |
1138 | While not really specific to libev, it is easy to forget about SIGPIPE: |
1129 | when reading from a pipe whose other end has been closed, your program |
1139 | when writing to a pipe whose other end has been closed, your program gets |
1130 | gets send a SIGPIPE, which, by default, aborts your program. For most |
1140 | send a SIGPIPE, which, by default, aborts your program. For most programs |
1131 | programs this is sensible behaviour, for daemons, this is usually |
1141 | this is sensible behaviour, for daemons, this is usually undesirable. |
1132 | undesirable. |
|
|
1133 | |
1142 | |
1134 | So when you encounter spurious, unexplained daemon exits, make sure you |
1143 | So when you encounter spurious, unexplained daemon exits, make sure you |
1135 | ignore SIGPIPE (and maybe make sure you log the exit status of your daemon |
1144 | ignore SIGPIPE (and maybe make sure you log the exit status of your daemon |
1136 | somewhere, as that would have given you a big clue). |
1145 | somewhere, as that would have given you a big clue). |
1137 | |
1146 | |
… | |
… | |
1188 | times out after an hour and you reset your system clock to January last |
1197 | times out after an hour and you reset your system clock to January last |
1189 | year, it will still time out after (roughly) and hour. "Roughly" because |
1198 | year, it will still time out after (roughly) and hour. "Roughly" because |
1190 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
1199 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
1191 | monotonic clock option helps a lot here). |
1200 | monotonic clock option helps a lot here). |
1192 | |
1201 | |
|
|
1202 | The callback is guaranteed to be invoked only after its timeout has passed, |
|
|
1203 | but if multiple timers become ready during the same loop iteration then |
|
|
1204 | order of execution is undefined. |
|
|
1205 | |
|
|
1206 | =head3 The special problem of time updates |
|
|
1207 | |
|
|
1208 | Requesting the current time is a costly operation (it usually takes at |
|
|
1209 | least two syscalls): EV therefore updates it's idea of the current time |
|
|
1210 | only before and after C<ev_loop> polls for new events, which causes the |
|
|
1211 | difference between C<ev_now ()> and C<ev_time ()>. |
|
|
1212 | |
1193 | The relative timeouts are calculated relative to the C<ev_now ()> |
1213 | The relative timeouts are calculated relative to the C<ev_now ()> |
1194 | time. This is usually the right thing as this timestamp refers to the time |
1214 | time. This is usually the right thing as this timestamp refers to the time |
1195 | of the event triggering whatever timeout you are modifying/starting. If |
1215 | of the event triggering whatever timeout you are modifying/starting. If |
1196 | you suspect event processing to be delayed and you I<need> to base the timeout |
1216 | you suspect event processing to be delayed and you I<need> to base the |
1197 | on the current time, use something like this to adjust for this: |
1217 | timeout on the current time, use something like this to adjust for this: |
1198 | |
1218 | |
1199 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
1219 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
1200 | |
|
|
1201 | The callback is guaranteed to be invoked only after its timeout has passed, |
|
|
1202 | but if multiple timers become ready during the same loop iteration then |
|
|
1203 | order of execution is undefined. |
|
|
1204 | |
1220 | |
1205 | =head3 Watcher-Specific Functions and Data Members |
1221 | =head3 Watcher-Specific Functions and Data Members |
1206 | |
1222 | |
1207 | =over 4 |
1223 | =over 4 |
1208 | |
1224 | |
… | |
… | |
1559 | handler, you can override it easily by installing your own handler for |
1575 | handler, you can override it easily by installing your own handler for |
1560 | C<SIGCHLD> after initialising the default loop, and making sure the |
1576 | C<SIGCHLD> after initialising the default loop, and making sure the |
1561 | default loop never gets destroyed. You are encouraged, however, to use an |
1577 | default loop never gets destroyed. You are encouraged, however, to use an |
1562 | event-based approach to child reaping and thus use libev's support for |
1578 | event-based approach to child reaping and thus use libev's support for |
1563 | that, so other libev users can use C<ev_child> watchers freely. |
1579 | that, so other libev users can use C<ev_child> watchers freely. |
|
|
1580 | |
|
|
1581 | =head3 Stopping the Child Watcher |
|
|
1582 | |
|
|
1583 | Currently, the child watcher never gets stopped, even when the |
|
|
1584 | child terminates, so normally one needs to stop the watcher in the |
|
|
1585 | callback. Future versions of libev might stop the watcher automatically |
|
|
1586 | when a child exit is detected. |
1564 | |
1587 | |
1565 | =head3 Watcher-Specific Functions and Data Members |
1588 | =head3 Watcher-Specific Functions and Data Members |
1566 | |
1589 | |
1567 | =over 4 |
1590 | =over 4 |
1568 | |
1591 | |
… | |
… | |
1662 | will be no polling. |
1685 | will be no polling. |
1663 | |
1686 | |
1664 | =head3 ABI Issues (Largefile Support) |
1687 | =head3 ABI Issues (Largefile Support) |
1665 | |
1688 | |
1666 | Libev by default (unless the user overrides this) uses the default |
1689 | Libev by default (unless the user overrides this) uses the default |
1667 | compilation environment, which means that on systems with optionally |
1690 | compilation environment, which means that on systems with large file |
1668 | disabled large file support, you get the 32 bit version of the stat |
1691 | support disabled by default, you get the 32 bit version of the stat |
1669 | structure. When using the library from programs that change the ABI to |
1692 | structure. When using the library from programs that change the ABI to |
1670 | use 64 bit file offsets the programs will fail. In that case you have to |
1693 | use 64 bit file offsets the programs will fail. In that case you have to |
1671 | compile libev with the same flags to get binary compatibility. This is |
1694 | compile libev with the same flags to get binary compatibility. This is |
1672 | obviously the case with any flags that change the ABI, but the problem is |
1695 | obviously the case with any flags that change the ABI, but the problem is |
1673 | most noticeably with ev_stat and large file support. |
1696 | most noticeably disabled with ev_stat and large file support. |
|
|
1697 | |
|
|
1698 | The solution for this is to lobby your distribution maker to make large |
|
|
1699 | file interfaces available by default (as e.g. FreeBSD does) and not |
|
|
1700 | optional. Libev cannot simply switch on large file support because it has |
|
|
1701 | to exchange stat structures with application programs compiled using the |
|
|
1702 | default compilation environment. |
1674 | |
1703 | |
1675 | =head3 Inotify |
1704 | =head3 Inotify |
1676 | |
1705 | |
1677 | When C<inotify (7)> support has been compiled into libev (generally only |
1706 | When C<inotify (7)> support has been compiled into libev (generally only |
1678 | available on Linux) and present at runtime, it will be used to speed up |
1707 | available on Linux) and present at runtime, it will be used to speed up |
… | |
… | |
2626 | libev. EV is developed together with libev. Apart from the EV core module, |
2655 | libev. EV is developed together with libev. Apart from the EV core module, |
2627 | there are additional modules that implement libev-compatible interfaces |
2656 | there are additional modules that implement libev-compatible interfaces |
2628 | to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the |
2657 | to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the |
2629 | C<libglib> event core (C<Glib::EV> and C<EV::Glib>). |
2658 | C<libglib> event core (C<Glib::EV> and C<EV::Glib>). |
2630 | |
2659 | |
2631 | It can be found and installed via CPAN, its homepage is found at |
2660 | It can be found and installed via CPAN, its homepage is at |
2632 | L<http://software.schmorp.de/pkg/EV>. |
2661 | L<http://software.schmorp.de/pkg/EV>. |
|
|
2662 | |
|
|
2663 | =item Python |
|
|
2664 | |
|
|
2665 | Python bindings can be found at L<http://code.google.com/p/pyev/>. It |
|
|
2666 | seems to be quite complete and well-documented. Note, however, that the |
|
|
2667 | patch they require for libev is outright dangerous as it breaks the ABI |
|
|
2668 | for everybody else, and therefore, should never be applied in an installed |
|
|
2669 | libev (if python requires an incompatible ABI then it needs to embed |
|
|
2670 | libev). |
2633 | |
2671 | |
2634 | =item Ruby |
2672 | =item Ruby |
2635 | |
2673 | |
2636 | Tony Arcieri has written a ruby extension that offers access to a subset |
2674 | Tony Arcieri has written a ruby extension that offers access to a subset |
2637 | of the libev API and adds file handle abstractions, asynchronous DNS and |
2675 | of the libev API and adds file handle abstractions, asynchronous DNS and |
… | |
… | |
2639 | L<http://rev.rubyforge.org/>. |
2677 | L<http://rev.rubyforge.org/>. |
2640 | |
2678 | |
2641 | =item D |
2679 | =item D |
2642 | |
2680 | |
2643 | Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to |
2681 | Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to |
2644 | be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>. |
2682 | be found at L<http://proj.llucax.com.ar/wiki/evd>. |
2645 | |
2683 | |
2646 | =back |
2684 | =back |
2647 | |
2685 | |
2648 | |
2686 | |
2649 | =head1 MACRO MAGIC |
2687 | =head1 MACRO MAGIC |
… | |
… | |
3173 | parallel from multiple threads, calls with the same loop parameter must be |
3211 | parallel from multiple threads, calls with the same loop parameter must be |
3174 | done serially (but can be done from different threads, as long as only one |
3212 | done serially (but can be done from different threads, as long as only one |
3175 | thread ever is inside a call at any point in time, e.g. by using a mutex |
3213 | thread ever is inside a call at any point in time, e.g. by using a mutex |
3176 | per loop). |
3214 | per loop). |
3177 | |
3215 | |
3178 | If you want to know which design is best for your problem, then I cannot |
3216 | If you want to know which design (one loop, locking, or multiple loops |
3179 | help you but by giving some generic advice: |
3217 | without or something else still) is best for your problem, then I cannot |
|
|
3218 | help you. I can give some generic advice however: |
3180 | |
3219 | |
3181 | =over 4 |
3220 | =over 4 |
3182 | |
3221 | |
3183 | =item * most applications have a main thread: use the default libev loop |
3222 | =item * most applications have a main thread: use the default libev loop |
3184 | in that thread, or create a separate thread running only the default loop. |
3223 | in that thread, or create a separate thread running only the default loop. |
… | |
… | |
3317 | more than a hundred or so sockets, then likely it needs to use a totally |
3356 | more than a hundred or so sockets, then likely it needs to use a totally |
3318 | different implementation for windows, as libev offers the POSIX readiness |
3357 | different implementation for windows, as libev offers the POSIX readiness |
3319 | notification model, which cannot be implemented efficiently on windows |
3358 | notification model, which cannot be implemented efficiently on windows |
3320 | (Microsoft monopoly games). |
3359 | (Microsoft monopoly games). |
3321 | |
3360 | |
|
|
3361 | A typical way to use libev under windows is to embed it (see the embedding |
|
|
3362 | section for details) and use the following F<evwrap.h> header file instead |
|
|
3363 | of F<ev.h>: |
|
|
3364 | |
|
|
3365 | #define EV_STANDALONE /* keeps ev from requiring config.h */ |
|
|
3366 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
|
|
3367 | |
|
|
3368 | #include "ev.h" |
|
|
3369 | |
|
|
3370 | And compile the following F<evwrap.c> file into your project (make sure |
|
|
3371 | you do I<not> compile the F<ev.c> or any other embedded soruce files!): |
|
|
3372 | |
|
|
3373 | #include "evwrap.h" |
|
|
3374 | #include "ev.c" |
|
|
3375 | |
3322 | =over 4 |
3376 | =over 4 |
3323 | |
3377 | |
3324 | =item The winsocket select function |
3378 | =item The winsocket select function |
3325 | |
3379 | |
3326 | The winsocket C<select> function doesn't follow POSIX in that it |
3380 | The winsocket C<select> function doesn't follow POSIX in that it |
3327 | requires socket I<handles> and not socket I<file descriptors> (it is |
3381 | requires socket I<handles> and not socket I<file descriptors> (it is |
3328 | also extremely buggy). This makes select very inefficient, and also |
3382 | also extremely buggy). This makes select very inefficient, and also |
3329 | requires a mapping from file descriptors to socket handles. See the |
3383 | requires a mapping from file descriptors to socket handles (the Microsoft |
|
|
3384 | C runtime provides the function C<_open_osfhandle> for this). See the |
3330 | discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and |
3385 | discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and |
3331 | C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info. |
3386 | C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info. |
3332 | |
3387 | |
3333 | The configuration for a "naked" win32 using the Microsoft runtime |
3388 | The configuration for a "naked" win32 using the Microsoft runtime |
3334 | libraries and raw winsocket select is: |
3389 | libraries and raw winsocket select is: |