Mutexes

Collaboration diagram for Mutexes:

Description

Mutex API.

Classes
struct	ar_mutex_t
	Mutex. More...
class	Ar::Mutex::Guard
	Utility class to automatically get and put a mutex. More...
class	Ar::Mutex
	Mutex object. More...

Mutexes
ar_status_t	ar_mutex_create (ar_mutex_t *mutex, const char *name)
	Create a new mutex object. More...
ar_status_t	ar_mutex_delete (ar_mutex_t *mutex)
	Delete a mutex. More...
ar_status_t	ar_mutex_get (ar_mutex_t *mutex, uint32_t timeout)
	Lock the mutex. More...
ar_status_t	ar_mutex_put (ar_mutex_t *mutex)
	Unlock the mutex. More...
bool	ar_mutex_is_locked (ar_mutex_t *mutex)
	Returns whether the mutex is currently locked. More...
ar_thread_t *	ar_mutex_get_owner (ar_mutex_t *mutex)
	Returns the current owning thread, if there is one. More...
const char *	ar_mutex_get_name (ar_mutex_t *mutex)
	Get the mutex's name. More...

---

Class Documentation

ar_mutex_t

struct ar_mutex_t

Collaboration diagram for ar_mutex_t:

Class Members
ar_list_t	m_blockedList	List of threads blocked on the mutex.
const char *	m_name	Name of the mutex.
uint8_t	m_originalPriority	Original priority of the owner thread before its priority was raised.
volatile ar_thread_t *	m_owner	Current owner thread of the mutex.
volatile unsigned	m_ownerLockCount	Number of times the owner thread has locked the mutex.

Function Documentation

ar_mutex_create()

ar_status_t ar_mutex_create	(	ar_mutex_t *	mutex,
		const char *	name
	)

Create a new mutex object.

The mutex starts out unlocked.

Parameters

mutex	Pointer to storage for the mutex.
name	The name of the mutex.

Return values

kArSuccess

ar_mutex_delete()

ar_status_t ar_mutex_delete

(

ar_mutex_t *

mutex

)

Delete a mutex.

Parameters

mutex

Pointer to the mutex to delete.

Return values

kArSuccess

ar_mutex_get()

ar_status_t ar_mutex_get	(	ar_mutex_t *	mutex,
		uint32_t	timeout
	)

Lock the mutex.

Mutexes are recursive, meaning that one thread can lock a mutex more than once when it already owns the lock. In this case, an internal count is incremented to track the number of times the owning thread has locked the mutex. The owner must make a matching number of calls to put in order to actually release the lock. Thus, a thread can lock a mutex any number of times as long as there are matching get() and put() calls.

Mutexes implement priority inheritance. If a given thread attempts to lock a mutex that is currently owned by a thread of lower priority, the lock owner thread has its priority boosted to that of the highest priority thread waiting to grab the lock.

Parameters

mutex	Pointer to the mutex.
timeout	The maximum number of milliseconds that the caller is willing to wait in a blocked state before the lock can be obtained. If this value is 0, or kArNoTimeout, then this method will return immediately if the lock cannot be obtained. Setting the timeout to kArInfiniteTimeout will cause the thread to wait forever for a chance to get the lock.

Return values

kArSuccess	The mutex was obtained without error.
kArTimeoutError	The specified amount of time has elapsed before the mutex could be obtained.
kArObjectDeletedError	Another thread deleted the mutex while the caller was blocked on it.

ar_mutex_get_name()

const char* ar_mutex_get_name

(

ar_mutex_t *

mutex

)

Get the mutex's name.

Parameters

mutex

Pointer to the mutex.

ar_mutex_get_owner()

ar_thread_t* ar_mutex_get_owner

(

ar_mutex_t *

mutex

)

Returns the current owning thread, if there is one.

Parameters

mutex

Pointer to the mutex.

ar_mutex_is_locked()

bool ar_mutex_is_locked

(

ar_mutex_t *

mutex

)

Returns whether the mutex is currently locked.

Parameters

mutex

Pointer to the mutex.

ar_mutex_put()

ar_status_t ar_mutex_put

(

ar_mutex_t *

mutex

)

Unlock the mutex.

Only the owning thread is allowed to unlock the mutex. If the owning thread has called get() multiple times, it must also call put() the same number of time before the lock is actually released. It is illegal to call put() when the mutex is not owned by the calling thread.

If the owning thread had its priority boosted due to priority inheritance, then its priority will be restored to the original value.

Execution will transition to the highest priority thread blocked on the mutex. This is likely to happen even before ar_mutex_put() returns. If there are no threads of higher priority waiting for the mutex, then no context change is performed.

Parameters

mutex

Pointer to the mutex.

Return values

kArAlreadyUnlockedError	The mutex is not locked.
kArNotOwnerError	The caller is not the thread that owns the mutex.