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.232 by root, Thu Apr 16 06:17:26 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
… …
1057integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1083integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1058(default: C<-2>). Pending watchers with higher priority will be invoked 1084(default: C<-2>). Pending watchers with higher priority will be invoked
1059before watchers with lower priority, but priority will not keep watchers 1085before watchers with lower priority, but priority will not keep watchers
1060from being executed (except for C<ev_idle> watchers). 1086from being executed (except for C<ev_idle> watchers).
1061 1087
1088See L<
1089
1062This means that priorities are I<only> used for ordering callback 1090This means that priorities are I<only> used for ordering callback
1063invocation after new events have been received. This is useful, for 1091invocation after new events have been received. This is useful, for
1064example, to reduce latency after idling, or more often, to bind two 1092example, to reduce latency after idling, or more often, to bind two
1065watchers on the same event and make sure one is called first. 1093watchers on the same event and make sure one is called first.
1066 1094
… …
1324year, it will still time out after (roughly) one hour. "Roughly" because 1352year, it will still time out after (roughly) one hour. "Roughly" because
1325detecting time jumps is hard, and some inaccuracies are unavoidable (the 1353detecting time jumps is hard, and some inaccuracies are unavoidable (the
1326monotonic clock option helps a lot here). 1354monotonic clock option helps a lot here).
1327 1355
1328The callback is guaranteed to be invoked only I<after> its timeout has 1356The callback is guaranteed to be invoked only I<after> its timeout has
1329passed, but if multiple timers become ready during the same loop iteration 1357passed. If multiple timers become ready during the same loop iteration
1330then order of execution is undefined. 1358then the ones with earlier time-out values are invoked before ones with
1359later time-out values (but this is no longer true when a callback calls
1360C<ev_loop> recursively).
1331 1361
1332=head3 Be smart about timeouts 1362=head3 Be smart about timeouts
1333 1363
1334Many real-world problems involve some kind of timeout, usually for error 1364Many real-world problems involve some kind of timeout, usually for error
1335recovery. A typical example is an HTTP request - if the other side hangs, 1365recovery. A typical example is an HTTP request - if the other side hangs,
… …
1554If the timer is started but non-repeating, stop it (as if it timed out). 1584If the timer is started but non-repeating, stop it (as if it timed out).
1555 1585
1556If the timer is repeating, either start it if necessary (with the 1586If the timer is repeating, either start it if necessary (with the
1557C<repeat> value), or reset the running timer to the C<repeat> value. 1587C<repeat> value), or reset the running timer to the C<repeat> value.
1558 1588
1559This sounds a bit complicated, see "Be smart about timeouts", above, for a 1589This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1560usage example. 1590usage example.
1561 1591
1562=item ev_tstamp repeat [read-write] 1592=item ev_tstamp repeat [read-write]
1563 1593
1564The current C<repeat> value. Will be used each time the watcher times out 1594The current C<repeat> value. Will be used each time the watcher times out
… …
1624timers, such as triggering an event on each "midnight, local time", or 1654timers, such as triggering an event on each "midnight, local time", or
1625other complicated rules. This cannot be done with C<ev_timer> watchers, as 1655other complicated rules. This cannot be done with C<ev_timer> watchers, as
1626those cannot react to time jumps. 1656those cannot react to time jumps.
1627 1657
1628As with timers, the callback is guaranteed to be invoked only when the 1658As 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 1659point in time where it is supposed to trigger has passed. If multiple
1630periodic timers become ready during the same loop iteration, then order of 1660timers become ready during the same loop iteration then the ones with
1631execution is undefined. 1661earlier time-out values are invoked before ones with later time-out values
1662(but this is no longer true when a callback calls C<ev_loop> recursively).
1632 1663
1633=head3 Watcher-Specific Functions and Data Members 1664=head3 Watcher-Specific Functions and Data Members
1634 1665
1635=over 4 1666=over 4
1636 1667

Diff Legend

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