I may update the article with explanations of what’s going on and why this all works later if time permits.

I’m going to jump in and start with a relisting of the Metadata class I built last time.

The Metadata class has just enough information for some interesting demos but not much else. The m_Size member might be enough to support a memory allocation method for applications that never need to worry about extended alignment, but that might not be enough for many games that use extended-alignment for vectors and matrices that are intended to be optimized with SSE, NEON, or AltiVec.

Inheritance information is one of the easier things to add to our Metadata class. Especially if we limit ourselves to single-inheritance patterns, which is what I do. Multiple-inheritance has a lot of valid use cases, but the complexity for our implementation is high and the benefits of supporting multiple-inheritance with dynamic type casting in an engine that makes heavy use of component-based design are relatively limited.

The first step then is to extend Metadata with a pointer to a parent Metadata, representing the inheritance.

Quite straight forward. You may have noticed that I also added an isa() method to Metadata. The method simply checks if the parameter is in the chain of parent pointers for the Metadata instance. It will be used for dynamic type casting/checking later on.

Actually setting the pointer require a small addition to the macros we created in the last article. The macros made use of templates and a special MetaSingleton<> class, which comes in very handy now.

Using the macros to define metadata for types with and without parents is simple:

It’s entirely reasonable to just create two different DEFINE_META macros; one for types with parents and one for types without, with the former removing the need to explicitly invoke META_TYPE when specifying the parent type. In a later article in the series we’ll cover some advanced tricks for making the definition of metadata exceedingly easy and readable (with some caveats, of course). For now, the simple macros get the trick done.

Extending the code to support multiple inheritance is not necessarily difficult, but it does require some thought. Maintaining a list or other data structure of all possible parents for a type without needing dynamic memory allocation will require a small bit of care. Initializing that list with clean, readable DEFINE_META-style macros requires even more care. All doable, but I’d recommend just skipping that unless a real need for it arises.

The dynamic_cast<> operator built-in to C++ works about as efficiently as possible and supports every conceivable valid type cast C++’s type system allows. Replacing it does not make a lot of sense unless there is some value to doing so. One reason may well be that the default RTTI system in C++ has been disabled because of its redundant data; even without a replacement metadata system, many games have been known to disable RTTI, especially those targeting resource-constrained mobile gaming platforms. A simpler, lighter replacement for dynamic_cast<> that supports exactly the features needed and no more can be valuable in these cases.

Another huge value of a replacement is that dynamic_cast<> does not support specifying the target type at runtime. That is, the target type is a compile-time template parameter to dynamic_cast<>. Actually casting to a runtime-specified type makes little sense in C++, but being able to query whether such a cast would be valid has plenty of uses.

A third reason to replace dynamic_cast<> is the exception-based failure mode for dynamic_cast<>. If exceptions are disabled, or if failures are expected to be common for some particular use, it is important to use a purely pointer-based implementation that can simply return NULL on failure.

Dynamic type casting via C++’s built-in dynamic_cast<> is a fairly complicated affair. At the simplest level, C++ needs to use the RTTI’s chain of inheritance, much as our system will do. At the most complicated level, C++ supports virtual inheritance, which can require a lot of black magic to do the proper pointer offset arithmetic. We’re not going to even consider supporting virtual bases in this article series, so we can ignore all that complexity.

The first thing we’re going to need is an implementation for the Metadata::isa() method I added to the class definition previously. All it does is walk a linked list, looking for a match.

Implementing a cast operator is now quite trivial, using a little bit of template magic and our MetaLookup<> template from the previous article.

Usage of the new “operator” is more or less identical to the dynamic_cast<> operator, except that only pointers are supported, and failure to perform the cast is signaled by a NULL return value.

Extending the operator to support multiple inheritance requires no changes to the implementation of MetaCast<>() itself, as all of the real work is performed by Metadata::isa().

A final real-world use for metadata that I’ll cover in this part of the metadata series is the creation of a memory allocation helper. We already have enough information for a basic implementation, as we have the size of the type stored in the Metadata class.

For the sake of many game engines, however, it can be quite handy to have alignment support as well. This can be a teeny bit tricky to do in an automatic way as not all compilers support the new C++11 alignof operator, including both GCC and Visual C++. Thankfully, GCC does provide a nearly identical proprietary operator, and Visual C++ has an operator that can be cajoled into doing the work we need. We can wrap them up in a macro easily enough. The VC++ version has some… magic involved to work around a compiler crash bug I ran into.

The Visual C++ version makes use of the proprietary __alignof operator. However, I found that it will cause a compiler crash for some cases, like references to abstract classes, which we certainly want to be able to create Metadata objects for. The mess up above was something I found that worked around the bug. The GCC version uses the proprietary __alignof__ operator, which has no bugs I could detect and which works enough like the C++11 alignof that it just works for all tests I’ve tried. Clang 3.0 should support alignof, but I don’t know if it defined __cplusplus to the appropriate version yet. I don’t have a build of Clang ready locally to test with, but the code may need a simple additional check for Clang to whitelist it to using the alignof operator. Please let me know if you test and find changes are necessary. I don’t use (or recommend) any other compilers, so I do not know if any need workarounds or what those might be.

That out of the way, the Metadata class can now be extended with alignment information and an allocate() method. We also can update the DEFINE_META macro to automatically generate the alignment data.

The allocate() method could almost just be a simple wrapper around operator new if it weren’t for C++’s embarrassing lack of alignment support in operator new (even in the new standard). We have to rely on platform-specific memory allocation routines. Unfortunately, on some platforms these also require platform-specific deallocation routines as well, hence the deallocate() method.

Implementing them is straight forward. I provide Win32/POSIX implementations here.

A few improvements and extensions can easily be made. Supporting array allocation and deallocation is quite trivial, for starts. Adding a bit more platform-specific logic can avoid the call to the aligned allocation functions (which may be slower than the regular allocation functions) if the type’s alignment is already less than or equal to the platform’s default alignment (8 on most PC platforms; 16 on OS X and Windowx x64).

Most importantly, it is quite possible to add support for custom allocator interfaces. My engine completely bans the use of default operator new or malloc(), for instance, and requires all allocations to go through a slightly more sophisticated memory management API. This API is used for custom allocator support (e.g., scratch allocators, pool allocators, etc.), handles hierarchical per-arena accounting, and ensures we have a decent general purpose allocation algorithm on platforms like Win XP which have pretty awful default allocators. Extending the allocate() API here is as easy as giving it a new parameter for the allocator and to replace the implementation with calls to that allocator.

Allocation and deallocation are not nearly enough, naturally. Objects need to be constructed and destructed. That requires a bit more work to accomplish, and will be part of the next article in the series.

A question I’ve been asked several times is, “why would anyone even want a system like this?” Right after that is usually, “won’t this be really slow, or waste a lot of memory, or just be more costly than a less flexible solution?” I often equate these questions to the old, “aren’t virtual functions too slow for games?” and the somewhat old, “aren’t components and data-driven design too inefficient to make up for their added flexibility?”

The Why of metadata is simply this: metadata allows for runtime data-driven systems in a game engine to work with a minimum of extra maintenance or bugs. Metadata systems allow for the creation of simple factories with almost no extra code. They make serialization of game objects trivial. They allow for property editing in a game editor window or debug toolbar to be very simple. Metadata allows for enhanced debugging output. Metadata helps with documenting objects. Metadata can even be used for script binding.

This all stems from the basic notion of what metadata is in a programming language. Metadata is simply the addition of information to the base type system. As a very simple example, take the name of a class. In C++, at runtime, there is normally no way to ask a question like, “what is the name of the class instance referenced by my Foo* variable?” (Yes, C++’s RTTI and its typeid and typeinfo provide a name but it’s not usually the name you’d expect or want.) If it weren’t for dynamic polymorphism, the answer might well just be “Foo” but it’s just not that simple for us. When we start using templates and metaprogramming, we likewise will not know the real type of an object by simply looking at the declaration for said object in the code.

With a proper metadata system, we have the ability to get an object that represents a class (or even a primitive type). We can have something similar to metaprogramming type traits except with even more information and which is available at runtime. We’ll be able to write code like the following:

As per the example, by far the biggest use I’m getting out of metadata in my current project is the data-driven runtime composition of game objects, which allows us to highly customize game entities in very intricate ways with just a simple text file. We’re also using it for our configuration system, some great debugging macros, and our editor is starting to make use of it for property editing as well.

Touching briefly on the questions above about performance, it’s worth noting that the system I’ll be describing is highly efficient in terms of both CPU time and memory. It’s possible to get even more efficiency at the cost of some API cleanliness. I’m going to describe the easier to use approach, but I’ll note the areas where things could be changed to maximize efficiency. In my projects I lean towards a middle of the road approach, which has an API slightly more cumbersome than what I describe here, but which has a bit more efficiency.

The first thing we’ll need is an actual class for our metadata objects. (Yes, by the end of this, our metadata system will be able to describe itself.) Nothing particularly complicated is needed, but we’re going to keep things extra simple for now. Our metadata system will have just enough information to print out the type and size of an object. Further articles in the series will expand its capabilities.

One of the core features of a metadata system is ability to find the metadata for a class by name without needing an instance of a class first. This is useful for factory systems, for example.

The idea then is that there should be another global system that manages all Metadata objects. There are a lot of ways to make this work, ranging from the simple but inefficient to the highly complex but (practically) zero-cost. I’m going to go over the simple approach.

At the most basic level, I just need to make a class to manage Metadata objects, and then have Metadata objects register themselves with that class. That class is going to only use static methods and members (and hence could just be a few C-style functions and globals, if you wish) in order to avoid order-of-initialization problems.

There’s not much more that would ever be needed than this. However, it’s not all that efficient to use std::string or std::map for this system. Especially for memory-constrained environments, it can be quite worthwhile to avoid these.

Avoiding the use of std::string is the easiest. There’s no reason to make a copy of the Metadata’s name rather than just using the C-style character pointer. It will be necessary to specify a custom comparator for the std::map instance, but that should hopefully be a trivial exercise.

Avoiding the std::map altogether is a bit trickier. We want to keep efficient lookup of Metadata objects (no worse than O(logN), which means we’re going to want to keep them in a well-behaved tree. The approach I’ve used is to actually write my own tree where the Metadata objects are also the nodes themselves; that is, the Metadata class has the child pointers and such necessary to implement a binary tree (or a red-black tree, or so on). The consequence is a lot of extra code since std::map can’t just be reused, but there are absolutely zero runtime memory allocations required for the metadata system, the memory cost of metadata is as good as or better than std::map, and the runtime complexity is the same.

If compile-time string hashing was feasible in Visual C++, it would also be an option to use a fixed-size hash table with our choice of “perfect” hash, but sadly that won’t be an option until at least Visual Studio 11 SP1 or so (whenever Microsoft finally gets us constexpr support like GCC and Clang already have).

If you do implement your own tree, I recommend doing it as a template mixin, as it will be useful later on for attaching properties to metadata, which has the same set of problems (and which is just another std::map member in the Metadata class if you go the simpler route).

To finish off the registration, the constructor for Metadata should call MetaManager::registerMeta(this), to register itself with the manager.

Now that we have a Metadata class, the question becomes, “how do I create an instance of the Metadata object for each class?” There’s a lot of ways to do this, I’ve used them all and seen most of them used in other engines, and they each have advantages and disadvantages. Let’s start with the simpler methods and build up to the one I feel is best.

The first approach is to simply make a global variable for each class. For example, if I had a class named GameObject, then I might have a global variable named g_MetaGameObject which is an instance of Metadata. That simple. A couple macros make it easy to declare, define, and reference these globals.

Pretty darned simple. Except for that last macro. That one is a problem, and is one of the bigger reasons why I don’t recommend this approach. It turns out that to actually get the metadata for a particular object, that object is going to have to have a method like getMetadata(). Required and mandatory. There is no need for a common base class, just that every class using metadata has a method named getMetadata which requires a pointer to the Metadata for the class.

This can be simplified ever so slightly with the addition of another macro. While this method does not need to be virtual for classes that won’t be derived from, it will need to be virtual for classes that have children so that the META macro works as expected when called on a base pointer. I’ll keep it simple and just show the version of the macro for dynamic classes.

There are three big problems with this approach. First, there is the requirement for the getMetadata() method. While the other approaches require that for dynamically polymorphic objects (there’s only one workaround there, but it has a cost), it should not be necessary to modify or extend a class just to participate in metadata. In particular, it’s impossible to add metadata to a class that cannot be modified, such as a third party library, as well as to primitive types.

The second big problem is that this approach does not work inside templates, as the compile-time metadata lookup requires knowledge of the type’s name (in order to construct the name of the appropriate metadata global) which the template does not have.

The third big problem is that types with namespaces or template parameters cannot have metadata, as there’s no way to construct a name for these objects. Passing a class identifier like MyNamespace::MyClass to any of the above macros will produce invalid code. The same happens if trying to pass a type like MyTemplate.

The second and final approach I’ll cover is to use templates to define and find metadata. The idea here is that a templated type can have static methods and even static members. By the same rules that all other static members and static local variables operate, a statically allocated object in a template will exist once and once only in the problem (the One Definition Rule guarantees this).

It’s thus possible to create a new simple templated type and a new set of macros for creating metadata. This template removes several of the disadvantages of the previous approach. First, it allows to lookup the metadata for any type based on the compiler’s knowledge of the type rather than the type’s name, so it works in templates. Second, as there is no need to construct a valid global identifier for each class, it trivially supports classes in namespaces or with template parameters, and it can be used without needing to extend a class, and it can even be used with primitive types like int or float. Finally, a bit of template metaprogramming we’ll go over lately will make the requirement of a getMetadata() method on objects go away in every case where dynamic polymorphism isn’t an issue.

That last macro probably requires some explanation. If we have an object, there is a new C++11 feature called decltype that allows us to get the type of that object. This may sound redundant (if we have an object, we must have declared its type somewhere, after all, so clearly we already know what it is), but it’s far more convenient to just pass in the object’s name to a macro than to duplicate the type, especially for some of those long and ugly templated names.

There is one downside to this implementation of the META macro: it does not work with dynamic polymorphism at all. That is, if we have a pointer to MyBase but the instance it references is actually MyDerived, the Metadata instance returned by META will be that of MyBase. That’s no good. We’ll fix this later on in the article.

You may have noticed that I implemented the singleton Metadata in MetaSingleton differently than I did in MetaManager. There are two reasons for that. Static local variables as found in the MetaManager::getMetas() method are usually implemented internally by having a hidden global boolean for each static local and checking if that boolean has been toggled to true or not ever time the function is called. Globals of primitive types like bool are always zero initialized before any code runs, so that hidden boolean is always guaranteed to be false the first time the getMetas() method is called, even if it’s called from some random constructor in a global object. In that first call, because the boolean is false the object is initialized and then the boolean is set to true, thereby guaranteeing that the static local object is initialized only once and initialized only when first used. However, that boolean is checked every time the method is called. While metadata objects are not generally accessed in any performance-sensitive part of a game, I did want to illustrate that raw bare-metal efficiency is possible even with a complex metadata system for the non-believers.

The second reason to use the static member is that it allows (requires, in fact) the initialization of that member to be explicit and in a .cpp file. Right now we need a macro during initialization in order to set the class name in the Metadata object. We’re also going to want that explicit initialization for a later article when I show how to add properties to objects and do other advanced runtime initialization.

We’ve got a major problem in our template approach right not. Whenever we access MetaSingleton<>, we’re passing in some qualified type name. Because of how templates work, MetaSingleton and MetaSingleton and MetaSingleton are all different, and hence will have their own static Metadata objects. We really don’t want that.

There’s two approaches to fixing this. The first is to make use of special metaprogramming templates like std::remove_const<>, std::remove_reference<>, and so on. They’re pretty easy to use, but they’re difficult to use just right in a case as complex as this one. If we have some qualified type like “MyType const* const&” then we’re going to have to nest those std::remove* uses pretty deeply to make sure it gets simplified down to the unqualified “MyType”. Thankfully, partial template specialization is much easier to use and solves all our problems here.

Partial template specialization allows us to make alternative versions of MetaSingleton that just reference the unqualified version. The end result is that no matter what we pass in as the template parameter, only the unqualified version’s static Metadata instance will ever be referenced. This isn’t hard to do, it just requires some mostly redundant typing.

Note that the const versions of reference and pointer specializations are required.

Also, as a quiz for the reader: for completeness’ sake, is a specialization for “volatile” necessary? What about “static” and “register”? (Hint: what is the difference in C++ between a type qualifier and a storage class, and which keywords fall into those categories, and why?)

Our META macro still does not support dynamic polymorphism. We need some way to get the Metadata instance for the type of actual object we’re interested in, independent of whether or not we’re accessing it by a pointer or reference to a base type.

This unfortunately goes back to needing a virtual getMetadata() method on our objects. Fortunately, with the template approach, this method is only needed when dynamic polymorphism is even an issue. Also, the template approach allows the use of a template mixin for creating the virtual method, which may be considered easier or prettier than the macro we used before.

Using this is just a simple application of CRTP (the Curiously Recursive Template Pattern).

It is arguable if this is prettier or not. I’m not particularly fond of needing to make the “real” base type be a template parameter to the mixin template, but there’s no way around it. Conversely, the macro variant is:

Either way works perfectly fine (and should generate identical class layouts and runtime code), so use whatever you feel looks best or is easier to understand. If you make use of C++’s builtin RTTI, the template mixin approach may bloat your RTTI tables a bit, so that may be a deciding factor to push you towards the macro approach.

Simply having this method where it’s needed is only part of the solution. We can now safely call this method where it needs to be called, but wouldn’t it be nice if we could just keep using that META macro, and have it automatically call getMetadata() if it exists or use the decltype trick otherwise?

Template metaprogramming offers us the ability to selectively call the getMetadata() method. It’s an ugly, horrific, mind-bending trick, but a working one none-the-less. Another article in the series is going to be making heavy use of metaprogramming to extend the capabilities of the Metadata object without requiring excessive manual intervention, so we’re going to have to cover this topic no matter what. Time to rip off the bandaid. In fact, let’s just look at the code.

Yeah, that’s pretty ugly. It’s not even particularly obvious. There’s an even uglier way to do this, and there’s a lot of ways that one would think should work but won’t (with Visual Studio, at least).

I’m not going to explain metaprogramming’s core tricks here. If you’re unfamiliar with template metaprogramming in general, I recommend the book Modern C++ Design. The topic is big enough that I simply can’t do it justice here, at least not without giving it an entire large article all to itself.

Let’s look back to MetaIsDynamic. We have a boolean result, defined as:

The tricky part is all the mess with std::is_same, no_return, decltype, and check(0). Like I said above, we’re using type comparisons internally. That use of the check(0) will evaluate to a function call which will have one of two different return types; if MetaType does NOT have a getMetadata() method, then the return type of the check<>() function will be the struct no_return defined in MetaIsDynamic, and if MetaType DOES have a getMetadata() method, then the return will be something other than struct no_return. I’m checking the return type by using decltype and the std::is_same template. The whole line can be read as “boolean ‘value’ is false if no_return is the same type as the return value of ‘check(0)’, and true otherwise.”

The big question then is how the return type of check<>() is chosen. This is done using the template behavior called Substitution Failure Is Not An Error (SFINAE). We can thus arrange for there to be two templated versions of a function that are non-ambiguous (because that would be an error, SFINAE or no) and where one will be invalid on some condition we specify (such as whether the templated type has a specific method or not).

To use that trick, the MetaIsDynamic struct has two versions of the check<>() function.

Let’s look at the first version of check<>(). It returns a char (our “true” value) and takes… some kind of mess. The parameter type is definitely a beast, but it’s not too bad at all once it’s broken down to its component parts. The parameter is a pointer, as can be seen by the asterisk at the end. It’s a pointer to decltype of an expression, which means that it’s a pointer to whatever type that expression evaluates to. That expression is the result of calling getMetadata() on some pointer cast, so the decltype evaluates to whatever the return type of getMetadata() is. The pointer cast is a cast from 0 (a.k.a. NULL) to the template type U, which is just a cheap way of constructing a “random” pointer to call a method on, because we need an expression using a method and that requires an object. Since decltype only looks at the type of an expression and never actually evaluates the expression, the pointer we use does not need to be a valid object, so casting NULL to our desired type is sufficient. Thus the whole parameter can be read as “a pointer to the return type of U::getMetadata()”.

One might ask “but what if type U doesn’t have a getMetadata() method?” Well, that’s the exact question that the compiler has to answer when it evaluates this declaration of check<>(). Because that expression is used to construct the parameter type, and since the parameter type must be a real valid type or else there is a substitution failure, this is where SFINAE kicks in. If typename U (which is always the same type as MetaType) does not have a getMetadata() method then this declaration of function check<>() is simply thrown away and ignored by the SFINAE rules, with no errors. Which is exactly what we want.

The second version of check<>() is simply the fallback. Its parameter is an ellipses because of the overload resolution precedence in C++, allowing it to accept a pointer argument but also ensuring that the first version of check<>() is always unambiguously chosen if it exists.

The one fault of the code as presented is that it does not in any way guarantee that the getMetadata() on the type actually returns pointer to Metadata. While it’s possible with a bit more effort to check that as well, I’d argue that there is little need; just don’t do anything silly like adding methods called “getMetadata” that don’t get Metadata and there won’t be a problem.

Actually using this new MetaIsDynamic metaprogramming struct takes just a bit more work. A new set of template specializations is needed, then it’s all done.

There’s a tad bit more metaprogramming in there via the use of std::enable_if. That is another neat little trick relying on SFINAE, which allows for a version of a function to exist based on some boolean constant. A boolean constant like the one produced by our MetaIsDynamic. One version of the resolve<>() function will invoke the getMetadata() method and the other just uses MetaSingleton directly.

Now we just need a new version of the META macro to make it all nice and easy to use.

Note again that decltype does not actually evaluate its arguments, so the repeated use of the ‘obj’ macro parameter does not run afoul of the usual double expansion problems of preprocessor macros.

It’s worth noting that when compiled with optimizations on, all of this metadata lookup code will compile away to either a trivial address lookup of a global object or (for classes that have a virtual getMetadata() method) a single virtual call to a function that simply returns the address of a global object. Stepping through the code in debug builds can be a little scary, though, as it may seem like there are hobajillion recursive calls (especially when those lookup templates get hit), but don’t be fooled by how dumb a compiler is with all of its optimizations turned off.

Keeping in mind that the Metadata class so far doesn’t do much, here’s a few examples of how the system can be used. There was a lot of innards and implementation details, but at the end of the day it’s nice to see what all that work can do.

Note you may get different sizes output depending on your compiler and standard library vendor.

In following articles in the series, I’ll go over making the Metadata class more useful. In particular, we’ll be adding factory methods including cloning, simple inheritance checks (think dynamic_cast<> that doesn’t require instances of objects), additional class attributes like alignment or an is_abstract flag, and named/typed class properties with full getter/setter support. I may even go over method binding for script language binding generation if I have the time (it’s a big topic).

Be warned: this is a particularly long article and delves into a fair bit of C++ magic.

By far the most important new feature of C++11 for container writers is rvalue references. This feature allows containers to efficiently move around objects that might otherwise be very expensive to copy. It’s also mandatory for supporting smart pointer classes like std::unique_ptr<>, and containers need to be made aware of rvalue references to be able to hold copies of those smart pointer types.

While on the topic of avoiding copies, there’s a few template tricks that very few people seem to be directly aware of that are important for making efficient containers. The primary trick I’m going to cover is making sure that objects passed in to methods like find() do not require the creation of unnecessary temporaries or copies.

Let’s go ahead and start things out with a container skeleton that we have all probably written at some point. I’m going to ignore the actual data structure of the container, as that’s honestly not too important for this discussion; it could be a vector, a hash table, a tree, or whatever is needed. For now, I’ll use set operations for the examples.

Pretty basic, and gets the job done.

Even in the C++98 era, however, there are a couple problems with this implementation. I’m going to cover those now, since the above is how almost all examples on custom containers start and end. The problem is that the operations like remove() and has() may create unnecessary temporaries for their parameters if a conversion is required.

Take the following code example:

What’s the problem? The problem is that the has() method I created on MyContainer takes a const reference to a std::string, but in the code snippet I passed a string literal (a const char[]) to the has() method. This means that the C++ compiler must construct a temporary std::string, which entails a memory allocation, copy, and eventual deallocation, all just to pass that string in to compare with the std::string contents. Since std::string can be compared with a regular string literal just fine, this copy is unnecessary.

The solution is fairly simple, if a little non-obvious. I’m going to declare the has() method as a templated method. That is, the method has its own template parameter, in addition to the template parameters of the container class itself. While I’m at it, I’m also going to do this for remove() since it has a similar problem. I’ll handle insert()’s performance issue later when I discuss rvalue references.

That’s all it takes! Now the object given as a parameter to has() or remove() will be used without any additional conversion operators. Assuming that the parameter can actually be compared with the type stored in the container, this will work perfectly.

Note that there is still room for problems. In particular, if the type passed in and the type stored in the container required an expensive conversion for the comparison operators, this version will actually be worse, not better, because the conversion will be performed once for each comparison! This is exactly the behavior found with std::find(), so it’s something to be aware of in general anyway.

There are two easy rules to follow to avoid this problem. First, only define the cheapest possible comparison operators. Comparisons between two std::string’s or two int’s have simple, obvious, maximally efficient implementations. A comparison operator between std::string and int, however, does not. It either requires converting the string to an integer or the integer to a string, and then calling one of the original same-type comparison operators. Comparison operators between two very similar types with no conversion overhead makes sense (like the built-in comparison operator support for int vs short), but avoid anything else.

The second rule is to avoid conversion constructors and conversion operators as much as possible; and when not possible, using the explicit keyword when declaring the conversions. There is absolutely no implicit conversion operator or constructor for turning a float into a std::string, for example, nor for turning a std::vector into a std::list. If it is ever necessary for such a conversion, the programmer can do so manually using library calls, but the language will never do sneaky and expensive things behind the programmer’s back.

As a side note, the STL and C++ in general does break the rule above in a few places. For instance, C-style strings are implicitly convertible to std::string, which is not particularly nice. In fact, the original problematic example I listed above would have been a lot more obvious if C++ did not allow for this automatic conversion. In games, we frequently write our own string libraries as well as container libraries, so I heartily recommend that any and all custom string classes where explicit conversion from string literals and C-style strings into C++ string classes if any memory allocation or copies are required.

All that said, it may seem that I’m being a contradictory, and the fact that STL implementations don’t use the performance advice above may seem a bit damning. After all, if the library has a minimal set of cheap comparison operators and conversions, the example above would never have even compiled, much less implicitly inserted inefficient code. The problem comes up from those few instances where one does have comparison operators between different types.

For instance, my string library has several types of string classes, with different use cases and performance characteristics. One type of string is for string pooling, and creating an instance of that type requires inserting the string into the string pool. Another type is intended for large or one-off strings that need to stick around for a while, and is basically just a reimplementation of std::string (without all the silliness found in most STL implementations). Yet another type is the string range, which is an efficient and safe way to pass around temporary string data without unnecessary, including slices of other strings. It is equally cheap and efficient to compare all these different string types, just like it’s equally cheap and efficient to compare as std::string to a char* as it is to another std::string. Therefor it’s quite reasonable even under these rules to have a container of one string type and using methods like has() or find() or remove() with a different string type as a parameter, where a conversion would be required without the above trick.

Furthermore, moving into rvalue reference territory, and the concept of “perfect forwarding” (which is one of the many great features that rvalue references unlock), it’s important for my container that I pass in parameters to the underlying comparison operators with no imposed conversions or other shenanigans.

There’s one example I’d like to go over, as it seems to be poorly understood. Here are three difference ways of creating an initializing an object:

Novice C++ programmers may not be aware that there’s any difference at all between the three, but even experienced C++ programmers may be unaware of some of the differences. Particularly, the first two have some non-obvious behavior. The example with foo1 will allocated storage on the stack and then invoke the the appropriate constructor. The example involving foo3 will allocate storage on the stack, invoke the default constructor, and then invoke the appropriate assignment operator. The example with foo2 is the most tricky.

In the case of foo2, there is no invocation of the assignment operator. When a variable is declared and assignment to in the same statement, the copy/conversion constructor is invoked rather than the default constructor. However, unlike the example with foo1, the explicit constructors will not be invoked! This is particularly important when writing containers that respect the programmer’s explicit constructors. If the container needs to move around its contents, such as when a std::vector is resized, then it should allocate the necessary space and then the constructor should be explicitly invoked. If the container is simply copying data passed in with a template like I showed above, it should avoid explicitly calling the copy constructor.

Moving on, I now have a container that requires no unnecessary copies for searching or removing items, but there’s still a lot of wastage when I call insert(). There are two cases where I will make potentially expensive conversions that I don’t want to. The first case is identical to the conversion problem with has() or remove(). An example:

Once again, a temporary std::string is created for the parameter. This temporary object is not the object that is actually stored in the container. A second copy will be made and inserted into the actual container. This means that I’ll get two copies for a single insert when ideally I should only need one.

This might not seem too bad with some “expensive” types like std::string, especially when GCC’s libstdc++ using reference counting and VC++’s DinkumWare-based STL uses small string optimization. These don’t apply to other types, like containers (it’s not uncommon to have a container of containers, after all), and honestly both of those string optimizations are really pessimizations in many uses (and reference counted std::string implementations are no longer allowed by C++11 in any case).

The second case of unnecessary copies during insert is when an already constructed temporary object is inserted. This is of course the golden example of rvalue reference. Most sites covering rvalue references list only that one use case, in fact. An example:

The temporary object returned by some_api_call() is called an rvalue, as compared to lvalue. For those wondering, an lvalue is an expression that can be assigned to, while an rvalue is any expression that cannot be assigned to. In other words, the expression “some_api_call()” can be on the right-hand side of an assignment, but not the left-hand side. Notably, rvalues only exist for a single expression: if I call some_api_call() twice, even if inside the same expression, I’m going to get two separate std::string temporary objects returned from each call. The problem with the above code is that I’m going to copy this temporary object into my container, and then throw away the temporary, which is wasteful. Since the compiler knows that nobody else can use that std::string (its an rvalue, and cannot be used or accessed in any way after the call to insert() because it has no name), the compiler should be able to just move that temporary object into the container with no unnecessary copying.

Rvalue references facilitate this by providing new syntax, allowing methods to be written that “know” whether their parameter is an rvalue or an lvalue, and which will only bind to non-const rvalues. The naive approach then for my container is to make two versions of insert; one for rvalue references that performs a move and another that makes copies. There’s a small trick to that, so an example is in order:

The copy version looks normal enough. The rvalue reference version has two significant changes. The first is the change to the parameter type. Rvalue references are denoted by using two ampersands && instead of a single ampersand. Also, it makes no sense to declare an rvalue reference as const (the whole point of an rvalue reference is to be able to destructively move the contents out of the object), and only normal references can be declared as const.

The second important note in the rvalue reference version of insert() is the use of std::move(). The std::move() function converts any non-const lvalue into an rvalue. At first that may seem redundant, since value was declared as an rvalue reference in the function prototype. However, it’s important to understand the precise meaning of the syntax.

When a function parameter is declared as an rvalue reference, that means that parameter will accept an rvalue. However, the parameter inside the function itself clearly has a name, and hence it is an lvalue! The parameter type declaration simply said what the function will accept, not how the function will actually use the value once it has it.

Note that if the function took a non-const reference, it would not be legal to pass an rvalue to the function. That is, this code does not compile:

The reason is that a regular non-const reference can only bind to an lvalue, and the temporary std::string object that must be created to convert the string literal is an rvalue (as are all temporaries). If my_func has been declared as taking an rvalue reference, or if there was an overloaded version taking an rvalue reference, the code would be valid.

Of course, in the presence of overloads, rvalues will bind to the overload taking an rvalue reference while, non-const lvalues will bind to the overload taking a non-const reference, and const rvalues and any lvalue will bind to the overload taking a const reference.

Examples of what works and what doesn’t below. Note that the variable one is an lvalue (it can be assigned to), the variable two is considered a constant (technically an rvalue, but it will not bind to rvalue reference), and that the expression one+two creates a new temporary integer which is an rvalue and not constant (conceptually the value 3 is absolutely constant, but remember that the result of 1 + 2 in C++ is a temporary object that simply contains the value 3).

One more example, showing overloads:

Hopefully that explains all the reference semantics clearly enough. It’s pretty confusing at first, but clears up a bit with examples. If the above aren’t enough, just try writing some more on your own, and it should start making sense soon enough. I recommend getting a grasp on this now before continuing, as the next part can be particularly tricky and requires a good understanding of the different types of references.

Up above when I added rvalue references to the MyContainer class, I said that was a naive approach. The approach I took was to write two different versions of insert(), once that makes copies and that that does not. The problem is that required a lot of duplicate code (or would, in a real implementation at least), and the only part that is actually different inside the implementation is the use of std::move() in the moving version of the method. All that duplication leads to maintenance overhead and large binary code size, neither of which is desirable.

Additionally, rvalue references have another important use, which is that of perfect forwarding. The idea of perfect forwarding is that sometimes programmers write functions or methods that are just wrap other functions, and take some or all of their parameters and pass them on to the wrapper functions. In fact, with my container, I have exactly this situation: the value I insert is actually passed on to the constructor for the instance of the object created inside the container. Now consider a wrapped function (or constructor) that takes multiple parameters, such as node type stored inside a key-value container like a map. What happens if this type’s constructor accepts an rvalue reference for its first parameter but not its second, or for its second parameter but not its first? Or both? Or neither? I’d have to write four overloaded versions of insert() for each possible combination. For other kinds of functions that may take even more parameters, the number of overloads grows exponentially. This is not good.

Thankfully the C++ committee took care of this problem, with a little bit of special magic for rvalue references. In fact, the example above is already using part of that trick, but not all of it.

The trick is… tricky. It is this: if a templated parameter is an rvalue reference, the actual type of the parameter is an rvalue reference if the template type is an rvalue, and a regular reference otherwise. That needs an example.

It’s magic. Normally, I hate magic. It makes code hard to read and maintain. Programmer luminaries such as Linus Torvalds famously despise C++ for the amount of magic it facilities, and its not hard to see their reasoning with features such as these. The feature does facilitate something useful, however, and mostly just works without much special effort.

It’s important to remember that this works only when the type is a template parameter. There’s some relatively straight forward rules explaining how it all works, but it’s definitely easier to understand with examples like the one above than it is to try to grok an explanation of the rules.

Alright, so now I can get rid of the copy version of my insert(). Well, almost. There’s the little problem of the std::move() call. If I try to pass a const reference to std::move(), the compiler will complain. With good reason, too. If the contained type has a move constructor, I only want that called when I’m actually passing an rvalue to the insert() method. What is needed then is a way to select which overloaded constructor to invoke based on the type passed into the insert(), and whether it was an rvalue reference or not.

That facility is the std::forward<>() function. It works very similarly to std::move(). However, its return type is an rvalue reference if and only if the input parameter is an rvalue or is an lvalue declared as an rvalue reference. Additionally, due to implementation details of how the template magic works, std::foward<>() requires that the type of the value be specified explicitly, unlike std::move() which can infer the template parameter type.

All that explanation and exposition and now we’re finally ready for the big reveal: the version of insert() I can use in my container:

There it is. Only one insert() method is needed. This version will bind to rvalue references as well as anything else, and will forward that type perfectly to the Node constructor. If the value passed to insert() is an rvalue, and Node has an rvalue reference constructor, then the value will be moved into the new Node with no additional copies.

To summarize what happens, I’ve got another example:

The second two do possibly require some qualification. Technically, baz() makes a copy of a string literal and returns that, so one copy is made. This copy is made by baz() itself and not by the container or its insert() method. It’s a bit of a poor example only because it’s such a trivial function. Likewise, the fourth insert of the string literal “qux” does make a copy when the literal is constructed, but it’s constructed in-place in the container, and does not require two copies like the original version of the container class did.

A more reasonable example of where the performance benefit comes in is as follows:

In C++89, or with a naive container, that code would allocate and copy each of the std::vector’s contents several times. With my container and the power of C++11 and rvalue reference, the only allocations made are when the std::vector’s are initialize constructed, and the data is never copied.

I’ve got this great container class that allows me to move expensive objects into it without requiring extra copies. Except, I haven’t actually implemented any real container, and it turns out there’s some things to know about how to do that.

Above I’ve been using a sort of set container skeleton as an example. From now on, I’m going to use a std::vector type of container as the example, because it’s the easier to understand for what I’m going to do. In particular, any container that has to move its elements around internally needs to do a few things specially. This might also include various implementations of hash tables that need to grow, as just one other example besides a vector.

I’m going to look specifically at a simple version of the reserve() method on std::vector, which is the function that allocates more memory.

Pretty basic. In quick review of std::vector’s behavior: reserve() will allocate another memory chunk of the requested size, copy the old data to the new memory area, delete the old memory chunk, and update our internal data. Note that capacity is the number of items the vector can hold without needing to allocate more memory, while size is the number of elements currently in the vector. Size is strictly less than or equal to capacity, and its completely legal for size to be zero while capacity is a large number.

Of course, that implementation will make full copies of its elements when it grows. That means making copies of expensive objects like those 3,000,000 element vectors in the previous example. It also means that objects of type std::unique_ptr<>, which do not have a copy constructor, cannot be used with that implementation.

The fix is ridiculously simple, and should hopefully be clear at this point. Instead of calling the copy constructor normally inside the loop, the move constructor (if available) should be invoked, letting it optimize things by moving resources instead of copying them. Move constructors are constructors are implemented using rvalue references, which are conceptually temporary objects that won’t be used anymore. The std::move() function forces an lvalue to be an rvalue reference. So the fix is to just update the actual copy construction line to use std::move(), resulting in the following loop:

Notice that I did not remove the call to the destructor. This is important. Whether or not an object is passed to a function as an rvalue reference, the destructor is always called for every object when it goes out of scope. The implementation of move constructors and move asssignment operators in most classes will rely on this fact, as I’ll go over soon. Short version: the destructor must always be called, always, period. If it’s not clear why just yet, read on.

I’ve got containers that can take advantage of move semantics with rvalue references, but what I haven’t done is explain how to actually write types that have move constructors that actually work. I’m coming up on the end of this long-winded article, so bear with me just a bit longer as I explain this final piece of the puzzle.

The idea of a move constructor or move assignment operator is that some class “own” other resources which are expensive to duplicate, and which shouldn’t be copied unnecessarily. Additionally, some classes have resources which cannot be duplicated at all, and hence it is not legal to copy the object; these types lack copy constructors and assignment operators, but should have move constructors and move assignment operators. A simple example of the former type is std::vector, which owns a pointer to a chunk of memory containing its elements. A good example of the latter type is std::unique_ptr<>, which guarantees that there is just one single handle to an object.

A move constructor looks a lot like a copy constructor, except it takes an rvalue reference. Likewise, a move assignment operator looks a lot like a regular assignment operator, but takes an rvalue reference.

I’m going to use a simplistic example class to illustrate things. Behold the integer box:

I’ll clarify what’s going on with the copy constructor for anyone not familiar with the trick used. The idea is that we can just default construct the object and then use the assignment operator and have the same result with less effort than if we duplicated the logic in both the copy constructor and assignment operator. Once again, such a trivial piece of code makes for a slightly poor example, but it gets the point across. Also note that while the class has a precondition that m_Ptr never be NULL, and the copy constructor initializes m_Ptr to NULL, it will always be given a real address by the time the constructor ends.

I recommend using that trick where possible. I’ve seen a few people express dismay over the “performance problems” with the code, so I’d like to take a moment to dispel those worries. Thing is, the compiler is very smart. It going to see all the redundancies that I see, and it’s going to remove them. But only when optimizations are turned on, and only when there’s actually redundancies. Programmers who try to “test” the optimization by setting break points in a debug build (with no optimizations turned on, and hence every empty useless do-nothing redundant line of code is executed as written) are getting misled. Likewise, trying to add output logging by definition makes the functions non-trivial and of course the logging calls are not going to be optimized out. Obvious enough, I’d hope.

Getting on to the interesting bit, I’m going to get rid of the inefficiency that IntBox has when it’s used inside a std::vector. I certainly don’t want the code to allocate a new chunk of memory and copy the value into it just to delete the old chunk of memory afterward. That doesn’t accomplish much besides burning cycles.

Not a whole lot to it. The move assignment operator is actually quite a bit simpler than the regular version, and the move constructor is almost identical to the copy constructor. Again, the use of std::move() in the move constructor is because the source parameter is an lvalue (because it has a name and can be assigned to) despite being declared as an rvalue reference.

The move assignment operator is a bit more interesting. I’m not deleting the old memory. I’m not checking to make sure the source isn’t the same as the this pointer. I’m just swapping the pointers around. Surely there’s a bug or two in such a naive implementation.

First, another example, just so we’re on the same page:

Actually, it’s quite rock solid. First, I’ll quickly address the lack of the identity check. The check is almost rendered unnecessary by the semantics of rvalues in the first place. If I’m moving from source, it must be an rvalue, and hence is an unnamed temporary object, and therefor it can’t possible exist on both sides of an assignment operator. Of course, the existence of std::move() allows me to violate those semantics (but only by writing horrible, incorrect code). That doesn’t matter, however, since std::swap() is safe to call with both parameters being the same object; it’s just a no-op in that case. And of course, std::swap() is using rvalue references and move semantics internally, so even it’s efficient even for types like std::vector in C++11.

The important bit is why std::swap() works at all for the move constructor. It’s pretty clear that it’ll take the pointer owned by the source object and move it into the destination object, which is what I want. The question then is what happens to the memory previously owned by the destination object. For the move constructor, this was just a NULL pointer anyway, but if the move assignment is called on a constructed object, m_Ptr will already point to allocated memory.

The answer goes back to what I mentioned above about how the destructor for an object must always be called, always. Since the destructor of the source object is always called, and the destructor for IntBox deallocates the memory referenced by m_Ptr, then the old memory in the destination IntBox will be given the source IntBox, and will be freed when the source IntBox is destructed.

Likewise, for the move constructor, the source IntBox’s m_Ptr will be set to NULL, and delete operator will safely do nothing. However, one might note that in that case, the source’s m_Ptr now violates the class’s precondition that m_Ptr never be NULL, and now calling get() on the source IntBox.

One final example, just showing what happens when each of the

One very final note. All classes by default will have a default copy constructor and assignment operator defined. In the first version of IntBox, if I had omitted my overridden versions of the constructor and assignment operator, the m_Ptr member would be copied by value and the class would likely not work correctly. However, in the second version that has the move constructor and move assignment operator, the default copy constructor and assignment operator would be suppressed.

The following class example, for instance, does not allow for copying, but does allow for moving. This is how types like std::unique_ptr are implemented:

Note that while not complete, it does offer most of the basic features of std::unique_ptr. This type can be put into any move-aware container and will guarantee that only one instance of its pointed-to object will exist at any time, and guarantees that its owned object will be deleted when the Unique object goes out of scope.

Pretty handy. Unfortunately, this new feature is not supported in MSVC 2010. In fact, very few C++11 features are supported in MSVC, while GCC supports a large majority of them. One of the popular solutions to many C++ problems like this one is to make use of Boost, which does include a ForEach library that can roughly simulate the new C++11 syntax. However, this facility is quite heavy-weight and like most Boost libraries it includes some very complicated templates which can have a very detrimental effect on compile times.

Users of MSVC (and any other recent C++ compiler) fortunately do have access to some other facilities of C++11 that make it significantly easier to implement a this loop construct with a minimal of fuss. While Boost attempts to service every major C++ compiler still in reasonably popular use, those of us who are explicitly targeting MSVC 2010 can make use of one of these other C++11 features to make a very small and efficient FOR_EACH macro. In fact, the implementation I’m presenting does not add any templates or other types at all; it’s just a simple four-line macro declaration that is free of side-effects and works with no surprising behavior in any enclosing context, and has absolutely no run-time overhead compared to a traditional iterator-based for-loop or any comparable hand-coded loop!

I must note that in my container and algorithm codebase I make use of ranges rather than STL-style iterators. For more information on that topic (which I plan on writing about later), check out the Andrei Alexandrescu’s paper Iterators Must Go. I’m going to assume for the rest of this article that the reader is familiar with the concept of ranges vs iterators and is using ranges in their own containers and algorithms, as my foreach implementation depends on them. Some sample code at the end of this article uses STL idioms for users not using a custom container and algorithm library.

I’m just going to post the code I have for FOR_EACH and then go through explaining how it works.

The one feature of C++11 that this code depends on is the new behavior for the auto keyword. This allows us to create a copy of the given range so that the input is only evaluated once, which is important to ensure that the macro has no unintended side-effects.

The second line has that odd-looking IF statement in the code. It exists to create a variable that we need for the second FOR statement. However, we have to be tricky and put that “{} else” bit in the code to ensure that the IF statement we made doesn’t bind to any other ELSE clauses. If we didn’t do that, the following code would not work correctly:

The next two lines are where things get tricky. We want our macro to allow the user declare a variable to start the values being enumerated, including the variable type. That is going to require creating a new variable in a new scope if we want to support references, which we do. We can’t do that with an IF statement on its own because that requires the variable to be convertible to false, which is of course not true for arbitrary types (or even most types, whose bool conversion tends to have some meaning attached to it rather than always being false). The only construct we have for creating a new variable for a following statement is to use a FOR statement. Howevever, that is a looping statement, and we only want to execute the following statement once. We’re going to have to construct a FOR statement that will run once and only once every time. To do that, we need a second variable to control the loop.

Enter the IF statement in the FOR_EACH macro. The _foreach_loop is a boolean value initialized to false. We initialize to false to make sure the ELSE clause that actually holds our FOR statement is always run. We then use that boolean in the following FOR statement to ensure it runs only once. The boolean is toggled to true after the loop is run once and then the loop terminates due to the condition !_foreach_loop.

The second FOR statement creates our local user-specified variable initialized to the front value from the range (which for STL adaptors is the same as initializing it to the iterator’s dereferenced value). The macro is complete; the body of the FOR statement is the statement the user entered after the FOR_EACH macro. We now have a simple means of iterating over any range, like so:

That’s all there is to it!

For those using the STL, it should be trivial to convert the code to operate on a pair of iterators instead of a range object. Modify the above code to use a std::pair<> of iterators and update the empty(), pop_front(), and front() calls with equivalent code: first != second, ++first, and *first, respectively. The code should look something like the following snippet. As I haven’t tested this version, note that if it breaks the reader gets to keep the pieces.

p.s. Forgive the use of printf rather than C++ iostreams; the blog is not liking the less-than signs used for the stream-out operators, and I’m not much in the mood to wrestle with WordPress right now.

SONAR is one of the first commercial WebGL games released (possibly the first one ever to be written from the ground up in pure JavaScript). The gameplay is very similar in spirit to Subsonic, our sophomore DigiPen project.

Aside from snazzy new 3D visuals, SONAR features more gadgets and enemies than the original, a new sound track, new story, and more content.

The first thing to note is that std::string is not immutable. This means that any string references can have its contents changed at any time, which leads to a greater deal of copying being done to ensure these changes never happen. Given that strings very rarely change — even in applications heavily focused on string/text editing — it makes sense to use immutable strings.

In practice, this basically just means writing a simple wrapper around C-style strings that copies its source string on initialization or assignment, and frees it in the destructor. That might sound inefficient, but in practice this string wrapper will be rarely used. We’re mostly interested in this custom class just to ensure that we aren’t suffering the penalties imposed by poor std::string implementations (for instance, MSVC’s std::string is 32 bytes in size on x86, not including any memory which may be dynamically allocated).

The work horse of our API will be a string range class. This is a pretty simple type which is just a wrapper around a start pointer and an end pointer. This class has a number of neat benefits. First, size of any string can be easily calculated by simply subtracting start from end.

Second, a string range can “look into” any character data buffer. APIs that need to process string data and which take string ranges can easily accept data from string literals, string objects, string builders, memory mapped files, and so on without any additional copies or temporary allocation.

Third, string ranges are quite fast to pass and return, being only two pointers in size. They require absolutely no dynamic allocation, can have trivial copy and move constructors, assignment operators, and destructors.

There’s one case where a string range may not be suitable, and that’s for use with any API that expects a regular C-style NUL-terminated string. This unfortunately includes almost all OS APIs on just about every platform. These calls are suitably rare however that makes temporary copies in these cases is not usually going to be a problem. There’s also a trick that you can use to avoid extraneous copies, with some care. This trick is to simple dereference the end pointer and check if the value is the NUL byte. If it is then the string range already represents a NUL-terminated string. This will usually be safe because your string ranges will be constructed from string literals, string objects, string builders, or other sources of string data where the buffer will always have a NUL byte at the end, so the end pointer of the string range will either be pointing at that NUL byte or at some other valid character inside the source string data. However, it is possible that your application does not always do this; if you use memory mapped files then it’s possible for a string range’s end pointer to be pointing at one byte past the end of the memory mapped range, and dereferencing it is undefined. If you use any string data sources that may not be NUL terminated, it’s important to keep this in mind if you ever plan on using the is-end-NUL trick. One final suggestion is that the default constructor for a string range should set the start and end pointers to reference an empty string literal rather than NULL. This means that your string range’s end pointer will never be NULL, making sure that even default constructed string ranges are safe to dereference and pass to C-style APIs.

When it comes to formatting strings, printf and other unsafe C style APIs are best avoided. C++ iostreams style APIs are also best avoided as they are very slow and use the standard C++ std::string API, which we’re trying to avoid.

Thankfully, building your own is rather easy. A string builder class is basically a wrapper around a std::vector (or an equivalent container of your own) that offers various methods for writing data into the buffer. Simple character append, string append, and number append functions are relatively easy to write. For floating point values, you can use the gvct function (called _gvct on Windows) to get correct and accurate string formatting. This is generally the function used internally by printf implementations.

If you desire, you can add advanced iterator support for using generic algorithms on string buffer data. Insert and cursor operations are also relatively easy to add, if you need them.

The API then simply offers a method that returns a string range, which can be copied into a string wrapper if necessary for longer term storage in memory.

Note that it’s best to ensure that the character buffer is always NUL terminated, making it easy to debug the data by calling OS print/debugoutput functions on the string buffer’s contents. It also enables the string range NUL check mentioned above. It’s also feasible to offer a method that returns an rvalue reference for creating string wrappers directly, particularly if you don’t mind the extra memory padding that the buffer will often have due to automatic buffer expansion algorithms.

A specialized use case of a string builder is to concatenate two or more strings. A simple + operator seems attractive, but remember that this only works for two operands. If you try to use a + operator with three or more strings then multiple temporary strings (and hence allocations/deallocations) become necessary, even with rvalue references and move constructors. However, using a string builder is also not the most efficient means of doing string concatenation.

First, the string builder is going to use an expansion algorithm that results in multiple buffer reallocations, and the final buffer will have extra space. If you are concatenating N strings, you can easily calculate the exact necessary space necessary (the sum of the lengths of all the operands, plus one byte for the NUL character), and you should at most need N copies (from each source to the proper location in the destination). This can be easily implemented as a single variadic function (using a count value or sentinel), a variadic template, or a series of overloaded functions supporting up to some pre-determined number of operands. The most operands I’ve seen in common use is 5, used for constructing paths (a directory, a path separator, a file name, a period, and an extension).

Though rarely needed, it’s easy enough to implement that doing so is a no brainer.

One further major consideration is string interning. String interning is the process of ensuring that there is only a single allocated copy of any particular string. When strings are loaded up or constructed dynamically, the string is searched for in a central table; if found, the existing instance is returned, and otherwise a new entry is made and returned.

One advantage is a reduction in memory usage for applications that make heavy use of frequently entered dynamic strings. Another advantage is that comparing interned strings is O(1) rather than O(n) and requires no dereferencing of the string pointers (because if the pointers are not equal, they must point to different strings).

Note that it is not generally a great idea to intern all strings. Large strings, temporary strings of dynamic nature, and strings that are highly likely to be unique gain no benefits from string interning. Especially for temporary unique strings, interning can mean that the strings never get freed in many simpler and more efficient implementations (as the interned string table is never pruned and entries never removed from it).

It’s also possible to allow multiple interning tables, which may make sense when there are different sets of strings that are unlikely to have values in common. An interned string handle class may in this case contain two pointers: one to the intern table and one to the table entry for the string. Checking strings for equality with this type is still fairly fast; if the table pointer is identical, simply compare the entry pointers, and if the table pointers are different, call the usual string range comparison types.

One final advantage of string interning is that the table entries can include hashes for each string (and in fact usually will, as the best interning table implementation is most often a hash table). This means that using interned strings as keys into other hash tables can be done without needing to rehash the key.

A final neat trick is to use a smart string literal class. Classes like the string wrapper, string builder, and string range would not be constructible from a string literal but would instead take a special literal string class. This class itself is the only constructor/method (other than OS functions and string library internals) that ever accepts a C-style string pointer.

The first advantage is that this lets you easily ban the use of char* in the application framework and safely search/grep for it in static analysis tools, as only the string library code will ever use it.

Second, the string literal can be implemented in such a way that it computes the string length at compile time (most compilers have a builtin version of strlen that does this). Furthermore, on current GCC and future MSVC compilers, this class can do compile-time string hashing, so that use of the literal as a hash table key or for string interning doesn’t require runtime hashing.

Finally, a string literal like this can be passed to a string intern lookup and, if the lookup requires the creation of a new entry, the implementation can know that it’s safe to just store the reference (as a string range, perhaps) without needing to make a copy of the string data.

One special use case for strings is editing. This includes both simple text entry interfaces in a simple GUI toolkit in a game to full-blown text editors and word processors.

It’s worth mentioning that none of the string classes outlined above are particularly suitable for those cases. A GUI text entry may be better off with a fixed-size character buffer class with cursor support (although a string builder with cursor support is also quite servicable). For larger text editors, more advanced string data types are called for. Usually there will be no benefit to interning, and you certainly don’t want to use a single large buffer that needs to resize frequently as text is entered or removed.

String ranges may not even be useful for this case as the more common large string data structures do not guarantee contiguous memory, which a string range requires.

The suggestions above are in many cases made based on performance claims. As with will performance tips, profile and test your changes to make sure they are actual performance improvements for you application.

Also, keep in mind that some applications may have different needs than most others and some of the above tips may not be as beneficial for your application.

(Note that the blog is having a little bit of fun with the formatting of the code below; my apologies.)

The code is available at GitHub as well, as will be any future updates/tweaks I make for the demo.

We’ll be getting a blog put together soon so everyone can follow the development of the game over the next three months, with in-depth articles on technological solutions to problems, art design and creation for Web-based games, the business challenges for a small startup, as well as game design and publishing stories.

Cleaner Object API

Direct State Access

Use simple and concise accessor functions. The map example above is a good indicator of what I mean, but here’s a few more examples.

Shader Semantics, Layouts, Bindings

The bind-by-name approach used by GLSL normally is cumbersome and slow. Bind-by-semantic simply makes more sense from both a performance a usability perspective.

I’d take things a step further and provide a layout configuration for drawing as well. Layouts are a continuation of the FrameBuffer Object support, and in fact can probably just supplant FBO’s entirely.

Separate Contexts from OS Windows

The platform GL context bindings such as WGL, AGL, and GLX all currently assume a single distinct context per window, which is similar to how Direct3D 9 and earlier worked as well. Unfortunately, this is pretty inflexible. It leads to a lot of pain on some platforms where simply resizing a window (or more likely, switching between a windowed display and a fullscreen display) requires destroying the platform window and hence destroying the GL context.

It also means that resources can’t easily be shared between different windows/displays without yet more platform-specific functionality and extensions.

GL platform bindings should all be updated to offer two distinct sets of functions that parallel the DXGI functions for creating “devices” and “swap chains.” One set of functions creates an OpenGL context that deals with resource management and access. A second set of functions allows binding to an OS window.

These could then contain a new set of objects, similar to how DXGI has separate SwapChain objects.

Alternatively, a context hierarchy could be used, where sub-contexts can be created from the main context with additional semantics, similar to how API’s like Cairo implement their state objects.

As examples of both approaches, see the following:

Shader Assembly Revisited

The assembly-language shader support has been deprecated in favor of forcing developers to always use GLSL. This is troublesome as it means that the development of alternative shading languages is much more difficult and limited to the features added to the core GLSL language. A simpler assembly language format alleviates this problem.

One of the problems with assembly languages is that they usually lack a lot of semantic information necessary to properly optimize code. I propose that a “high level” assembly language be implemented. Utilize simple three-address-form operators in place of C-like expressions, allow direct indexing into buffers and input sets, but still provide high level flow control and semantic hints for inputs and output.

Something like the TGSI format used by Mesa 3D would be a good start, though it’s not a complete solution.

This would allow tools like Cg to more easily target GL and optimize shader inputs and outputs properly. It would also open the doors to getting a high quality port of HLSL or even the development of an entirely new high-level shading language. Which is actually the next point.

GLSL++

GLSL was one of the first high-level shading languages and was very revolutionary for its time, but it many of the assumptions and design considerations of GLSL simply haven’t panned out all that well. The bind-by-name behavior is still one of the better examples. The lack of a high level effect framework, the inability to combine multiple shaders into a single source file, and the lack of overloading by version/profile are all additional negative points.

I’ll admit that I’m largely in favor of simply adopting Cg as an official shading language at this pointer, as it solves most of the above problems and already has a large body of documentation, examples, tools, and experience built up behind it. I’m not at all opposed to an entirely new language though so long as it does fix of all the above problems without introducing new ones.

I’m certainly in favor of retaining column-major, right-handed math. That row-major left-handed stuff from D3D is just… odd.

Simply expanding GLSL wouldn’t be too terribly complex. Shader semantics need to become first class syntax, rather than the nameless and chunky layout qualifiers introduced in GLSL 4.10. The idea of a “main” function needs to be replaced with user-named entry points that are qualified with their pipeline stage. Finally, add profile/version overloading to functions, so shaders can be written that fallback easily to older hardware profiles as the GPU scene continues to evolve.

Improved Utility Library

Give us at least a few convenience library functions that most developers need. Some basic functions for loading textures and shaders from files, for instance. Even if you can only load DDS, TGA, and PNG images, that will save a lot of developers a lot of time and headaches. Almost everyone has to write their own, or use some non-standard add-on library. Almost nobody even implements these correctly; the number of load_shader_from_file() functions on the Net that break all kinds of rules (fseek, ftell, fseek, fread patterns, for instance) is simply huge, for instance.

One wouldn’t be opposed to a simple TTF font rendering library, or an improved GLUT that at the very least offered timers so animations and simple game loops could be implemented without resorting to platform-specific API calls would be nice.

Conclusion

The interesting thing I think about the above proposals is that they’re all rather trivially implementable on existing drivers. They mostly just come down to developing a new set of API entry points over the existing functionality found in the drivers today. As both the NVIDIA and AMD drivers already expose EXT_direct_state_access, simply updating the entry points to use the new opaque types and naming is mostly just busywork rather than serious development. The vendors’ shader compilers are mostly all about the low-level optimization and code generation, and adding new frontends is relatively easy compared to the effort of adding a new hardware profile, for instance.

Such an API could almost be implemented as a wrapper around OpenGL 4.1, EXT_direct_state_access, EXT_Cg_shader. It can almost be implemented as a wrapper around Direct3D 10/11.