[vlc-devel] [PATCH 2/3] decoder: document vout/aout locking

[Steve Lhomme]

From: Thomas Guillem <thomas at gllm.fr>

---
 src/input/decoder.c | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/input/decoder.c b/src/input/decoder.c
index 48bb18c9719..288059e313c 100644
--- a/src/input/decoder.c
+++ b/src/input/decoder.c
@@ -101,7 +101,26 @@ struct decoder_owner
     vlc_cond_t  wait_acknowledge;
     vlc_cond_t  wait_fifo; /* TODO: merge with wait_acknowledge */
 
-    /* -- These variables need locking on write(only) -- */
+    /*
+     * 3 threads can read/write these output variables, the DecoderThread, the
+     * input thread, and the ModuleThread. The ModuleThread is either the
+     * DecoderThread for synchronous modules or any thread for asynchronous
+     * modules.
+     *
+     * Asynchronous modules are responsible for serializing/locking every
+     * output calls in any thread as long as the decoder_UpdateVideoFormat() or
+     * decoder_NewPicture() calls are not concurrent, cf.
+     * decoder_UpdateVideoFormat() and decoder_NewPicture() notes.
+     *
+     * The ModuleThread is the owner of these variables, it should hold
+     * the lock when writing them but doesn't have to hold it when using them.
+     *
+     * The DecoderThread should always hold the lock when reading/using
+     * aout/vouts.
+     *
+     * The input thread can read these variables in order to stop outputs, when
+     * both ModuleThread and DecoderThread are stopped (from DecoderDelete()).
+     */
     audio_output_t *p_aout;
 
     vout_thread_t   *p_vout;
-- 
2.17.1