[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.228 by root, Sat Mar 28 08:22:30 2009 UTC vs.
Revision 1.231 by root, Wed Apr 15 19:35:53 2009 UTC

 This function is rarely useful, but when some event callback runs for a
 very long time without entering the event loop, updating libev's idea of
 the current time is a good idea.
 See also "The special problem of time updates" in the C<ev_timer> section.
+=item ev_suspend (loop)
+=item ev_resume (loop)
+These two functions suspend and resume a loop, for use when the loop is
+not used for a while and timeouts should not be processed.
+A typical use case would be an interactive program such as a game:  When
+the user presses C<^Z> to suspend the game and resumes it an hour later it
+would be best to handle timeouts as if no time had actually passed while
+the program was suspended. This can be achieved by calling C<ev_suspend>
+in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
+C<ev_resume> directly afterwards to resume timer processing.
+Effectively, all C<ev_timer> watchers will be delayed by the time spend
+between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
+will be rescheduled (that is, they will lose any events that would have
+occured while suspended).
+After calling C<ev_suspend> you B<must not> call I<any> function on the
+given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
+without a previous call to C<ev_suspend>.
+Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
+event loop time (see C<ev_now_update>).
 =item ev_loop (loop, int flags)
 Finally, this is it, the event handler. This function usually is called
 after you initialised all your watchers and you want to start handling
 If you have a watcher you never unregister that should not keep C<ev_loop>
 from returning, call ev_unref() after starting, and ev_ref() before
 stopping it.
-As an example, libev itself uses this for its internal signal pipe: It is
+As an example, libev itself uses this for its internal signal pipe: It
-not visible to the libev user and should not keep C<ev_loop> from exiting
+is not visible to the libev user and should not keep C<ev_loop> from
-if no event watchers registered by it are active. It is also an excellent
+exiting if no event watchers registered by it are active. It is also an
-way to do this for generic recurring timers or from within third-party
+excellent way to do this for generic recurring timers or from within
-libraries. Just remember to I<unref after start> and I<ref before stop>
+third-party libraries. Just remember to I<unref after start> and I<ref
-(but only if the watcher wasn't active before, or was active before,
+before stop> (but only if the watcher wasn't active before, or was active
-respectively).
+before, respectively. Note also that libev might stop watchers itself
+(e.g. non-repeating timers) in which case you have to C<ev_ref>
+in the callback).
 Example: Create a signal watcher, but keep it from keeping C<ev_loop>
 running when nothing else is active.
    ev_signal exitsig;
 C<ev_fork>).
 =item C<EV_ASYNC>
 The given async watcher has been asynchronously notified (see C<ev_async>).
+=item C<EV_CUSTOM>
+Not ever sent (or otherwise used) by libev itself, but can be freely used
+by libev users to signal watchers (e.g. via C<ev_feed_event>).
 =item C<EV_ERROR>
 An unspecified error has occurred, the watcher has been stopped. This might
 happen because the watcher could not be properly started because libev
 year, it will still time out after (roughly) one hour. "Roughly" because
 detecting time jumps is hard, and some inaccuracies are unavoidable (the
 monotonic clock option helps a lot here).
 The callback is guaranteed to be invoked only I<after> its timeout has
-passed, but if multiple timers become ready during the same loop iteration
+passed. If multiple timers become ready during the same loop iteration
-then order of execution is undefined.
+then the ones with earlier time-out values are invoked before ones with
+later time-out values (but this is no longer true when a callback calls
+C<ev_loop> recursively).
 =head3 Be smart about timeouts
 Many real-world problems involve some kind of timeout, usually for error
 recovery. A typical example is an HTTP request - if the other side hangs,
 timers, such as triggering an event on each "midnight, local time", or
 other complicated rules. This cannot be done with C<ev_timer> watchers, as
 those cannot react to time jumps.
 As with timers, the callback is guaranteed to be invoked only when the
-point in time where it is supposed to trigger has passed, but if multiple
+point in time where it is supposed to trigger has passed. If multiple
-periodic timers become ready during the same loop iteration, then order of
+timers become ready during the same loop iteration then the ones with
-execution is undefined.
+earlier time-out values are invoked before ones with later time-out values
+(but this is no longer true when a callback calls C<ev_loop> recursively).
 =head3 Watcher-Specific Functions and Data Members
 =over 4

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.228 by root, Sat Mar 28 08:22:30 2009 UTC vs. Revision 1.231 by root, Wed Apr 15 19:35:53 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.228 by root, Sat Mar 28 08:22:30 2009 UTC vs.
Revision 1.231 by root, Wed Apr 15 19:35:53 2009 UTC