Curtis Krauskopf is the principal of The Database Managers Inc., where he creates decompilers. He can be contacted at curtis@ decompile.com.
My C++ program is using a third-party database library. It uses one object that represents the state of the database. The database object can be dynamically deleted to release all of its resources and it needs to be automatically deleted if it still exists at program termination. "So how am I going to solve this problem?" I ask myself.
The "one object" requirement screams for a Singleton solution. But the ability to dynamically destroy a Singleton isn't handled by most Singleton implementations [1]. After the Singleton has been manually destroyed, it needs to automatically resurrect itself the next time it's used in the program. Also, if the Singleton exists when the program terminates, it needs to destroy itself to release its resources.
In this article, I examine the trade-offs in implementing the Singleton design pattern, show how the Loki C++ Library of design patterns and idioms accommodates them, and then define a new policy to solve a difficult problem that Loki does not address. Along the way, I illustrate several issues related to std::atexit, create a new policy that works well within a policy-based framework, and work around the abstraction limitations offered by Loki's Singleton. The policy encapsulates a technique in which a Singleton watches the lifetime of another Singleton.
The Loki library has a Singleton template called a SingletonHolder, which lets you instantiate a Singleton from any struct or class with a constructor that takes no parameters [2]. The Loki implementation provides template policies that let you specify how the Singleton is created, how it is destroyed, and even what threading model it uses (either single threaded or multithreaded).
From a user's perspective, all of these features are wrapped into a single typedef that looks like this:
typedef SingletonHolder<MyClass, CreateUsingNew, DefaultLifetime, SingleThreaded > obj;
And because of default parameters in the template, this declaration can be simplified to be more friendly looking:
typedef SingletonHolder<MyClass>obj;
The Singleton is accessed by using obj::Instance(). The Instance() method returns a reference to the Singleton so you access the Singleton's methods with the dot operator, like this:
obj::Instance().method();
SingletonHolder Policies
There are three template policies that specify how a Singleton is created: CreateUsingNew, CreateUsingMalloc, and CreateStatic. Both CreateUsingNew and CreateUsingMalloc do that obvious thing of creating the object using new or malloc. CreateStatic uses placement new to create the object in static memory.
There are four template policies that define the Singleton's lifetime: DefaultLifetime, NoDestroy, PhoenixSingleton, and SingletonWithLongevity.
The DefaultLifetime policy mimics the lifespan of a normal global C++ object: The object lives until the program terminates, then the object's destructor is called.
The NoDestroy policy is the simplest—the Singleton is not destroyed. Undestroyed Singletons are not a memory leak but are a potential resource leak [3].
The PhoenixSingleton is an interesting policy because it can resurrect a Singleton during program termination. When the Singleton is needed after it has been destroyed (when the program is terminating), the PhoenixSingleton policy causes the Singleton to be reincarnated. All of the code needed for this ability is invisible to users. Here's an example of a PhoenixSingleton declaration and use:
class Example {
public:
void method() { ... }
};
typedef SingletonHolder<
Example,
CreateUsingNew,
PhoenixSingleton
> myExample;
...
myExample()::Instance().method();
Despite its name, the SingletonWithLongevity policy does not create a Singleton that retains its state after it has been destroyed (it does not create a persistent Singleton). Instead, it lets users specify the order in which Singletons are destroyed. With this policy, regardless of what order the Singletons were created or first accessed, the Singletons are destroyed in a user-defined priority [4].
The SingletonWithLongevity policy has a static function called SetLongevity. Both globally and locally declared dynamic objects can be scheduled for destruction by using SetLongevity():
Example *pLocal =
new Example("Dynamic Example");
SetLongevity(pLocal, 5);
The default (third) parameter for SetLongevity is:
Loki::Private::Deleter<Example>::Delete
This is a static function that simply calls delete on whatever object is passed to it. SetLongevity uses std::atexit() to register a callback function that deletes the object during program termination. Listing 1 is a Keyboard Singleton object scheduled for destruction with a longevity value of 10.
Back to PhoenixSingleton
Whereas SingletonWithLongevity lets users specify the destruction order of Singletons, the PhoenixSingleton policy takes a different philosophy. It says, "I don't care what order the Singletons are destroyed; but if I need a Singleton after it has been destroyed, automatically bring it back to life and then schedule it for destruction again."
Listing 2, an example of the PhoenixSingleton policy at work, defines Example and Log classes that display text when each class's constructor and destructor execute. Log is a PhoenixSingleton.
The Example object's destructor calls the Log Singleton. If a Log Singleton doesn't exist when the Example destructor executes, a Log object is instantiated.
In main(), the longevity for the Example object is set before a Log object is instantiated. Calling SetLongevity schedules the object for destruction. This is important because, for this test program, the Log Singleton needs to be destroyed before the Example object is destroyed so that the Log Singleton is a dead reference when the Example object is destroyed. Loki causes the Log Singleton to be destroyed before the dynamically allocated Example object because the Log Singleton was the last object instantiated—this mimics automatic C++ object destruction rules. Figure 1 shows the output of Listing 2.
What should be surprising about this output is the last line—or rather, what's not the last line. If the PhoenixSingleton policy was really working, you should expect "Log d'tor" to be the last line. So why is the PhoenixSingleton policy not destroying Log a second time?
The reason is because of some oddities in the std::atexit function. Both the C and C++ Standards were unclear about what should happen when atexit() is called from within a function that itself was called when the atexit call stack is unwinding. This has been fixed in a subsequent corrigendum [5], but your compiler may not be compatible.
Common sense says "it should just work," but Andrei Alexandrescu discovered "on three widely used compilers that the behavior ranges from incorrect (resource leaks) to application crashes" [6].
Loki allows PhoenixSingletons that are resurrected to become resource leaks when the ATEXIT_FIXED symbol is not defined at compile time. Of course, one reliable way of knowing if atexit works well for functions called during exit processing on your compiler is to read the documentation. Because most compilers don't have obscure library functions documented to that degree, you can try the atexit/test.cpp program (available at http://www.cuj.com/code/).
Back To the Problem
Table 1 shows a comparison of the Loki lifetime policies and the problem. The PhoenixSingleton policy is the closest solution because its limitation is being able to handle a Singleton deleted by users. The limitation exists because there is no way to tell atexit that a function shouldn't be called anymore.
Building a Policy
I need a callback function for atexit that doesn't blindly delete a Singleton. I also need to create a policy that lets the Singleton be deleted on demand but automatically deletes the Singleton at the end of the program, if it's still alive.
DeletableSingleton seems like an appropriate name. It needs the same policy interface that the SingletonHolder lifetime policies use. Listing 3 is the public interface for DeletableSingleton.
It looks straightforward. The oddest part is the pFun parameter—it's a pointer to a static function that takes no arguments and returns void. When a SingletonHolder wants to schedule a Singleton for destruction, it calls ScheduleDestruction in the lifetime policy and passes a callback function that the policy should use when the Singleton needs to be destroyed.
Listing 4 shows a snippet of the SingletonHolder class that schedules a Singleton's destruction when the object is instantiated. Listing 5 is the DestroySingleton template method that is used to destroy SingletonHolder Singletons. This is the function pointer that is passed to ScheduleDestruction.
The way that a Singleton is destroyed depends on how it was created. Listing 5 shows that CreationPolicy<T>::Destroy is called to destroy the Singleton.
Putting all of these pieces together, this is how it works:
- The first time the code in Listing 4 executes, pInstance_ is null and destroyed_ is false.
- MakeInstance() creates an instance of the Singleton by calling CreationPolicy<T>:: Create();.
- MakeInstance() calls ScheduleDestruction with a callback function pointer. This is where the DestroySingleton policy gets to take over. It needs to remember the pointer function passed to DestroySingleton so that it can be called later when the Singleton needs to be deleted during program termination. ScheduleDestruction needs to register a callback function in atexit that is smart enough to not blindly delete the Singleton if it has already been deleted by users.
- At some point, users might manually delete the Singleton. When that happens, the private destroyed_ Boolean in SingletonHolder is set to true to signal that pInstance_ is a dead reference.
- The Singleton might again be referenced in the program. Since it's a dead reference when MakeInstance() is called, this time, MakeInstance() calls OnDeadReference() in the DestroySingleton policy.
- MakeInstance then calls CreationPolicy<T>:: Create() again to recreate the Singleton.
- MakeInstance then once again calls ScheduleDestruction. Because the DeletableSingleton-specific callback static function has already been registered in atexit (in step 2), ScheduleDestruction only needs to remember the pointer function passed on this iteration. This is because it might be different than on the first pass when the original (now dead) Singleton was instantiated.
- The program eventually terminates. atexit unwinds the function callback stack and the custom static for DestroySingleton is called. If the Singleton is still alive (if destroyed_ in SingletonHolder is false), the most recent function pointer passed to ScheduleDestruction is called to destroy the Singleton. If the Singleton has been killed manually, there is nothing for the callback function to do so, it should quietly terminate.
Based on this step-by-step account, the code for DestroySingleton's ScheduleDestruction method is in Listing 6.
GracefulDelete is a function for the DeletableSingleton policy that checks if the Singleton has been deleted. It's a static callback function that atexit calls when the program terminates.
For GracefulDelete to do its work, it needs to know the status of SingletonHolder's destroyed_ Boolean. Unfortunately, that is private data and SingletonHolder doesn't provide any method that otherwise exposes destroyed_.
Back To the Drawing Board
I could cheat and make destroyed_ public—or better (if there is such a thing as "better" cheating), I could add a method to SingletonHolder that returns destroyed_'s status.
The abstraction provided by SingletonHolder is otherwise fine, so I'll do some more work to accommodate a new policy.
I only need to know when the Singleton is manually destroyed; otherwise, I can assume it's still alive and Do The Right Thing in GracefulDelete.
The way users would manually destroy a SingletonHolder that uses the DestroySingleton policy is to call this prototype:
CreationPolicy<T>::Destroy(T*);
where CreationPolicy is the creation policy users specified for the SingletonHolder for class T. Because MakeInstance() returns a reference and Destroy takes a pointer, an actual call would look like this:
MyClass &singleton = myclass::MakeInstance(); CreateUsingMalloc<MyClass> ::Destroy(singleton);
This would certainly delete the Singleton, but there are two problems:
- Whenever the creation policy for the Singleton changes, it's inconvenient to find all of the occurrences of Destroy and change the creation policy there, too. A typedef would simplify the work, but the typedef would still have to be changed whenever the creation policy for the Singleton was changed. If you get it wrong, the compiler will not help you because it doesn't know why you're calling Destroy—it just knows that you want to call Destroy for a particular creation policy. The compiler will use a template that uses the obsolete policy you've specified. You could be using free() to destroy your statically allocated Singletons!
- However Destroy is called, there needs to be some kind of hook that tells DeletableSingleton that the Singleton is dead because we can't peek into SingletonHolder to get that information.
What about that Loki::Private::Deleter<...>::Delete static that is used as a default parameter to SetLongevity? It's just fine for Singletons that use the CreateUsingNew policy, but it won't work for the other policies because the Deleter static always uses delete to kill the Singleton.
Since atexit() is calling a static method to destroy the Singleton (GracefulDelete) when the program terminates, what if users called the same method? That would actually work if GracefulDelete kept track of the status of the Singleton.
The pseudocode for GracefulDelete is:
if (singleton is dead) then exit mark singleton as dead call SingletonHolder's callback function
The code for GracefulDelete is:
void DeletableSingleton<T>
::GracefulDelete()
{
if (isDead) return;
isDead = true;
deleter();
}
Remember that deleter is a pointer to the SingletonHolder callback function.
Listing 7 implements the DeletableSingleton policy. The code to delete a Singleton that is using the DeletableSingleton policy is:
DeletableSingleton<MyClass>:: GracefulDelete();
This can even be simplified by using a typedef:
typedef DeletableSingleton<MyClass> killMyClass; ... killMyClass::GracefulDelete();
What if the typedef for the Singleton for MyClass is changed to not be a DeletableSingleton? What if it's changed to use the PhoenixSingleton or even the NoDelete policy?
The program still uses this code to try to manually delete the Singleton. The compiler won't catch this mistake, but it's not a problem. The first thing that GracefulDelete does is check if isDead is true. isDead defaults to true and it is only set false when ScheduleDestruction is called in DeletableSingleton. Since that never happens for Singletons that don't use the DeletableSingleton policy, there isn't a problem. The Singleton isn't manually deleted, but it still is automatically deleted when using policies other than NoDelete.
That's exactly what you would like to have happen. The code for manually deleting the policy does nothing when the Singleton isn't using DeletableSingleton and the code works right when the Singleton is using the DeletableSingleton policy.
Program Termination
DeletableSingleton only calls std::atexit() the first time a specific Singleton class is instantiated to prevent filling up the atexit() stack. DeletableSingletons are always deleted in the order of their first instantiation, not based on their most recent instantiation.
That leads to a problem, though. What happens if a DeletableSingleton is instantiated after its own atexit callback function has executed? In that case, based on Listing 7, the Singleton becomes a resource leak because GracefulDelete will not be passed to atexit again.
That problem can be fixed, too. Listing 8 shows the differences of Listing 7 that eliminate a resource leak. atexitCallback was made protected so that users wouldn't accidentally use it instead of GracefulDelete.
Conclusion
The Loki library provides a SingletonHolder template that is able to create a Singleton object from any user-defined class. The library is flexible enough to provide automatic deletion for most policies and to provide automatic deletion for objects allocated with new that are not otherwise deleted by users.
The PhoenixSingleton policy lets a Singleton be resurrected if it was destroyed during program termination. None of the Loki policies allow Singletons to be manually deleted by users and to provide automatic deletion if the Singleton is still alive at program termination.
The DeletableSingleton policy provides exactly those services. The GracefulDelete static is even graceful enough to not do any harm if it's called when the Singleton does not use the DeletableSingleton policy.
Because DeletableSingleton is using a template, all of the instances of DeletableSingleton<T> for any type T are using the same pairs of static Booleans (isDead and needCallback). Effectively, DeletableSingleton becomes a Singleton that is watching another Singleton.
Acknowledgment
Thanks to Andrei Alexandrescu for peer-reviewing this article and providing excellent suggestions.
References
- [1] Vlissides, John. "To Kill a Singleton," C++ Report, June 1996.
- [2] http://sourceforge.net/projects/loki-lib/.
- [3] Alexandrescu, Andrei. Modern C++ Design: Generic Programming and Design Patterns Applied, Addison-Wesley, 2001, page 133.
- [4] The errata note for Modern C++ Design, located at http://moderncppdesign.com/errata/, for page 142 reports that the comparison for LifetimeTracker::Compare is backwards—it should make higher longevity objects last longer, but instead it destroys the highest longevity objects first. Alexandrescu's note for this errata is that it has been fixed in the code on SourceForge. If your implementation of Loki does the opposite, then download the most current version of Loki and try again.
- [5] The full WG21 committee has voted to accept the Defect Report's Proposed Resolution as a Technical Corrigenda (ISO/IEC IS 14882:1998(E)). The solution is completely compatible with Loki's expectation of having ATEXIT_FIXED defined at compile time.
- [6] Alexandrescu, Andrei. Modern C++ Design: Generic Programming and Design Patterns Applied, Addison-Wesley, 2001, page 139.
