Wefts::RWMutex Class Reference
[Mutexes]

#include <wefts_rwmutex.h>

Inheritance diagram for Wefts::RWMutex:

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

Collaboration graph
[legend]
List of all members.

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 are currently held.

While read locks are reentrant, a second write lock request from a thread already holding 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 RRWMutex (Reentrant-read/write mutex), that has the ability to stop further read requests when a write lock request has been issued.

Also, this mutex lock() requests can be canceled by another thread using deferred cancellation schemes; RRWMutex()::lock() are cancellation points, and care must be taken to 1) arrive at this point ready to be canceled or 2) disable cancellation.

See also:
Cancellation Issues


Public Member Functions

 RWMutex ()
 Initializes the internal members of the mutex.

virtual bool lockRead (double time=0.0)
 Locks the mutex for reading.

virtual bool tryLockRead ()
 Try to lock mutex for reading.

virtual bool lockWrite (double time=0.0)
 Locks the mutex for writing.

virtual bool tryLockWrite ()
 Try to lock the mutex for writing.

virtual bool promote (double time=0.0) throw ( InvalidError )
 Promote the locks from read only to read write.

virtual bool tryPromote ()
 Try to promote the read lock mutex immediately.

void degrade () throw ( InvalidError )
 Degrade the mutex from read-write to read only.

virtual void unlock () throw ( InvalidError )
 Unlocks the mutex.

virtual void handleCleanup (int code, void *caller=0)

Protected Attributes

Mutex m_mutex
Condition m_condRead
Condition m_condWrite
int m_locking
int m_waitingRead
int m_waitingWrite
int m_promoting


Constructor & Destructor Documentation

Wefts::RWMutex::RWMutex  ) 
 

Initializes the internal members of the mutex.


Member Function Documentation

void Wefts::RWMutex::degrade  )  throw ( InvalidError )
 

Degrade the mutex from read-write to read only.

Releases the write lock held by the calling thread, but maintain grip as a reader, without giving away the lock. This will prevent writers from locking the mutex in the meanwhile, so a degraded mutex will still grant that the locked data are not changed, while this cannot be granted if the mutex is unlocked and then reacquired read-only.

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 not owningg thread has undefined results.

Exceptions:
InvalidError if the mutex is not locked for writing.

Reimplemented in Wefts::RRWMutex.

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

Implements Wefts::CleanupHandler.

Reimplemented in Wefts::RRWMutex.

bool Wefts::RWMutex::lockRead double  time = 0.0  )  [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 until all the read lockers have released their locks.

If the time parameter is given, and if the lock can be achieved during the given time, the method returns true, else the method return false.

If the parameter is 0, this method returns always true.

This method is a cancellation point, so actions must be taken to prevent cancellation, or to be canceled cleanly.

Parameters:
time seconds to wait for (0 = forever)
Returns:
true if lock is achieved, false otherwise

Reimplemented in Wefts::RRWMutex.

bool Wefts::RWMutex::lockWrite double  time = 0.0  )  [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.

If the time parameter is given, and if the lock can be achieved during the given time, the method returns true, else the method return false.

If the parameter is 0, this method returns always true.

This method is a cancellation point, so actions must be taken to prevent cancellation, or to be canceled cleanly.

Parameters:
time seconds to wait for (0 = forever)
Returns:
true if lock is achieved, false otherwise

Reimplemented in Wefts::RRWMutex.

bool Wefts::RWMutex::promote double  time = 0.0  )  throw ( InvalidError ) [virtual]
 

Promote the locks from read only to read write.

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 change the data, but that all the other readers are done before this newly promoted thread can work.

If the time parameter is given, and if the lock can be achieved during the given time, the method returns true, else the method return false.

If the parameter is 0, this method returns always true.

This method is a cancellation point, so actions must be taken to prevent cancellation, or to be canceled cleanly.

Note:
This mutex must be locked for reading before issuing a promote, or an InvalidError will be thrown.
Parameters:
time seconds to wait for (0 = forever)
Returns:
true if lock is achieved, false otherwise

Reimplemented in Wefts::RRWMutex.

bool Wefts::RWMutex::tryLockRead  )  [virtual]
 

Try to lock mutex for reading.

If the mutex can be locked for reading, the lock is achieved and the this call returns true; If the mutex can't be locked (i.e. writers are at work), the function returns false.

See also:
lockRead()

Reimplemented in Wefts::RRWMutex.

bool Wefts::RWMutex::tryLockWrite  )  [virtual]
 

Try to lock the mutex for writing.

If the mutex can be locked for writing, the lock is achieved and the this call returns true; If the mutex can't be locked the function returns false.

This method is a cancellation point, so actions must be taken to prevent cancellation, or to be canceled cleanly.

See also:
lockWrite()

bool Wefts::RWMutex::tryPromote  )  [virtual]
 

Try to promote the read lock mutex immediately.

If it is not possible to achieve the write lock immediately, the function returns false, else it returns true and the lock is achieved.

See also:
promote()

void Wefts::RWMutex::unlock  )  throw ( InvalidError ) [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 not owningg thread has undefined results.

Exceptions:
InvalidError if the mutex is not locked.

Reimplemented in Wefts::RRWMutex.


Member Data Documentation

Condition Wefts::RWMutex::m_condRead [protected]
 

Condition Wefts::RWMutex::m_condWrite [protected]
 

int Wefts::RWMutex::m_locking [protected]
 

Mutex Wefts::RWMutex::m_mutex [protected]
 

int Wefts::RWMutex::m_promoting [protected]
 

int Wefts::RWMutex::m_waitingRead [protected]
 

int Wefts::RWMutex::m_waitingWrite [protected]
 


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