osx_write: Add big fat comment on callback btr node.
authorAndre Noll <maan@systemlinux.org>
Thu, 14 Jun 2012 11:26:32 +0000 (13:26 +0200)
committerAndre Noll <maan@systemlinux.org>
Tue, 30 Oct 2012 12:24:32 +0000 (13:24 +0100)
osx_write.c

index 8dcfb4c..e34f038 100644 (file)
@@ -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;
 };