It’s nice to make EPOLL_EVENTS an enum, since doing so aids in debugging and is more elegant. But it’s also nice for programs to be able to check for the availability of a particular flag with #ifdef EPOLLPRI. So the <sys/epoll.h> header solves both problems, taking advantage of the fact that cpp mostly doesn’t expand macros recursively. After these definitions, the token EPOLLIN will expand to itself once and then stop expanding, so it’s effectively equivalent to an enum that also supports #ifdef.

To prevent recursion, cpp associates a bit with every macro that has been defined. The bit reflects whether the macro is currently being replaced with its substitution list, so let’s call it the replacing bit. Cpp furthermore associates a bit with each token in the input stream, signifying that the token can never be macro-expanded. Let’s call the latter bit the unavailable bit. Initially, the replacing and unavailable bits are all clear.

As cpp processes each input token T, it sets T’s unavailable bit and decides whether or not to macro-expand T as follows:

If cpp decides not to macro-expand T, it simply adds T to the current output token list. Otherwise, it expands T in two phases.

Let’s look at a simple example:

In phase 1, the argument of the outer macro, namely “FL(5),” gets expanded to the token list ((5)+1), yielding FL(((5)+1)). Expanding the outer FL macro substitutes this argument for the parameter x in the substitution list, producing ((((5)+1))+1). The result should be reasonably intuitive. The one thing to note is that because expansion of the inner FL happened in phase 1, FL’s replacing bit was clear and no tokens ever needed their unavailable bits set.

Now let’s look at a more interesting example:

Consider the first part of the token sequence, namely ID(ID). We start in phase 1 by macro-expanding the inner ID, but since it’s a function-like macro not followed by (, cpp decides not to expand it. Hence, cpp replaces arg with ID in the outer ID’s substitution list, and pushes the result onto the input list. Then it sets macro ID’s replacing bit and proceeds to phase 2 (rescan). Upon processing the first token, ID, cpp will set its unavailable bit (since ID has replacing true) and not expand it. Finally, cpp will clear ID’s replacing bit, but at this point there is nothing left to expand because the third ID is not followed by (.

In the above examples, various portions of the (ID) argument to ID2 are moved into the argument of the first ID, and you can see that the second ID starts getting the unavailable bit set as soon as it moves into the substitution list of the first ID.

Recursive macros

When we expand F(), note that F_AGAIN is not followed by (, so it does not get expanded as a macro. Sure, one step later, PARENS gets expanded to (), but at this point cpp has already output the token F_AGAIN, so it’s too late to decide to expand it. Hence, the output of F()—namely f F_AGAIN ()()—may contain an unexpanded macro call, but the unavailable bits are clear on all tokens.

Now consider what happens when we call ID(F()). Well, fist we expand the argument F() to f F_AGAIN ()(). Then we are done, so we clear F’s replacing bit. Next, ID substitutes f F_AGAIN ()() for arg in its substitution list (namely the single token arg). So the preprocessor sets ID’s replacing bit and rescans f F_AGAIN ()(), causing F_AGAIN and then F to expand. But of course the same PARENS trick prevents the second F_AGAIN from getting expanded.

Variable-argument macros

C++11 added variable-argument macros. When the last macro parameter in a #define is ... rather than an identifier, it can accept an arbitrary number of arguments and the special token __VA_ARGS__ in the substitution list expands to all of these arguments, separated by commas. The canonical example is:

Unfortunately, there’s a slight annoyance that, in many situations, it’s hard to write a macro that generates syntactically correct C code when ... represents zero arguments. For example, suppose you want a macro that prints messages in brackets. You might try to do something like this:

Here we take advantage of the fact that C concatenates adjacent string constants. Since the first argument to LOG, corresponding to parameter fmt, is expected to be a string constant, we can construct a new format argument to printf in which this string has been bracketed. Unfortunately, this doesn’t work if there are no arguments after the format string:

The extra comma in printf("hello",) is a syntax error in C and C++. C++20 solved this problem by adding a new special identifier, __VA_OPT__. The sequence __VA_OPT__(x), which is only legal in the substitution list of a variable-argument macro, expands to x if __VA_ARGS__ is non-empty and to nothing if it is empty. That allows us to fix the LOG macro by suppressing the comma when the argument list is empty:

But of course, as an unintended benefit, differentiating between empty and non-empty argument lists is exactly the mechanism we need to implement the base case in recursion…

The FOR_EACH macro

We now have all the pieces we need to implement a FOR_EACH macro:

Note that we’ve tweaked EXPAND so that it handles macros that output commas by simply using __VA_ARGS__ instead of a named arg.

The bulk of the work happens in FOR_EACH_HELPER(macro, a1, ...), which applies macro to argument a1, and then uses __VA_OPT__ to recurse if the remaining arguments are not empty. Just as in the previous section, it uses the PARENS trick to enable recursion. The only catch, of course, is that we have to keep re-scanning the macro, which is why the FOR_EACH macro wraps FOR_EACH_HELPER in the EXPAND macro we saw before. For good measure, FOR_EACH also uses __VA_OPT__ to handle the case of an empty argument list.

Will I use this in production code? I’m thinking about it. In my first decade of C++ programming, I used to think that being a good C++ programmer was all about showing how clever you are. Now as a wise old senior faculty member, I know that being a good C++ programmer is all about showing restraint. You need to know both how to be clever and when to be clever. So let’s do the cost-benefit analysis, starting with the alternative approaches: