Boost.Flyweight Documentation - Locking policies reference

# Boost.Flyweight Locking policies reference

Holders
Boost.Flyweight reference
Tracking policies

## Contents

- Preliminary concepts
- Locking policies
- Header `"boost/flyweight/locking_tag.hpp"` synopsis
  - Class template `is_locking`
  - Class template `locking`
- Header `"boost/flyweight/simple_locking_fwd.hpp"` synopsis
- Header `"boost/flyweight/simple_locking.hpp"` synopsis
  - Class `simple_locking`
- Header `"boost/flyweight/no_locking_fwd.hpp"` synopsis
- Header `"boost/flyweight/no_locking.hpp"` synopsis
  - Class `no_locking`

## Preliminary concepts

A mutex is a type whose objects can be in either of two states, called locked and unlocked, with the property that when a thread A has locked a mutex `m` and a different thread B tries to lock `m`, B is blocked until A unlocks `m`. Additionally, a mutex is said to support recursive locking if a thread can succesfully invoke the locking operation for a mutex already locked by this same thread; in this case, it is required that the thread execute as many unlock operations as lock operations it has performed for the mutex to become effectively unlocked. A scoped lock is a type associated to some mutex type whose objects do the locking/unlocking of a mutex on construction/destruction time.

In the following table, `Mutex` is a mutex type, `m` is an object of type `Mutex`, `Lock` is a scoped lock associated to `Mutex` and `lk` is a value of `Lock`.

Mutex and Scoped Lock requirements.
expression | return type | assertion/note pre/post-condition
--- | --- | ---
`Mutex m;` |  | Post: `m` is unlocked.
`(&m)->~Mutex();` | `void` | Pre: `m` is unlocked.
`Lock lk(m);` |  | Associates `m` to `lk` and locks `m`.
`(&lk)->~Lock();` | `void` | Unlocks the mutex associated to `lk`.

These concepts are very similar, but not entirely equivalent, to the homonym ones described in the Boost Thread Library.

## Locking policies

Locking policies describe a mutex type and an associated scoped lock type. `flyweight` uses a given locking policy to synchronize the access to its internal factory.

A type `Locking` is a locking policy if:

- One of the following conditions is satisfied:
  1. `is_locking<Locking>::type` is `boost::mpl::true_`,
  2. `Locking` is of the form `locking<Locking'>`.
- The type `Locking::mutex_type` (or `Locking'::mutex_type` if (b) applies) is a model of `Mutex` and supports recursive locking.
- The type `Locking::lock_type` (or `Locking'::lock_type` if (b) applies) is a `Scoped Lock` of the mutex referred to above.

## Header `"boost/flyweight/locking_tag.hpp"` synopsis

>     namespace boost{

>     namespace flyweights{

>     struct locking_marker;

>     template<typename T>
>     struct is_locking

>     template<typename T>
>     struct locking;

>     } // namespace boost::flyweights

>     } // namespace boost

### Class template `is_locking`

Unless specialized by the user, `is_locking<T>::type` is `boost::mpl::true_` if `T` is derived from `locking_marker`, and it is `boost::mpl::false_` otherwise.

### Class template `locking`

`locking<T>` is a syntactic construct meant to indicate that `T` is a locking policy without resorting to the mechanisms provided by the `is_locking` class template.

## Header `"boost/flyweight/simple_locking_fwd.hpp"` synopsis

>     namespace boost{

>     namespace flyweights{

>     struct simple_locking;

>     } // namespace boost::flyweights

>     } // namespace boost

`simple_locking_fwd.hpp` forward declares the class `simple_locking`.

## Header `"boost/flyweight/simple_locking.hpp"` synopsis

### Class `simple_locking`

`Locking Policy` that specifies a basic mutex type based on the simplest synchronization mechanisms provided by the environment; When no threading capabilities are available, `simple_locking` specifies a dummy type without actual synchronization capabilities.

## Header `"boost/flyweight/no_locking_fwd.hpp"` synopsis

>     namespace boost{

>     namespace flyweights{

>     struct no_locking;

>     } // namespace boost::flyweights

>     } // namespace boost

`no_locking_fwd.hpp` forward declares the class `no_locking`.

## Header `"boost/flyweight/no_locking.hpp"` synopsis

### Class `no_locking`

Null `Locking Policy`: it specifies a dummy type that satisfies the formal requirements for the `Mutex` concept but does not perform thread blocking. `no_locking` should only be used in single-threaded environments.

Holders
Boost.Flyweight reference
Tracking policies

Revised January 27th 2009

© Copyright 2006-2009 Joaquín M López Muñoz. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)