carma::util::Singleton< TYPE, InstantiationPolicy > Class Template Reference

Thread-safe, templatized Singleton class with policy based creation. More...

#include <carma/util/Singleton.h>

Static Public Member Functions
static TYPE &	instance ()
	Retrieve a reference to underlying instance. More...

Protected Types
enum	INSTANCE_STATE { NO_INSTANCE, INSTANCE_CREATED, INSTANCE_DESTROYED, NUM_INSTANCE_STATES }
typedef enum carma::util::Singleton::INSTANCE_STATE	InstanceStateType

Static Protected Member Functions
static void	destroyInstance ()
	Should be called when instance is destroyed. More...

Static Protected Attributes
static TYPE *	instancePtr_
static InstanceStateType	state_

Friends
class	InstantiationPolicy< TYPE >

Detailed Description

template<class TYPE, template< class > class InstantiationPolicy>
class carma::util::Singleton< TYPE, InstantiationPolicy >

Thread-safe, templatized Singleton class with policy based creation.

Singleton attempts to mimic the Loki and ACE libraries policy based approach towards Singleton instance creation. It was designed around two basic use cases. The first, allows a user to subclass from the templatized Singleton class and create a singleton in the classical sense:

* class Lonely : public Singleton<Lonely, CreateWithNewPolicy> {
* private:
*   
*     // Must declare CreationPolicy<TYPE> a friend to allow 
*     // internal access to your c'tor and d'tor.
*     friend class CreateWithNewPolicy<Lonely>;
*
*     // Tribute to the Beatles dark side...
*     Lonely() { cout << "Yes I'm Lonely, want to die..." << endl;}
*     ~Lonely() { cout << "If I ain't dead already "
*                      << "Ooh girl you know the reason why!" << endl;}
* };
* 

This defines a true Singleton in that only one instance of Lonely will ever exist. Please note the friend access to the Creation Policy - it is required.

So the steps to create a Singleton become:

1. Make your class constructor Private.
2. Publicly subclass from Singleton<Yourself, YourCreationPolicy>.
3. Declare your creation policy as a friend using:
   • carma::util::CreateWithNewPolicy
   • carma::util::CreateStaticPolicy
   • carma::util::CreateWithNewUnmanagedPolicy

The second major use case centers around using Singleton as a convenient way to access a single instance of a class. This technique is not a Singleton in the classical sense, as multiple instances of TYPE may be created independently of Singleton. However, it does allow one to conveniently access a certain single instance of TYPE if need be (think carma::monitor subsystem access).

* class PseudoLonely {
* public:
*
*     // Constructor - note that it's public and anybody can use it!
*     PseuedoLonely();
*
*     ~PseudoLonely();
* ...
* }; 
* 
* typedef Singleton<PseudoLonely, CreateWithNewPolicy> LonelyAccessor;
* 

The above concluding typedef allows one to easily change the creation policy of the Singleton accessor. Changing it to:

* typedef StaticSingleton<PseudoLonely, CreateStaticPolicy> LonelyAccessor;
* 

will cause the PseudoLonely instance to be created in static memory instead of on the heap.

Regardless of which use case is used, the instance storage policy can be easily changed by either inheriting from or typdefing to an alternate creation policy. So far the following three exist:

See Also

carma::util::CreateWithNewPolicy

carma::util::CreateStaticPolicy

carma::util::CreateWithNewUnmanagedPolicy

Unfortunately, Singleton falls short in several areas. It is based only on creation policies and does not allow one to change the lifetime of the instance nor the threading model. One of the main drawbacks of this is that Singletons which depend on Singletons cannot guarantee destruction order. Nonetheless, Singleton, will throw exceptions if any invariants are violated.

Please visit the documentation for Singleton.h for more information and references.

Definition at line 126 of file Singleton.h.

Member Function Documentation

template<class TYPE , template< class > class InstantiationPolicy>

void carma::util::Singleton< TYPE, InstantiationPolicy >::destroyInstance ( )

staticprotected

Should be called when instance is destroyed.

Responsible for setting state to INSTANCE_DESTROYED and setting instancePtr to NULL.

Definition at line 269 of file Singleton.h.

template<class TYPE , template< class > class InstantiationPolicy>

TYPE & carma::util::Singleton< TYPE, InstantiationPolicy >::instance ( )

static

Retrieve a reference to underlying instance.

Returns

Reference to TYPE

Exceptions

::std::logic_error

on invalid Singleton state.

Definition at line 238 of file Singleton.h.

---

The documentation for this class was generated from the following file:

• carma/util/Singleton.h