VMutex Class Reference

VMutex implements a platform-independent mutex that you can embed in an object or place on the stack to guarantee its cleanup when the VMutex object is destructed. More...

#include <vmutex.h>

List of all members.

Public Member Functions
	VMutex (const VString &name=VString::EMPTY(), bool suppressLogging=false)
	Creates and initializes the mutex with an optional name that can be used when debugging mutex and lock behavior.
virtual	~VMutex ()
	Destructs the mutex.
void	setName (const VString &name)
	In some cases it's more convenient to name a mutex after constructing, in which case you can call setName().
VMutex_Type *	getMutex ()
	Returns a pointer to the raw OS mutex handle.
bool	isLockedByCurrentThread () const
	Returns true if the following conditions hold:
Static Public Member Functions
static bool	mutexInit (VMutex_Type *mutex)
	Initializes the platform mutex value.
static void	mutexDestroy (VMutex_Type *mutex)
	Destroys the platform mutex value.
static bool	mutexLock (VMutex_Type *mutex)
	Locks the platform mutex value.
static bool	mutexUnlock (VMutex_Type *mutex)
	Unlocks the platform mutex value.
static void	setLockDelayLoggingThreshold (const VDuration &threshold)
	The following methods set and get the configuration for emitting a log message if there is a lengthy holding of, or delay in acquiring a lock.
static VDuration	getLockDelayLoggingThreshold ()
static void	setLockDelayLoggingLevel (int logLevel)
static int	getLockDelayLoggingLevel ()
Friends
class	VMutexLocker
class	VMutexUnlocker
class	VThreadsUnit

---

Detailed Description

VMutex implements a platform-independent mutex that you can embed in an object or place on the stack to guarantee its cleanup when the VMutex object is destructed.

You can call the lock() and unlock() methods to acquire and release the mutex lock. However, it is recommended that you use the helper class VMutexLocker to do this, because you can use VMutexLocker to guarantee the proper release of the mutex when the VMutexLocker is destructed (typically by going out of scope) regardless of exceptions being raised.

See also:

VMutexLocker

Definition at line 37 of file vmutex.h.

---

Constructor & Destructor Documentation

VMutex::VMutex	(	const VString &	name = VString::EMPTY(),
		bool	suppressLogging = false
	)

Creates and initializes the mutex with an optional name that can be used when debugging mutex and lock behavior.

Parameters:

name	a name for the mutex; should be unique to avoid confusion
suppressLogging	if this mutex is specifically locked during logging, this flag must be set so that VMutex doesn't try to log information about this mutex (avoids recursive locking deadlock)

Definition at line 19 of file vmutex.cpp.

References VString::chars(), and mutexInit().

---

Member Function Documentation

void VMutex::setName

(

const VString &

name

)

In some cases it's more convenient to name a mutex after constructing, in which case you can call setName().

The name is only used for diagnostic purposes when debugging mutex and lock behavior.

Parameters:

name	a name for the mutex; should be unique to avoid confusion

Definition at line 37 of file vmutex.cpp.

VMutex_Type * VMutex::getMutex

(

)

Returns a pointer to the raw OS mutex handle.

Returns:

a pointer to the raw OS mutex handle

Definition at line 41 of file vmutex.cpp.

bool VMutex::isLockedByCurrentThread

(

)

const

Returns true if the following conditions hold:

• the mutex has been lock()'ed but not yet unlock()'ed
• the lock() occurred on the current thread This is intended to be used for one purpose: asserting that a mutex is held by the current thread. If another thread is concurrently locking or unlocking the mutex, the lock state may change during this call, but in a way that still allows this test to work. Note that you can't test whether a mutex is locked or unlocked in general because the answer is obsolete on return.

  Returns:

  true if the mutex was locked on the current thread

Definition at line 45 of file vmutex.cpp.

References VThread::threadSelf().

bool VMutex::mutexInit

(

VMutex_Type *

mutex

)

[static]

Initializes the platform mutex value.

Wrapper on Unix for pthread_mutex_init.

Parameters:

mutex

pointer to the platform mutex

Returns:

true on success; false on failure

Definition at line 118 of file vthread_platform.cpp.

References NULL.

void VMutex::mutexDestroy

(

VMutex_Type *

mutex

)

[static]

Destroys the platform mutex value.

Wrapper on Unix for pthread_mutex_destroy.

Parameters:

mutex

pointer to the platform mutex

Definition at line 123 of file vthread_platform.cpp.

bool VMutex::mutexLock

(

VMutex_Type *

mutex

)

[static]

Locks the platform mutex value.

Wrapper on Unix for pthread_mutex_lock.

Returns:

true on success; false on failure

Definition at line 128 of file vthread_platform.cpp.

bool VMutex::mutexUnlock

(

VMutex_Type *

mutex

)

[static]

Unlocks the platform mutex value.

Wrapper on Unix for pthread_mutex_unlock.

Returns:

true on success; false on failure

Definition at line 133 of file vthread_platform.cpp.

static void VMutex::setLockDelayLoggingThreshold

(

const VDuration &

threshold

)

[inline, static]

The following methods set and get the configuration for emitting a log message if there is a lengthy holding of, or delay in acquiring a lock.

First, you must compile with VAULT_MUTEX_LOCK_DELAY_CHECK defined (presumably in vconfigure.h) to have the delay checking code in place. The default delay threshold is 50ms. If you specify 0, every lock will log a message. You can set the log leve at which the output will be emitted.

Definition at line 125 of file vmutex.h.

---

The documentation for this class was generated from the following files:

• vmutex.h
• vthread_platform.cpp
• vmutex.cpp