From 6c518525ac7f8fa270882d5fa90efbb3478b0231 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 7 Oct 2026 09:36:12 -0400
Subject: [PATCH] audio: Added notes about the risks of SDL_LockAudioStream vs
the device lock.
Fixes #16362.
---
include/SDL3/SDL_audio.h | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 7c96faac892e5..7fbcd629038e2 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -1847,6 +1847,16 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *st
* As this is just a wrapper over SDL_LockMutex for an internal lock; it has
* all the same attributes (recursive locks are allowed, etc).
*
+ * Note that when the stream's callback runs, SDL is holding both an internal
+ * mutex for the audio device and the stream's lock, in that order. Which is
+ * to say: while this function can protect arbitrary data, calling into some
+ * SDL audio functions while holding this lock may cause a deadlock--the app
+ * holds this lock, and then calls into something that wants to obtain the
+ * device lock, in the opposite order that SDL's audio thread obtained them.
+ * Therefore, best practice is to use this function to protect simple app
+ * data against the audio callback, and be careful about what SDL functions
+ * one calls while locked outside of the callback.
+ *
* \param stream the audio stream to lock.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.