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.
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 Mutex using Window 7 APIs.

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

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.

---

In a multiprocessor system, it's necessary to have multiple threads access the same data at the same time. To prevent data collisions, this class is locked just before the data is used/modified and unlocked after the data access/modification is complete so all CPUs/threads do not have to worry about data collisions.

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_count()

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

inlinenoexcept

Get the lock count for a SRWLock.

---

On Windows and Xbox ONE, if the Mutex 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 Mutex, usually zero.

See also

get_threadID(), or set_state(uint32_t, uint32_t)

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 ThreadID of the owner thread is maintained. If it's zero, there is no owner.

Note

Available on Xbox ONE and Windows only

Returns

ThreadID 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::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 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::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::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.