… | |
… | |
633 | This function is rarely useful, but when some event callback runs for a |
633 | This function is rarely useful, but when some event callback runs for a |
634 | very long time without entering the event loop, updating libev's idea of |
634 | very long time without entering the event loop, updating libev's idea of |
635 | the current time is a good idea. |
635 | the current time is a good idea. |
636 | |
636 | |
637 | See also "The special problem of time updates" in the C<ev_timer> section. |
637 | See also "The special problem of time updates" in the C<ev_timer> section. |
|
|
638 | |
|
|
639 | =item ev_suspend (loop) |
|
|
640 | |
|
|
641 | =item ev_resume (loop) |
|
|
642 | |
|
|
643 | These two functions suspend and resume a loop, for use when the loop is |
|
|
644 | not used for a while and timeouts should not be processed. |
|
|
645 | |
|
|
646 | A typical use case would be an interactive program such as a game: When |
|
|
647 | the user presses C<^Z> to suspend the game and resumes it an hour later it |
|
|
648 | would be best to handle timeouts as if no time had actually passed while |
|
|
649 | the program was suspended. This can be achieved by calling C<ev_suspend> |
|
|
650 | in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling |
|
|
651 | C<ev_resume> directly afterwards to resume timer processing. |
|
|
652 | |
|
|
653 | Effectively, all C<ev_timer> watchers will be delayed by the time spend |
|
|
654 | between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers |
|
|
655 | will be rescheduled (that is, they will lose any events that would have |
|
|
656 | occured while suspended). |
|
|
657 | |
|
|
658 | After calling C<ev_suspend> you B<must not> call I<any> function on the |
|
|
659 | given loop other than C<ev_resume>, and you B<must not> call C<ev_resume> |
|
|
660 | without a previous call to C<ev_suspend>. |
|
|
661 | |
|
|
662 | Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the |
|
|
663 | event loop time (see C<ev_now_update>). |
638 | |
664 | |
639 | =item ev_loop (loop, int flags) |
665 | =item ev_loop (loop, int flags) |
640 | |
666 | |
641 | Finally, this is it, the event handler. This function usually is called |
667 | Finally, this is it, the event handler. This function usually is called |
642 | after you initialised all your watchers and you want to start handling |
668 | after you initialised all your watchers and you want to start handling |
… | |
… | |
1324 | year, it will still time out after (roughly) one hour. "Roughly" because |
1350 | year, it will still time out after (roughly) one hour. "Roughly" because |
1325 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
1351 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
1326 | monotonic clock option helps a lot here). |
1352 | monotonic clock option helps a lot here). |
1327 | |
1353 | |
1328 | The callback is guaranteed to be invoked only I<after> its timeout has |
1354 | The callback is guaranteed to be invoked only I<after> its timeout has |
1329 | passed, but if multiple timers become ready during the same loop iteration |
1355 | passed. If multiple timers become ready during the same loop iteration |
1330 | then order of execution is undefined. |
1356 | then the ones with earlier time-out values are invoked before ones with |
|
|
1357 | later time-out values (but this is no longer true when a callback calls |
|
|
1358 | C<ev_loop> recursively). |
1331 | |
1359 | |
1332 | =head3 Be smart about timeouts |
1360 | =head3 Be smart about timeouts |
1333 | |
1361 | |
1334 | Many real-world problems involve some kind of timeout, usually for error |
1362 | Many real-world problems involve some kind of timeout, usually for error |
1335 | recovery. A typical example is an HTTP request - if the other side hangs, |
1363 | recovery. A typical example is an HTTP request - if the other side hangs, |
… | |
… | |
1624 | timers, such as triggering an event on each "midnight, local time", or |
1652 | timers, such as triggering an event on each "midnight, local time", or |
1625 | other complicated rules. This cannot be done with C<ev_timer> watchers, as |
1653 | other complicated rules. This cannot be done with C<ev_timer> watchers, as |
1626 | those cannot react to time jumps. |
1654 | those cannot react to time jumps. |
1627 | |
1655 | |
1628 | As with timers, the callback is guaranteed to be invoked only when the |
1656 | As with timers, the callback is guaranteed to be invoked only when the |
1629 | point in time where it is supposed to trigger has passed, but if multiple |
1657 | point in time where it is supposed to trigger has passed. If multiple |
1630 | periodic timers become ready during the same loop iteration, then order of |
1658 | timers become ready during the same loop iteration then the ones with |
1631 | execution is undefined. |
1659 | earlier time-out values are invoked before ones with later time-out values |
|
|
1660 | (but this is no longer true when a callback calls C<ev_loop> recursively). |
1632 | |
1661 | |
1633 | =head3 Watcher-Specific Functions and Data Members |
1662 | =head3 Watcher-Specific Functions and Data Members |
1634 | |
1663 | |
1635 | =over 4 |
1664 | =over 4 |
1636 | |
1665 | |