###  | # Boost.Threads ## Lock Concepts

Introduction
Concept Requirements
Lock Concept
ScopedLock Concept
ScopedTryLock Concept
ScopedTimedLock Concept
Models

## Introduction

The lock concepts provide exception safe means for locking and unlocking a mutex model. In other words they are an implementation of the Scoped Locking [Schmidt 00] pattern. The ScopedLock concept, with ScopedTryLock and ScopedTimedLock refinements, formalize the requirements.

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

Instances of lock models are meant to be short lived, expected to be used at block scope only. The lock models are not thread-safe. Lock models 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 an instance of a lock model should never be shared between multiple threads.

## Concept Requirements

[For documentation purposes, portions of the concept requirements are repeated in the documentation for specific lock classes. Those copies need to be kept in sync with the requirements here.]

### Lock Concept

For a ScopedLock, ScopedTryLock, or ScopedTimedLock 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.

The Lock concept is used as a base for the ScopedLock, ScopedTryLock, and ScopedTimedLock refinements. The associated mutex type is as specified for each of those refinements respectively.

Expression | Effects
`(&lk)->~L();` | `if (locked()) unlock();`
`(&clk)->operator const void*()` | Returns type void*, non-zero if if the associated mutex has been locked by `clk`, otherwise 0.
`clk.locked()` | Returns a `bool`, `(&clk)->operator const void*() != 0`
`lk.lock()` | Throws lock_error if locked(). If the associated mutex 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. Postcondition: locked()
`lk.unlock()` | If !locked(), throws lock_error, otherwise unlocks the associated mutex. Postcondition: !locked()

### ScopedLock Concept

A ScopedLock must meet the Lock requirements. 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.

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

### ScopedTryLock Concept

A ScopedTryLock must meet the Lock requirements. 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.

Expression | Effects
`L lk(m);` | Constructs an object `lk`, and associates mutex `m` with it, then calls `try_lock()`
`L lk(m,b);` | Constructs an object `lk`, and associates mutex `m` with it, then if `b`, calls `lock()`
`lk.try_lock()` | If locked(), throws `lock_error`. Makes a non-blocking attempt to lock the associated mutex, returning `true` if the lock attempt is successful, otherwise `false`.

### ScopedTimedLock Concept

A ScopedTimedLock must meet the Lock requirements. 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 `xtime`, the following expressions must be well-formed and have the indicated effects.

Expression | Effects
`L lk(m,t);` | Constructs an object `lk`, and associates mutex `m` with it, then calls `timed_lock(t)`
`L lk(m,b);` | Constructs an object `lk`, and associates mutex `m` with it, then if `b`, calls `lock()`
`lk.timed_lock(t)` | If locked(), throws lock_error. Makes a blocking attempt to lock the associated mutex, and returns `true` if successful within the specified time `t`, otherwise `false`.

## Models

Boost.Threads currently supplies three classes which model lock concepts.

These classes are normally accessed via typedefs of the same name supplied by a mutex model.

Concept | Refines | Classes Modeling the Concept
ScopedLock |  | scoped_lock
ScopedTryLock | ScopedLock | scoped_try_lock
ScopedTimedLock | ScopedLock | scoped_timed_lock

Revised 05 November, 2001

© Copyright William E. Kempf 2001 all rights reserved.