singleton.h File Reference

Manage a single instance of an object. More...

Include dependency graph for singleton.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	TfSingleton< T >
	Manage a single instance of an object (see. More...

Detailed Description

Manage a single instance of an object.

Many classes (for example, registries) should have only a single, globally available instance that is created as needed on demand. This is a classic design pattern known as a singleton. Additionally, creation of this class (though not access to it per se) must be made threadsafe.

There are two possibilities in creating a singleton: you can create a class all of whose member functions and variables are static, and let users access this class. Unfortunately, instantiating the static variables of this class is prone to difficulty; more importantly, should you change your mind and wish to allow multiple instances of the class, much rewriting follows.

A better solution is to define the class with regular members and variables, and then permit only a single instance of the class to exist. This is the philosophy embodied by the TfSingleton template. It takes care of both multithreaded initialization and initialization before main; the cost of this is quite low (a single boolean comparison to access the instanced object after initial creation). The TfSingleton template works in conjunction with a macro in the source file TF_INSTANTIATE_SINGLETON(), which is itself defined by including the file "pxr/base/tf/instantiateSingleton.h".

Typical Use

The typical use of TfSingleton is as follows:

*      // file: registry.h
*      #include "pxr/base/tf/singleton.h"
*      #include <boost/noncopyable.hpp>
* 
*      class Registry : boost::noncopyable {
*      public:
*          static Registry& GetInstance() {
*               return TfSingleton<Registry>::GetInstance();
*          }
* 
*          ...
* 
*      private:
*          Registry();
*          ~Registry();
* 
*          friend class TfSingleton<Registry>;
*       };
* 
*      // file: Registry.cpp
*      #include "common/astrology/registry.h"
*      #include "pxr/base/tf/instantiateSingleton.h"
* 
*      TF_INSTANTIATE_SINGLETON(Registry);
*      
* 
*      // file: RandomCode.cpp
*      #include "common/astrology/registry.h"
* 
*      void Code() {
*           Registry& r = Registry::GetInstance();
*           r.Lookup(...);
*           ...
*      }
*  

The constructor and destructor are declared private, and the singleton object will typically derive off of boost::noncopyable to prevent copying. Note that singleton objects quite commonly also make use of TfRegistryManager to acquire the data they need throughout a program.

The friend class TfSingleton<Registry> is the only class allowed to create an instance of a Registry. The helper function Registry::GetInstance() is for convenience only; one can just as well call the longer TfSingleton<Registry>::GetInstance() to obtain a reference to the sole instance of the registry.

Definition in file singleton.h.