(Sigh. I just noted that Blogger's WYSIWYG editor doesn't escape brackets properly, so all the template parameters are gone from the code examples... sorry about that.)
Having coded a lot of C++ (10 years professionally), plus a brief (1,5 year) string in Python, I've gained some perspective on how to cope with these beasts. I hope some of you will find it interesting, but I expect (or rather, hope) experienced readers with mostly just nod and agree.
The notable C++ apps I've been involved with usually has between two and fifteen "manager" objects that we use here and there. This involves various tasks, accessing the file system (usually with some caching and custom path lookups), managing logging, loading shared (graphics) resources such as sounds, textures, shaders (and during development, instantly reload these if the change on-disk), being etc etc etc.
So, you have all these things that:
- need to be accessed by a large number of components in your app
- should usually exist as one instance
- should exist when we access it
- will probably depend on each other a bit (loading a texture needs the file system, logging needs file system, file system might want to log, etc.)
(Experienced readers will loudly think "separation of concerns", and rightly so. I'll get there eventually.)
As touted by the GoF as a proper Design Pattern (which, IMHO according to them, is often just a term for how to code something in pure-OOP that should be in the language from the start, such as multiple-dispatch, visitor, etc etc..) they should be initialized lazily.
Singleton implementation 101
The easiest way in C++ to do this is a function local static variable. This is not thread-safe unless your compiler supports it (usually with a flag).
class Singleton {
static Singleton& the() {
static Singleton s_the;
return s_the;
}
void foo() { ... }
private:
...
};
(FYI, I prefer the m_ prefix for member variables, s_ for static, and ms_ for member-static...)
To get something thread-safe without compiler support, you have to check this yourself, but you also need a mutex or two, which must be created safely too. (Locking the mutex on every access can be avoided by doing double-dispatch. This requires careful attention to the memory semantics on your platfrom (default behaviour x86 seem ok though), but note that Java's double-dispatch is broken due to it's slack memory model & aggressive optimizating compilers. It might be fixed in more recent version though.)
So, with locking, you have something like this:
class Singleton {
static Singleton& the() {
scoped_lock lock(&ms_mutex);
if (ms_the== 0) {
ms_the = new Singleton();
atexit(deleteMe);
}
return *ms_the;
}
void foo() { ... }
private:
static std::Singleton* ms_the // set to null before main(), declared in cpp-file
static Mutex ms_mutex; // constructed before main()
static void deleteMe() { delete ms_the; }
...
};
// you could/should probably use boost/std scoped_ptr/unique_ptr to avoid calling the c-library's atexit(), if you have access to those.
A lot of problems here are caused by having to implement lazy initialization. And most often, you don't need that, because your managers-as-singletons are created deterministically anyway, and if things get hairy, you want explicit control. I'll get to that in a moment.
My default singleton implementation for small C++ projects avoids lazy initialization and the problems with order-dependency during construction/destruction between managers by simply not constructing itself. That is usually left to the main() function. (Or the unit test fixture, or whatnot...) Usually your app has some well defined, single-threaded, execution-paths where this takes place, if main() doesn't suit you.
class Singleton {
Singleton& the() {
assert(ms_the);
return *ms_the;
}
Singleton() {
assert(ms_the == 0);
ms_the = this;
}
~Singleton() {
assert(ms_the == this);
ms_the = 0;
}
void foo() { ... }
private:
static Singleton* ms_the // declared in cpp file, so is set to null before main()
};
int main(...) {
Singleton mysingleton;
Singleton2 mysingleton2; // uses first singleton
mainloop();
return 0;
}
This is rather neat, I think. The singleton class has pretty minimal logic, just guarding against programming errors. It's constructed at a well defined point, and it's cleaned up on exceptions, or before main() returns (so we don't end up with half-unloaded DLLs during exit. This can be a problem..)
This way, we've solved how to make singletons always exist before we access them. We create the objects up-front, in a specific order. They will be destroyed in opposite order.
Also, if we have several managers that depend on each other, any ordering issues can be resolved manually. This is especially important when shutting down (if you want to clean up properly...). Modern OS:es don't require that as much, since they will clean up your mess regardless if you crash and burn or exit the building the right way. However, it feels better to do it properly. You might have hardware that need shutting down or notification to network services to say that you're going down and you know about it (more or less).
Having an explicit construction order like this means that at the very least, you don't have to mess with something like the
Loki SingletonHolder's LifetimePolicy imlemented by the LifeTimeTracker and the GetLongevity funciton. Ugh. I've done that once, hunting around and setting longevity values in files all over the framework. Never again,!
It should be noted that the drawback of managing your singletons manually is that you need to alter a lot of main methods or unit test fixtures if you add a new singleton to a library that many of your apps uses. However, that's usually only done once (or twice), so it's not that bad. The asserts should trip in your smoke tests if something is wrong (smoke tests is incidentally the minimal amount of testing anyone should have, IMO. The rest is a never-ending debate...)
So, all's seems fine here... until you want:
Two instances of a singleton!
(This is not a doubleton, which is more like what happens when you get the singleton creation logic wrong, or load the different versions of the same DLL, or are running Java, or... well..)
As an example, say if you have a TextureManager. This loads the images you apply on everything in the game, from environment to characters to the GUI. It has a function for reloading all textures (if the graphics context is lost, as can happens on Windows), clearing everything (done before loading a new level) etc. etc. Say, you might want one for overlay GUI (static throughout the run) and another for the in-game assets (that differ between each level). Separating this inside the TextureManager might feel backward to you, so what do we do?
If we had managed the singleton's lifetime with a static local function variable, just adding a second such function would work pretty well. Except that we don't want to do that, since the lazy initialization has issues with threading and lifetime ordering.
We could, and should, extract the management of the singleton's global access out from the class itself. ("Separate these concerns, already!" I hear... :) This is what Loki's SingletonHolder tries to do, except it's a toolbox so big you're likely to get something that
shoots you in the foot, C++ style, or at least chose the wrong tool).
Here's something smaller for brevity, where we use an integer template parameter simply to tag the class so that the compiler will generate different types (i.e. different classes) and thus separate static member variables.
template
class SingletonHolder {
T& the() { assert(ms_the); return *ms_the; }
SingletonHolder() { assert(!ms_the); ms_the = new T(); };
~SingletonHolder() { assert(ms_the); delete ms_the; ms_the = 0; }
private:
static T* ms_the;
};
I'd put these typedefs somewhere, probably in the same header as the TextureMgr class for a small project.
typedef SingletonHolder GuiTexMgr;
typedef SingletonHolder LevelTexMgr;
Tehn, our main() would then look something like this:
int main(...) {
GuiTexMgr gui_texmgr;
LevelTexMgr level_texmgr;
mainloop();
return 0;
};
... and we need to declare these, as with all the other statics from previous examples (I left that part out earlier).
TextureMgr* GuiTexMgr::ms_the = 0;
TextureMgr* LevelTexMgr::ms_the = 0;
This is not too bad actually. The TextureMgr class doesn't need to bother about it's own lifetime or visibility. Our SingletonHolder does that work for us, isn't overly complex, and the order is well defined by main as we saw earlier.
Still, there's room for improvement, especially if we want to...
Swap implementations!
As might be required depending on the current situation. (mocking out stuff during testing is a prime example, running a local vs. remote master server is another, as was done in Quake/Doom...). Not that singletons are really necessary for that, it could be hidden beneath interfaces and so on.
Anyway, it's rather simple to alter our SingletonHolder to manage that. We simply give it the instance that it should store:
template
class SingletonHolder {
public:
T& the() { assert(ms_the); return *ms_the; }
SingletonHolder(T* t) { assert(!ms_the); ms_the = t; };
~SingletonHolder() { assert(ms_the); delete ms_the; ms_the = 0; }
private:
static T* ms_the;
};
And the main() is just this:
int main(...) {
GuiTexMgr gui_texmgr(new TextureMgr);
LevelTexMgr level_texmgr(new TextureMgr);
mainloop();
return 0;
};
This also allows us to send constructor parameters to our instances (cache size or max memory usage, as could be relevant in the case of texture management in the example here).
Note that we're essentially going backwards from fully-automatic to manual handling of things. I argue that this is a good thing as your application grows. I also think we're quite low on overhead & complexity still, and the goings-on are easy to follow, understand and debug.
You can also write a small test that uses a mock implementation in the fixture (if you remove the GuiTexMgr from your test applications global fixture).
SingletonRegistry
If (a.k.a. once) we get enough of these objects (and there could be more than a few, if you have a GUI app and want to track undo management, the applications "current" document's status, global time of the process you're modelling, settings saving to file/registry, etc) it can get both expensive and bothersome to having to create/destroy all these every time you want to test something. Also, there will be a lot of SingletonHolder instances here and there.
So, rather than having a lot of SingletonHandlers, we store everything in one place. For simplicity here, we assume all singleton-objects have a common base class (use
boost::any to work around that) and that we store and lookup the objects by strings (integers are fine too if it suits you, then you could use a std::vector instead of map for extra speed.).
Since we want to store everything in one place, we need to singletonize the holder I've used one of the earlier methods for that here. Recurse ad lib (ad nauseum?).
class SingletonRegistry {
public:
static SingletonRegistry* the() { return ms_the; }
SingletonRegistry() { ms_the = this; }
void store(Manager* mgr, const std::string& id) {
assert(m_map.find(id) != m_map.end());
m_map[id] = mgr;
m_seq.push_back(id);
};
template
T& lookup(const std::string& id) {
assert(m_map.find(id) != m_map.end());
Manager* mgr = m_map[id];
assert(dynamic_cast(mgr));
return *static_cast(*t);
}
~SingletonRegistry() {
// destroy in insertion order
for(size_t i=0; i
Manager* mgr = lookup(m_seq[i]);
m_map.erase(m_seq[i]);
delete mgr;
}
ms_the = 0;
}
private:
std::map m_map;
std::vector m_seq;
};
(Here, I've used RTTI via dynamic_cast to assert that the type is right. If you want to use some other type-lookup, feel free to do that. I think enforcing type-safety inside the lookup is a good thing.)
Our main function then looks like:
int main(...) {
SingletonRegistry reg;
reg.store(new TextureMgr, "textures/gui");
reg.store(new TextureMgr, "textures/level");
mainloop();
return 0;
}
Now accessing the object is different, because we need to get by string rather than just call a static function on a class:
TextureMgr* mgr = SingletonRegistry::the().lookup("textures/gui");
mgr->load(...);
If we like strings (note the hierarchy I introduced), we can avoid doing this string-based lookup each time, we can trade time for space by re-casting our SingletonHolder into a reference holder:
template
class SingletonHolder {
public:
SingletonHolder(const std::string& id) : m_the( SingletonRegistry::the().lookup(id)) { }
~SingletonHolder() { ms_the = 0; }
T& the() { return *m_the; }
// or, even neater:
T* operator->() { return *m_the; }
private:
T* m_the;
};
So, a class using this could look like this:
class ProgressBar {
public:
ProgressBar() : m_texmgr("texture/gui") {
m_texmgr->loadTexture("progress.tex");
}
void draw() {
m_texmgr->bindTexture("progress.tex");
...
}
private:
SingletonHolder m_texmgr;
};
Then, we can add instances of this class as member variables to our objects, or as on-stack function variables. Of course, you don't want this in a class that you have millions of instances of, but do each instance there really need global access this way? I think not...but you could fall back to some of the options listed above if necessary, or combine and mix as you'd like.
class ParticleSystem {
public:
ProgressBar() : m_texmgr("texture/dynamic") { }
void draw() {
foreach(Particle& p : m_particles) {
p.draw(m_texmgr);
}
}
private:
SingletonHolder m_texmgr;
std::vector m_particles;
};
(For nitpicks: Yes, I know you should don't do a draw call per particle... you'd store the data (pos, vel, colour, whatnot) in a buffer on to the graphics card and render it with one call. That buffer could be a texture from which the vertex shader reads... so, this code isn't too wrong.. ;-p.)
Final words..
So, we've basically gone from the singleton-is-the-class to
dependency injection. A side note is that the classes are called InjectionRegistry/Injected on our own library. Also, that wikipedia page has Java examples with object lookup based on type, whose issues we covered earlier.
One could extend the implementation outlined above to a dependency injection "framework" by reading stuff from a config file and instantiating different classes based on that, but then you need some way to lookup types and set properties and so on, which is not the sort of batteries includedo in C++. (OTOH, if you're developing with
Qt or a similar framework, you have much of the required tools at your disposal.)
The registry shown here could alsobe used for more than just long-lifed objects, of course, but then you'd need to communicate changes in the registry to the holders and maybe also the instances which contain them.
However, this post is already long enough, so I'll draw the line here.
I hope you enjoyed it. :)
