The slide illustrates a straw-man first attempt at implementing singleton using static methods and data. Here is an elaboration:
class Font { ... };
class PrintPort { ... };
class PrintJob { ... };
class MyOnlyPrinter
{
public:
static void AddPrintJob(PrintJob& newJob)
{
if (printQueue_.empty() && printPort_.available())
{
printPort_.send(newJob.Data());
}
else
{
printQueue_.push(newJob);
}
}
private:
static std::queue<PrintJob> printQueue_;
static PrintPort printPort_;
static Font defaultFont_;
};
// client code:
PrintJob somePrintJob("MyDoc.txt");
MyOnlyPrinter::AddPrintJob(somePrintJob);
There are two basic problems with this approach. First: it is difficult to change behavior because static functions cannot be virtual, so a singleton cannot be polymorphic.
Second:
initialization and cleanup are not well supported. For example, initializing a
MyOnlyPrinter object might need to set the default font depending on the speed
of the port.
Features:
While static initialization is performed prior to any execution of code, the
order in which initialization is done for static items in different
translation units is not specified by the standard.
Improvements:
The Myers singleton (invented by Scott Myers) uses local static variable. This is initialized when control flow first passes through its definition, and it is registered for destruction during normal program termination. Sample code is shown in the slide. The following "compiler pseudocode" illustrates how variable is handled by runtime system:
Singleton& Instance()
{
// functions generated by compiler
extern void __ConstructSingleton(void* memory);
extern void DestroySingleton();
// variables constructed by compiler
static bool __initialized = false;
static char __object[sizeof(Singleton)]; // holds singleton - aligned
// code
if (!__initialized)
{
__ConstructSingleton(__buffer);
atexit(__DestroySingleton);
__initialzzed = true;
}
return *reinterpret_cast<Singleton*>(__object);
}
The atexit function is in the standard C library. It can be called to register a function to be automatically called during program exit. The signature of atexit is:
int atexit ( void (*pFun)() );
A call to atexit pushes the parameter onto a stack maintained by the
runtime system. During program exit, these are called and popped off this
stack. Hence the registered items are called in LIFO order of registration.
The dead reference problem is illustrated by the keyboard-display-log interaction: keyboard and display are created; at some later time a first error is logged, which creates the log; then an error during detsruction of the keyboard attempts to access the log, which has already been destroyed. There is no systematic way around this problem when multiple Singletons interact.
The slide shows a compact version of this embellishment of the Meyers singleton that at least detects a dead reference:
// Singleton.h
class Singleton
{
public:
static Singleton& Instance()
{
if (!pInstance)
{
if (destroyed) // check for dead reference
{
OnDeadReference();
}
else // create on first call
{
Create();
}
}
return *pInstance_;
}
virtual ~Singleton()
{
pInstancce_ = 0;
destroyed_ = true;
}
private:
static void Create()
{
static Singleton theInstance;
pInstance_ = &theInstance;
}
static void OnDeadReference()
{
throw std::runtime_error("Dead Reference Detected");
}
// variables
static Singleton* pInstance_;
static bool destroyed_;
// disabled - do not implement
Singleton(const Singleton&)
Singleton& operator=(const Singleton&);
};
// Singleton.cpp
Singleton * Singleton::pInstance_ = 0;
bool Singleton::destroyed_ = false;
As the application exits, the singleton destructor is called, which sets
pInstance_ to zero and destroyed_ to true. If a longer-living
object attempts to access the singleton after it is destroyed, control flow
reaches OnDeadReference which throws a runtime_error exception.
Note that the destructor is changed to have public access so that the runtime
system can make the call.
If we want a singleton to be available after its automatic destruction during program termination, one approach is to resurrect it. For the KDL problem above, we would make keyboard and display regular singletons and the error log a phoenix singleton.
The phoenix singleton rises from the ashes of the destroyed original. When a dead reference is detected, a new one is created on the footprint of the old. The new version must schedule its destruction by hand, done with a call to atexit.
Example code for phoenix singleton is given in the slide, as a modification of Singleton. The changes consist of adding KillPhoenixSingleton() and modifying OnDeadReference().
The standard does not specify what happens when a function is registered during a call made as a result of a previously registered function, as in the call to OnDeadReference() in a phoenix singleton. This is an omission in the C and C++ standards which will likely be corrected, but for now compilers differ on how they handle this situation. The loki library uses macros to force destruction when ATEXIT_FIXED is defined, as in the following fragment:
class PhoenixSingleton
{
...
static void OnDeadReference()
{
#ifndef ATEXIT_FIXED
destroyedOnce_ = true;
#endif
}
...
private:
#ifndef ATEXIT_FIXED
static bool destroyedOnce_;
#endif
...
};
#ifndef ATEXIT_FIXED
template <class T> bool PhoenixSingleton<T>::destroyedOnce_ = false;
#endif
The design is obviously somewhat different from our example, due largely to
the use of policy-based design template parameters, but the basic principles are
followed.
The complete loki header file is included at the end of this chapter.
The idea is to create a LifeTimeTracker object that maintains a priority queue of items to register, prioritized by longevity and keeping items with the same priority in LIFO order in which SetLongivity is called. The LifeTimeTracker destructor then registers with atexit the items in order determined by the priority queue.
In order to avoid the ambiguity created by automatic registration of the
destructor, the LifeTimeTracker object must be created on the first
call to SetLongevity
and destroyed dynamically just prior to program termination.
All of this is behind the scenes of a client call to
SetLongevity. Clearly, one should: Use with Caution!
In a multithreaded world, we need to avoid possible duplication of the call pInstance = new Singleton. One obvious solution:
Singleton& Singleton::Instance()
{
// assumes mutex object mutex_
// Lock objects manage the mutex
Lock myGuard(mutex_); // performance penalty, mostly wasted
if (!pInstance_)
{
pInstance_ = new Singleton;
}
return *pInstance_;
}
This has an undesirable performance penalty, creating a lock object on all calls when it would be needed only in rare cases. A faulty fix would be:
Singleton& Singleton::Instance()
{
if (!pInstance_) // check
{ // twilight zone
Lock myGuard(mutex_); // too late: maybe another thread has created *pInstance_
pInstance_ = new Singleton;
}
return *pInstance_;
}
Here, another thread might execute after the check but before the lock: twilight zone. The double-checked locking pattern provides a correct and efficient solution:
Singleton& Singleton::Instance()
{
if (!pInstance_) // 1 first check
{ // 2 twilight zone
Lock myGuard(mutex_); // 3 no more twilight
if (!pInstance_) // 4 second check
{
pInstance_ = new Singleton;
}
}
return *pInstance_;
}
Now, we avoid creating a lock object until the first check has revealed the need
for creating a new instance. Then we lock, and perform a second check. This may
pass or fail, depending on whether another thread has created a new object or
not. Either way, we are safe. If the check fails again, we need to proceed with
the lock and new instance creation, otherwise the need has been fulfilled.
The previous discussions show that there are many choices to make as well as
certain policies that should be universal. The choices can be decomposed into
orthogonal policies (passed as template parameters) with a stock collection of
choices available as well as user-supplied policies.
The slide shows the SingletonHolder template class with template
parameters representing the policies discussed earlier. The first template
parameter T is the type of the singleton object to be
created. SingletonHolder is a container class that wraps a type
T object in the Singletoin design pattern, with policies selected using
the other three template parameters.
A singleton would be declared by a client program as follows:
The class T needs to follow the
standard C++ idiom for Singleton, enumerated in the slide.
The slide shows how the KDL solution could be implemented. First the three
client classes should be implemented, with the protective assumptions and
friendship with class CreateUsingNew. Then the singleton types are
defined using typedef statements. The second argument
CreateUsingNew is a default value but must be given explicitly because
the third argument is also given explicitly. Then Keyboard,
Display, and Log objects can be created in any order in the
application, yet Log will outlive the others if it is created.
The predefined policies in loki represent all of the viable options
discussed in this chapter.
The slide illustrates a simple modification of a stock policy easily implemented
by a client program.
Instance is the unique public member function in SingletonHolder. Instance ties the three policies together.
ThreadingModel exposes an inner class Lock. For the lifetime of a Lock object, all other threads trying to create objects of type Lock will block.
DestroySingleton destroys the Singleton object and sets
destroyed_ to true. SingleHolder does not call
DestroySingleton, rather it passes its address to
LifetimePolicy<T>::ScheduleDestruction which in turn registers
a call to be made at the appropriate time (as determined by LifetimePolicy).
////////////////////////////////////////////////////////////////////////////////
// The Loki Library
// Copyright (c) 2001 by Andrei Alexandrescu
// This code accompanies the book:
// Alexandrescu, Andrei. "Modern C++ Design: Generic Programming and Design
// Patterns Applied". Copyright (c) 2001. Addison-Wesley.
// Permission to use, copy, modify, distribute and sell this software for any
// purpose is hereby granted without fee, provided that the above copyright
// notice appear in all copies and that both that copyright notice and this
// permission notice appear in supporting documentation.
// The author or Addison-Welsey Longman make no representations about the
// suitability of this software for any purpose. It is provided "as is"
// without express or implied warranty.
////////////////////////////////////////////////////////////////////////////////
// Last update: June 20, 2001
#ifndef SINGLETON_INC_
#define SINGLETON_INC_
#include "Threads.h"
#include <algorithm>
#include <stdexcept>
#include <cassert>
#include <cstdlib>
#include <new>
namespace Loki
{
namespace Private
{
////////////////////////////////////////////////////////////////////////////////
// class LifetimeTracker
// Helper class for SetLongevity
////////////////////////////////////////////////////////////////////////////////
class LifetimeTracker
{
public:
LifetimeTracker(unsigned int x) : longevity_(x)
{}
virtual ~LifetimeTracker() = 0;
static bool Compare(const LifetimeTracker* lhs,
const LifetimeTracker* rhs)
{
return rhs->longevity_ < lhs->longevity_;
// bug in distributed code corrected (wrong comparison)
}
private:
unsigned int longevity_;
};
// Definition required
inline LifetimeTracker::~LifetimeTracker() {}
// Helper data
typedef LifetimeTracker** TrackerArray;
extern TrackerArray pTrackerArray;
extern unsigned int elements;
// Helper destroyer function
template <typename T>
struct Deleter
{
static void Delete(T* pObj)
{ delete pObj; }
};
// Concrete lifetime tracker for objects of type T
template <typename T, typename Destroyer>
class ConcreteLifetimeTracker : public LifetimeTracker
{
public:
ConcreteLifetimeTracker(T* p,unsigned int longevity, Destroyer d)
: LifetimeTracker(longevity)
, pTracked_(p)
, destroyer_(d)
{}
~ConcreteLifetimeTracker()
{ destroyer_(pTracked_); }
private:
T* pTracked_;
Destroyer destroyer_;
};
void AtExitFn(); // declaration needed below
} // namespace Private
////////////////////////////////////////////////////////////////////////////////
// function template SetLongevity
// Assigns an object a longevity; ensures ordered destructions of objects
// registered thusly during the exit sequence of the application
////////////////////////////////////////////////////////////////////////////////
template <typename T, typename Destroyer>
void SetLongevity(T* pDynObject, unsigned int longevity,
Destroyer d = Private::Deleter<T>::Delete)
{
using namespace Private;
TrackerArray pNewArray = static_cast<TrackerArray>(
std::realloc(pTrackerArray, sizeof(LifeTimeTracker)*elements + 1));
// bug in distributed code corrected
if (!pNewArray) throw std::bad_alloc();
LifetimeTracker* p = new ConcreteLifetimeTracker<T, Destroyer>(
pDynObject, longevity, d);
// Delayed assignment for exception safety
pTrackerArray = pNewArray;
// Insert a pointer to the object into the queue
TrackerArray pos = std::upper_bound(
pTrackerArray,
pTrackerArray + elements,
p,
LifetimeTracker::Compare);
std::copy_backward(
pos,
pTrackerArray + elements,
pTrackerArray + elements + 1);
*pos = p;
++elements;
// Register a call to AtExitFn
std::atexit(Private::AtExitFn);
}
////////////////////////////////////////////////////////////////////////////////
// class template CreateUsingNew
// Implementation of the CreationPolicy used by SingletonHolder
// Creates objects using a straight call to the new operator
////////////////////////////////////////////////////////////////////////////////
template <class T> struct CreateUsingNew
{
static T* Create()
{ return new T; }
static void Destroy(T* p)
{ delete p; }
};
////////////////////////////////////////////////////////////////////////////////
// class template CreateUsingNew
// Implementation of the CreationPolicy used by SingletonHolder
// Creates objects using a call to std::malloc, followed by a call to the
// placement new operator
////////////////////////////////////////////////////////////////////////////////
template <class T> struct CreateUsingMalloc
{
static T* Create()
{
void* p = std::malloc(sizeof(T));
if (!p) return 0;
return new(p) T;
}
static void Destroy(T* p)
{
p->~T();
std::free(p);
}
};
////////////////////////////////////////////////////////////////////////////////
// class template CreateStatic
// Implementation of the CreationPolicy used by SingletonHolder
// Creates an object in static memory
// Implementation is slightly nonportable because it uses the MaxAlign trick
// (an union of all types to ensure proper memory alignment). This trick is
// nonportable in theory but highly portable in practice.
////////////////////////////////////////////////////////////////////////////////
template <class T> struct CreateStatic
{
union MaxAlign
{
char t_[sizeof(T)];
short int shortInt_;
int int_;
long int longInt_;
float float_;
double double_;
long double longDouble_;
struct Test;
int Test::* pMember_;
int (Test::*pMemberFn_)(int);
};
static T* Create()
{
static MaxAlign staticMemory_;
return new(&staticMemory_) T;
}
static void Destroy(T* p)
{
p->~T();
}
};
////////////////////////////////////////////////////////////////////////////////
// class template DefaultLifetime
// Implementation of the LifetimePolicy used by SingletonHolder
// Schedules an object's destruction as per C++ rules
// Forwards to std::atexit
////////////////////////////////////////////////////////////////////////////////
template <class T>
struct DefaultLifetime
{
static void ScheduleDestruction(T*, void (*pFun)())
{ std::atexit(pFun); }
static void OnDeadReference()
{ throw std::logic_error("Dead Reference Detected"); }
};
////////////////////////////////////////////////////////////////////////////////
// class template PhoenixSingleton
// Implementation of the LifetimePolicy used by SingletonHolder
// Schedules an object's destruction as per C++ rules, and it allows object
// recreation by not throwing an exception from OnDeadReference
////////////////////////////////////////////////////////////////////////////////
template <class T>
class PhoenixSingleton
{
public:
static void ScheduleDestruction(T*, void (*pFun)())
{
#ifndef ATEXIT_FIXED
if (!destroyedOnce_)
#endif
std::atexit(pFun);
}
static void OnDeadReference()
{
#ifndef ATEXIT_FIXED
destroyedOnce_ = true;
#endif
}
private:
#ifndef ATEXIT_FIXED
static bool destroyedOnce_;
#endif
};
#ifndef ATEXIT_FIXED
template <class T> bool PhoenixSingleton<T>::destroyedOnce_ = false;
#endif
////////////////////////////////////////////////////////////////////////////////
// class template Adapter
// Helper for SingletonWithLongevity below
////////////////////////////////////////////////////////////////////////////////
namespace Private
{
template <class T>
struct Adapter
{
void operator()(T*) { return pFun_(); }
void (*pFun_)();
};
}
////////////////////////////////////////////////////////////////////////////////
// class template SingletonWithLongevity
// Implementation of the LifetimePolicy used by SingletonHolder
// Schedules an object's destruction in order of their longevities
// Assumes a visible function GetLongevity(T*) that returns the longevity of the
// object
////////////////////////////////////////////////////////////////////////////////
template <class T>
class SingletonWithLongevity
{
public:
static void ScheduleDestruction(T* pObj, void (*pFun)())
{
Private::Adapter<T> adapter = { pFun };
SetLongevity(pObj, GetLongevity(pObj), adapter);
}
static void OnDeadReference()
{ throw std::logic_error("Dead Reference Detected"); }
};
////////////////////////////////////////////////////////////////////////////////
// class template NoDestroy
// Implementation of the LifetimePolicy used by SingletonHolder
// Never destroys the object
////////////////////////////////////////////////////////////////////////////////
template <class T>
struct NoDestroy
{
static void ScheduleDestruction(T*, void (*)())
{}
static void OnDeadReference()
{}
};
////////////////////////////////////////////////////////////////////////////////
// class template SingletonHolder
// Provides Singleton amenities for a type T
// To protect that type from spurious instantiations, you have to protect it
// yourself.
////////////////////////////////////////////////////////////////////////////////
template
<
typename T,
template <class> class CreationPolicy = CreateUsingNew,
template <class> class LifetimePolicy = DefaultLifetime,
template <class> class ThreadingModel = SingleThreaded
>
class SingletonHolder
{
public:
static T& Instance();
private:
// Helpers
static void MakeInstance();
static void DestroySingleton();
// Protection
SingletonHolder();
// Data
typedef typename ThreadingModel<T*>::VolatileType PtrInstanceType;
static PtrInstanceType pInstance_;
static bool destroyed_;
};
////////////////////////////////////////////////////////////////////////////////
// SingletonHolder's data
////////////////////////////////////////////////////////////////////////////////
template
<
class T,
template <class> class C,
template <class> class L,
template <class> class M
>
typename SingletonHolder<T, C, L, M>::PtrInstanceType
SingletonHolder<T, C, L, M>::pInstance_;
template
<
class T,
template <class> class C,
template <class> class L,
template <class> class M
>
bool SingletonHolder<T, C, L, M>::destroyed_;
////////////////////////////////////////////////////////////////////////////////
// SingletonHolder::Instance
////////////////////////////////////////////////////////////////////////////////
template
<
class T,
template <class> class CreationPolicy,
template <class> class LifetimePolicy,
template <class> class ThreadingModel
>
inline T& SingletonHolder<T, CreationPolicy,
LifetimePolicy, ThreadingModel>::Instance()
{
if (!pInstance_)
{
MakeInstance();
}
return *pInstance_;
}
////////////////////////////////////////////////////////////////////////////////
// SingletonHolder::MakeInstance (helper for Instance)
////////////////////////////////////////////////////////////////////////////////
template
<
class T,
template <class> class CreationPolicy,
template <class> class LifetimePolicy,
template <class> class ThreadingModel
>
void SingletonHolder<T, CreationPolicy,
LifetimePolicy, ThreadingModel>::MakeInstance()
{
typename ThreadingModel<T>::Lock guard;
(void)guard;
if (!pInstance_)
{
if (destroyed_)
{
LifetimePolicy<T>::OnDeadReference();
destroyed_ = false;
}
pInstance_ = CreationPolicy<T>::Create();
LifetimePolicy<T>::ScheduleDestruction(pInstance_,
&DestroySingleton);
}
}
template
<
class T,
template <class> class CreationPolicy,
template <class> class L,
template <class> class M
>
void SingletonHolder<T, CreationPolicy, L, M>::DestroySingleton()
{
assert(!destroyed_);
CreationPolicy<T>::Destroy(pInstance_);
pInstance_ = 0;
destroyed_ = true;
}
} // namespace Loki
////////////////////////////////////////////////////////////////////////////////
// Change log:
// May 21, 2001: Correct the volatile qualifier - credit due to Darin Adler
// June 20, 2001: ported by Nick Thurn to gcc 2.95.3. Kudos, Nick!!!
////////////////////////////////////////////////////////////////////////////////
#endif // SINGLETON_INC_
////////////////////////////////////////////////////////////////////////////////
// The Loki Library
// Copyright (c) 2001 by Andrei Alexandrescu
// This code accompanies the book:
// Alexandrescu, Andrei. "Modern C++ Design: Generic Programming and Design
// Patterns Applied". Copyright (c) 2001. Addison-Wesley.
// Permission to use, copy, modify, distribute and sell this software for any
// purpose is hereby granted without fee, provided that the above copyright
// notice appear in all copies and that both that copyright notice and this
// permission notice appear in supporting documentation.
// The author or Addison-Welsey Longman make no representations about the
// suitability of this software for any purpose. It is provided "as is"
// without express or implied warranty.
////////////////////////////////////////////////////////////////////////////////
// Last update: June 20, 2001
#include "Singleton.h"
using namespace Loki::Private;
Loki::Private::TrackerArray Loki::Private::pTrackerArray = 0;
unsigned int Loki::Private::elements = 0;
////////////////////////////////////////////////////////////////////////////////
// function AtExitFn
// Ensures proper destruction of objects with longevity
////////////////////////////////////////////////////////////////////////////////
void Loki::Private::AtExitFn()
{
assert(elements > 0 && pTrackerArray != 0);
// Pick the element at the top of the stack
LifetimeTracker* pTop = pTrackerArray[elements - 1];
// Remove that object off the stack
// Don't check errors - realloc with less memory
// can't fail
pTrackerArray = static_cast<TrackerArray>(std::realloc(
pTrackerArray, --elements));
// Destroy the element
delete pTop;
}
////////////////////////////////////////////////////////////////////////////////
// Change log:
// June 20, 2001: ported by Nick Thurn to gcc 2.95.3. Kudos, Nick!!!
////////////////////////////////////////////////////////////////////////////////
