// NOISY CODE
#define MULTI_LINE_MACRO \
	do { \
		std::printf("Hello "); \
		std::printf("world!\n"); \
	} while (0)

will trigger C4127: “Conditional expression is constant” in Visual Studio 2003/2005, and probably 2008 as well (but I haven’t tried it).  The culprit is the “while(0)” part, the compiler thinks we’re making a mistake when of course this is all very intentional. Let’s see what we can do to fix it!

This is really unfortunate because these macros live in header files, and for the life of me I couldn’t figure out a way to shut up that warning!  The best way I’d found to deal with it was simply to issue a sledgehammer #pragma “shut the hell up” directive:

// QUIET BUT RUDE CODE
#pragma warning(disable:4127)
#define MULTI_LINE_MACRO \
	do { \
		std::printf("Hello "); \
		std::printf("world!\n"); \
	} while (0)

This is very bad.  I don’t want to globally silence 4127, just only for my multi-line macro stuff, but now every cpp file that #includes my header file has 4127 forever silenced!  This is inconvenient enough inside your own codebase, but it’s flat-out rude if you’re writing middleware!  I’ve used middleware that changes the warning levels on my cpp files, and it was an unpleasant surprise to find that the warnings I was expecting to receive were being muted before the compiler ever saw any of my code!

What we really want to do is something like this:

// BROKEN CODE
#define MULTI_LINE_MACRO \
	do { \
		std::printf("Hello "); \
		std::printf("world!\n"); \
#pragma warning(push)
#pragma warning(disable:4127)
	} while (0)
#pragma warning(pop)

This preserves the global warning state, but still disables 4127 for the duration of our intentional violation. Unfortunately though, since the preprocessor isn’t recursive, that’s illegal.  We can’t put #pragma directives inside macro definitions!  We can also try doing something like this:

// STUPID CODE
#pragma warning(push)
#pragma warning(disable:4127)
#define MULTI_LINE_MACRO \
	do { \
		std::printf("Hello "); \
		std::printf("world!\n"); \
	} while (0)
#pragma warning(pop)

But that doesn’t do what we want at all, because of course the #pragmas don’t wrap the macro at its invocation site, and wrapping the definition doesn’t do anything!

Well, it turns out that Microsoft implemented the __pragma directive for just this purpose. Using __pragma instead of #pragma lets you embed pragma directives inside of macros!  This turns out to be just what the doctor ordered.  We can now throw together multi-line macro wrappers that emit no warnings on /W4 and don’t change the global warning state!

// WORKING CODE
#define MULTI_LINE_MACRO \
	do { \
		std::printf("Hello "); \
		std::printf("world!\n"); \
__pragma(warning(push)) \
__pragma(warning(disable:4127)) \
	} while (0) \
__pragma(warning(pop))

We can now generalize this approach to a set of helper macros that help you always correctly implement multi-line macros:

#define MULTI_LINE_MACRO_BEGIN do {
#define MULTI_LINE_MACRO_END \
	__pragma(warning(push)) \
	__pragma(warning(disable:4127)) \
	} while(0) \
	__pragma(warning(pop))

And here’s our original example reimplemented:

#define MULTI_LINE_MACRO \
	MULTI_LINE_MACRO_BEGIN \
		std::printf("Hello "); \
		std::printf("world!\n"); \
	MULTI_LINE_MACRO_END

Finally, I should point out that both a coworker of mine and someone on the boost mailing list have found another slightly bizarre workaround to this problem:  For some reason, the code

// WORKING CODE, BUT A LITTLE SCARY
#define MULTI_LINE_MACRO \
	do { \
		std::printf("Hello "); \
		std::printf("world!\n"); \
	} while (__LINE__ == -1)

 
doesn’t trigger C4127.  I can only conclude that it’s unintended compiler behavior, because replacing __LINE__ with a literal integer causes it to trigger, and I can’t imagine that MS intended that code to be the correct way to dodge 4127.  Use it at your own peril, and don’t be surprised if a new version of Visual Studio or some random service pack breaks it!

Grab Pow2Assert.h and Pow2Assert.cpp, now under the MIT license!

The simple joys of hack-and-slash prototyping are over!  We’re convinced the gameplay is fun, so it’s time to buckle down and start coding “for real.”  We’re saying goodbye to the guilty pleasures of undisciplined C++ hacking and hello to solid, well-engineered code.  I recently had the pleasure of writing our assert macros and came across some surprisingly challenging problems.  This article is about how to make your assert macro as bulletproof as possible when you want it, and totally disappear into nothingness when you don’t.

We’re very aggressive about assert.  Noel even cared enough a couple years ago to stand up to the haters!  We assert everything from pointer function parameters to Direct3D return codes.  We use it everywhere so it’s got to be absolutely rock solid.  ”No problem,” you think, “assert is some beginner C++ stuff.  I’m a C++ animal!  I can write assert macros in my sleep!”  Most assert code looks something like this (Assert::Fail is a function that does about what you’d expect, report the assert and terminate the program):

#define POW2_ASSERT(x) \
    if (!x) { pow2::Assert::Fail(#x, __FILE__, __LINE__); }

Take a minute right now and think of everything you’d fix about this assert macro.  If this code makes you run screaming for the hills (and scheduling a heart-to-heart with your lead programmer), good for you!  If you look at this code and think “yeah, that’s pretty cool chas, I dig that code!” then unhook the paint can from your face, keep reading, and promise me you won’t write any assert macros until you’re done.

OK we’ll go step by step here, in order of severity (and effect on sanity!).  Let’s start with the basics:

1.  Always wrap your macro parameters in parentheses.

Would you expect the following code to trigger an assert?

POW2_ASSERT(true || false);

The correct answer, by the way, is “absolutely not.”  But look at what it expands into when subjected to our awful assert macro:

if (!true || false) { pow2::Assert::Fail(...); }

Yeah, oops. “!true || false” of course collapses into “false”, which causes the assert to fire. Not what we want at all.  The standard fix is to always wrap your macro parameters in parentheses.  The corrected macro thus far now reads:

#define POW2_ASSERT(x) \
    if (!(x)) { pow2::Assert::Fail(#x, __FILE__, __LINE__); }

Not great, but slightly better.

2.  Wrap your macros in do { … } while(0).

What would you expect to have happen here?

if (x == 3)
    POW2_ASSERT(y == 4);
else
    DoSomethingReallyImportant();

The actual code is much different:

if (x == 3)
    if (!(y == 4))
        pow2::Assert::Fail(...);
    else
        DoSomethingReallyImportant();

Not so great. There are even scarier cases, too!  Anyway, the ‘canonical’ and ugly-as-hell solution is to wrap your macros in a “do { … } while(0)” line.  Note the lack of semicolon at the end there, it’s very important.  It’s a surprisingly involved discussion that I won’t rehash because it’s in the comp.lang.c FAQ and you’re starting to get a little bored by now.  Don’t worry, the best fun is yet to come! 

Here’s our best stab at assert yet:

#define POW2_ASSERT(x) \
    do { if (!(x)) { pow2::Assert::Fail(#x, __FILE__, __LINE__); } } while(0)

3.  Go away!  Sit in the corner, face the wall; I don’t want to even know you’re here.

Asserts are great!  Let’s assert everywhere that our vectors are normalized!  Let’s assert that our strings are all exactly 12,592 bytes long by scanning for the first ‘\0′!  Let’s assert that every time we clear the back buffer, each pixel is set to burnt umber!  Let’s figure out why we’re only rendering at 1fps in release build!  Hmm.

A very nice thing to be able to do with assert is compile it out of existence.  The standard form looks something like this:

#ifdef POW2_ASSERTS_ENABLED
    #define POW2_ASSERT(x) \
        do { if (!(x)) { pow2::Assert::Fail(#x, __FILE__, __LINE__); } } while(0)
#else
    #define POW2_ASSERT(x)
#endif

OK, now it compiles out, and things are well and good, right? Sure, if you like spurious compiler warnings.

const bool success = DoStuff();  POW2_ASSERT(success);

Gives us this output (in MSVC8 but gcc gives an almost identical one):

main.cpp(7) : warning C4189: 'success' : local variable is initialized but not referenced

Not great.  These warnings only show up on MSVC’s (level 4) and gcc’s (-Wall) highest warning levels, but they can be valuable in other situations so we don’t want to disable them.  We can try the standard cast-to-void trick:

#define POW2_ASSERT(x) do { (void)(x); } while(0)

But then x is still evaluated.  Both gcc and MSVC are smart enough to optimize out the evaluation of x, but only if they can determine if  there are no side effects associated with the evaluation.  Unfortunately, this can only be done if the body of x is known entirely to the compiler.  If x is a function call to another module MSVC can still make it go away with Link-Time Code Generation (via cross-module inlining), but poor gcc is dead in the water and emits the call.  Either way, we’re relying on compiler and linker optimizations to make this code go away.

This code:

int main(int, char*[])
{
    bool DoStuff(); // comes from another .cpp file
    POW2_ASSERT(DoStuff());
    return 0;
}

Causes gcc (-O3 -pedantic -Wall –save-temps) to emit the following assembly:

_main:
pushl %ebp
movl $16, %eax
movl %esp, %ebp
subl $8, %esp
andl $-16, %esp
call __alloca
call ___main
call __Z7DoStuffv
leave
xorl %eax, %eax
ret

We’re not so crazy about the whole “call __Z7DoStuffv” line, but at least the compiler shut up.  We’re halfway there, I suppose.  The standard “UNUSED” macro has the same problem:

#define POW2_UNUSED(x) do { (void)(x); } while(0)

This can be useful for shutting up warnings during deep spelunking in the bowels of template code, but not here. The parameter is still evaluated and now we’ve also got this extra little clingy macro that follows our assert around everywhere. Nope, unused won’t do the trick here.

The best optimization you can ever do is to completely remove the code in question.  Both gcc and MSVC have pretty decent optimizing compilers, but why bother requiring them to be good at their jobs?  If there were a way we could force assert to boil down to nothing when we want and not emit any spurious warnings, we’d totally be money. 

Boy, if only there were some C++ keyword that could syntactically accept almost anything and be guaranteed not to emit any code.

Enter the ever-humble sizeof keyword.  This little guy must be the absolute bane of C++ compiler writers.  Alexandrescu thoroughly exploits it in Modern C++ Design, and we can steal a page from his playbook here.  Let’s check the C++ Standard, (5.3.3), shall we?

The operand is either an expression, which is not evaluated, or a parenthesized type-id.

Now I’m nowhere near as tricky as Alexandrescu or the slew of C++ luminaries who have discovered new and insane things to do with this awful language, but I know a useful keyword when I see it!  Baby, you had me at “which is not evaluated”.  Let’s rig it up and take it for a spin.  Note that gcc will correctly warn about the sizeof statement “having no effect,” but we can shut that up easily enough using the cast-to-void trick mentioned earlier:

#define POW2_ASSERT(x) do { (void)sizeof(x); } while(0)

Our old test case now emits the following assembly in gcc:

_main:
pushl %ebp
movl $16, %eax
movl %esp, %ebp
subl $8, %esp
andl $-16, %esp
call __alloca
call ___main
leave
xorl %eax, %eax
ret

And on MSVC8:

_main PROC
xor eax, eax
ret 0
_main ENDP

Our warnings are now silenced on both gcc and MSVC, too!  Looks pretty good to me. Let’s look at our final code, which is getting much closer to our quality bar:

#ifdef POW2_ASSERTS_ENABLED
    #define POW2_ASSERT(x) \
        do { if (!(x)) { pow2::Assert::Fail(#x, __FILE__, __LINE__); } } while(0)
#else
    #define POW2_ASSERT(x) \
        do { (void)sizeof(x); } while(0)
#endif

4.  Assert should always halt execution of the program, except for when it shouldn’t.

The standard trick on Windows under MSVC to halt the program and break into the debugger is to use __debugbreak():

#define POW2_HALT() __debugbreak()

This is always what you want to do when your assert fires, right?  I mean, it’s an assert!  You can’t really continue gracefully, even if you wanted to.  Things are too insane.  That’s why you asserted in the first place!

Except maybe if you’re running unit tests.  If an assert fires inside a unit test, you probably don’t want a “friendly” modal dialog box to pop up and require you to hit abort, retry, or cancel.  You certainly don’t want that modal dialog box popping up on your poor automated build server.  You want to terminate that particular unit test and keep going.

That makes the requirements of your assert code a little more demanding.  Does it have to know if it’s running inside tests?  How can it possibly know these things even if you wanted to couple your code to your tests?  It can’t.  Not in any sort of clean way, anyway.  Not in any way that doesn’t couple your code too tightly for our comfort.

Assert::Fail hasn’t really been doing much of interest to date.  You’ve probably assumed that it prints the failed assert to the screen in a compiler-friendly format and then halt the program using a macro like POW2_HALT() above.  If it trampolined directly into a user-provided handler, it could report whether or not to terminate the program.  Let’s change it from:

namespace pow2 { namespace Assert
{
    void Fail(char const* condition, char const* msg, char const* file, int line);
}}

to this:

namespace pow2 { namespace Assert
{
	enum FailBehavior
	{
		Halt,
		Continue,
	};

	typedef FailBehavior (*Handler)(const char* condition,
                                    const char* msg,
                                    const char* file,
                                    int line);
	Handler GetHandler();
	void SetHandler(Handler newHandler);

	FailBehavior ReportFailure(const char* condition,
                               const char* file,
                               int line,
                               const char* msg, ...);
}}

We hide the current handler and default handler in Assert.cpp so as to keep our header file as simple as possible.  Now we can set any handler we want, and the app will only halt if the handler returns true. For our unit tests, our assert handler reports the assert to our testing framework, and the test fails gracefully.  Let’s beef up our macro yet again:

#ifdef POW2_ASSERTS_ENABLED
    #define POW2_ASSERT(cond) \
        do \
        { \
            if (!(cond)) \
            { \
                if (pow2::Assert::ReportFailure(#cond, __FILE__, __LINE__, 0) == \
                    pow2::Assert::Halt) \
                    POW2_HALT(); \
            } \
        } while(0)
#else
    #define POW2_ASSERT(condition) \
        do { POW2_UNUSED(condition); } while(0)
#endif

We’re in the home stretch!  This is actually our final code, but we’re not done discussing things yet. Note also in the real Pow2Assert.h there are overloaded forms of these macros that support variadic parameters for printf-style formatting. I’ve omitted them here for brevity.
 

5.  Hooray!  My assert fired!  Where the hell am I?!

The final common problem with assert macros is that they often leave you alone and lost in the wilderness, about 3 stack frames away from the code that actually triggered the assert.  I hope to inflict a violent emotional reaction by showing you this next image:

Ahh yes.  Thanks a ton MSVC for taking me to…  _NMSG_WRITE(int rterrnum=10).  It’s at line 198 of crt0msg.c, if that helps you.  But it doesn’t.  Know why? Because it’s completely useless!  _NMSG_WRITE doesn’t have a damn thing to do with why our program is now dead.

The nicest side effect of item 4 (moving the POW2_HALT() back to the assert macro itself) is that the fired assert lands you in the debugger AT THE SITE OF THE FAILING ASSERT.  Sorry to yell, but it’s important.  Look at this call stack and tell me it’s not nicer:

And we got it as a free side effect of making our assert macro cooler!

So that’s pretty much it for Assert.  I’m still tinkering with it every now and then, but it’s about as solid as I know how to make it at this point.  It’s certainly serving me well in the meantime. 

Credit goes to Steve Rabin for his chapter in Game Programming Gems 1, it was the inspiration for item 5.  Thanks as always to Andrei Alexandrescu for opening my eyes to the sheer blinding madness of sizeof.  Tom Plunket was good enough to beat the do/while(0) stuff into me.