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

Wefts::RRWMutex Class Reference
[Mutexes]

This is an advanced (and fully reentrant) read/write mutex. More...

#include <wefts_rrwmutex.h>

Inheritance diagram for Wefts::RRWMutex:

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

Collaboration graph
[legend]
List of all members.

Public Methods

 RRWMutex ()
 Initializes the internal members of the mutex.

virtual bool lockRead (double seconds=0.0)
 Try to lock for reading this mutex for a certain time, or forever.

virtual bool tryLockRead ()
 Try to lock a mutex for reading and returns immediately.

virtual bool promoteFence (double time=0.0, bool fence=true) throw ( InvalidError )
 Promotes a mutex to Write Lock.

virtual bool promote (double time=0.0) throw ( InvalidError )
 Promotes a mutex to Write Lock, rising the fence Calls promoteFence( 0.0, true ), that is waits forever to acquire a write lock and rises the fence preventing readers from locking again.

virtual bool lockWriteFence (double time=0.0, bool fence=true)
 Locks the mutex for writing, possibly rising the fence.

virtual bool lockWrite (double seconds=0.0)
 Locks the mutex for writing, without rising the fence.

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)
 Callback method called on cleanup.


Private Attributes

int m_fence
OSThread m_owner

Detailed Description

This is an advanced (and fully reentrant) read/write mutex.

Read locks can be achieved as long as only read locks have been achieved; write locks can be achieved only by one thread at a time, and only if no read locks are currently held.

In this mutex kind, write locks are reentrant. Also, a write locker can require to rise a read lock fence, thus blocking any further request of new read lockers. This means that no new read lock will be allowed on the mutex, and the write locker will take onwership as soon as the last reader that had control over it finishes its operations.

This mutex class ereditates the read lock promotion ability of its ancestor. It is also possible to promote a read-lock to write-lock while rising the read lock fence.

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

See also:
howto_cancel


Constructor & Destructor Documentation

Wefts::RRWMutex::RRWMutex   [inline]
 

Initializes the internal members of the mutex.


Member Function Documentation

void Wefts::RRWMutex::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 reaquired read-only.

This function does checks if the calling thread is the rightful owner of the mutex, and issues an exception if it isnt.

Being reentrant, this function must be called a number of time equal to the write locks acquired on the mutex to drop the write-only rights. Also, unlock() calls have the same effect as degrade() until the last lock is being held; is the last call (degrade or unlock) to determine if the mutex is retained read-only or not.

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

Reimplemented from Wefts::RWMutex.

void Wefts::RRWMutex::handleCleanup int    code [virtual]
 

Callback method called on cleanup.

When a thread is terminated (stopped or finished), and a cleanup request have been set, this method is called. Use the code parameter to decide what action among the possible ones must be taken.

Reimplemented from Wefts::RWMutex.

bool Wefts::RRWMutex::lockRead double    seconds = 0.0 [virtual]
 

Try to lock for reading this mutex for a certain time, or forever.

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.

If a write locker has risen the read fence, this function will block the calling thread also if the writer is WAITING to achieve the lock.

If the time parameter is given, and if the lock can be achived 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 cancelation point, so actions must be taken to prevent cancelation, or to becanceled cleanly.

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

Reimplemented from Wefts::RWMutex.

virtual bool Wefts::RRWMutex::lockWrite double    seconds = 0.0 [inline, virtual]
 

Locks the mutex for writing, without rising the fence.

Calls lockWrite( seconds, false ).

Parameters:
time  maximum time to wait for the promotion, or 0 to wait forever.

Reimplemented from Wefts::RWMutex.

bool Wefts::RRWMutex::lockWriteFence double    time = 0.0,
bool    fence = true
[virtual]
 

Locks the mutex for writing, possibly rising the fence.

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.

Works as the RWMutex::lockWrite(), but with the ability to rise the reader's fence.

Parameters:
fence  if true, prevents any reader to acquire the lock thereafter.
time  maximum time to wait for the promotion, or 0 to wait forever.

virtual bool Wefts::RRWMutex::promote double    time = 0.0 throw ( InvalidError ) [inline, virtual]
 

Promotes a mutex to Write Lock, rising the fence Calls promoteFence( 0.0, true ), that is waits forever to acquire a write lock and rises the fence preventing readers from locking again.

Note:
This mutex must be locked for reading before issuing a promote, or an assertion error will be risen.
Parameters:
time  maximum time to wait for the promotion, or 0 to wait forever.

Reimplemented from Wefts::RWMutex.

bool Wefts::RRWMutex::promoteFence double    time = 0.0,
bool    fence = true
throw ( InvalidError ) [virtual]
 

Promotes a mutex to Write Lock.

This methods works like the RWMutex::promote() provided in its ancestor, but it has also the ability to rise the fence, to prevent further readers to gain control of the mutex while this thread is waiting to be promoted.

Note:
This mutex must be locked for reading before issuing a promote, or an assertion error will be risen.
Parameters:
time  maximum time to wait for the promotion, or 0 to wait forever.
fence  if true, rises the read lock fence: any call to read lock after this one will be blocked.

bool Wefts::RRWMutex::tryLockRead   [virtual]
 

Try to lock a mutex for reading and returns immediately.

Returns:
true if the lock is achived, false otherwise.

Reimplemented from Wefts::RWMutex.

void Wefts::RRWMutex::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). If the mutex is locked for writing and the calling thread is not the owner of the lock, this call is ignored.

Reimplemented from Wefts::RWMutex.


Member Data Documentation

int Wefts::RRWMutex::m_fence [private]
 

OSThread Wefts::RRWMutex::m_owner [private]
 


The documentation for this class was generated from the following files:
Generated on Mon Dec 22 04:12:40 2003 for Wefts by doxygen1.2.18