C++ Singleton design pattern

Why use a singleton class?

This design pattern and methodology ensures that only one instance of the C++ class is instantiated. It assures that only one object is created and no more. It is often used for a logging class so only one object has access to log files, or when there is a single resource, where there should only be a single object in charge of accessing the single resource. The singleton pattern discussed here gives the class itself, the responsibility of enforcement of the guarantee that only one instance of the class will be allowed to be generated.

 

---

Example of a C++ Singleton class:

 

File: logger.hpp

#include <string> class Logger{ public: static Logger* Instance(); bool openLogFile(std::string logFile); void writeToLogFile(); bool closeLogFile(); private: Logger(){}; // Private so that it can not be called Logger(Logger const&){}; // copy constructor is private Logger& operator=(Logger const&){}; // assignment operator is private static Logger* m_pInstance; };

Note:

• That the instance function returns a pointer to a static variable and thus is declared static.
• Only the class function Instance can call the constructor. Public access to the constructor is denied.
• The constructor, copy constructor and assignment operator are all private to ensure that the programmer using the singleton class can only create a single instance of the class using only the Instance() function.
• The life of the singleton instantiation is for the duration of the application.

 

File: logger.cpp

#include "logger.h" // Global static pointer used to ensure a single instance of the class. Logger* Logger::m_pInstance = NULL; /** This function is called to create an instance of the class. Calling the constructor publicly is not allowed. The constructor is private and is only called by this Instance function. */ Logger* Logger::Instance() { if (!m_pInstance) // Only allow one instance of class to be generated. m_pInstance = new Logger; return m_pInstance; } bool Logger::openLogFile(std::string _logFile) { ... ... ... } ... ...

Usage:

... ... Logger::Instance()->openLogFile("logFile.txt"); ... ...

 

---

C++ Singleton class using inheritance:

In this example the base class enforces a singleton pattern.

File: base.hpp

// Singleton base class hpp file class sBase { public: static sBase* instance(); static bool exists(); inline int getDataX(){ return mDataX; }; inline int setDataX(int _in){ mDataX = _in; }; virtual int getDataY() = 0; virtual int setDataY(int _in) = 0; protected: sBase(int); virtual ~sBase(){}; static sBase* mpoSssInstance; private: int mDataX; };

 

File: base.cpp

#include <iostream> #include "base.hpp" // Singleton base class cpp file sBase* sBase::mpoSssInstance = 0; // Global initialization to facilitate singleton design pattern sBase::sBase(int _initialValueX) : mDataX(_initialValueX) { } bool sBase::exists() { return (mpoSssInstance != NULL); // Return true/false } sBase* sBase::instance() { if(mpoSssInstance == 0) std::cout << "Class has not been created" << std::endl; return mpoSssInstance; }

 

File: derived.hpp

// Singleton derived class hpp file #include "base.hpp" class sDerived : public sBase { public: static void create(int,int); virtual inline int getDataY(){ return mDataY; }; virtual inline int setDataY(int _in){ mDataY = _in; }; protected: sDerived(int,int); // Can't be called by non-member functions virtual ~sDerived() {}; // Can't be called by non-member functions private: int mDataY; };

 

File: derived.cpp

// Singleton derived class cpp file #include <iostream> #include "derived.hpp" sDerived::sDerived(int _initialValueX, int _initialValueY) : sBase(_initialValueX) { mDataY =_initialValueY; } void sDerived::create(int _initialValueX, int _initialValueY) { if(mpoSssInstance) std::cout << "Singleton has already been created" << std::endl; else mpoSssInstance = new sDerived(_initialValueX, _initialValueY); }

 

File: main.cpp

#include <derived.hpp> #include <iostream> using namespace std; // Program which uses singleton class main() { // Only one instance of the singleton class can be created sDerived::create(3,3); // Polymorphic: functions called by base class pointer sDerived::instance()->setDataX(5); cout << sDerived::instance()->getDataX() << endl; sDerived::instance()->setDataY(7); cout << sDerived::instance()->getDataY() << endl; }

Compile: g++ main.cpp derived.cpp base.cpp

 

Results: a.out

5
7

 

---

The Template Singleton class:

One can inherit a singleton class from a base class or use a template for each type of instantiation. The Base class and Derived class relationship offers flexibility as there are no design limits in the derived class.

The Template singleton is also flexible and is used in a manner where any class can be turned into a singleton by using this template.

File: singleton.hpp

#ifndef __SINGLETON_HPP_ #define __SINGLETON_HPP_ template <class T> class Singleton { public: static T* Instance() { if(!m_pInstance) m_pInstance = new T; assert(m_pInstance !=NULL); return m_pInstance; } protected: Singleton(); ~Singleton(); private: Singleton(Singleton const&); Singleton& operator=(Singleton const&); static T* m_pInstance; }; template <class T> T* Singleton<T>::m_pInstance=NULL; #endif

Usage:

#include "singleton.hpp" class Logger { public: Logger() {}; ~Logger() {}; bool openLogFile(string); void writeToLogFile(string); bool closeLogFile(string); private: ... ... }; bool Logger::openLogFile(std::string) { ... ... } ... ...

 

---

The static stack variable Singleton class:

 

class Logger { public: static Logger& Instance() { static Logger theLogger; // Instantiated when this function is called return theLogger; } bool openLogFile(string logFile); void writeToLogFile(string sLine); bool closeLogFile(string logFile); private: Logger(); // constructor is private Logger(Logger const&); // copy constructor is private Logger& operator=(Logger const&); // assignment operator is private ~Logger(); // destructor is private };

Note:

• This version of a singleton class initializes when the Instance() function is called.
• The Instance() function returns an instance instead of a pointer. The pointer is not exposed and thus a delete can not be inappropriately applied.
• [Potential Pitfall]: This form of the singleton can present a problem because of the life expectancy of the object. If one singleton is instantiated within another, one must be keenly aware of the destructor call sequence.

Usage:

... ... Logger::Instance().openLogFile("logFile.txt"); ... ...

Also see An Exception Correct C++ Singleton Template Base Class with Controlled Destruction Order

 

---

Other variations and tips:

 

Optimization option:

static Abc* Abc::Instance() // Singleton { return mInstance ? mInstance : (mInstance = new Abc); }

This should slightly reduce the number of computed operations and thus is slightly more optimized.

 

---

 

The examples given above use a C++ global static variable. Other variations of a singleton can use:

• an environment variable.
• a file (A lock file is often used to insure a single instance of a process).
• a static STL list or STL map of values or paired values can be used by a singleton class as a singleton registry for other classes to verify singleton compliance.