osx_write: Add big fat comment on callback btr node.

diff --git a/osx_write.c b/osx_write.c
index 8dcfb4cd1fcc32082abeae34bdff3a23214a2f20..e34f03888c800ba5e157c89a4cc011aa66fc9469 100644 (file)
--- a/osx_write.c
+++ b/osx_write.c
@@ -43,9 +43,28 @@ struct private_osx_write_data {
        unsigned sample_format;
        /** Number of channels of the current audio stream. */
        unsigned channels;
-       /** Serializes access to buffer tree nodes. */
+       /**
+        * Serializes access to buffer tree nodes between the writer and
+        * the callback which runs in a different thread.
+        */
        int mutex;
-       /** The btr node of the callback. */
+       /**
+        * The btr node of the callback.
+        *
+        * Although access to the btr node is serialized between the writer and
+        * the callback via the above mutex, this does not stop other buffer
+        * tree nodes, for example the decoder, to race against the osx
+        * callback.
+        *
+        * However, since all operations on buffer tree nodes are local in the
+        * sense that they only affect one level in the buffer tree (i.e.
+        * parent or child nodes, but not the grandparent or the
+        * grandchildren), we may work around this problem by using another
+        * buffer tree node for the callback.
+        *
+        * The writer grabs the mutex in its post_select method and pushes down
+        * the buffers to the callback node.
+        */
        struct btr_node *callback_btrn;
 };