MIX_LockMixer(3)

💖 MIX_LockMixer(3) — the SDL_mixer3 glow-up page 💖

okay bestie, so this is a page from the SDL_mixer3 manual, and today's main character is MIX_LockMixer. it's a whole function. it locks a mixer. let's get into it 🎀

---

✨ NAME ✨

MIX_LockMixer — locks a mixer by grabbing its internal mutex. that's it, that's the vibe 🔒

---

🌸 SYNOPSIS 🌸

#include <SDL3_mixer/SDL_mixer.h>

void MIX_LockMixer(MIX_Mixer *mixer);

---

🦋 DESCRIPTION 🦋

so while the mixer is locked, it literally cannot mix more audio or change its internal state from another thread. those other threads? they just block until you unlock again. no cutting the line, periodt 💅

under the hood this function calls SDL_LockMutex(), so every single rule that applies there applies here too: the lock can be recursive, it has to be unlocked the same number of times from the same thread that locked it, etc. iykyk.

now here's the tea: literally just about every SDL_mixer API also locks the mixer while doing its work, and the SDL audio device thread locks it too while actual mixing is going down. so for basic use of this library, your app never has to explicitly lock anything to be thread safe. iconic behaviour honestly 👑

but there are two scenarios where explicitly locking is actually useful:

• your app handed over a callback that the mixing thread might call, and there's some app state that needs protecting against race conditions while changes are being made and mixing is progressing at the same time. any lock works for this, but this one is just conveniently available. convenient queen 🫶
• your app wants to make multiple atomic changes to the mix. for example, to start several tracks at the exact same moment, you'd lock the mixer, call MIX_PlayTrack multiple times, and then unlock again — all the tracks will start mixing on the same sample frame. chef's kiss 😭✨

every call to this function must be paired with a call to MIX_UnlockMixer from the same thread. and yes, it's safe to lock a mixer multiple times — it stays locked until that final matching unlock call. no cap.

⚠️ do NOT hold the lock for significant amounts of time, bestie, or you can cause audio dropouts. just do simple things quickly and unlock again. get in, get out, slay 💀

and lastly: locking a NULL mixer is a safe no-op. no crash, no drama, it just doesn't do anything 🌈

---

🎀 FUNCTION PARAMETERS 🎀

• mixer — the mixer to lock. it may be NULL. yes really, she's flexible like that 💅

---

🔥 THREAD SAFETY 🔥

it is safe to call this function from any thread. go off, girlies 🌸

---

⭐ AVAILABILITY ⭐

this function has been available since SDL_mixer 3.0.0. she's been here, she's been that girl 💜

---

👑 SEE ALSO 👑

• MIX_UnlockMixer(3) — the other half of this situationship, they come as a pair fr fr 🫶

---

and that's the whole page, bestie!! mwah 💖 this little love letter came to you from SDL_mixer, version 3.2.4 — so go lock something (and then unlock it the same number of times, from the same thread, or it's giving ✨undefined consequences✨). byeeee 🎀🦋💅