SDL::MutexRef Struct Reference

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

Inheritance diagram for SDL::MutexRef:

Public Member Functions
void	Lock ()
	Lock the mutex.
void	TryLock ()
	Try to lock a mutex without blocking.
void	Unlock ()
	Unlock the mutex.
constexpr	Resource (T resource={})
	Constructs from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
Public Member Functions inherited from SDL::Resource< SDL_Mutex * >
constexpr	Resource (SDL_Mutex * resource={})
	Constructs from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< SDL_Mutex * > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
constexpr	operator bool () const
	True if contains a valid resource.
constexpr	operator value_type () const
	Converts back to underlying type.
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 const SDL_Mutex *	operator-> () const
	Access to fields.
constexpr SDL_Mutex *	operator-> ()
	Access to fields.

Static Public Member Functions
static void	reset (SDL_Mutex *resource)
	Destroy a mutex created with Mutex.Create().

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_Mutex * >
using	value_type = SDL_Mutex *
	The raw resource type.

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

Member Function Documentation

Lock()

void SDL::MutexRef::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

MutexRef.TryLock

MutexRef.Unlock

reset()

static void SDL::MutexRef::reset ( SDL_Mutex *  resource )

inlinestatic

This function must be called on any mutex that is no longer needed. Failure to destroy a mutex will result in a system memory or resource leak. While it is safe to destroy a mutex that is unlocked, it is not safe to attempt to destroy a locked mutex, and may result in undefined behavior depending on the platform.

Parameters

resource

the mutex to destroy.

Since

This function is available since SDL 3.2.0.

See also

Mutex.Create

TryLock()

void SDL::MutexRef::TryLock ( )

inline

This works just like MutexRef.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

MutexRef.Lock

MutexRef.Unlock

Unlock()

void SDL::MutexRef::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

MutexRef.Lock

MutexRef.TryLock

---

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

• SDL3pp/SDL3pp_mutex.h