X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Utils%2FLogger%2FLog.hh;h=8ddcc7167cdf62c50671496c676254a9234d9213;hb=5fb9163ddc78aa5ab5a35b27e13ccb2c1028692a;hp=072e89387f3141f8e65cd3f8bc751c09a9d22ecf;hpb=9bfe0b87be0926193b5baf13865cf045f0de0b0d;p=senf.git diff --git a/Utils/Logger/Log.hh b/Utils/Logger/Log.hh index 072e893..8ddcc71 100644 --- a/Utils/Logger/Log.hh +++ b/Utils/Logger/Log.hh @@ -1,8 +1,8 @@ // $Id$ // // Copyright (C) 2007 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY // Stefan Bund // // This program is free software; you can redistribute it and/or modify @@ -34,13 +34,75 @@ #include "Parameters.hh" //#include "Log.mpp" +#include "Log.ih" ///////////////////////////////hh.p//////////////////////////////////////// +/** \defgroup logging Logging commands + + The logging library provides several commands to create log messages. All these macro commands + take a variable number of arguments. Since this is not supported in a usable way by the C++ + preprocessor, the arguments are encoded into a Boost.Preprocessor like + sequence: + + \code + SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") ); + \endcode + + The argument is comprised of a sequence of parameters and the log message itself. The parameters + are + \li the log stream, + \li the log area, + \li the log level. + + These parameters are optional and may be specified in arbitrary order (with the log + message always being the last sequence element) and even multiple times in the parameter + sequence. If some argument type occurs multiple times, the last occurrence wins. If any one of + the parameters is not specified, it's current default value will be used. + + This current default value is set using \ref SENF_LOG_DEFAULT_STREAM, \ref SENF_LOG_DEFAULT_AREA + and \ref SENF_LOG_DEFAULT_LEVEL respectively. These macros set the default stream, area and/or + level of the current scope. They may be used with a class declaration to set defaults + for all class members or within a function or member body to set the default for that member + only. They may be used only \e once within each scope. + + The logging library defines the global defaults for stream, area and level to be \c + senf::log::Debug, senf::log::DefaultArea, and senf::log::NONE respectively. + + The log level senf::log::NONE is special. If the log level is set to this value, the log level + will be set from the stream provided default value. + + All these parameters must be compile time constants (they are all types, so it's + difficult form them to be something else). + + \section logging_aliases Aliases + + To further simplify logging commands, aliases may be defined within any scope. An alias is an + arbitrary collection of log parameters: + \code + SENF_LOG_DEF_ALIAS( VerboseDebug, (senf::log::Debug)(senf::log::VERBOSE) ); + \endcode + Within log statements, aliases may be used like normal parameters. They will be substituted for + the parameter sequence they represent: + \code + SENF_LOG( (VerboseDebug)("Debug message") ) + // is equivalent to + SENF_LOG( (senf::log::Debug)(senf::log::VERBOSE)("Debug message") ) + \endcode + Aliases may be used together with other parameters, even with further aliases in any order. + */ + +///\addtogroup logging +///\{ + +///\name Generating log messages +///\{ + /** \brief Write log message This macro will write it's last argument to the log stream. The last argument must be an expression which will be placed after a streaming \c operator<< (like - some-log-sttream \c << last-macro-arg). + some-log-stream \c << last-macro-arg). \code SENF_LOG((parameters...)("log message " << args << ...)); \endcode @@ -51,6 +113,12 @@ SENF_LOG_BLOCK_( SENF_LOG_MERGE_PARAMETERS(BOOST_PP_SEQ_POP_BACK(args)), \ { log << BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args); }) +/** \brief Write log message (template context) + + This macro is used like \ref SENF_LOG() if called from a template context + + \hideinitializer + */ #define SENF_LOG_TPL(args) \ SENF_LOG_BLOCK_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)), \ { log << BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args); }) @@ -72,18 +140,18 @@ SENF_LOG_BLOCK_( SENF_LOG_MERGE_PARAMETERS(BOOST_PP_SEQ_POP_BACK(args)), \ BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args)) +/** \brief Write log message (template context) + + This macro is used like \ref SENF_LOG_BLOCK() if called from a template context + + \hideinitializer + */ #define SENF_LOG_BLOCK_TPL(args) \ - SENF_LOG_BLOCK_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)), \ - BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args)) + SENF_LOG_BLOCK_TPL_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)), \ + BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args)) -#define SENF_LOG_BLOCK_(parameters, block) \ - do { \ - if (parameters::compile_enabled && parameters::enabled()) { \ - std::ostream & log (parameters::log_stream()); \ - do block while(0); \ - log << std::endl; \ - } \ - } while(0) +///\} +///\} ///////////////////////////////hh.e//////////////////////////////////////// //#include "Log.cci"