SDL::MutexBase Struct Reference

A means to serialize access to a resource between threads. More...

Inheritance diagram for SDL::MutexBase:

Public Member Functions
	MutexBase ()
	Create a new mutex.
void	Lock ()
	Lock the mutex.
void	TryLock ()
	Try to lock a mutex without blocking.
void	Unlock ()
	Unlock the mutex.
constexpr	Resource (T resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Public Member Functions inherited from SDL::Resource< SDL_Mutex * >
constexpr	Resource (SDL_Mutex * resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Resource &	operator= (const Resource &other)=delete
Resource &	operator= (Resource &&other)=delete
constexpr	operator bool () const
	True if contains a valid resource.
constexpr bool	operator== (const Resource &other) const=default
	Comparison.
constexpr bool	operator== (std::nullopt_t) const
	Comparison.
constexpr bool	operator== (std::nullptr_t) const
	Comparison.
constexpr SDL_Mutex *	get () const
	Return contained resource;.
constexpr SDL_Mutex *	release (SDL_Mutex * newResource={})
	Return contained resource and empties or replace value.
constexpr const SDL_Mutex *	operator-> () const
	Access to fields.
constexpr SDL_Mutex *	operator-> ()
	Access to fields.

Detailed Description

Mutexes (short for "mutual exclusion") are a synchronization primitive that allows exactly one thread to proceed at a time.

Wikipedia has a thorough explanation of the concept:

https://en.wikipedia.org/wiki/Mutex

Since

This struct is available since SDL 3.2.0.

Category:

Resource

See also

Mutex

MutexRef

Constructor & Destructor Documentation

MutexBase()

SDL::MutexBase::MutexBase ( )

inline

All newly-created mutexes begin in the unlocked state.

Calls to MutexBase.Lock() will not return while the mutex is locked by another thread. See MutexBase.TryLock() to attempt to lock without blocking.

SDL mutexes are reentrant.

Postcondition

the initialized and unlocked mutex or nullptr on failure; call GetError() for more information.

Since

This function is available since SDL 3.2.0.

See also

MutexBase.Lock

MutexBase.TryLock

MutexBase.Unlock

Member Function Documentation

Lock()

void SDL::MutexBase::Lock ( )

inline

This will block until the mutex is available, which is to say it is in the unlocked state and the OS has chosen the caller as the next thread to lock it. Of all threads waiting to lock the mutex, only one may do so at a time.

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

This function does not fail; if mutex is nullptr, it will return immediately having locked nothing. If the mutex is valid, this function will always block until it can lock the mutex, and return with it locked.

Since

This function is available since SDL 3.2.0.

See also

MutexBase.TryLock

MutexBase.Unlock

TryLock()

void SDL::MutexBase::TryLock ( )

inline

This works just like MutexBase.Lock(), but if the mutex is not available, this function returns false immediately.

This technique is useful if you need exclusive access to a resource but don't want to wait for it, and will return to it to try again later.

This function returns true if passed a nullptr mutex.

Exceptions

Error

on failure.

Since

This function is available since SDL 3.2.0.

See also

MutexBase.Lock

MutexBase.Unlock

Unlock()

void SDL::MutexBase::Unlock ( )

inline

It is legal for the owning thread to lock an already-locked mutex. It must unlock it the same number of times before it is actually made available for other threads in the system (this is known as a "recursive mutex").

It is illegal to unlock a mutex that has not been locked by the current thread, and doing so results in undefined behavior.

Since

This function is available since SDL 3.2.0.

See also

MutexBase.Lock

MutexBase.TryLock

---

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

• SDL3pp/SDL3pp_mutex.h