| Home | Libraries | People | FAQ | More

## Concepts

Boost.Thread currently supports two types of mutex concepts: ordinary Mutexes, which allow only one thread at a time to access a resource, and Read/Write Mutexes, which allow only one thread at a time to access a resource when it is being modified (the "Write" part of Read/Write), but allows multiple threads to access a resource when it is only being referenced (the "Read" part of Read/Write).

| Note
Unfortunately it turned out that the current implementation of Read/Write Mutex has some serious problems. So it was decided not to put this implementation into release grade code. Also discussions on the mailing list led to the conclusion that the current concepts need to be rethought. In particular the schedulings Inter-Class Scheduling Policies are deemed unnecessary. There seems to be common belief that a fair scheme suffices. The following documentation has been retained however, to give readers of this document the opportunity to study the original design.

### Mutexes

| Note
Certain changes to the mutexes and lock concepts are currently under discussion. In particular, the combination of the multiple lock concepts into a single lock concept is likely, and the combination of the multiple mutex concepts into a single mutex concept is also possible.

A mutex (short for mutual-exclusion) object is used to serialize access to a resource shared between multiple threads. The Mutex concept, with TryMutex and TimedMutex refinements, formalize the requirements. A model that implements Mutex and its refinements has two states: locked and unlocked. Before using a shared resource, a thread locks a Boost.Thread mutex object (an object whose type is a model of Mutex or one of it's refinements), ensuring thread-safe access to the shared resource. When use of the shared resource is complete, the thread unlocks the mutex object, allowing another thread to acquire the lock and use the shared resource.

Traditional C thread APIs, like POSIX threads or the Windows thread APIs, expose functions to lock and unlock a mutex object. This is dangerous since it's easy to forget to unlock a locked mutex. When the flow of control is complex, with multiple return points, the likelihood of forgetting to unlock a mutex object becomes even greater. When exceptions are thrown, it becomes nearly impossible to ensure that the mutex object is unlocked properly when using these traditional API's. The result is deadlock.

Many C++ threading libraries use a pattern known as Scoped Locking [SchmidtStalRohnertBuschmann] to free the programmer from the need to explicitly lock and unlock mutex objects. With this pattern, a Lock concept is employed where the lock object's constructor locks the associated mutex object and the destructor automatically does the unlocking. The Boost.Thread library takes this pattern to the extreme in that Lock concepts are the only way to lock and unlock a mutex object: lock and unlock functions are not exposed by any Boost.Thread mutex objects. This helps to ensure safe usage patterns, especially when code throws exceptions.

#### Locking Strategies

Every mutex object follows one of several locking strategies. These strategies define the semantics for the locking operation when the calling thread already owns a lock on the mutex object.

##### Recursive Locking Strategy

With a recursive locking strategy, when a thread attempts to acquire a lock on the mutex object for which it already owns a lock, the operation is successful. Note the distinction between a thread, which may have multiple locks outstanding on a recursive mutex object, and a lock object, which even for a recursive mutex object cannot have any of its lock functions called multiple times without first calling unlock.

Internally a lock count is maintained and the owning thread must unlock the mutex object the same number of times that it locked it before the mutex object's state returns to unlocked. Since mutex objects in Boost.Thread expose locking functionality only through lock concepts, a thread will always unlock a mutex object the same number of times that it locked it. This helps to eliminate a whole set of errors typically found in traditional C style thread APIs.

Classes `boost::recursive_mutex`, `boost::recursive_try_mutex` and `boost::recursive_timed_mutex` use this locking strategy.

##### Checked Locking Strategy

With a checked locking strategy, when a thread attempts to acquire a lock on the mutex object for which the thread already owns a lock, the operation will fail with some sort of error indication. Further, attempts by a thread to unlock a mutex object that was not locked by the thread will also return some sort of error indication. In Boost.Thread, an exception of type `boost::lock_error` would be thrown in these cases.

Boost.Thread does not currently provide any mutex objects that use this strategy.

##### Unchecked Locking Strategy

With an unchecked locking strategy, when a thread attempts to acquire a lock on a mutex object for which the thread already owns a lock the operation will deadlock. In general this locking strategy is less safe than a checked or recursive strategy, but it's also a faster strategy and so is employed by many libraries.

Boost.Thread does not currently provide any mutex objects that use this strategy.

##### Unspecified Locking Strategy

With an unspecified locking strategy, when a thread attempts to acquire a lock on a mutex object for which the thread already owns a lock the operation results in undefined behavior.

In general a mutex object with an unspecified locking strategy is unsafe, and it requires programmer discipline to use the mutex object properly. However, this strategy allows an implementation to be as fast as possible with no restrictions on its implementation. This is especially true for portable implementations that wrap the native threading support of a platform. For this reason, the classes `boost::mutex`, `boost::try_mutex` and `boost::timed_mutex` use this locking strategy despite the lack of safety.

#### Scheduling Policies

Every mutex object follows one of several scheduling policies. These policies define the semantics when the mutex object is unlocked and there is more than one thread waiting to acquire a lock. In other words, the policy defines which waiting thread shall acquire the lock.

##### FIFO Scheduling Policy

With a FIFO ("First In First Out") scheduling policy, threads waiting for the lock will acquire it in a first-come-first-served order. This can help prevent a high priority thread from starving lower priority threads that are also waiting on the mutex object's lock.

##### Priority Driven Policy

With a Priority Driven scheduling policy, the thread with the highest priority acquires the lock. Note that this means that low-priority threads may never acquire the lock if the mutex object has high contention and there is always at least one high-priority thread waiting. This is known as thread starvation. When multiple threads of the same priority are waiting on the mutex object's lock one of the other scheduling priorities will determine which thread shall acquire the lock.

##### Unspecified Policy

The mutex object does not specify a scheduling policy. In order to ensure portability, all Boost.Thread mutex objects use an unspecified scheduling policy.

#### Mutex Concepts

##### Mutex Concept

A Mutex object has two states: locked and unlocked. Mutex object state can only be determined by a lock object meeting the appropriate lock concept requirements and constructed for the Mutex object.

A Mutex is NonCopyable.

For a Mutex type `M` and an object `m` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.1. Mutex Expressions

Expression | Effects
--- | ---
M m; | Constructs a mutex object m. Postcondition: m is unlocked.
(&m)->~M(); | Precondition: m is unlocked. Destroys a mutex object m.
M::scoped_lock | A model of ScopedLock

##### TryMutex Concept

A TryMutex is a refinement of Mutex. For a TryMutex type `M` and an object `m` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.2. TryMutex Expressions

Expression | Effects
--- | ---
M::scoped_try_lock | A model of ScopedTryLock

##### TimedMutex Concept

A TimedMutex is a refinement of TryMutex. For a TimedMutex type `M` and an object `m` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.3. TimedMutex Expressions

Expression | Effects
--- | ---
M::scoped_timed_lock | A model of ScopedTimedLock

#### Mutex Models

Boost.Thread currently supplies six models of Mutex and its refinements.

Table 15.4. Mutex Models

Concept | Refines | Models
--- | --- | ---
Mutex |  | `boost::mutex` `boost::recursive_mutex`
TryMutex | Mutex | `boost::try_mutex` `boost::recursive_try_mutex`
TimedMutex | TryMutex | `boost::timed_mutex` `boost::recursive_timed_mutex`

#### Lock Concepts

A lock object provides a safe means for locking and unlocking a mutex object (an object whose type is a model of Mutex or one of its refinements). In other words they are an implementation of the Scoped Locking [SchmidtStalRohnertBuschmann] pattern. The ScopedLock, ScopedTryLock, and ScopedTimedLock concepts formalize the requirements.

Lock objects are constructed with a reference to a mutex object and typically acquire ownership of the mutex object by setting its state to locked. They also ensure ownership is relinquished in the destructor. Lock objects also expose functions to query the lock status and to manually lock and unlock the mutex object.

Lock objects are meant to be short lived, expected to be used at block scope only. The lock objects are not thread-safe. Lock objects must maintain state to indicate whether or not they've been locked and this state is not protected by any synchronization concepts. For this reason a lock object should never be shared between multiple threads.

##### Lock Concept

For a Lock type `L` and an object `lk` and const object `clk` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.5. Lock Expressions

Expression | Effects
--- | ---
`(&lk)->~L();` | `if (locked()) unlock();`
`(&clk)->operator const void*()` | Returns type void*, non-zero if the associated mutex object has been locked by `clk`, otherwise 0.
`clk.locked()` | Returns a `bool`, `(&clk)->operator const void*() != 0`
`lk.lock()` | Throws `boost::lock_error` if `locked()`. If the associated mutex object is already locked by some other thread, places the current thread in the Blocked state until the associated mutex is unlocked, after which the current thread is placed in the Ready state, eventually to be returned to the Running state. If the associated mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated mutex object.

Postcondition: `locked() == true`

`lk.unlock()` | Throws `boost::lock_error` if `!locked()`. Unlocks the associated mutex. Postcondition: `!locked()`

##### ScopedLock Concept

A ScopedLock is a refinement of Lock. For a ScopedLock type `L` and an object `lk` of that type, and an object `m` of a type meeting the Mutex requirements, and an object `b` of type `bool`, the following expressions must be well-formed and have the indicated effects.

Table 15.6. ScopedLock Expressions

Expression | Effects
--- | ---
`L lk(m);` | Constructs an object `lk`, and associates mutex object `m` with it, then calls `lock()`
`L lk(m,b);` | Constructs an object `lk`, and associates mutex object `m` with it, then if `b`, calls `lock()`

##### TryLock Concept

A TryLock is a refinement of Lock. For a TryLock type `L` and an object `lk` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.7. TryLock Expressions

Expression | Effects
--- | ---
`lk.try_lock()` | Throws `boost::lock_error` if locked(). Makes a non-blocking attempt to lock the associated mutex object, returning `true` if the lock attempt is successful, otherwise `false`. If the associated mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated mutex object.

##### ScopedTryLock Concept

A ScopedTryLock is a refinement of TryLock. For a ScopedTryLock type `L` and an object `lk` of that type, and an object `m` of a type meeting the TryMutex requirements, and an object `b` of type `bool`, the following expressions must be well-formed and have the indicated effects.

Table 15.8. ScopedTryLock Expressions

Expression | Effects
--- | ---
`L lk(m);` | Constructs an object `lk`, and associates mutex object `m` with it, then calls `try_lock()`
`L lk(m,b);` | Constructs an object `lk`, and associates mutex object `m` with it, then if `b`, calls `lock()`

##### TimedLock Concept

A TimedLock is a refinement of TryLock. For a TimedLock type `L` and an object `lk` of that type, and an object `t` of type `boost::xtime`, the following expressions must be well-formed and have the indicated effects.

Table 15.9. TimedLock Expressions

Expression | Effects
--- | ---
`lk.timed_lock(t)` | Throws `boost::lock_error` if locked(). Makes a blocking attempt to lock the associated mutex object, and returns `true` if successful within the specified time `t`, otherwise `false`. If the associated mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated mutex object.

##### ScopedTimedLock Concept

A ScopedTimedLock is a refinement of TimedLock. For a ScopedTimedLock type `L` and an object `lk` of that type, and an object `m` of a type meeting the TimedMutex requirements, and an object `b` of type `bool`, and an object `t` of type `boost::xtime`, the following expressions must be well-formed and have the indicated effects.

Table 15.10. ScopedTimedLock Expressions

Expression | Effects
--- | ---
`L lk(m,t);` | Constructs an object `lk`, and associates mutex object `m` with it, then calls `timed_lock(t)`
`L lk(m,b);` | Constructs an object `lk`, and associates mutex object `m` with it, then if `b`, calls `lock()`

#### Lock Models

Boost.Thread currently supplies twelve models of Lock and its refinements.

Table 15.11. Lock Models

Concept | Refines | Models
--- | --- | ---
Lock |  |
ScopedLock | Lock | `boost::mutex::scoped_lock` `boost::recursive_mutex::scoped_lock` `boost::try_mutex::scoped_lock` `boost::recursive_try_mutex::scoped_lock` `boost::timed_mutex::scoped_lock`

`boost::recursive_timed_mutex::scoped_lock`

TryLock | Lock |
ScopedTryLock | TryLock | `boost::try_mutex::scoped_try_lock` `boost::recursive_try_mutex::scoped_try_lock` `boost::timed_mutex::scoped_try_lock` `boost::recursive_timed_mutex::scoped_try_lock`
TimedLock | TryLock |
ScopedTimedLock | TimedLock | `boost::timed_mutex::scoped_timed_lock` `boost::recursive_timed_mutex::scoped_timed_lock`

### Read/Write Mutexes

| Note
Unfortunately it turned out that the current implementation has some serious problems. So it was decided not to put this implementation into release grade code. Also discussions on the mailing list led to the conclusion that the current concepts need to be rethought. In particular the schedulings Inter-Class Scheduling Policies are deemed unnecessary. There seems to be common belief that a fair scheme suffices. The following documentation has been retained however, to give readers of this document the opportunity to study the original design.

A read/write mutex (short for reader/writer mutual-exclusion) object is used to serialize access to a resource shared between multiple threads, where multiple "readers" can share simultaneous access, but "writers" require exclusive access. The ReadWriteMutex concept, with TryReadWriteMutex and TimedReadWriteMutex refinements formalize the requirements. A model that implements ReadWriteMutex and its refinements has three states: read-locked, write-locked, and unlocked. Before reading from a shared resource, a thread read-locks a Boost.Thread read/write mutex object (an object whose type is a model of ReadWriteMutex or one of it's refinements), ensuring thread-safe access for reading from the shared resource. Before writing to a shared resource, a thread write-locks a Boost.Thread read/write mutex object (an object whose type is a model of ReadWriteMutex or one of it's refinements), ensuring thread-safe access for altering the shared resource. When use of the shared resource is complete, the thread unlocks the mutex object, allowing another thread to acquire the lock and use the shared resource.

Traditional C thread APIs that provide read/write mutex primitives (like POSIX threads) expose functions to lock and unlock a mutex object. This is dangerous since it's easy to forget to unlock a locked mutex. When the flow of control is complex, with multiple return points, the likelihood of forgetting to unlock a mutex object becomes even greater. When exceptions are thrown, it becomes nearly impossible to ensure that the mutex object is unlocked properly when using these traditional API's. The result is deadlock.

Many C++ threading libraries use a pattern known as Scoped Locking [SchmidtStalRohnertBuschmann] to free the programmer from the need to explicitly lock and unlock read/write mutex objects. With this pattern, a Read/Write Lock concept is employed where the lock object's constructor locks the associated read/write mutex object and the destructor automatically does the unlocking. The Boost.Thread library takes this pattern to the extreme in that Read/Write Lock concepts are the only way to lock and unlock a read/write mutex object: lock and unlock functions are not exposed by any Boost.Thread read/write mutex objects. This helps to ensure safe usage patterns, especially when code throws exceptions.

#### Locking Strategies

Every read/write mutex object follows one of several locking strategies. These strategies define the semantics for the locking operation when the calling thread already owns a lock on the read/write mutex object.

##### Recursive Locking Strategy

With a recursive locking strategy, when a thread attempts to acquire a lock on a read/write mutex object for which it already owns a lock, the operation is successful, except in the case where a thread holding a read-lock attempts to obtain a write lock, in which case a `boost::lock_error` exception will be thrown. Note the distinction between a thread, which may have multiple locks outstanding on a recursive read/write mutex object, and a lock object, which even for a recursive read/write mutex object cannot have any of its lock functions called multiple times without first calling unlock.

Lock Type Held | Lock Type Requested | Action
--- | --- | ---
read-lock | read-lock | Grant the read-lock immediately
read-lock | write-lock | If this thread is the only holder of the read-lock, grants the write lock immediately. Otherwise throws a `boost::lock_error` exception.
write-locked | read-lock | Grants the (additional) read-lock immediately.
write-locked | write-lock | Grant the write-lock immediately

Internally a lock count is maintained and the owning thread must unlock the mutex object the same number of times that it locked it before the mutex object's state returns to unlocked. Since mutex objects in Boost.Thread expose locking functionality only through lock concepts, a thread will always unlock a mutex object the same number of times that it locked it. This helps to eliminate a whole set of errors typically found in traditional C style thread APIs.

Boost.Thread does not currently provide any read/write mutex objects that use this strategy. A successful implementation of this locking strategy may require thread identification.

##### Checked Locking Strategy

With a checked locking strategy, when a thread attempts to acquire a lock on the mutex object for which the thread already owns a lock, the operation will fail with some sort of error indication, except in the case of multiple read-lock acquisition which is a normal operation for ANY ReadWriteMutex. Further, attempts by a thread to unlock a mutex that was not locked by the thread will also return some sort of error indication. In Boost.Thread, an exception of type `boost::lock_error` would be thrown in these cases.

Lock Type Held | Lock Type Requested | Action
--- | --- | ---
read-lock | read-lock | Grant the read-lock immediately
read-lock | write-lock | Throw `boost::lock_error`
write-locked | read-lock | Throw `boost::lock_error`
write-locked | write-lock | Throw `boost::lock_error`

Boost.Thread does not currently provide any read/write mutex objects that use this strategy. A successful implementation of this locking strategy may require thread identification.

##### Unchecked Locking Strategy

With an unchecked locking strategy, when a thread attempts to acquire a lock on the read/write mutex object for which the thread already owns a lock, the operation will deadlock. In general this locking strategy is less safe than a checked or recursive strategy, but it can be a faster strategy and so is employed by many libraries.

Lock Type Held | Lock Type Requested | Action
--- | --- | ---
read-lock | read-lock | Grant the read-lock immediately
read-lock | write-lock | Deadlock
write-locked | read-lock | Deadlock
write-locked | write-lock | Deadlock

Boost.Thread does not currently provide any mutex objects that use this strategy. For ReadWriteMutexes on platforms that contain natively recursive synchronization primitives, implementing a guaranteed-deadlock can actually involve extra work, and would likely require thread identification.

##### Unspecified Locking Strategy

With an unspecified locking strategy, when a thread attempts to acquire a lock on a read/write mutex object for which the thread already owns a lock, the operation results in undefined behavior. When a read/write mutex object has an unspecified locking strategy the programmer must assume that the read/write mutex object instead uses an unchecked strategy as the worse case, although some platforms may exhibit a mix of unchecked and recursive behavior.

Lock Type Held | Lock Type Requested | Action
--- | --- | ---
read-lock | read-lock | Grant the read-lock immediately
read-lock | write-lock | Undefined, but generally deadlock
write-locked | read-lock | Undefined, but generally deadlock
write-locked | write-lock | Undefined, but generally deadlock

In general a read/write mutex object with an unspecified locking strategy is unsafe, and it requires programmer discipline to use the read/write mutex object properly. However, this strategy allows an implementation to be as fast as possible with no restrictions on its implementation. This is especially true for portable implementations that wrap the native threading support of a platform. For this reason, the classes `read_write_mutex`, `try_read_write_mutex`, and `timed_read_write_mutex` use this locking strategy despite the lack of safety.

##### Thread Identification

ReadWriteMutexes can support specific Locking Strategies (recursive and checked) which help to detect and protect against self-deadlock. Self-deadlock can occur when a holder of a locked ReadWriteMutex attempts to obtain another lock. Given an implemention I which is susceptible to self-deadlock but otherwise correct and efficient, a recursive or checked implementation Ir or Ic can use the same basic implementation, but make special checks against self-deadlock by tracking the identities of thread(s) currently holding locks. This approach makes deadlock detection othrogonal to the basic ReadWriteMutex implementaion.

Alternatively, a different basic implementation for ReadWriteMutex concepts, I' (I-Prime) may exist which uses recursive or checked versions of synchronization primitives to produce a recursive or checked ReadWriteMutex while still providing flexibility in terms of Scheduling Policies.

Please refer to the Boost.Thread read/write mutex concept documentation for a discussion of locking strategies. The read/write mutex supports only the unspecified locking strategy. ReadWriteMutexes are parameterized on a Mutex type which they use to control write-locking and access to internal state.

##### Lock Promotion

ReadWriteMutexes can support lock promotion, where a mutex which is in the read-locked state transitions to a write-locked state without releasing the lock. Lock promotion can be tricky to implement; for instance, extra care must be taken to ensure that only one thread holding a read-lock can block awaiting promotion at any given time. If more than one read-lock holder is allowed to enter a blocked state while waiting to be promoted, deadlock will result since both threads will be waiting for the other to release their read-lock.

Currently, Boost.Thread supports lock promotion through `promote()`, `try_promote()`, and `timed_promote()` operations.

##### Lock Demotion

ReadWriteMutexes can support lock demotion, where a mutex which is in the write-locked state transitions to a read-locked state without releasing the lock. Since by definition only one thread at a time may hold a write-lock, the problem with deadlock that can occur during lock promotion is not a problem for lock demotion.

Currently, Boost.Thread supports lock demotion through `demote()`, `try_demote()`, and `timed_demote()` operations.

#### Scheduling Policies

Every read/write mutex object follows one of several scheduling policies. These policies define the semantics when the mutex object is unlocked and there is more than one thread waiting to acquire a lock. In other words, the policy defines which waiting thread shall acquire the lock. For a read/write mutex, it is particularly important to define the behavior when threads are requesting both read and write access simultaneously. This will be referred to as "inter-class scheduling" because it describes the scheduling between two classes of threads (those waiting for a read lock and those waiting for a write lock).

For some types of inter-class scheduling, an "intra-class" scheduling policy can also be defined that will describe the order in which waiting threads of the same class (i.e., those waiting for the same type of lock) will acquire the thread.

##### Inter-Class Scheduling Policies

###### ReaderPriority

With ReaderPriority scheduling, any pending request for a read-lock will have priority over a pending request for a write-lock, irrespective of the current lock state of the read/write mutex, and irrespective of the relative order that the pending requests arrive.

Current mutex state | Request Type | Action
--- | --- | ---
unlocked | read-lock | Grant the read-lock immediately
read-locked | read-lock | Grant the additional read-lock immediately.
write-locked | read-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock (or until the specified time, if any). A read-lock will be granted to all pending readers before any other thread can acquire a write-lock. TODO: try-lock, timed-lock.
unlocked | write-lock | Grant the write-lock immediately, if and only if there are no pending read-lock requests. TODO: try-lock, timed-lock.
read-locked | write-lock | Wait to acquire the lock until all threads holding read-locks release their locks AND no requests for read-locks exist. If other write-lock requests exist, the lock is granted in accordance with the intra-class scheduling policy. TODO: try-lock, timed-lock.
write-locked | write-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock AND no requests for read-locks exist. If other write-lock requests exist, the lock is granted in accordance with the intra-class scheduling policy. TODO: try-lock, timed-lock.
read-locked | promote | TODO
write-locked | demote | TODO

###### WriterPriority

With WriterPriority scheduling, any pending request for a write-lock will have priority over a pending request for a read-lock, irrespective of the current lock state of the read/write mutex, and irrespective of the relative order that the pending requests arrive.

Current mutex state | Request Type | Action
--- | --- | ---
unlocked | read-lock | Grant the read-lock immediately.
read-locked | read-lock | Grant the additional read-lock immediately, IF no outstanding requests for a write-lock exist; otherwise TODO. TODO: try-lock, timed-lock.
write-locked | read-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock. The read lock will be granted once no other outstanding write-lock requests exist. TODO: try-lock, timed-lock.
unlocked | write-lock | Grant the write-lock immediately.
read-locked | write-lock | Wait to acquire the lock until all threads holding read-locks release their locks. If other write-lock requests exist, the lock is granted in accordance with the intra-class scheduling policy. This request will be granted before any new read-lock requests are granted.

TODO: try-lock, timed-lock.

write-locked | write-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock. If other write-lock requests exist, the lock is granted in accordance with the intra-class scheduling policy. This request will be granted before any new read-lock requests are granted.

TODO: try-lock, timed-lock.

read-locked | promote | TODO
write-locked | demote | TODO

###### AlternatingPriority/ManyReads

With AlternatingPriority/ManyReads scheduling, reader or writer starvation is avoided by alternatively granting read or write access when pending requests exist for both types of locks. Outstanding read-lock requests are treated as a group when it is the "readers' turn"

Current mutex state | Request Type | Action
--- | --- | ---
unlocked | read-lock | Grant the read-lock immediately.
read-locked | read-lock | Grant the additional read-lock immediately, IF no outstanding requests for a write-lock exist. If outstanding write-lock requests exist, this lock will not be granted until at least one of the write-locks is granted and released. If other read-lock requests exist, all read-locks will be granted as a group.

TODO: try-lock, timed-lock.

write-locked | read-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock. If other outstanding write-lock requests exist, they will have to wait until all current read-lock requests are serviced. TODO: try-lock, timed-lock.
unlocked | write-lock | Grant the write-lock immediately.
read-locked | write-lock | Wait to acquire the lock until all threads holding read-locks release their locks. If other write-lock requests exist, this lock will be granted to one of them in accordance with the intra-class scheduling policy. TODO: try-lock, timed-lock.
write-locked | write-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock. If other outstanding read-lock requests exist, this lock will not be granted until all of the currently waiting read-locks are granted and released. If other write-lock requests exist, this lock will be granted in accordance with the intra-class scheduling policy.

TODO: try-lock, timed-lock.

read-locked | promote | TODO
write-locked | demote | TODO

###### AlternatingPriority/SingleRead

With AlternatingPriority/SingleRead scheduling, reader or writer starvation is avoided by alternatively granting read or write access when pending requests exist for both types of locks. Outstanding read-lock requests are services one at a time when it is the "readers' turn"

Current mutex state | Request Type | Action
--- | --- | ---
unlocked | read-lock | Grant the read-lock immediately.
read-locked | read-lock | Grant the additional read-lock immediately, IF no outstanding requests for a write-lock exist. If outstanding write-lock requests exist, this lock will not be granted until at least one of the write-locks is granted and released. TODO: try-lock, timed-lock.
write-locked | read-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock. If other outstanding write-lock requests exist, exactly one read-lock request will be granted before the next write-lock is granted. TODO: try-lock, timed-lock.
unlocked | write-lock | Grant the write-lock immediately.
read-locked | write-lock | Wait to acquire the lock until all threads holding read-locks release their locks. If other write-lock requests exist, this lock will be granted to one of them in accordance with the intra-class scheduling policy.
write-locked | write-lock | Wait to acquire the lock until the thread holding the write-lock releases its lock. If other outstanding read-lock requests exist, this lock can not be granted until exactly one read-lock request is granted and released. If other write-lock requests exist, this lock will be granted in accordance with the intra-class scheduling policy.

TODO: try-lock, timed-lock.

read-locked | promote | TODO
write-locked | demote | TODO

##### Intra-Class Scheduling Policies

Please refer to the section called “Scheduling Policies” for a discussion of mutex scheduling policies, which are identical to read/write mutex intra-class scheduling policies.

For threads waiting to obtain write-locks, the read/write mutex supports only the Unspecified intra-class scheduling policy. That is, given a set of threads waiting for write-locks, the order, relative to one another, in which they receive the write-lock is unspecified.

For threads waiting to obtain read-locks, the read/write mutex supports only the Unspecified intra-class scheduling policy. That is, given a set of threads waiting for read-locks, the order, relative to one another, in which they receive the read-lock is unspecified.

#### Mutex Concepts

##### ReadWriteMutex Concept

A ReadWriteMutex object has three states: read-locked, write-locked, and unlocked. ReadWriteMutex object state can only be determined by a lock object meeting the appropriate lock concept requirements and constructed for the ReadWriteMutex object.

A ReadWriteMutex is NonCopyable.

For a ReadWriteMutex type `M`, and an object `m` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.12. ReadWriteMutex Expressions

Expression | Effects
--- | ---
`M m;` | Constructs a read/write mutex object `m`. Post-condition: `m` is unlocked.
`(&m)->~M();` | Precondition: `m` is unlocked. Destroys a read/write mutex object `m`.
`M::scoped_read_write_lock` | A type meeting the ScopedReadWriteLock requirements.
`M::scoped_read_lock` | A type meeting the ScopedLock requirements.
`M::scoped_write_lock` | A type meeting the ScopedLock requirements.

##### TryReadWriteMutex Concept

A TryReadWriteMutex is a refinement of ReadWriteMutex. For a TryReadWriteMutex type `M` and an object `m` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.13. TryReadWriteMutex Expressions

Expression | Effects
--- | ---
`M::scoped_try_read_write_lock` | A type meeting the ScopedTryReadWriteLock requirements.
`M::scoped_try_read_lock` | A type meeting the ScopedTryLock requirements.
`M::scoped_try_write_lock` | A type meeting the ScopedTryLock requirements.

##### TimedReadWriteMutex Concept

A TimedReadWriteMutex is a refinement of TryReadWriteMutex. For a TimedReadWriteMutex type `M` and an object `m` of that type the following expressions must be well-formed and have the indicated effects.

Table 15.14. TimedReadWriteMutex Expressions

Expression | Effects
--- | ---
`M::scoped_timed_read_write_lock` | A type meeting the ScopedTimedReadWriteLock requirements.
`M::scoped_timed_read_lock` | A type meeting the ScopedTimedLock requirements.
`M::scoped_timed_write_lock` | A type meeting the ScopedTimedLock requirements.

#### Mutex Models

Boost.Thread currently supplies three models of ReadWriteMutex and its refinements.

Table 15.15. Mutex Models

Concept | Refines | Models
--- | --- | ---
ReadWriteMutex |  | `boost::read_write_mutex`
TryReadWriteMutex | ReadWriteMutex | `boost::try_read_write_mutex`
TimedReadWriteMutex | TryReadWriteMutex | `boost::timed_read_write_mutex`

#### Lock Concepts

A read/write lock object provides a safe means for locking and unlocking a read/write mutex object (an object whose type is a model of ReadWriteMutex or one of its refinements). In other words they are an implementation of the Scoped Locking [SchmidtStalRohnertBuschmann] pattern. The ScopedReadWriteLock, ScopedTryReadWriteLock, and ScopedTimedReadWriteLock concepts formalize the requirements.

Read/write lock objects are constructed with a reference to a read/write mutex object and typically acquire ownership of the read/write mutex object by setting its state to locked. They also ensure ownership is relinquished in the destructor. Lock objects also expose functions to query the lock status and to manually lock and unlock the read/write mutex object.

Read/write lock objects are meant to be short lived, expected to be used at block scope only. The read/write lock objects are not thread-safe. Read/write lock objects must maintain state to indicate whether or not they've been locked and this state is not protected by any synchronization concepts. For this reason a read/write lock object should never be shared between multiple threads.

##### ReadWriteLock Concept

For a read/write lock type `L` and an object `lk` and const object `clk` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.16. ReadWriteLock Expressions

Expression | Effects
--- | ---
`(&lk)->~L();` | `if (locked()) unlock();`
`(&clk)->operator const void*()` | Returns type void*, non-zero if the associated read/write mutex object has been either read-locked or write-locked by `clk`, otherwise 0.
`clk.locked()` | Returns a `bool`, `(&clk)->operator const void*() != 0`
`clk.state()` | Returns an enumeration constant of type `read_write_lock_state`: `read_write_lock_state::read_locked` if the associated read/write mutex object has been read-locked by `clk`, `read_write_lock_state::write_locked` if it has been write-locked by `clk`, and `read_write_lock_state::unlocked` if has not been locked by `clk`.
`clk.read_locked()` | Returns a `bool`, `(&clk)->state() == read_write_lock_state::read_locked`.
`clk.write_locked()` | Returns a `bool`, `(&clk)->state() == read_write_lock_state::write_locked`.
`lk.read_lock()` | Throws `boost::lock_error` if `locked()`. If the associated read/write mutex object is already read-locked by some other thread, the effect depends on the inter-class scheduling policy of the associated read/write mutex: either immediately obtains an additional read-lock on the associated read/write mutex, or places the current thread in the Blocked state until the associated read/write mutex is unlocked, after which the current thread is placed in the Ready state, eventually to be returned to the Running state.

If the associated read/write mutex object is already write-locked by some other thread, places the current thread in the Blocked state until the associated read/write mutex is unlocked, after which the current thread is placed in the Ready state, eventually to be returned to the Running state.

If the associated read/write mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated read/write mutex object.

Postcondition: `state() == read_write_lock_state::read_locked`

`lk.write_lock()` | Throws `boost::lock_error` if `locked()`. If the associated read/write mutex object is already locked by some other thread, places the current thread in the Blocked state until the associated read/write mutex is unlocked, after which the current thread is placed in the Ready state, eventually to be returned to the Running state.

If the associated read/write mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated read/write mutex object.

Postcondition: `state() == read_write_lock_state::write_locked`

`lk.demote()` | Throws `boost::lock_error` if `state() != read_write_lock_state::write_locked`. Converts the lock held on the associated read/write mutex object from a write-lock to a read-lock without releasing the lock. Postcondition: `state() == read_write_lock_state::read_locked`
`lk.promote()` | Throws `boost::lock_error` if `state() != read_write_lock_state::read_locked` or if the lock cannot be promoted because another lock on the same mutex is already waiting to be promoted. Makes a blocking attempt to convert the lock held on the associated read/write mutex object from a read-lock to a write-lock without releasing the lock.
`lk.unlock()` | Throws `boost::lock_error` if `!locked()`. Unlocks the associated read/write mutex. Postcondition: `!locked()`

##### ScopedReadWriteLock Concept

A ScopedReadWriteLock is a refinement of ReadWriteLock. For a ScopedReadWriteLock type `L` and an object `lk` of that type, and an object `m` of a type meeting the ReadWriteMutex requirements, and an object `s` of type `read_write_lock_state`, the following expressions must be well-formed and have the indicated effects.

Table 15.17. ScopedReadWriteLock Expressions

Expression | Effects
--- | ---
`L lk(m,s);` | Constructs an object `lk` and associates read/write mutex object `m` with it, then: if `s == read_write_lock_state::read_locked`, calls `read_lock()`; if `s==read_write_lock_state::write_locked`, calls `write_lock()`.

##### TryReadWriteLock Expressions

A TryReadWriteLock is a refinement of ReadWriteLock. For a TryReadWriteLock type `L` and an object `lk` of that type, the following expressions must be well-formed and have the indicated effects.

Table 15.18. TryReadWriteLock Expressions

Expression | Effects
--- | ---
`lk.try_read_lock()` | Throws `boost::lock_error` if locked(). Makes a non-blocking attempt to read-lock the associated read/write mutex object, returning `true` if the attempt is successful, otherwise `false`. If the associated read/write mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated read/write mutex object.
`lk.try_write_lock()` | Throws `boost::lock_error` if locked(). Makes a non-blocking attempt to write-lock the associated read/write mutex object, returning `true` if the attempt is successful, otherwise `false`. If the associated read/write mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated read/write mutex object.
`lk.try_demote()` | Throws `boost::lock_error` if `state() != read_write_lock_state::write_locked`. Makes a non-blocking attempt to convert the lock held on the associated read/write mutex object from a write-lock to a read-lock without releasing the lock, returning `true` if the attempt is successful, otherwise `false`.
`lk.try_promote()` | Throws `boost::lock_error` if `state() != read_write_lock_state::read_locked`. Makes a non-blocking attempt to convert the lock held on the associated read/write mutex object from a read-lock to a write-lock without releasing the lock, returning `true` if the attempt is successful, otherwise `false`.

##### ScopedTryReadWriteLock Expressions

A ScopedTryReadWriteLock is a refinement of TryReadWriteLock. For a ScopedTryReadWriteLock type `L` and an object `lk` of that type, and an object `m` of a type meeting the TryReadWriteMutex requirements, and an object `s` of type `read_write_lock_state`, and an object `b` of type `blocking_mode`, the following expressions must be well-formed and have the indicated effects.

Table 15.19. ScopedTryReadWriteLock Expressions

Expression | Effects
--- | ---
`L lk(m,s,b);` | Constructs an object `lk` and associates read/write mutex object `m` with it, then: if `s == read_write_lock_state::read_locked`, calls `read_lock()` if `b`, otherwise `try_read_lock()`; if `s==read_write_lock_state::write_locked`, calls `write_lock()` if `b`, otherwise `try_write_lock`.

##### TimedReadWriteLock Concept

A TimedReadWriteLock is a refinement of TryReadWriteLock. For a TimedReadWriteLock type `L` and an object `lk` of that type, and an object `t` of type `boost::xtime`, the following expressions must be well-formed and have the indicated effects.

Table 15.20. TimedReadWriteLock Expressions

Expression | Effects
--- | ---
`lk.timed_read_lock(t)` | Throws `boost::lock_error` if locked(). Makes a blocking attempt to read-lock the associated read/write mutex object, and returns `true` if successful within the specified time `t`, otherwise `false`. If the associated read/write mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated read/write mutex object.
`lk.timed_write_lock(t)` | Throws `boost::lock_error` if locked(). Makes a blocking attempt to write-lock the associated read/write mutex object, and returns `true` if successful within the specified time `t`, otherwise `false`. If the associated read/write mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated read/write mutex object.
`lk.timed_demote(t)` | Throws `boost::lock_error` if `state() != read_write_lock_state::write_locked`. Makes a blocking attempt to convert the lock held on the associated read/write mutex object from a write-lock to a read-lock without releasing the lock, returning `true` if the attempt is successful in the specified time `t`, otherwise `false`.
`lk.timed_promote(t)` | Throws `boost::lock_error` if `state() != read_write_lock_state::read_locked`. Makes a blocking attempt to convert the lock held on the associated read/write mutex object from a read-lock to a write-lock without releasing the lock, returning `true` if the attempt is successful in the specified time `t`, otherwise `false`.

##### ScopedTimedReadWriteLock Concept

A ScopedTimedReadWriteLock is a refinement of TimedReadWriteLock. For a ScopedTimedReadWriteLock type `L` and an object `lk` of that type, and an object `m` of a type meeting the TimedReadWriteMutex requirements, and an object `s` of type `read_write_lock_state`, and an object `t` of type `boost::xtime`, and an object `b` of type `blocking_mode`, the following expressions must be well-formed and have the indicated effects.

Table 15.21. ScopedTimedReadWriteLock Expressions

Expression | Effects
--- | ---
`L lk(m,s,b);` | Constructs an object `lk` and associates read/write mutex object `m` with it, then: if `s == read_write_lock_state::read_locked`, calls `read_lock()` if `b`, otherwise `try_read_lock()`; if `s==read_write_lock_state::write_locked`, calls `write_lock()` if `b`, otherwise `try_write_lock`.
`L lk(m,s,t);` | Constructs an object `lk` and associates read/write mutex object `m` with it, then: if `s == read_write_lock_state::read_locked`, calls `timed_read_lock(t)`; if `s==read_write_lock_state::write_locked`, calls `timed_write_lock(t)`.

#### Lock Models

Boost.Thread currently supplies six models of ReadWriteLock and its refinements.

Table 15.22. Lock Models

Concept | Refines | Models
--- | --- | ---
ReadWriteLock |  |
ScopedReadWriteLock | ReadWriteLock | `boost::read_write_mutex::scoped_read_write_lock` `boost::try_read_write_mutex::scoped_read_write_lock` `boost::timed_read_write_mutex::scoped_read_write_lock`
TryReadWriteLock | ReadWriteLock |
ScopedTryReadWriteLock | TryReadWriteLock | `boost::try_read_write_mutex::scoped_try_read_write_lock` `boost::timed_read_write_mutex::scoped_try_read_write_lock`
TimedReadWriteLock | TryReadWriteLock |
ScopedTimedReadWriteLock | TimedReadWriteLock | `boost::timed_read_write_mutex::scoped_timed_read_write_lock`

Last revised: January 02, 2007 at 21:44:39 GMT | Copyright © 2001-2003 William E. Kempf