targets at the same time. To allow concise usage of the library, a utility to define logging
defaults for any scope is provided.
- An important basic concept of the library is, that most of the macros take a variable number of
- arguments. Since this is not supported in the needed manner by the C++ preprocessor, the
- arguments are encoded into a <a
- href="http://www.boost.org/libs/preprocessor/doc/index.html">Boost.Preprocessor</a> like
- sequence:
+ \see
+ \ref logging \n
+ \ref config \n
- \code
- SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") );
- \endcode
+ \section logging_tutorial Tutorial introduction
- The last sequence element always is the log message. Before that we have a number of log
- parameters <i>in arbitrary order</i>. Since giving all the parameters in every log message is to
- verbose, there are two helpful constructs to reduce the verbosity. Using \ref
- SENF_LOG_DEFAULT_STREAM, \ref SENF_LOG_DEFAULT_AREA and \ref SENF_LOG_DEFAULT_LEVEL it is
- possible to define the default logging parameters to be used within a given scope. Using \ref
- SENF_LOG_DEF_ALIAS you can define an alias (which is a scoped symbol) as an arbitrary
- combination of parameters.
+ Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
+ some other helpers used to simplify specifying parameters.
\code
- SENF_LOG_DEF_STREAM( userLog, senf::log::MESSAGE, senf::log::MESSAGE );
+ namespace foo {
- class Froblizer
- {
- // Define a new log area
- SENF_LOG_DEF_AREA(FroblizerArea);
+ // Define a new log stream with default level, runtime limit and compile time limit
+ // set to senf::log::MESSAGE
+ SENF_LOG_DEF_STREAM( UserLog, senf::log::MESSAAGE, senf::log::MESSAGE, senf::log::MESSAGE );
- // Set default log parameters for this scope
- SENF_LOG_DEFAULTS((senf::log::Debug)(senf::log::NOTICE)(FroblizerArea));
+ class Froblizer
+ {
+ // Define a log area which will automatically be used by all members of this class.
+ // This is a combination of SENF_LOG_DEF_AREA and SENF_LOG_DEFAULT_AREA.
+ SENF_LOG_CLASS_AREA();
- // Define an alias for emergency messages to the sysadmin.
- // The log area is inherited from the default at the place, where this
- // alias is used *not* where it is defined
- SENF_LOG_DEF_ALIAS(LogEmerg, (userLog)(senf::log::CRITICAL));
+ // Set default log parameters for this scope. The values here are not really
+ // necessary since these are the global default values
+ SENF_LOG_DEFAULT_STREAM(foo::UserLog);
+ SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
- void test();
+ // Define an alias for emergency debug messages
+ // The log area is inherited from the default at the place, where this
+ // alias is used *not* where it is defined
+ SENF_LOG_DEF_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
- public:
- void froblize();
- };
+ void test();
+
+ public:
+ void froblize();
+ };
+ }
- void Froblizer::froblize()
+ void foo::Froblizer::froblize()
{
- SENF_LOG(("This is the Debug stream at level NOTICE in the FroblizeArea"));
+ SENF_LOG(("This is the UserLog at level NOTICE in the FroblizeArea"));
SENF_LOG((senf::log::WARNING) ("Same stream and area but at warning level"));
- SENF_LOG((LogEmerg) ("This goes to the userLog at level CRITICAL in the FroblizerArea"));
+ SENF_LOG((LogEmerg) ("This goes to the DebugLog at level CRITICAL in the FroblizerArea"));
}
- void Froblizer::test()
+ void foo::Froblizer::test()
{
// Change the default log level for this method. stream and area are taken
// from the next scope up
- SENF_LOG_DEFAULTS((senf::log::VERBOSE));
+ SENF_LOG_DEFAULT_LEVEL(senf::log::VERBOSE);
- SENF_LOG(("Log to Debug stream in Froblizer area however at VERBOSE level"));
+ SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
}
\endcode
- Currently, the library is not implemented in any way. The interface has been defined up to a
- point and we have dummy implementations of the 'in-code' part of the interface. This is the
- part, which is called throughout the code. The configuration API is defined but we don't even
- have a template implementation. However, this allows starting to use the SENF Logger in newly
- developed code. Even though this code will unconditionally log everything to \c std::cerr for
- now and errors in the parameter specification will not be caught (since they are just ignored)
- the logging should work automatically as advertised as soon as the logger is completely
- implemented.
-
- I did not find any implementation which was not either completely convoluted, unusable or
- slow. So I turned to a macro based implementation which can provide all the design goals stated
- above.
-
- \section logger_compile_conf Compile time configuration
-
- The logger infrastructure allows to enable or disable log levels or areas at compile
- time. Levels or areas disabled at compile time do not generate any code. The compile time
- configuration is done in two parts: When defining log streams, default log levels and log level
- limits are defined. Additionally the \c SENF_LOG_CONF symbol can be defined to customize this
- default configuration.
-
- The \c SENF_LOG_CONF symbol is a Boost.Preprocessor style sequence of sequences:
- <pre>
- g++ ... -DSENF_LOG_CONF="((senf::log::Debug)(_)(DISABLED)) \
- ((senf::log::Debug)(foo::FooArea)(VERBOSE))" ...
- </pre>
- Each element defines the compile time limit for a stream and optional area.
-
\implementation I would have much preferred a more C++ like implementation. However given the
- design goals
- \li Flexible configuration at compile and runtime
- \li Concise usage and simple interface
- \li Zero overhead for compile-time disabled log messages
+ design goals
+ \li Flexible configuration at compile and runtime
+ \li Concise usage and simple interface
+ \li Zero overhead for compile-time disabled log messages I did not find any non-mcaro
+ implementation which was not either completely convoluted, unusable or slow. So I turned to
+ a macro based implementation which can provide all the design goals stated above.
*/
\f
projects / senf.git / blobdiff