A Singleton describes a globally accessible and unique facility, typically
implemented as a class with inaccessible constructors and a globally acessible
function for clients to access a single instance which is created when accessed
for the first time.

There are several reasons to use a scheme like this instead a class-typed global
variable:

Uniqueness of the instance can be enforced,

on-demand initialization allows different Singleton instances to depend on
each other (which is impossible with globals, because their initialization
order is undefined and dependencies are not resolved),

the instances can be destroyed in a controlled order, and

the invocation of the constructor can be ensured, even with ABIs that do
not support running initialization code for dynamic libraries.

This library provides three Singleton templates that share an identical interface
implementing identical behavior in a single-threaded environment differing
in the following properties in multi-threaded context:

boost::singleton can be used to create Singletons
with synchronized initialization. If further synchronization is required it
has to be implemented by the user.

boost::mutexed_singleton additionally ensures that
concurrent access to the instance is mutually exclusive. In other words, only
one thread can access the instance at a given time.

The boost::restricted type used for the parameter of
the constructor is an unspecified, reserved type whose purpose is to prevent
accidental construction and the requirement of verbose "template...friend-making" for client-code (which may
still be used, if desried - e.g. to make the constructor disappear with some
IDEs' code completion features).

A static member proxy object called instance
and a nested class lease allow
to access the instance through overloaded member access and member dereference
operators. The static instance
member should be used for accessing a single member of the instance while a
typically short-lived lease
object should be used instead to minimize synchronization overhead in places
where the instance is accessed frequently. For a mutexed_singleton
the instance will only be accessible by the owning thread for the lifetime
of the lease.

voiduse_my_singleton(){// ... through the instance proxy
my_singleton::instance->foo(1);}voiduse_my_singleton_a_lot(){// ...through a lease object:
//
// - it makes accessing the object more efficient for
// any boost::singleton, and
// - locks a mutexed_singleton's mutex for the lifetime
// of the lease
my_singleton::leasemy_singleton_lease;if(!my_singleton_lease->foo(1))my_singleton_lease->bar(2);my_singleton_lease->foo(3);}

The instance object may be
used in a reference wrapper (applying boost::ref)
to boost::bind
a member pointer to the instance.

bind(&my_singleton::foo,ref(my_singleton::instance),_1)// is a function object that will issue a mutexed call to
// my_singleton::foo (since my_singleton is a mutexed_singleton).

Objects of the nested lease
class can be used by-value in a similar context. In this case a mutexed_singleton will lock its mutex for
the lifetime of the function object and copies thereof.

bind(&my_singleton::foo,my_singleton::lease(),_1)// is a function object that will call my_singleton:foo and
// whose mere existence locks mutex of 'my_singleton'.

It is possible to turn an existing object into a Singleton applying multiple
inheritance:

We might as well have a static facility use the Singleton internally, by using
non-public inheritance:

classglobal_log:privateboost::singleton<global_log>{logobj_log;public:staticvoidmessage(std::string);// [...]
private:// We make friends with the singleton template to also
// hide the constructor, this time:
global_log(boost::restricted);template<classT,intDS>friendclassboost::singleton;};

Singleton instances are normally destroyed in reverse order of their construction,
that is for a group of Singletons with their integral DisposalSlot
template arguments being equal, where the destruction of these groups is ordered
by the ascending DisposalSlot
values.

We could raise the DisposalSlot
value of global_log from the
previous examples to make sure it outlives other singletons that use 0 (the
default):

classglobal_log:privateboost::singleton<global_log,1>// ...

Attempts to access already destroyed Singleton instances cause the instance
to be re-created.

These rules for destruction apply to any set of Singletons of possibly different
variants with the same SubsystemTag:
For example a mutexed_singleton
created before a singleton
(both using the same DisposalSlot
value) is guaranteed to outlive that singleton.

Special constraints apply when using Singletons together with dynamic libraries:
- There must be at most one single instance of a Singleton, even if it is exposed
by a dynamic library, - the mechanism that controls the lifetime of Singleton
instances must exist once per dynamic library, as the dynamic library may get
unloaded at any time, and - there should be an interface to invoke Singleton
destruction manually, as not all operating systems' loaders guarantee execution
of destructors in static context.

Keeping the former can be problematic if the management code gets inlined into
the client or if symbols are not being merged automatically. As a solution,
this library provides two macros, BOOST_SINGLETON_PLACEMENT
and BOOST_SINGLETON_PLACEMENT_DECLARATION
to compile the effective code into a specific source file.

The second constraint breaks if the symbols of the internal management code
get merged. In this case an application that contains Singletons itself will
"adopt" dynamic libraries' Singletons and possibly crash during shutdown
trying to execute already-unloaded code. As a solution, this library allows
the user to specify a third template argument for the SubsystemTag
parameter, which is used to key the lifetime management code; two Singletons
with different SubsystemTag
have independent lifetime control.

To address the third constraint, the destruction mechanism can be invoked manually
by calling boost::destroy_singletons. It is safe to call this
function even if cleanup can happen automatically so portable code can look
the same for all platforms.

The derived class' public constructor is invoked with a single argument that
can be bound to the unspecified paramter type boost::restricted.

The constructor is executed at most one time in a (possibly multi-threaded)
program, immediately before the instance is first accessed or leased.

Once constructed, no effort is taken to synchronize concurrent access to
class members of the single instance.

The destruction order of Singleton instances is defined by the ascending
order of (DisposalSlot,-tctor) tuples regardless of the template variant
used, where -tctor
is the negative construction time and the secondary sorting criterion.

Attempts to access an already destroyed Singleton instance cause the instance
to be re-created.

Destruction takes place when static objects are destroyed on a best-effort
basis, that is the destruction mechanism must be invoked manually by calling
boost::destroy_singletons for dynamic libraries
and ABIs that do not support running cleanup code.

The derived class' public constructor is invoked with a single argument that
can be bound to the unspecified paramter type boost::restricted.
The constructor is executed at most one time in a (possibly multi-threaded)
program, immediately before the instance is first accessed or leased.

Once constructed, concurrent access is mutually exclusive. In other words
only one thread can access the instance at a given time. The creation of
a lease object causes concurrent attempts to access the instance or to create
lease objects from other
threads to be block until the lease is destroyed.

The destruction order of Singleton instances is defined by the ascending
order of (DisposalSlot,-tctor) tuples regardless of the template variant
used, where -tctor
is the negative construction time and the secondary sorting criterion.

Attempts to access an already destroyed Singleton instance cause the instance
to be re-created.

Destruction takes place when static objects are destroyed on a best-effort
basis, that is the destruction mechanism must be invoked manually by calling
boost::destroy_singletons for dynamic libraries
and ABIs that do not support running cleanup code.

Thread-specific singleton instances of threads different from the program's
initial thread may be destroyed earlier, when the corresponding thread terminates.
Above ordering rules must still hold for singleton instances specific to
that thread, however.

Base class template that provides global access to a single instance of the
derived class per thread.

The derived class' public constructor is invoked with a single argument that
can be bound to the unspecified paramter type boost::restricted.
An instance is constructed once the instance is accessed or leased by a given
thread for the first time.

The destruction order of Singleton instances is defined by the ascending
order of (DisposalSlot,-tctor) tuples regardless of the template variant
used, where -tctor
is the negative construction time and the secondary sorting criterion.

Attempts to access an already destroyed Singleton instance cause the instance
to be re-created.

Destruction takes place when static objects are destroyed on a best-effort
basis, that is the destruction mechanism must be invoked manually by calling
boost::destroy_singletons for dynamic libraries
and ABIs that do not support running cleanup code.

Thread-specific singleton instances of threads different from the program's
initial thread may be destroyed earlier, when the corresponding thread terminates.
Above ordering rules must still hold for singleton instances specific to
that thread, however.