[xiph-commits] r3139 - liboggplay/trunk/plugin

[tahn at svn.annodex.net]

Author: tahn
Date: 2007-06-28 18:39:15 -0700 (Thu, 28 Jun 2007)
New Revision: 3139

Modified:
   liboggplay/trunk/plugin/plugin_gui_mac.c
Log:
Added a nice big comment about play/pause state handling.


Modified: liboggplay/trunk/plugin/plugin_gui_mac.c
===================================================================
--- liboggplay/trunk/plugin/plugin_gui_mac.c	2007-06-29 01:12:11 UTC (rev 3138)
+++ liboggplay/trunk/plugin/plugin_gui_mac.c	2007-06-29 01:39:15 UTC (rev 3139)
@@ -693,6 +693,36 @@
 }
 
 
+/*
+ * Several factors complicate play/pause state handling:
+ *
+ * - We can't just block the display loop to pause (see the comments in
+ *   display_thread() for more info). So, we need to use a "change state"
+ *   semantic; we tell the display thread that it needs to change state and
+ *   let it sort itself out. This means the real paused state is tracked by
+ *   an interval display thread variable.
+ *
+ * - The outside world thinks there are 3 playback states, but there's really
+ *   4: playing, pause, finished and paused while finished. To make it easy to
+ *   handle the various transitions, we keep playing/paused in one flag, and
+ *   finished in the other. The display thread has control over the finished
+ *   flag (because only it knows when end-of-stream is reached).
+ *
+ * - Trying to access the display loop's paused and finished flags from
+ *   gui_get_current_state in the main thread can lead to a race condition.
+ *
+ * - Setting a new movie while paused doesn't start playing, but restarting
+ *   while paused does. However, both of these events flow through
+ *   update_gui_with_new_oggplay, and we can't tell which is which.
+ *   Yes, we could add a flag for it, but it just gets reaaaally messy
+ *   trying to keep track of it all in the display loop.
+ *
+ * So, after all that, it's much easier and safer to keep a "fake" paused
+ * state here in the main thread, and combine that with the real finished
+ * state when reporting to the user. In any case, given the speed at which
+ * the display loop spins, the fake paused state will only lag behind the
+ * real one for a very short time whenever the user calls play or pause.
+ */
 void
 gui_play(void *gui_handle) {