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

Comparing libev/ev.pod (file contents):
Revision 1.254 by root, Tue Jul 14 19:02:43 2009 UTC vs.
Revision 1.257 by root, Wed Jul 15 16:08:24 2009 UTC

 This call will simply invoke all pending watchers while resetting their
 pending state. Normally, C<ev_loop> does this automatically when required,
 but when overriding the invoke callback this call comes handy.
+=item int ev_pending_count (loop)
+Returns the number of pending watchers - zero indicates that no watchers
+are pending.
 =item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
 This overrides the invoke pending functionality of the loop: Instead of
 invoking all pending watchers when there are any, C<ev_loop> will call
 this callback instead. This is useful, for example, when you want to
 If the event loop is suspended for a long time, you can also force an
 update of the time returned by C<ev_now ()> by calling C<ev_now_update
 ()>.
+=head3 The special problems of suspended animation
+When you leave the server world it is quite customary to hit machines that
+can suspend/hibernate - what happens to the clocks during such a suspend?
+Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
+all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
+to run until the system is suspended, but they will not advance while the
+system is suspended. That means, on resume, it will be as if the program
+was frozen for a few seconds, but the suspend time will not be counted
+towards C<ev_timer> when a monotonic clock source is used. The real time
+clock advanced as expected, but if it is used as sole clocksource, then a
+long suspend would be detected as a time jump by libev, and timers would
+be adjusted accordingly.
+I would not be surprised to see different behaviour in different between
+operating systems, OS versions or even different hardware.
+The other form of suspend (job control, or sending a SIGSTOP) will see a
+time jump in the monotonic clocks and the realtime clock. If the program
+is suspended for a very long time, and monotonic clock sources are in use,
+then you can expect C<ev_timer>s to expire as the full suspension time
+will be counted towards the timers. When no monotonic clock source is in
+use, then libev will again assume a timejump and adjust accordingly.
+It might be beneficial for this latter case to call C<ev_suspend>
+and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
+deterministic behaviour in this case (you can do nothing against
+C<SIGSTOP>).
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
 protecting the loop data, respectively.
    static void
    l_release (EV_P)
    {
-     udat *u = ev_userdata (EV_A);
+     userdata *u = ev_userdata (EV_A);
      pthread_mutex_unlock (&u->lock);
    }
    static void
    l_acquire (EV_P)
    {
-     udat *u = ev_userdata (EV_A);
+     userdata *u = ev_userdata (EV_A);
      pthread_mutex_lock (&u->lock);
    }
 The event loop thread first acquires the mutex, and then jumps straight
 into C<ev_loop>:
    }
 Instead of invoking all pending watchers, the C<l_invoke> callback will
 signal the main thread via some unspecified mechanism (signals? pipe
 writes? C<Async::Interrupt>?) and then waits until all pending watchers
-have been called:
+have been called (in a while loop because a) spurious wakeups are possible
+and b) skipping inter-thread-communication when there are no pending
+watchers is very beneficial):
    static void
    l_invoke (EV_P)
    {
-     udat *u = ev_userdata (EV_A);
+     userdata *u = ev_userdata (EV_A);
+     while (ev_pending_count (EV_A))
+       {
-     wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
+         wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
-     pthread_cond_wait (&u->invoke_cv, &u->lock);
+         pthread_cond_wait (&u->invoke_cv, &u->lock);
+       }
    }
 Now, whenever the main thread gets told to invoke pending watchers, it
 will grab the lock, call C<ev_invoke_pending> and then signal the loop
 thread to continue:
    static void
    real_invoke_pending (EV_P)
    {
-     udat *u = ev_userdata (EV_A);
+     userdata *u = ev_userdata (EV_A);
      pthread_mutex_lock (&u->lock);
      ev_invoke_pending (EV_A);
      pthread_cond_signal (&u->invoke_cv);
      pthread_mutex_unlock (&u->lock);
 Whenever you want to start/stop a watcher or do other modifications to an
 event loop, you will now have to lock:
    ev_timer timeout_watcher;
-   udat *u = ev_userdata (EV_A);
+   userdata *u = ev_userdata (EV_A);
    ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
    pthread_mutex_lock (&u->lock);
    ev_timer_start (EV_A_ &timeout_watcher);
 =head3 COROUTINES
 Libev is very accommodating to coroutines ("cooperative threads"):
 libev fully supports nesting calls to its functions from different
 coroutines (e.g. you can call C<ev_loop> on the same loop from two
-different coroutines, and switch freely between both coroutines running the
+different coroutines, and switch freely between both coroutines running
-loop, as long as you don't confuse yourself). The only exception is that
+the loop, as long as you don't confuse yourself). The only exception is
-you must not do this from C<ev_periodic> reschedule callbacks.
+that you must not do this from C<ev_periodic> reschedule callbacks.
 Care has been taken to ensure that libev does not keep local state inside
 C<ev_loop>, and other calls do not usually allow for coroutine switches as
 they do not call any callbacks.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.254 by root, Tue Jul 14 19:02:43 2009 UTC vs. Revision 1.257 by root, Wed Jul 15 16:08:24 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.254 by root, Tue Jul 14 19:02:43 2009 UTC vs.
Revision 1.257 by root, Wed Jul 15 16:08:24 2009 UTC