# ReaderWriterMutex Concept

The ReaderWriterMutex concept extends the Mutex Concept to include the notion of reader-writer locks. It introduces a boolean parameter `write` that specifies whether a writer lock (`write` =true) or reader lock (`write` =false) is being requested. Multiple reader locks can be held simultaneously on a ReaderWriterMutex if it does not have a writer lock on it. A writer lock on a ReaderWriterMutex excludes all other threads from holding a lock on the mutex at the same time.

The following table shows the requirements for a ReaderWriterMutex `RW`. They form a superset of the Mutex Concept.

ReaderWriterMutex Concept
Pseudo-Signature | Semantics
--- | ---
`RW()` | Construct unlocked mutex.
`~RW()` | Destroy unlocked mutex.
`typename RW::scoped_lock` | Corresponding scoped-lock type.
`RW::scoped_lock()` | Construct lock without acquiring mutex.
`RW::scoped_lock(RW&, bool write=true)` | Construct lock and acquire lock on mutex.
`RW::~scoped_lock()` | Release lock (if acquired).
`RW::scoped_lock::acquire(RW&,bool write=true)` | Acquire lock on mutex.
`bool RW::scoped_lock::try_acquire(RW&, bool write=true)` | Try to acquire lock on mutex. Return `true` if lock acquired, `false` otherwise.
`RW::scoped_lock::release()` | Release lock.
`bool RW::scoped_lock::upgrade_to_writer()` | Change reader lock to writer lock.
`bool RW::scoped_lock::downgrade_to_reader()` | Change writer lock to reader lock.
`static const bool RW::is_rw_mutex = true` | True.
`static const bool RW::is_recursive_mutex` | True if mutex is recursive; false otherwise. For all current reader-writer mutexes, false.
`static const bool RW::is_fair_mutex` | True if mutex is fair; false otherwise.

The following table provides explain the semantics of the ReaderWriterMutex concept in detail.
Member | Description
--- | ---
Model Types | Classes ``spin_rw_mutex`` and ``queuing_rw_mutex`` model the ReaderWriterMutex concept.
ReaderWriterMutex() | Constructs unlocked `ReaderWriterMutex`.
~ReaderWriterMutex() | Destroys unlocked `ReaderWriterMutex`. The effect of destroying a locked `ReaderWriterMutex` is undefined.
ReaderWriterMutex::scoped_lock() | Constructs a `scoped_lock` object that does not hold a lock on any mutex.
ReaderWriterMutex::scoped_lock( ReaderWriterMutex& rw, bool write =true) | Constructs a `scoped_lock` object that acquires a lock on mutex rw. The lock is a writer lock if `write` is true; a reader lock otherwise.
ReaderWriterMutex::~scoped_lock() | If the object holds a lock on a `ReaderWriterMutex`, releases the lock.
void ReaderWriterMutex:: scoped_lock:: acquire( ReaderWriterMutex& rw, bool write=true ) | Acquires a lock on mutex rw. The lock is a writer lock if `write` is true; a reader lock otherwise.
bool ReaderWriterMutex:: scoped_lock::try_acquire( ReaderWriterMutex& rw, bool write=true ) | Attempts to acquire a lock on mutex rw. The lock is a writer lock if `write` is true; a reader lock otherwise. Returns: `true` if the lock is acquired, `false` otherwise.
void ReaderWriterMutex:: scoped_lock::release() | Releases lock. The effect is undefined if no lock is held. Returns: `false` if lock was released in favor of another upgrade request and then reacquired; `true` otherwise.
bool ReaderWriterMutex:: scoped_lock::upgrade_to_writer() | Changes reader lock to a writer lock. The effect is undefined if the object does not already hold a reader lock. Returns: `false` if lock was released and reacquired; `true` otherwise.
bool ReaderWriterMutex:: scoped_lock::downgrade_to_reader() | Changes writer lock to a reader lock. The effect is undefined if the object does not already hold a writer lock. Returns: `false` if lock was released and reacquired; `true` otherwise. Intel's current implementations for `spin_rw_mutex` and `queuing_rw_mutex` always return `true`. Different implementations might sometimes return `false`.

Parent topic: Mutexes