This class defines a thread synchronisation object. More...

#include <syncthrd.h>

Inheritance diagram for PReadWriteMutex:

Collaboration diagram for PReadWriteMutex:

Classes
struct	Nest

Public Member Functions
virtual void	PrintOn (ostream &strm) const
	Output the contents of the object to the stream. More...

Construction
	PReadWriteMutex ()

	PReadWriteMutex (const PDebugLocation &location, unsigned timeout=0)

	~PReadWriteMutex ()

Operations
__inline void	StartRead ()
	This function attempts to acquire the mutex for reading. More...

__inline void	StartRead (const PDebugLocation &location)

__inline void	EndRead ()
	This function attempts to release the mutex for reading. More...

__inline void	EndRead (const PDebugLocation &location)

__inline void	StartWrite ()
	This function attempts to acquire the mutex for writing. More...

__inline void	StartWrite (const PDebugLocation &location)

void	EndWrite ()
	This function attempts to release the mutex for writing. More...

void	EndWrite (const PDebugLocation &location)

Public Member Functions inherited from PObject
__inline unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

__inline void	SetTraceContextIdentifier (unsigned id)

__inline void	SetTraceContextIdentifier (const PObject &obj)

__inline void	SetTraceContextIdentifier (const PObject *obj)

__inline void	CopyTraceContextIdentifier (PObject &obj) const

__inline void	CopyTraceContextIdentifier (PObject *obj) const

virtual	~PObject ()

__inline const char *	GetClass () const

__inline bool	IsClass (const char *name) const

__inline const PObject *	PTraceObjectInstance () const

virtual PObject *	Clone () const
	Create a copy of the class on the heap. More...

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual PINDEX	HashFunction () const
	This function yields a hash value required by the `PDictionary` class. More...

virtual Comparison	Compare (const PObject &obj) const
	Compare the two objects and return their relative rank. More...

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

virtual void	ReadFrom (istream &strm)
	Input the contents of the object from the stream. More...

Public Member Functions inherited from PMutexExcessiveLockInfo
void	SetLocationName (const char *name)

Protected Types
typedef std::map < PThreadIdentifier, Nest >	NestMap

Protected Member Functions
void	InternalStartRead (const PDebugLocation *location)

void	InternalEndRead (const PDebugLocation *location)

void	InternalStartWrite (const PDebugLocation *location)

void	InternalEndWrite (const PDebugLocation *location)

Nest *	GetNest ()

Nest &	StartNest ()

void	EndNest ()

void	InternalStartReadWithNest (Nest &nest, const PDebugLocation &location)

void	InternalEndReadWithNest (Nest &nest, const PDebugLocation &location)

void	InternalStartWriteWithNest (Nest &nest, const PDebugLocation &location)

void	InternalEndWriteWithNest (Nest &nest, const PDebugLocation &location)

void	InternalWait (Nest &nest, PSync &sync, const PDebugLocation &location) const

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Member Functions inherited from PMutexExcessiveLockInfo
	PMutexExcessiveLockInfo ()

	PMutexExcessiveLockInfo (const PDebugLocation &location, unsigned timeout)

	PMutexExcessiveLockInfo (const PMutexExcessiveLockInfo &other)

virtual	~PMutexExcessiveLockInfo ()

void	Construct (unsigned timeout)

void	PrintOn (ostream &strm) const

void	ExcessiveLockPhantom (const PObject &mutex) const

virtual void	AcquiredLock (uint64_t startWaitCycle, bool readOnly, const PDebugLocation &location)

virtual void	ReleasedLock (const PObject &mutex, uint64_t startHeldSamplePoint, bool readOnly, const PDebugLocation &location)

Protected Attributes
PSemaphore	m_readerSemaphore

PTimedMutex	m_readerMutex

unsigned	m_readerCount

PTimedMutex	m_starvationPreventer

PSemaphore	m_writerSemaphore

PTimedMutex	m_writerMutex

unsigned	m_writerCount

NestMap	m_nestedThreads

PCriticalSection	m_nestingMutex

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Protected Attributes inherited from PMutexExcessiveLockInfo
PDebugLocation	m_location

unsigned	m_excessiveLockTimeout

atomic< bool >	m_excessiveLockActive

uint64_t	m_startHeldSamplePoint

Additional Inherited Members
Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Static Public Member Functions inherited from PObject
static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject *from)

static __inline void	CopyTraceContextIdentifier (PObject *to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject to, const PObject from)

static __inline const char *	Class ()

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

template<typename T >
static Comparison	Compare2 (T v1, T v2)
	Compare two types, returning Comparison type. More...

static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

Static Protected Member Functions inherited from PMutexExcessiveLockInfo
static unsigned	MinDeadlockTime (unsigned waitTime)

Detailed Description

This class defines a thread synchronisation object.

This is a special type of mutual exclusion, where the excluded area may have multiple read threads but only one write thread and the read threads are blocked on write as well.

The original algorithm for this was described in 'Communications of the ACM: Concurrent Control with "Readers" and "Writers" P.J. Courtois,* F. H, 1971' http://cs.nyu.edu/~lerner/spring10/MCP-S10-Read04-ReadersWriters.pdf which can be changed via #define to an alternate algorithm 'Faster Fair Solution for the Reader-Writer Problem. V.Popov, O.Mazonka 2013' http://arxiv.org/ftp/arxiv/papers/1309/1309.4507.pdf to improve efficiency.

Member Typedef Documentation

typedef std::map<PThreadIdentifier, Nest> PReadWriteMutex::NestMap

protected

Constructor & Destructor Documentation

PReadWriteMutex::PReadWriteMutex ( )

explicit

PReadWriteMutex::PReadWriteMutex	(	const PDebugLocation &	location,
		unsigned	timeout = `0`
	)

explicit

Parameters

location	Source file/line of mutex definition
timeout	Timeout in ms, before declaring a possible deadlock. Zero uses default.

PReadWriteMutex::~PReadWriteMutex ( )

Member Function Documentation

void PReadWriteMutex::EndNest ( )

protected

__inline void PReadWriteMutex::EndRead ( )

inline

This function attempts to release the mutex for reading.

References InternalEndRead().

Referenced by PHTTPSpace::EndRead().

__inline void PReadWriteMutex::EndRead ( const PDebugLocation & location )

inline

References InternalEndRead().

void PReadWriteMutex::EndWrite ( )

inline

This function attempts to release the mutex for writing.

Note, if the same thread had a read lock when the StartWrite() was called which has not yet been released by an EndRead() call then this will reacquire the read lock.

It should also be noted that a consequence of this is that another thread may acquire the write lock before the thread that regains the read lock. Thus it is impossibly to go straight from a write lock to read lock without the possiblility of the object being changed and application logic should take this into account.

References InternalEndWrite().

Referenced by PHTTPSpace::EndWrite().

void PReadWriteMutex::EndWrite ( const PDebugLocation & location )

inline

References InternalEndWrite().

Nest* PReadWriteMutex::GetNest ( )

protected

void PReadWriteMutex::InternalEndRead ( const PDebugLocation * location )

protected

Referenced by EndRead().

void PReadWriteMutex::InternalEndReadWithNest	(	Nest &	nest,
		const PDebugLocation &	location
	)

protected

void PReadWriteMutex::InternalEndWrite ( const PDebugLocation * location )

protected

Referenced by EndWrite().

void PReadWriteMutex::InternalEndWriteWithNest	(	Nest &	nest,
		const PDebugLocation &	location
	)

protected

void PReadWriteMutex::InternalStartRead ( const PDebugLocation * location )

protected

Referenced by StartRead().

void PReadWriteMutex::InternalStartReadWithNest	(	Nest &	nest,
		const PDebugLocation &	location
	)

protected

void PReadWriteMutex::InternalStartWrite ( const PDebugLocation * location )

protected

Referenced by StartWrite().

void PReadWriteMutex::InternalStartWriteWithNest	(	Nest &	nest,
		const PDebugLocation &	location
	)

protected

void PReadWriteMutex::InternalWait	(	Nest &	nest,
		PSync &	sync,
		const PDebugLocation &	location
	)		const

protected

virtual void PReadWriteMutex::PrintOn ( ostream & strm ) const

virtual

Output the contents of the object to the stream.

The exact output is dependent on the exact semantics of the descendent class. This is primarily used by the standard operator<< function.

The default behaviour is to print the class name.

Reimplemented from PObject.

Nest& PReadWriteMutex::StartNest ( )

protected

__inline void PReadWriteMutex::StartRead ( )

inline

This function attempts to acquire the mutex for reading.

This call may be nested and must have an equal number of EndRead() calls for the mutex to be released.

References InternalStartRead().

Referenced by PHTTPSpace::StartRead().

__inline void PReadWriteMutex::StartRead ( const PDebugLocation & location )

inline

References InternalStartRead().

__inline void PReadWriteMutex::StartWrite ( )

inline

This function attempts to acquire the mutex for writing.

This call may be nested and must have an equal number of EndWrite() calls for the mutex to be released.

Note, if the same thread had a read lock previous to this call then the read lock is automatically released and reacquired when EndWrite() is called, unless an EndRead() is called. The EndRead() and EndWrite() calls do not have to be strictly nested.

It should also be noted that a consequence of this is that another thread may acquire the write lock before the thread that previously had the read lock. Thus it is impossibly to go straight from a read lock to write lock without the possiblility of the object being changed and application logic should take this into account.

References InternalStartWrite().

Referenced by PHTTPSpace::StartWrite().

__inline void PReadWriteMutex::StartWrite ( const PDebugLocation & location )

inline

References InternalStartWrite().

Member Data Documentation

NestMap PReadWriteMutex::m_nestedThreads

protected

PCriticalSection PReadWriteMutex::m_nestingMutex

protected

unsigned PReadWriteMutex::m_readerCount

protected

PTimedMutex PReadWriteMutex::m_readerMutex

protected

PSemaphore PReadWriteMutex::m_readerSemaphore

protected

PTimedMutex PReadWriteMutex::m_starvationPreventer

protected

unsigned PReadWriteMutex::m_writerCount

protected

PTimedMutex PReadWriteMutex::m_writerMutex

protected

PSemaphore PReadWriteMutex::m_writerSemaphore

protected

The documentation for this class was generated from the following file:

syncthrd.h

Classes

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation