Wefts::XMutex Class Reference
[Mutexes]

#include <wefts_xmutex.h>

Inheritance diagram for Wefts::XMutex:

Inheritance graph
[legend]
Collaboration diagram for Wefts::XMutex:

Collaboration graph
[legend]
List of all members.

Detailed Description

Advanced mutex class.

This class implements a mutex with advanced behavior, that can also be used as a base to build even more complex syncrhonization objects. Among the capabilities of this class are:

An XMutex can be used to try to lock and return immediately on failure, to try to lock for a given amount of time, and then return on failure, or to wait indefinitely for a lock. In this two latter cases, an XMutex can be stopped from another thread; by all means, XMutex::lock() is a valid "deferred cancellation point" (see Cancellation Issues); care must be taken to 1) arrive at this point ready to be cancelled or 2) disable cancellation before trying a lock.

XMutex takes care that on lock method exit the mutex is either locked or unlocked, and that cancellation may happen only when mutex is unlocked. As there aren't undefined outcomes, the mutex can be considered cancellation safe.

Anyhow, XMutex has a major drawback in efficiency; lock and unlock requests are relatively slow, so it must be used to synchronize time-sparse operations, or operations having an heavy set of instructions to be mutexed, so that the ovherhead of this class is transcurable.

Todo:
write how a cancellable mutex can be used.


Public Member Functions

 XMutex ()
 Initializes the mutex.

void lock ()
 Lock the mutex.

bool lock (double seconds)
 Try to lock a mutex for a given amount of seconds.

bool tryLock ()
 Try to lock a mutex and returns immediately.

void unlock ()
 Unlock a mutex.

bool own ()
 Returns true if current thread owns the mutex.

bool locked ()
 Returns true if the mutex has been locked.

void handleCleanup (int, void *caller=0)
 Cleanup routines.


Private Attributes

Condition m_cond
Mutex m_mutex
int m_locked
int m_waiting
OSThread m_owner


Constructor & Destructor Documentation

Wefts::XMutex::XMutex  ) 
 

Initializes the mutex.


Member Function Documentation

void Wefts::XMutex::handleCleanup int  ,
void *  caller = 0
[virtual]
 

Cleanup routines.

Implements Wefts::CleanupHandler.

bool Wefts::XMutex::lock double  seconds  ) 
 

Try to lock a mutex for a given amount of seconds.

If the timeout expires and the lock can't be achived, the thread is resumed and the function returns false.

void Wefts::XMutex::lock  ) 
 

Lock the mutex.

The calling thread is suspended until the lock is achived; another thread may stop this one cleanly, preventing it from gainig the lock.

The lock owner can also lock the mutex more than one time, allowing this method to be used in recursive calls. The unlock() method must be called the same amount of times lock() has been called to release the mutex.

bool Wefts::XMutex::locked  )  [inline]
 

Returns true if the mutex has been locked.

This data may change even before the reading thread has a chance to test its value, so it must not be relied on; it is provided for debugging reasons.

bool Wefts::XMutex::own  )  [inline]
 

Returns true if current thread owns the mutex.

bool Wefts::XMutex::tryLock  ) 
 

Try to lock a mutex and returns immediately.

On success, retruns true

void Wefts::XMutex::unlock  ) 
 

Unlock a mutex.

Requests to unlock a mutex from a thread that is not owning the lock are ignored.


Member Data Documentation

Condition Wefts::XMutex::m_cond [private]
 

int Wefts::XMutex::m_locked [private]
 

Mutex Wefts::XMutex::m_mutex [private]
 

OSThread Wefts::XMutex::m_owner [private]
 

int Wefts::XMutex::m_waiting [private]
 


The documentation for this class was generated from the following files:
Generated on Tue Oct 5 14:57:03 2004 for Wefts by doxygen 1.3.7