VSingleton< T > Class Template Reference

VSingleton is a template class that provides a "singleton holder" that implements the "singleton" pattern behavior for a class T you write. More...

#include <vsingleton.h>

Inheritance diagram for VSingleton< T >:

List of all members.

Public Types
enum	HolderDeletionPolicy { kDeleteHolderAtShutdown, kDontDeleteHolderAtShutdown }
	Specifies whether the VSingleton can be deleted. More...
enum	ThreadSafetyPolicy { kThreadSafeAccess, kSimpleAccess }
	Specifies whether a mutex is used to access the instance. More...
enum	ShutdownPolicy { kRegisterForShutdown, kDontRegisterForShutdown }
	Specifies whether the instance is shut down via the shutdown registry. More...
enum	ResurrectionPolicy { kDontAllowResurrection, kAllowResurrection }
	Specifies whether the instance can be re-created after being previously destroyed. More...
Public Member Functions
	VSingleton (HolderDeletionPolicy holderDeletionPolicy, ThreadSafetyPolicy threadSafetyPolicy, ShutdownPolicy shutdownPolicy, ResurrectionPolicy resurrectionPolicy=kDontAllowResurrection)
	Constructs the singleton holder.
T *	instance ()
	Returns a pointer to the instance of T.
void	deleteInstance ()
	Deletes the instance of T if it exists.
Protected Member Functions
virtual void	_shutdown ()
	Implementation of IVShutdownHandler interface.

---

Detailed Description

template<class T>
class VSingleton< T >

VSingleton is a template class that provides a "singleton holder" that implements the "singleton" pattern behavior for a class T you write.

As of this version, the only key requirement of class T is that it has a default constructor, which will be used when VSingleton instantiates it. The behavior VSingleton gives you is:

• There is only 1 instance of T.
• The instance of T is not instantiated until the first time it is accessed (via the instance() method). This is sometimes called "lazy initialization".
• The instance of T can be deleted, at which point another instance of T may be permitted or prohibited.
• The instance of T can be set for (almost) automatic deletion during program shutdown.
• Callers access the instance of T by calling the holder's instance() method.
• Callers may destroy the instance of T by calling the holder's deleteInstance() method.
• It makes no sense to create multiple holders of the same class T. There will still only be one instance of T since the holders will share the same static variables (such as the instance pointer), but the holders' policy flags could have differing behavior, which would be strange.

You should define T's constructor and destructor private, and the template class a friend, so that only the template class can create and destroy the instance of T. Otherwise, the singleton behavior can be circumvented.

VSingleton can work with the VShutdownRegistry to make sure that the instance of T is cleaned up at shutdown, so you don't leak global resources (even in a simple case, a leak-detecting debugger will infer that there is a leak if the instance of T exists at program exit).

When you construct the VSingleton<T>, you pass it four "policy" flags:

• HolderDeletionPolicy. If you're using the VShutdownRegistry, you need to specify whether the VSingleton itself can be deleted. (Note that I am referring to the VSingleton, not the instance of T.) If it's allocated via "new", it should be deleted, so pass kDeleteHolderAtShutdown. If it's a global variable, it must not be deleted, so pass kDontDeleteHolderAtShutdown. (It would be strange to declare it as a local variable! But if you did, it would have to be flagged like a global variable since it cannot be deleted with operator delete.) If you specify kDeleteHolderAtShutdown, the VShutdownRegistry will delete the VSingleton immediately after it tells it to shutdown().
• ThreadSafetyPolicy. If you know that the instance will be created during the main thread's startup with no possibility of other threads trying to access/create the instance at the same time, you can avoid the overhead of locking, in which case pass kSimpleAccess. However, you should not normally assume this is the case, and should thus normally pass kThreadSafeAccess.
  • ShutdownPolicy. If you want the singleton deleted when the program shuts down, pass kRegisterForShutdown. Otherwise, pass kDontRegisterForShutdown.
• ResurrectionPolicy. If you want to allow the instance of T to be re-created after it was previously created and destroyed, pass kAllowResurrection. Otherwise, pass kDontAllowResurrection, which will cause a VException to be thrown if someone tries to access the instance() after it was previously destroyed. This situation would typically arise if you invoke the VShutdownRegistry before all non-main threads have terminated, or if some singleton's shutdown/cleanup procedure access another deleted singleton's instance. These are typically design bugs that need to be re-thought.

See also:

VShutdownRegistry

IVShutdownHandler

Definition at line 86 of file vsingleton.h.

---

Member Enumeration Documentation

template<class T >

enum VSingleton::HolderDeletionPolicy

Specifies whether the VSingleton can be deleted.

Definition at line 90 of file vsingleton.h.

template<class T >

enum VSingleton::ThreadSafetyPolicy

Specifies whether a mutex is used to access the instance.

Definition at line 92 of file vsingleton.h.

template<class T >

enum VSingleton::ShutdownPolicy

Specifies whether the instance is shut down via the shutdown registry.

Definition at line 94 of file vsingleton.h.

template<class T >

enum VSingleton::ResurrectionPolicy

Specifies whether the instance can be re-created after being previously destroyed.

Definition at line 96 of file vsingleton.h.

---

Constructor & Destructor Documentation

template<class T >

VSingleton< T >::VSingleton	(	HolderDeletionPolicy	holderDeletionPolicy,
		ThreadSafetyPolicy	threadSafetyPolicy,
		ShutdownPolicy	shutdownPolicy,
		ResurrectionPolicy	resurrectionPolicy = kDontAllowResurrection
	)		[inline]

Constructs the singleton holder.

Parameters:

holderDeletionPolicy	specifies whether the holder can be deleted
threadSafetyPolicy	specifies whether a mutex is used to access the instance
shutdownPolicy	specifies whether the instance is shut down via the shutdown registry
resurrectionPolicy	specifies whether the instance can be re-created after being previously destroyed

Definition at line 105 of file vsingleton.h.

---

Member Function Documentation

template<class T >

T* VSingleton< T >::instance

(

)

[inline]

Returns a pointer to the instance of T.

If the instance does not yet exist, it is created. If the resurrection policy prohibits resurrection and the instance was previously deleted, a VException is thrown.

Returns:

the instance of T

Definition at line 124 of file vsingleton.h.

References NULL.

template<class T >

virtual void VSingleton< T >::_shutdown

(

)

[inline, protected, virtual]

Implementation of IVShutdownHandler interface.

To shut down the singleton means to delete the instance.

Implements IVShutdownHandler.

Definition at line 158 of file vsingleton.h.

References VSingleton< T >::deleteInstance().

---

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

• vsingleton.h