Burger::RecursiveMutex Class Reference

Class for creating a RecursiveMutex for a critical section of data. More...

Inheritance diagram for Burger::RecursiveMutex:

Public Member Functions
	RecursiveMutex () noexcept
	Initialize the data in the class.
	~RecursiveMutex ()
	Shutdown the data in the class.
void	lock (void) noexcept
	Locks the mutex.
uint_t	try_lock (void) noexcept
	Attempt to lock the mutex.
void	unlock (void) noexcept
	Unlocks the mutex.
void *	get_platform_mutex (void) noexcept
	Access the platform mutex data.
uint32_t	get_threadID (void) const noexcept
	Access the owner thread ID for the SRWLock.
uint32_t	get_count (void) const noexcept
	Get the lock count for a SRWLock.
void	set_state (uint32_t uCount, uint32_t uThreadID) noexcept
	Set the SRWLock state.
uint_t	is_using_SRWlock (void) const noexcept
	Is the RecursiveMutex using Window 7 APIs.

Protected Attributes
uint32_t	m_PlatformMutex [7]
	Platform specific CRITICAL_SECTION or mutex object.

Private Member Functions
	RecursiveMutex (const RecursiveMutex &)=delete
RecursiveMutex &	operator= (const RecursiveMutex &)=delete
	RecursiveMutex (RecursiveMutex &&)=delete
RecursiveMutex &	operator= (RecursiveMutex &&)=delete

Detailed Description

Class for creating a RecursiveMutex for a critical section of data.

---

This synchronization primitive is used to protect shared data from being simultaneously accessed by multiple threads.

This class enforces these rules:

• A calling thread owns the RecursiveMutex after a successfull call to lock() or try_lock() until a call to unlock() is performed.
• When a thread owns a RecursiveMutex, all other threads other than the owning thread will block or return FALSE for try_lock()
• Multiple calls by the owning thread to lock() are allowed. They must be matched by an equal number of calls to unlock().

This is a functional equivalent to std::recursive_mutex

See also

RecursiveMutexStatic and RecursiveMutexLock

Constructor & Destructor Documentation

RecursiveMutex() [1/3]

Burger::RecursiveMutex::RecursiveMutex ( const RecursiveMutex & )

privatedelete

RecursiveMutex() [2/3]

Burger::RecursiveMutex::RecursiveMutex ( RecursiveMutex && )

privatedelete

RecursiveMutex() [3/3]

Burger::RecursiveMutex::RecursiveMutex ( )

noexcept

Initialize the data in the class.

---

Sets up operating system defaults to the data

~RecursiveMutex()

Burger::RecursiveMutex::~RecursiveMutex

(

)

Shutdown the data in the class.

---

Releases the operating system resources allocated by the constructor.

Member Function Documentation

get_count()

uint32_t Burger::RecursiveMutex::get_count ( void ) const

inlinenoexcept

Get the lock count for a SRWLock.

---

On Windows and Xbox ONE, if the RecursiveMutex is managed by an SRWLock, a count is maintained for the number of times a lock was obtained for recursion. Return that count.

Note

Available on Xbox ONE and Windows only

Returns

Levels of recursion for this RecursiveMutex, usually zero.

See also

get_threadID(), or set_state(uint32_t, uint32_t)

get_platform_mutex()

void * Burger::RecursiveMutex::get_platform_mutex ( void )

inlinenoexcept

Access the platform mutex data.

---

On platforms that support mutexes, a structure is needed to contain the platform specific mutex. This function returns a pointer to that structure. Use this call with caution because the data returned is platform specific.

Returns

Pointer to the internal pthread_mutex_t, CRITICAL_SECTION, etc structure

get_threadID()

uint32_t Burger::RecursiveMutex::get_threadID ( void ) const

inlinenoexcept

Access the owner thread ID for the SRWLock.

---

On Windows and Xbox ONE, if the Mutex is managed by an SRWLock, a thread_ID_t of the owner thread is maintained. If it's zero, there is no owner.

Note

Available on Xbox ONE and Windows only

Returns

thread_ID_t of the owner of this RecursiveMutex

See also

get_count(), or set_state(uint32_t, uint32_t)

is_using_SRWlock()

uint_t Burger::RecursiveMutex::is_using_SRWlock ( void ) const

inlinenoexcept

Is the RecursiveMutex using Window 7 APIs.

---

On Windows 7 or higher, RecursiveMutex is implemented by using the lightweight SRWLock API. On Windows XP and Vista, RecursiveMutex will use a CRITICAL_SECTION. Test which API is being used.

Note

This is only available on Windows

Returns

TRUE if using Windows 7 APIs, FALSE if not.

lock()

void BURGER_API Burger::RecursiveMutex::lock ( void )

noexcept

Locks the mutex.

---

If the mutex is locked, a lock is obtained and execution continues. If the mutex was already locked, the thread halts until the alternate thread that has this mutex locked releases the lock. There is no timeout.

See also

try_lock(), or unlock()

operator=() [1/2]

RecursiveMutex & Burger::RecursiveMutex::operator= ( const RecursiveMutex & )

privatedelete

operator=() [2/2]

RecursiveMutex & Burger::RecursiveMutex::operator= ( RecursiveMutex && )

privatedelete

set_state()

void Burger::RecursiveMutex::set_state ( uint32_t uCount, uint32_t uThreadID )

inlinenoexcept

Set the SRWLock state.

---

On Windows and Xbox ONE, CondionalVariable may need to override the values of the SRWLock. This call will allow that.

Note

Available on Xbox ONE and Windows only

Parameters

uCount	New recursion level
uThreadID	New owner ID, can be 0.

See also

get_threadID(), or get_count()

try_lock()

uint_t BURGER_API Burger::RecursiveMutex::try_lock ( void )

noexcept

Attempt to lock the mutex.

---

If the mutex is locked, the function fails and returns FALSE. Otherwise, the mutex is locked and the function returns TRUE.

See also

lock(), or unlock()

unlock()

void BURGER_API Burger::RecursiveMutex::unlock ( void )

noexcept

Unlocks the mutex.

---

Releases a lock on a mutex and if any other threads are waiting on this lock, they will obtain the lock and the other thread will continue execution. The caller will never block.

Note

This call MUST be preceded by a matching lock() call. Calling unlock() without a preceding lock() call will result in undefined behavior and in some cases can result in thread lock or a crash.

See also

lock(), or try_lock()

Member Data Documentation

m_PlatformMutex

uint32_t Burger::RecursiveMutex::m_PlatformMutex[7]

protected

Platform specific CRITICAL_SECTION or mutex object.