Boost.Flyweight Documentation - Tracking policies reference

# Boost.Flyweight Tracking policies reference

Locking policies
Boost.Flyweight reference
Performance

## Contents

- Preliminary concepts
- Tracking policies
- Header `"boost/flyweight/tracking_tag.hpp"` synopsis
  - Class template `is_tracking`
  - Class template `tracking`
- Header `"boost/flyweight/refcounted_fwd.hpp"` synopsis
- Header `"boost/flyweight/refcounted.hpp"` synopsis
  - Class `refcounted`
- Header `"boost/flyweight/no_tracking_fwd.hpp"` synopsis
- Header `"boost/flyweight/no_tracking.hpp"` synopsis
  - Class `no_tracking`

## Preliminary concepts

A tracking policy helper provides access to some of the functionality of a factory so as to be used in the implementation of an associated `Tracking Policy`. In the following table, `TrackingHelper` is a tracking policy helper associated to a factory type `Factory` of elements of type `Entry`, `h` is a value of `Factory::handle_type` associated to a `Factory` `f` and `check` is a value of a `Predicate` type `Checker` with argument of type `Factory::handle_type`.

Tracking Policy Helper requirements.
expression | return type | assertion/note pre/post-condition
--- | --- | ---
`TrackingHelper::entry(h);` | `const Entry&` | Returns `f.entry(h)`.
`TrackingHelper::erase(h,check);` | `void` | If `check(h)`, invokes `f.erase(h)`.

The execution of `TrackingHelper::erase` (including the invocation of `check(h)`) is done in a synchronized manner so as to prevent any other thread of execution from simultaneously accessing the factory's insertion or deletion facilities.

## Tracking policies

A tracking policy defines the strategy to be followed by a `flyweight` instantiation when all the flyweight objects associated to a given value are destroyed. The tracking policy contributes some type information necessary for the definition of the `flyweight` internal factory.

A type `Tracking` is a tracking policy if:

- One of the following conditions is satisfied:
  1. `is_tracking<Tracking>::type` is `boost::mpl::true_`,
  2. `Tracking` is of the form `tracking<Tracking'>`.
- The expression `Tracking::entry_type` (or `Tracking'::entry_type` if (b) applies) is an `MPL Lambda Expression` that resolves, when invoked with different types (`Value`,`Key`) such that `Value` is `Assignable` and implicitly convertible to `const Key&`, to an `Assignable` type `Entry` implicitly convertible to both `const Value&` and `const Key&`.
- The expression `Tracking::handle_type` (or `Tracking'::handle_type` if (b) applies) is an `MPL Lambda Expression`; this expression, when invoked with types (`InternalHandle`,`TrackingHelper`), with `InternalHandle` being `Assignable` and providing the nothrow guarantee for copy and assignment, resolves to an `Assignable` type `Handle` which also provides the nothrow guarantee for copy and assignment and is constructible from and implicitly convertible to `InternalHandle`. `TrackingHelper` is an incomplete type at the time of invocation of `Tracking::handle_type`.

`Tracking::handle_type` is parameterized by a helper that provides access to some of the functionality of the factory associated to the tracking policy. This factory's associated entry and handle types are the types `Entry` and `Handle` defined above, respectively.

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

>     namespace boost{

>     namespace flyweights{

>     struct tracking_marker;

>     template<typename T>
>     struct is_tracking

>     template<typename T>
>     struct tracking;

>     } // namespace boost::flyweights

>     } // namespace boost

### Class template `is_tracking`

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

### Class template `tracking`

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

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

>     namespace boost{

>     namespace flyweights{

>     struct refcounted;

>     } // namespace boost::flyweights

>     } // namespace boost

`refcounted_fwd.hpp` forward declares the class `refcounted`.

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

### Class `refcounted`

`Tracking Policy` providing `flyweight` instantiations with reference counting semantics: when all the flyweight objects associated to a given value are destroyed, the corresponding entry is erased from `flyweight`'s internal factory.

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

>     namespace boost{

>     namespace flyweights{

>     struct no_tracking;

>     } // namespace boost::flyweights

>     } // namespace boost

`no_tracking_fwd.hpp` forward declares the class `no_tracking`.

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

### Class `no_tracking`

Null `Tracking Policy`: elements inserted into `flyweight`'s internal factory are not erased until program termination.

Locking policies
Boost.Flyweight reference
Performance

Revised August 18th 2008

© Copyright 2006-2008 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)