Ar::Mutex Class Reference

#include <ar_classes.h>

Inheritance diagram for Ar::Mutex:

Description

Mutex object.

Very similar to a binary semaphore, except that a single thread can lock the mutex multiple times without deadlocking. In this case, the number of calls to get() and put() must be matched.

Another difference from semaphores is that mutexes support priority inheritance. If a high- priority thread blocks on a mutex held by a lower-priority thread, the thread holding the mutex will have its priority temporarily raised to the priority of the thread waiting on the mutex.

See also

Mutex::Guard

Collaboration diagram for Ar::Mutex:

Classes
class	Guard
	Utility class to automatically get and put a mutex. More...

Public Member Functions
	Mutex ()
	Default constructor.
	Mutex (const char *name)
	Constructor.
	~Mutex ()
	Cleanup.
ar_status_t	get (uint32_t timeout=kArInfiniteTimeout)
	Lock the mutex. More...
const char *	getName () const
	Get the mutex's name.
ar_thread_t *	getOwner ()
	Returns the current owning thread, if there is one.
ar_status_t	init (const char *name)
	Initialiser. More...
bool	isLocked ()
	Returns whether the mutex is currently locked. More...
ar_status_t	put ()
	Unlock the mutex. More...

Member Function Documentation

get()

ar_status_t Ar::Mutex::get ( uint32_t  timeout = kArInfiniteTimeout )

inline

Lock the mutex.

If the thread that already owns the mutex calls get() more than once, a count is incremented rather than attempting to decrement the underlying semaphore again. The converse is true for put(), thus allowing a thread to lock a mutex any number of times as long as there are matching get() and put() calls.

Parameters

timeout

The maximum number of milliseconds that the caller is willing to wait in a blocked state before the semaphore 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 semaphore while the caller was blocked on it.

init()

ar_status_t Ar::Mutex::init ( const char *  name )

inline

Initialiser.

The mutex starts out unlocked.

Parameters

name	The name of the mutex.

Return values

SUCCCESS

isLocked()

bool Ar::Mutex::isLocked ( )

inline

Returns whether the mutex is currently locked.

Return values

true	The mutex is locked.
false	The mutex is unlocked.

put()

ar_status_t Ar::Mutex::put ( )

inline

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 underlying semaphore is actually released. It is illegal to call put() when the mutex is not owned by the calling thread.

Return values

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