From: Andre Noll <maan@systemlinux.org>
Date: Thu, 14 Jun 2012 11:26:32 +0000 (+0200)
Subject: osx_write: Add big fat comment on callback btr node.
X-Git-Tag: v0.4.12~8^2~3
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=1c6fa9aa4483c491c4edf0129bc26478513324ed;p=paraslash.git

osx_write: Add big fat comment on callback btr node.
---

diff --git a/osx_write.c b/osx_write.c
index 8dcfb4cd..e34f0388 100644
--- 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;
 };