A Little Flag Waving

If you want a symbolic gesture, don't burn the flag; wash it. - Norman Thomas

In a few of the previous posts, 'Failure To Launch', 'Pebble In The Ocean', and 'The Value of Partnership' we took the high road and spoke about some of the generalities of launching a product, an immediate perspective of what that was like, and a little reminiscence on partnership both loose and tight. Today we'll change it up a bit and take the low road to explore some of the nity grity details of development with an entry I wrote soon after the initial release of Through To Iota.

While writing this entry, an old friend sent me a very appropriate comic that is something to keep in mind while reading what follows. After working to bring one of our prototype products up to date using the latest version of our game engine, Phoenix, I could particularly appreciate its humour. Of course, we always strive for the door on the left but sometimes even our best efforts eek out a little of that on the right - especially when time has provided a better perspective.

Later perspective aside, lets take a closer look at a single software construction issue; how to handle flags. A good, brief introduction is here. A quick glance at the reference indicates that this is inherently a trivial problem; you get some data type composed of a bunch of bits then use the bitwise operators to check to see if a bit is on or off. Something like this is usually the order of the day:


int main(int argc, char* argv[])
{
unsigned int uiFlags = 0;
unsigned int uiValue = (1 << 0);
bool bFlagSet = (uiFlags & uiValue);
return bFlagSet ? 1 : 0;
};


Piece of cake right? Sure, and if you've only got one flag, one area that needs to know it's value and you don't need to check it often or asynchronously, something this simple works - use the right tool for the job. There is quite a bit of reference material out there that will get you this far in understanding the usage of flags, but what about integrating this into an object oriented system like Phoenix? For Phoenix we wanted objects to be updated as to the status of a flag change right away so that if their internal state depended on a specific flag in a specific object changing, they'd be notified right away without having to poll. The approach taken, an observer pattern implementation, allows objects to be notified immediately and for each individual flag state change. I've crafted an example bit of code utilizing our flag handling classes to go along with this blog post which can be found here.

In this case, templates are your friend, no really, as without them this approach wouldn't work. The three templated classes to focus on are Flags in flags.h/cpp and the IFlagsWatcher interface in IFlagsWatcher.h. Let's talk about each in turn:

Flags.h

No rocket science here, a few basic setting, unsetting, and checking methods; Set, UnSet, and Is. Which as you would imagine set a flag, unset a flag and check it's state. However there are a few more which require a little extra detail; NextAvailableFlag, Watch, and DontWatch. NextAvailableFlag allows us to, when creating a flag, simply call this method to get the next available bit in order. No more counting up the numbers as you create your flags. Watch and DontWatch are part of the observer implementation, in the provided example you can see ChangeTracker calling Watch to request notification of changes and then later calling DontWatch to stop receiving them. The only other method left is 'NotifyWatchers' which as you might expect notifies any objects who are 'Watch'ing that a flags value has changed.

Flags.cpp

Nothing much of note here, just a fairly basic use of stl map's and list's to keep track of who to notify and the actual code to do so. You might notice the one glaring hole that you could probably drive a Mac truck through though... The Flags::Flags(T* pT) constructor simply assumes that T will have a m_uiFlags member and that this member matches the MAX_FLAGS = sizeof(unsigned int) * 8 above. Certainly room for improvement here no doubt, although it has served our needs as is so far.

IFlagsWatcher.h

This specifies the interface that objects must implement if they want to receive notification of flag changes via the 'FlagsChanged' method. Of note it is again a template so generic types of objects with flags can be 'Watch'd.

Overall is this the be all and end all of flag implementations? Certainly not, it's just another case of using the right tool for the job. For our particular requirements in Phoenix it was a good way of keeping those objects that needed to be aware of each others state changes up to date, but it may be overkill for what you need to do. As always there are trade-offs to be made and even in our case we later substituted our flags template usage with a more direct generic publisher/subscriber callback approach in many cases.

Comments an questions welcome as there's always a different road that could be taken and more to learn.

Get the full example source.