| Home | Libraries | People | FAQ | More

### Concepts

#### 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.Threads 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.Threads 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.Threads 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.Threads 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.Threads, an exception of type `boost::lock_error` would be thrown in these cases.

Boost.Threads 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.Threads 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.Threads 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 12.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 12.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 12.3. TimedMutex Expressions

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

##### Mutex Models

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

Table 12.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 12.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 12.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 12.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 12.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 12.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 12.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.Threads currently supplies twelve models of Lock and its refinements.

Table 12.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`

Last revised: October 16, 2005 at 14:37:34 GMT | Copyright © 2001-2003 William E. Kempf