---

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:

[legend]Collaboration diagram for Wefts::RRWMutex:

[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	promote (bool fence) throw ( InvalidError )
	Promote the lock from read only to readwrite.
virtual bool	promote (double time=0.0, bool fence=false) throw ( InvalidError )
	Promotes a mutex to Write Lock.
virtual bool	lockWrite (bool fence)
	Locks the mutex for writing.
virtual bool	lockWrite (double time=0.0, bool fence=false)
	Locks the mutex for writing.
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::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.

bool Wefts::RRWMutex::lockWrite (  double    time = 0.0, bool    fence = false )  [virtual]

Locks the mutex for writing. As the RWMutex::lockWrite(), but with the add of the fence. 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 will be locked.

virtual bool Wefts::RRWMutex::lockWrite (  bool    fence )  [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. Parameters: fence  if true, rises the read lock fence: any call to read lock after this will be blocked.

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

Promotes a mutex to Write Lock. As the RWMutex::promote(), but with the add of the fence. 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 will be blocked.

virtual bool Wefts::RRWMutex::promote (  bool    fence )  throw ( InvalidError ) [inline, virtual]

Promote the lock from read only to readwrite. This methods works like the one 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: fence  true to block further readers trying to achieve the lock, false otherwise See also: RWMutex::promote(double)

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:

• wefts_rrwmutex.h
• wefts_rrwmutex.cpp

---