From 67232453d4dae4752f290373dff51bb5161eb737 Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@musicpd.org>
Date: Mon, 7 Aug 2017 16:56:41 +0200
Subject: [PATCH] output/Control: more locking information in API docs

---
 src/output/Control.hxx | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/src/output/Control.hxx b/src/output/Control.hxx
index 215ca7c2e..232af6e5d 100644
--- a/src/output/Control.hxx
+++ b/src/output/Control.hxx
@@ -353,6 +353,8 @@ public:
 	}
 
 	/**
+	 * Caller must lock the mutex.
+	 *
 	 * Throws #std::runtime_error on error.
 	 */
 	void InternalOpen2(AudioFormat in_audio_format);
@@ -405,30 +407,37 @@ public:
 
 private:
 	/**
-	 * Runs inside the OutputThread.  Handles exceptions.
+	 * Runs inside the OutputThread.
+	 * Caller must lock the mutex.
+	 * Handles exceptions.
 	 *
 	 * @return true on success
 	 */
 	bool InternalEnable() noexcept;
 
 	/**
-	 * Runs inside the OutputThread.  Handles exceptions.
+	 * Runs inside the OutputThread.
+	 * Caller must lock the mutex.
 	 */
 	void InternalDisable() noexcept;
 
 	/**
-	 * Runs inside the OutputThread.  Handles exceptions.
+	 * Runs inside the OutputThread.
+	 * Caller must lock the mutex.
+	 * Handles exceptions.
 	 */
 	void InternalOpen(AudioFormat audio_format,
 			  const MusicPipe &pipe) noexcept;
 
 	/**
 	 * Runs inside the OutputThread.
+	 * Caller must lock the mutex.
 	 */
 	void InternalClose(bool drain) noexcept;
 
 	/**
 	 * Runs inside the OutputThread.
+	 * Caller must lock the mutex.
 	 */
 	void InternalCheckClose(bool drain) noexcept;
 
@@ -440,8 +449,14 @@ private:
 	 */
 	bool WaitForDelay() noexcept;
 
+	/**
+	 * Caller must lock the mutex.
+	 */
 	bool FillSourceOrClose();
 
+	/**
+	 * Caller must lock the mutex.
+	 */
 	bool PlayChunk() noexcept;
 
 	/**
@@ -449,7 +464,9 @@ private:
 	 * been reached (and no more chunks are queued), or until a
 	 * command is received.
 	 *
-	 * Runs inside the OutputThread.  Handles exceptions.
+	 * Runs inside the OutputThread.
+	 * Caller must lock the mutex.
+	 * Handles exceptions.
 	 *
 	 * @return true if at least one chunk has been available,
 	 * false if the tail of the pipe was already reached
@@ -457,7 +474,9 @@ private:
 	bool InternalPlay() noexcept;
 
 	/**
-	 * Runs inside the OutputThread.  Handles exceptions.
+	 * Runs inside the OutputThread.
+	 * Caller must lock the mutex.
+	 * Handles exceptions.
 	 */
 	void InternalPause() noexcept;