PReadWriteMutex Class Reference

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

`#include <syncthrd.h>`

Inheritance diagram for PReadWriteMutex:

## Classes

class | Nest

## Public Member Functions

Construction
| PReadWriteMutex ()
| ~PReadWriteMutex ()
Operations
void | StartRead ()
| This function attempts to acquire the mutex for reading. More...
void | EndRead ()
| This function attempts to release the mutex for reading. More...
void | StartWrite ()
| This function attempts to acquire the mutex for writing. More...
void | EndWrite ()
| This function attempts to release the mutex for writing. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
virtual PINDEX | HashFunction () const
| This function yields a hash value required by the `PDictionary` class. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified 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 | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. More...

## Protected Types

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

## Protected Member Functions

Nest * | GetNest ()
Nest & | StartNest ()
void | EndNest ()
void | InternalStartRead ()
void | InternalEndRead ()
void | InternalWait (PSemaphore &semaphore) const
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes

PSemaphore | readerSemaphore
PMutex | readerMutex
unsigned | readerCount
PMutex | starvationPreventer
PSemaphore | writerSemaphore
PMutex | writerMutex
unsigned | writerCount
NestMap | m_nestedThreads
PMutex | m_nestingMutex

## 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 const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...

## 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.

## Member Typedef Documentation

## NestMap

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

protected

## Constructor & Destructor Documentation

## PReadWriteMutex()

PReadWriteMutex::PReadWriteMutex | ( |  | ) |

## ~PReadWriteMutex()

PReadWriteMutex::~PReadWriteMutex | ( |  | ) |

## Member Function Documentation

## EndNest()

void PReadWriteMutex::EndNest | ( |  | ) |

protected

## EndRead()

void PReadWriteMutex::EndRead | ( |  | ) |

This function attempts to release the mutex for reading.

Referenced by PHTTPSpace::EndRead().

## EndWrite()

void PReadWriteMutex::EndWrite | ( |  | ) |

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.

Referenced by PHTTPSpace::EndWrite().

## GetNest()

Nest* PReadWriteMutex::GetNest | ( |  | ) |

protected

## InternalEndRead()

void PReadWriteMutex::InternalEndRead | ( |  | ) |

protected

## InternalStartRead()

void PReadWriteMutex::InternalStartRead | ( |  | ) |

protected

## InternalWait()

void PReadWriteMutex::InternalWait | ( | PSemaphore & | semaphore | ) | const

protected

## StartNest()

Nest& PReadWriteMutex::StartNest | ( |  | ) |

protected

## StartRead()

void PReadWriteMutex::StartRead | ( |  | ) |

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.

Referenced by PHTTPSpace::StartRead().

## StartWrite()

void PReadWriteMutex::StartWrite | ( |  | ) |

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.

Referenced by PHTTPSpace::StartWrite().

## Member Data Documentation

## m_nestedThreads

NestMap PReadWriteMutex::m_nestedThreads

protected

## m_nestingMutex

PMutex PReadWriteMutex::m_nestingMutex

protected

## readerCount

unsigned PReadWriteMutex::readerCount

protected

## readerMutex

PMutex PReadWriteMutex::readerMutex

protected

## readerSemaphore

PSemaphore PReadWriteMutex::readerSemaphore

protected

## starvationPreventer

PMutex PReadWriteMutex::starvationPreventer

protected

## writerCount

unsigned PReadWriteMutex::writerCount

protected

## writerMutex

PMutex PReadWriteMutex::writerMutex

protected

## writerSemaphore

PSemaphore PReadWriteMutex::writerSemaphore

protected

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

- syncthrd.h