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

Comparing libev/ev.pod (file contents):
Revision 1.229 by root, Wed Apr 15 17:49:27 2009 UTC vs.
Revision 1.231 by root, Wed Apr 15 19:35:53 2009 UTC

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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines