whalloc  WHALLOC_API

The WHALLOC_API Macro

If you look at the whalloc sources you will see that all types and function names look like WHALLOC_API(foo), as opposed to whalloc_foo. This is somewhat unconventional (and possibly unsightly, though i kinda like it), but is has a reason...

The macro is defined in whalloc_namespace.h (it is the only thing in that file, in fact), and looks something like this:

#define WHALLOC_API(X) whalloc_ ## X

Thus WHALLOC_API(foo) evaluates to whalloc_foo. The reason the API does this is because i use whalloc internally in several other libraries. Some of those libraries will eventually be used together in a larger application, and i don't want any symbol collisions. So... using this macro, instead of hard-coded names, allows me to change the namespace for specific projects, or even import the whole whalloc API into another project's namespace by re-defining WHALLOC_API() to use the project's naming prefix. e.g.

#define WHALLOC_API(X) my_ ## X

which would transform, e.g., the whalloc_bt class to my_bt. In client code you could then reference the whalloc types and functions using either WHALLOC_API(typeOrFuncName) or my_typeOrFuncName.

The one gotcha here is that there are several other macros in whalloc which cannot be defined in terms of WHALLOC_API() because the macro expansion rules won't allow us to do it. Thus even if the namespace is changed (changing all function and type names), there are still a number of macros in the library which are named WHALLOC_xxx (or even whalloc_xxx). Those can be sed/perl'd into something else if name collisions become a problem.