SDL::MixerLock Class Reference

Lock a mixer by obtaining its internal mutex. More...

Public Member Functions
	MixerLock (MixerRef resource)
	Lock a mixer by obtaining its internal mutex.
	MixerLock (const MixerLock &other)=delete
	Copy constructor.
	MixerLock (MixerLock &&other) noexcept
	Move constructor.
	~MixerLock ()
	Unlock a mixer previously locked by a call to Mixer.Lock().
MixerLock &	operator= (const MixerLock &other)=delete
MixerLock &	operator= (MixerLock &&other) noexcept
	Assignment operator.
constexpr	operator bool () const
	True if not locked.
void	reset ()
	Unlock a mixer previously locked by a call to Mixer.Lock().
MixerRef	resource () const
	Get the reference to locked resource.
void	release ()
	Releases the lock without unlocking.

Detailed Description

Lock a mixer by obtaining its internal mutex.

While locked, the mixer will not be able to mix more audio or change its internal state in another thread. Those other threads will block until the mixer is unlocked again.

Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.

Just about every SDL_mixer API also locks the mixer while doing its work, as does the SDL audio device thread while actual mixing is in progress, so basic use of this library never requires the app to explicitly lock the device to be thread safe. There are two scenarios where this can be useful, however:

• The app has a provided a callback that the mixing thread might call, and there is some app state that needs to be protected against race conditions as changes are made and mixing progresses simultaneously. Any lock can be used for this, but this is a conveniently-available lock.
• The app wants to make multiple, atomic changes to the mix. For example, to start several tracks at the exact same moment, one would lock the mixer, call Track.Play multiple times, and then unlock again; all the tracks will start mixing on the same sample frame.

Each call to this function must be paired with a call to Mixer.Unlock from the same thread. It is safe to lock a mixer multiple times; it remains locked until the final matching unlock call.

Do not lock the mixer for significant amounts of time, or it can cause audio dropouts. Just do simply things quickly and unlock again.

Locking a nullptr mixer is a safe no-op.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL_mixer 3.0.0.

See also

Mixer.Unlock

Constructor & Destructor Documentation

~MixerLock()

SDL::MixerLock::~MixerLock ( )

inline

Unlock a mixer previously locked by a call to Mixer.Lock().

While locked, the mixer will not be able to mix more audio or change its internal state another thread. Those other threads will block until the mixer is unlocked again.

Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.

Unlocking a nullptr mixer is a safe no-op.

Thread safety:

This call must be paired with a previous Mixer.Lock call on the same thread.

Since

This function is available since SDL_mixer 3.0.0.

See also

Mixer.Lock

---

The documentation for this class was generated from the following file:

• SDL3pp/SDL3pp_mixer.h