Burger::Mutex Class Reference

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

Inheritance diagram for Burger::Mutex:

Public Member Functions
	Mutex () noexcept
	Initialize the data in the class.
	~Mutex ()
	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.
void	set_state (uint32_t uThreadID) noexcept
	Set the SRWLock state.
uint_t	is_using_SRWlock (void) const noexcept
	Is the Mutex using Window 7 APIs.

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

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

Detailed Description

Class for creating a Mutex 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 Mutex after a successfull call to lock() or try_lock() until a call to unlock() is performed.
• When a thread owns a Mutex, all other threads will block or return FALSE for try_lock()
• Multiple calls by the owning thread to lock() are not allowed.

This is a functional equivalent to std::mutex

See also

MutexStatic and MutexLock

Constructor & Destructor Documentation

Mutex() [1/3]

Burger::Mutex::Mutex ( const Mutex & )

privatedelete

Mutex() [2/3]

Burger::Mutex::Mutex ( Mutex && )

privatedelete

Mutex() [3/3]

Burger::Mutex::Mutex ( )

noexcept

Initialize the data in the class.

---

Sets up operating system defaults to the data

~Mutex()

Burger::Mutex::~Mutex

(

)

Shutdown the data in the class.

---

Releases the operating system resources allocated by the constructor.

Member Function Documentation

get_platform_mutex()

void * Burger::Mutex::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::Mutex::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 Mutex

See also

get_count(), or set_state(uint32_t, uint32_t)

is_using_SRWlock()

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

inlinenoexcept

Is the Mutex using Window 7 APIs.

---

On Windows 7 or higher, Mutex is implemented by using the lightweight SRWLock API. On Windows XP and Vista, Mutex 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::Mutex::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]

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

privatedelete

operator=() [2/2]

Mutex & Burger::Mutex::operator= ( Mutex && )

privatedelete

set_state()

void Burger::Mutex::set_state ( 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::Mutex::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::Mutex::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::Mutex::m_PlatformMutex[7]

protected

Platform specific CRITICAL_SECTION or mutex object.

m_uOwnerThreadID

uint32_t Burger::Mutex::m_uOwnerThreadID

protected