Linux Tutorial - 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

01#include <string>
02 
03class Logger{
04public:
05   static Logger* Instance();
06   bool openLogFile(std::string logFile);
07   void writeToLogFile();
08   bool closeLogFile();
09 
10private:
11   Logger(){};  // Private so that it can  not be called
12   Logger(Logger const&){};             // copy constructor is private
13   Logger& operator=(Logger const&){};  // assignment operator is private
14   static Logger* m_pInstance;
15};

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

01#include <stddef.h>  // defines NULL
02#include "logger.h"
03 
04// Global static pointer used to ensure a single instance of the class.
05Logger* Logger::m_pInstance = NULL;  
06 
07/** This function is called to create an instance of the class. 
08    Calling the constructor publicly is not allowed. The constructor 
09    is private and is only called by this Instance function.
10*/
11   
12Logger* Logger::Instance()
13{
14   if (!m_pInstance)   // Only allow one instance of class to be generated.
15      m_pInstance = new Logger;
16 
17   return m_pInstance;
18}
19 
20bool Logger::openLogFile(std::string _logFile)
21{
22   ...
23   ...
24   ...
25}
26 
27...
28...

Usage:

1...
2...
3 
4Logger::Instance()->openLogFile("logFile.txt");
5 
6...
7...

C++ Singleton class using inheritance:

In this example the base class enforces a singleton pattern.

File: base.hpp

01// Singleton base class hpp file
02 
03class sBase
04{
05public:
06   static sBase* instance();
07   static bool exists();
08   inline int getDataX(){ return mDataX; };
09   inline int setDataX(int _in){ mDataX = _in; };
10   virtual int getDataY() = 0;
11   virtual int setDataY(int _in) = 0;
12protected:
13   sBase(int);
14   virtual ~sBase(){};
15   static sBase* mpoSssInstance;
16private:
17   int mDataX;
18};

File: base.cpp

01#include <stddef.h>  // defines NULL
02#include <iostream>
03#include "base.hpp"
04 
05// Singleton base class cpp file
06 
07sBase* sBase::mpoSssInstance = 0;  // Global initialization to facilitate singleton design pattern
08 
09sBase::sBase(int _initialValueX)
10: mDataX(_initialValueX)
11{
12}
13 
14bool sBase::exists()
15{
16   return (mpoSssInstance != NULL); // Return true/false
17}
18 
19sBase* sBase::instance()
20{
21   if(mpoSssInstance == 0) std::cout << "Class has not been created" << std::endl;
22 
23   return mpoSssInstance;
24}

File: derived.hpp

01// Singleton derived class hpp file
02 
03#include "base.hpp"
04 
05class sDerived : public sBase
06{
07public:
08   static void create(int,int);
09   virtual inline int getDataY(){ return mDataY; };
10   virtual inline int setDataY(int _in){ mDataY = _in; };
11protected:
12   sDerived(int,int);      // Can't be called by non-member functions
13   virtual ~sDerived() {}; // Can't be called by non-member functions
14private:
15   int mDataY;
16};

File: derived.cpp

01// Singleton derived class cpp file
02 
03#include <iostream>
04#include "derived.hpp"
05 
06sDerived::sDerived(int _initialValueX, int _initialValueY)
07: sBase(_initialValueX)
08{
09   mDataY =_initialValueY;
10}
11 
12void sDerived::create(int _initialValueX, int _initialValueY)
13{
14   if(mpoSssInstance)
15      std::cout << "Singleton has already been created" << std::endl;
16   else
17      mpoSssInstance = new sDerived(_initialValueX, _initialValueY);
18}

File: main.cpp

01#include <derived.hpp>
02#include <iostream>
03using namespace std;
04 
05// Program which uses singleton class
06 
07main()
08{
09   // Only one instance of the singleton class can be created
10   sDerived::create(3,3);
11 
12   sDerived::instance()->setDataX(5);
13   cout << sDerived::instance()->getDataX() << endl;
14 
15   sDerived::instance()->setDataY(7);
16   cout << sDerived::instance()->getDataY() << endl;
17}

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

Results: a.out

5
7

Note that the function calls are static calls to their global names using the scope resolution operator. The functions create() and instance() are defined as static functions in the class definitions. Note that static member functions do not have a this pointer as they exist independent of any objects of a class.

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

01#ifndef __SINGLETON_HPP_
02#define __SINGLETON_HPP_
03#include <stddef.h>  // defines NULL
04 
05template <class T>
06class Singleton
07{
08public:
09  static T* Instance() {
10      if(!m_pInstance) m_pInstance = new T;
11      assert(m_pInstance != NULL);
12      return m_pInstance;
13  }
14protected:
15  Singleton();
16  ~Singleton();
17private:
18  Singleton(Singleton const&);
19  Singleton& operator=(Singleton const&);
20  static T* m_pInstance;
21};
22 
23template <class T> T* Singleton<T>::m_pInstance=NULL;
24 
25#endif

Usage:

01#include "singleton.hpp"
02 
03class Logger
04{
05public:
06   Logger() {};
07   ~Logger() {};
08   bool openLogFile(string);
09   void writeToLogFile(string);
10   bool closeLogFile(string);
11private:
12   ...
13   ...
14};
15 
16bool Logger::openLogFile(std::string)
17{
18   ...
19   ...
20}
21 
22...
23...
24 
25typedef Singleton<Logger> LoggerSingleton;   // Global declaration
26 
27main()
28{
29    ...
30 
31    LoggerSingleton::Instance()->openLogFile("logFile.txt");
32 
33    ...
34}

The static stack variable Singleton class:

01class Logger {
02public:
03  static Logger& Instance() {
04    static Logger theLogger;   // Instantiated when this function is called
05    return theLogger;
06  }
07  bool openLogFile(string logFile);
08  void writeToLogFile(string sLine);
09  bool closeLogFile(string logFile);
10 
11private:
12  Logger();                                  // constructor is private
13  Logger(Logger const&);                 // copy constructor is private
14  Logger& operator=(Logger const&);  // assignment operator is private
15  ~Logger();                                 // destructor is private
16};

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:

1...
2...
3 
4Logger::Instance().openLogFile("logFile.txt");
5 
6...
7...

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

Other variations and tips:

Optimization option:

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

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.

Books:

	"Design Patterns" by Erich Gamma, Richard Helm, Ralph Johnson, John M. Vissides ISBN # 0201633612, Addison-Wesley Professional Computing Series Object oriented design patterns by example in C++.
	Modern C++ Design: Generic Programming and Design Patterns Applied by Andrei Alexandrescu ISBN #0201704315, Addison-Wesley Professional Reviews use of the Phoenix Singleton and policy template classes (allows policy choice for behavior control) to control a singletons lifetime.
	Design Patterns Explained: A New Perspective on Object-Oriented Design by Alan Shalloway, James Trott ISBN #0321247140, Addison-Wesley Professional Java examples.