I've finally uploaded my logging macros to github, along with a sample program (you must have either Boost Log or Poco installed to run it). In this post, I'll detail its design.
My original requirements were prompted by a particular "use-case" - adding reusable classes to an application and allowing those classes to use the application's logging implementation, instead of whatever implementation was originally used. So, in this scenario, my requirements translate to: 1) The reusable classes must be used with no changes; and 2) The application developer should only need to create a header file with a list of well-defined macros that will invoke the app's logging implementation, thus causing the reusable classes to invoke that same implementation.
I've divided this into several header files, keeping in mind requirement #2. Let's take a look at these header files, then.
Macro Overloading - macro_overload_base.h
This is the foundation of it all. It's a group of macros that allow overloading based on the number of arguments, up to a limit of 16.
My first design required the distinction between zero arguments, one argument, and more than one argument. However, the complexity of correctly detecting zero arguments was more than I was willing to accept, so I've worked around that requirement. Detecting invocations with one argument proved to be good enough, and the resulting macros, although still ugly, are a lot simpler.
Detecting the number of arguments is up to the
PCBASE__MOVERLOAD_SELECT_VALUE macro. In order to make it work, you must call it with the correct list of values. PCBASE__MOVERLOAD_ONE_ARG_OR_MORE calls it like this#define PCBASE__MOVERLOAD_ONE_ARG_OR_MORE(...) \
PCBASE__MOVERLOAD_SELECT_VALUE(__VA_ARGS__,\
2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1)
because we just want to know if we have one argument or more than one argument.
OTOH,
PCBASE__MOVERLOAD_VA_NUM_ARGS calls it like this#define PCBASE__MOVERLOAD_VA_NUM_ARGS(...) \
PCBASE__MOVERLOAD_SELECT_VALUE(__VA_ARGS__, \
16,15,14,13,12,11,9,8,7,6,5,4,3,2,1)
because we need to know the exact number of arguments.
PCBASE__MOVERLOAD_FOR_EACH does something similar, but passes as arguments the names of the macros that will allow to apply an action to each argument. E.g.,PCBASE__MOVERLOAD_FOR_EACH(<<, "[", __FILE__, ":", __LINE__, "] ",
"Blimey! I didn't expect the Spanish Inquisition!",
chiefWeapons, mill.Trouble(), 42);
becomes
<< "[" << __FILE__ << ":" << __LINE__ << "] "
<< "Blimey! I didn't expect the Spanish Inquisition!"
<< chiefWeapons << mill.Trouble() << 42
You may have noticed the macro names look quite ugly. Since there's no namespace partitioning with macros, I've decided to make these names as ugly as I possibly can, to minimize name clashing.
Now, Let's move up one layer.
Logging Interface Type Abstraction - li_concat.h / li_outop.h
Here, we build on macro_overload_base.h to create the macros that will receive the logging arguments and call the user-supplied macros (USMs), which will, in turn, call the logging implementation.
There is an abstraction leak at this point. At some point in this "macro chain", we have to invoke the USMs. This means we have a contact point, similar to this:
#define PCBASE__LAMOVERLOAD_LOG_IMPL_1(level, ...) \
PCBLUESY__##level(__VA_ARGS__)
#define PCBASE__LAMOVERLOAD_LOG_IMPL_2(level, x, ...) \
PCBLUESY__##level((x) PCBASE__MOVERLOAD_FOR_EACH(+, __VA_ARGS__))
On the left-hand side we have the names from the logging abstraction macros, on the right-hand side we have the USMs.
I considered three locations for this contact point:
- Place it in the logging abstraction headers, i.e., in li_concat.h and li_outop.h. I rejected this idea because it would require the user to edit an extra header file, thus going against requirement #2.
- Place it in the user-supplied header.
- Create a separate header just for these macros.
While I don't like the fact the we'll have references to "abstraction names" in the user-supplied header, it seemed the best alternative, so I went for alternative #2.
li_output.h is quite simple - for each argument, prepend a "<<" to it. li_concat.h is more complex, because we can't add a "+" to a single argument.
In fact, li_output.h is so simple it could almost be dispensed with; however I couldn't come up with a design clean enough without it. Besides, keeping it maintains the parallelism between the design for these two interfaces, concatenation and stream.
NOTE: Concatenation is working, but it doesn't actually respect requirement #1 (read why here), because it's not automatically converting its arguments to string.
Logging Interface Type Selection - log_interface_type.h
This is where we define the interface type, which can be one of:
- Comma. Function call interface with several arguments, such as we would have in a
printf()-like output function. I have not implemented this. - Stream output operator (
operator<<). - Concatenation (using
+). Function call interface with only one argument, created from the concatenation of several arguments. Since it's a binary operator, it requires a more complex implementation, because it needs to distinguish between two different cases: one argument, which must not involve any concatenation ("a" +is not a valid expression); and more than one argument, which must be concatenated.
This header file will also #include the correct header file for the interface type chosen. For now, it's a choice of either li_concat.h or li_outop.h. Both are described above.
We use this it by adding a #define to the project file/makefile, defining which interface type we want. E.g., on Qt Creator, to use the stream output operator, we'd do something like this on the .pro file:
DEFINES += "PCBLUESY__LOGINTERFACETYPE=3"
The default type (if we haven't #defined
PCBLUESY__LOGINTERFACETYPE anywhere) is the stream output operator.
For now, I'll leave this header specific to the application, i.e., I'll have to create a new header for each application. I suspect this is not the best design, but I'll wait until I've used it a few times to see how it turns out.
Logging implementation - e.g., poco_log.h or boost_log.h
This is where we define the macros that will directly invoke the required functionality in the logging implementation (e.g., Poco or Boost).
The way I've set it up, we have a macro to get the logger (e.g., for Boost Log):
#define PCBLUESY__GETLOGGER(PCBLUESY_LOG_NAME) \
src::severity_logger<boost::log::trivial::severity_level> \
PCBLUESY__BOOSTLOG
Then, we have the top level logging macro, i.e., the macro that will get used in all the logging statements in the code:
#define PCBLUESY__LOG(level, ...) \
PCBASE__LOG_ABSTRACTION(level, __VA_ARGS__)
These are the only two macros used in the application code. We then have the actual logging macros, i.e., the macros that call the logging implementation. Again, example for Boost Log:
#define PCBLUESY__PCBLUESY__TRACE(...) \
BOOST_LOG_SEV(PCBLUESY__BOOSTLOG, \
boost::log::trivial::severity_level::trace) __VA_ARGS__
Why the
PCBLUESY__ repetition? This is the way the macro is used in the code:PCBLUESY__LOG(PCBLUESY__ERROR, \
"Blimey! I didn't expect the Spanish Inquisition ERROR!", \
chiefWeapons, mill.Trouble(), 42);
I'm using
PCBLUESY__ERROR as logging level in order to distinguish it from any other *ERROR* defined "out there". Since these names are defined in this header and won't be used anywhere else, I figured a little uglyness would be harmless, and could actually be useful.
Finally...
How do we use this? I've set up an example on my "SimpleSampleTuts" github. You'll need Boost Log and/or Poco C++ to see it in action. And if you use any other logging lib, provided it has an interface compatible with the ones discussed here, you should be able to create a header like poco_log.h/boost_log.h and start using it.
One final detail - initializing the logger. If you use a different implementation, you'll have to add that code, too.
No comments:
Post a Comment