Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   Related Pages  

Wefts::RWMutex Class Reference

This is a read/write mutex. More...

#include <wefts_rwmutex.h>

Inheritance diagram for Wefts::RWMutex:

Inheritance graph
List of all members.

Public Methods

 RWMutex ()
 Initializes the internal members of the mutex.

 ~RWMutex ()
 Destroys the mutex.

virtual void lockRead ()
 Locks the mutex for reading.

virtual void lockWrite ()
 Locks the mutex for writing.

virtual void promote ()
 Promote the locks from read only to readwrite.

virtual void unlock ()
 Unlocks the mutex.

Protected Attributes

pthread_mutex_t m_mutex
pthread_cond_t m_cond
volatile int m_lockCount
volatile int m_promCount

Detailed Description

This is a read/write mutex.

Read lock can be achieved as long as only read locks have been achieved; write lock can be achieved only by one thread, and only if no read locks area currently held.

While read locks are reentrant, a second write lock request from a thread already helding the write lock will cause a deadlock.

This class also implements read-lock promotion. If a thread inspecting the data (and doing this under a read-only lock) has the need to alter the data, it can require its mutex to be promoted to write lock, so that it hasn't to release the read only lock to begin writing. See promote() method for details.

This mutex model has the drawback that, if read locks are frequent enough, the write lock requests could be held waiting indefinitely. As long as read lock threads are served, the write locker may be never capable to achieve its lock. If you meet such a situation, you should use the wtRRWMutex (Reentrant-read/write mutex), that has the ability to stop further read requests when a write lock request has been issued.

All mutex classes are implemented via inline calls to maximize execution speed; also, their metods are extremely small.

Constructor & Destructor Documentation

Wefts::RWMutex::RWMutex   [inline]

Initializes the internal members of the mutex.

Wefts::RWMutex::~RWMutex   [inline]

Destroys the mutex.

Only call this when the mutex is fully unlocked: destroyng a locked mutex has undefinded result.

Member Function Documentation

virtual void Wefts::RWMutex::lockRead   [inline, virtual]

Locks the mutex for reading.

Any amount of read locks can be achieved by the calling thread or by other read-locking threads. After that a read lock has been achieved, write lock requests will be blocked untill all the read lockers have relased their locks.

Reimplemented in Wefts::RRWMutex.

virtual void Wefts::RWMutex::lockWrite   [inline, virtual]

Locks the mutex for writing.

After this call has returned any request of lock (both read or write) will cause blocking of the caller until the owner of this thread releases the lock. This method is not reentrant, so never call lockWrite() twice from the same thread.

Reimplemented in Wefts::RRWMutex.

virtual void Wefts::RWMutex::promote   [inline, virtual]

Promote the locks from read only to readwrite.

Often, threads that have a read only lock on some data, after inspecting that data, find out that they need to alter it. Releasing the readLock and getting a write lock is not the optimal solution, both because it can cause unnecessary context switch, and because the situation of the data may change while the data is unlocked, requiring then a new rescan of the data to check if there is still a need for this thread to write it.

Another solution may be locking for writing the whole scanning code, if there is any possibility that, sometimes, a write is also needed.

But the most elegant solution is to promote a lock from read-only to read-write, so that no other writer is allowed to proceed before this thread can chage the data, but that all the other readers are done before this newly promoted thread can work.

This mutex must be locked for reading before issuing a promote, or an assertion error will be risen.

Reimplemented in Wefts::RRWMutex.

virtual void Wefts::RWMutex::unlock   [inline, virtual]

Unlocks the mutex.

Releases the lock held by the calling thread (be it a read-only lock or a write lock). This function does not checks for the calling thread to be the rightful owner of the mutex; calling an unlock on a write locked mutex from an unrightful thread has undefined results.

Reimplemented in Wefts::RRWMutex.

Member Data Documentation

pthread_cond_t Wefts::RWMutex::m_cond [protected]

volatile int Wefts::RWMutex::m_lockCount [protected]

pthread_mutex_t Wefts::RWMutex::m_mutex [protected]

volatile int Wefts::RWMutex::m_promCount [protected]

The documentation for this class was generated from the following file:
Generated on Tue Aug 5 18:09:03 2003 for Wefts by doxygen1.2.18