The factory class used to store
and retrieve the shared value objects.

The type of holder used to
instantiate the flyweight factory and a mutex object, both of
which are unique to each specialization of the flyweight
class template.

A locking policy determining
the synchronization mechanisms for internal access to shared resources.

A tracking policy which controls
how values are treated when all their associated flyweight objects are
destroyed.

These aspects impact the internal structure and behavior
of the flyweight instantiation in the following manner:

Each instantation of flyweight internally owns
a unique factory object and a unique synchronization
mutex object, both of which
are created through the use of an associated holder type.

The flyweight factory stores elements of an undisclosed type
Entry that is implicitly convertible to
const key_type& and also stores a subobject of
value_type. Every flyweight object is associated
to a value_type subobject of some Entry
stored in the factory.

The associated mutex object is used to protect all invocations
to the insertion and deletion functions of the internal flyweight
factory.

Each flyweight object internally stores a value of some
undisclosed type Handle. Handle and
the Entry type referred to above are obtained
from invocations to the associated tracking policy, in the
manner described for this concept.

In what follows, we implicitly assume that key_type equivalence
refers to the equivalence relationship induced by the factory class used.
Also, two values of value_type are considered equivalent
if they are constructed from equivalent keys, or are copies of
objects constructed from equivalent keys.

In the first case, the nested types key_type and value_type
are both equal to T. In the second case, key_type=Key,
value_type=Value; we say then that the instantiation
of flyweight is a key-value flyweight.
value_type is the type of the values flyweight objects give access to,
while value lookup is based on associated key_type values.
key_value must be
Assignable
and value_type must be constructible from key_type;
additionally, key_value must
conform to any extra requirements imposed by the type of factory used.
For key-value flyweights, it is guaranteed that the creation or assignment of a flyweight
object results in at most one construction (or copy construction in some
particular cases) of an object
of value_type, and this construction only occurs in the case that no
equivalent value existed previously in the flyweight factory.

The types Arg1, ... , Arg5, if provided, must be any
of the following, in no particular order:

No aspect can be specified twice. Each internal component of the
flyweight instantiation is obtained through use of the
corresponding specifier; for instance, the factory results from a
certain (MPL) invocation of the given factory specifier, the internal
mutex from the given locking policy, etc.
The default configuration arguments are:

The static data internal to a given flyweight instantiation
(factory instance, etc.) is constructed during the dynamic initialization
phase of the program and always before the first program-wide use of the
instantiated class. The following utilities can be
used when more control about the moment of construction is required.

static bool init();

Effects: After execution of this function the static data associated
to the instantiation of flyweight is guaranteed to be
constructed.Note: Concurrent execution of this function is not thread safe.

Effects: Constructs a flyweight object with the value
value_type(key_type(std::forward<Args>(args)...))
if flyweight is key-value
or value_type(std::forward<Args>(args)...)
otherwise.Note: In compilers without variadic template support, the implementation
replaces this constructor with a number of overloads accepting
any combination of const/non-const lvalue/rvalue reference arguments
up to a maximum number that
can be globally configured by the user.

template<typename V>
flyweight(std::initializer_list<V> list);

Effects: Constructs a flyweight object with the value
value_type(key_type(list)) if flyweight is key-value
or value_type(list) otherwise.Note: The specialization for a particular std::initializer_list<V'>
of this member function template is not available unless
key_type is constructible from
std::initializer_list<V'>.

Requires: If flyweight is key-value,
value_type is
Assignable
and the
Key ExtractorKeyFromValue must have been supplied as part of the
key_value<> construct.Effects: Constructs a flyweight associated to a
copy of x or with a value_type constructed
from a key equivalent to that associated to x. For non-key-value
flyweights, x is its own key; for key-value flyweights,
the key is extracted through use of an object of type KeyFromValue.

Effects:*this=flyweight(list).Returns:*this.Note: The specialization for a particular std::initializer_list<V'>
of this member function template is not available unless
key_type is constructible from
std::initializer_list<V'>.

flyweight& operator=(const flyweight& x);

Effects: Associates the flyweight object with the same value
as x.Returns:*this.Exception safety:nothrow.

Returns: If x and y are of the same type, returns
true if and only if they are associated to the same value; if
x and y have different types, returns
x.get()==y.get().Exception safety: If x and y are of the same type,
nothrow.

Requires: If flyweight is key-value,
value_type is
Assignable
and the
Key ExtractorKeyFromValue must have been supplied as part of the
key_value<> construct.Effects: Reads an object of type value_type from in
and assigns it to x.Returns:in.

Support is provided for hashing flyweights both with std::hash and
boost::hash. In either case, the calculation
does not involve hashing the associated value_type objects themselves; so, it is
immaterial whether value_type is hashable or not.
The results given by std::hash and boost::hash for the same
flyweight object will usually differ.Note: Hash support can be disabled to solve
clashes with code where this has already been defined by the user.

flyweights can be archived and retrieved by means of
Boost.Serialization. Regular as well
as XML archives are supported.
Serialization is done in an efficient manner so that saving equivalent flyweights
result in their common key_type value being stored only once, regardless
of whether key_type is
tracked by
Boost.Serialization or not.

Requires:key_type is serializable (XML-serializable).Effects: The value k=x.get_key() is saved into ar as
part of this operation or of a previous saving operation of a flyweight
object with the same key.Exception safety: Strong with respect to x. If an exception
is thrown, ar may be left in an inconsistent state.

Operation: loading of a flyweightx' from an
input archive (XML archive) ar.

Requires:key_type is serializable (XML-serializable).Effects:x' is associated to a value constructed from a key
equivalent to k', a restored copy of the value k
defined above.Exception safety: Strong with respect to x'. If an exception
is thrown, ar may be left in an inconsistent state.