Utils/Logger/Config.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief Config public header */
  25
  26 #ifndef HH_Config_
  27 #define HH_Config_ 1
  28
  29 // Custom includes
  30 #include "Levels.hh"
  31
  32 //#include "Config.mpp"
  33 #include "Config.ih"
  34 ///////////////////////////////hh.p////////////////////////////////////////
  35
  36 /** \defgroup config Configuration
  37
  38     The logger infrastructure provides for very fine-grained configuration of log messages. There
  39     are two parts to this configuration: compile-time configuration and runtime configuration.
  40
  41     <em>Compile-time</em> configuration selects, which log statements will even be compiled. If
  42     logging for a certain combination of stream, area and level is disabled at compile time, no code
  43     will be generated for any such disabled log statement. This type of configuration is done using
  44     \ref SENF_LOG_CONF.
  45
  46     <em>Runtime</em> configuration on the other hand deals with routing all those messages, which
  47     are enabled at compile time to the logging targets. If a message is not routed, it will be
  48     discarded. This allows to additionally disable messages at run-time. Message routing is managed
  49     via the \ref Target interface.
  50
  51     \section config_compile Compile time configuration
  52
  53     Compile time configuration is set on the compiler command line:
  54     <pre>
  55     g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
  56                              (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
  57                              (( (foo)(Transactions),(_),NOTICE ))" ...
  58     </pre>
  59     The value is relatively complex; It's a Boost.Preprocessor style sequence of tuples, of which
  60     the first and second elements are again sequences. What this boils down to, is that it allows to
  61     configure compile time logging limits based on stream and optional area.
  62
  63     The above example disables all debug logging by setting the default log limit for all areas on
  64     the \c senf::log::Debug stream to \c DISABLED. It then re-enables debug logging only within the
  65     \c foo::SomeClass area, where it is set to \c VERBOSE. Furthermore, the limit on the \c
  66     foo::Transactions stream is set to \c NOTICE.
  67
  68     \see \ref SENF_LOG_CONF
  69
  70     \section config_runtime Runtime configuration
  71
  72     The runtime configuration is performed by routing messages to one or more logging targets:
  73     \code
  74     senf::log::ConsoleLog consoleLog;
  75     senf::log::FileLog fileLog ("my.log");
  76
  77     consoleLog.route<senf::log::Debug>();
  78     consoleLog.route<foo::Transactions, foo::SomeClass>(senf::log::Target::REJECT);
  79     consoleLog.route<foo::Transactions, senf::log::IMPORTANT>();
  80
  81     fileLog.route<foo::Transactions>();
  82     \endcode Here we see an already relatively complex setup: All debug messages (that is, those,
  83     which are not disabled at compile time) are routed to the console. We also route important
  84     transactions to the console \e except transactions from the \c foo::SomeClass area. The \c
  85     fileLog simply receives all transaction log messages.
  86
  87     The routing statements are processed by the targets in order, the first matching rule will
  88     decide a log messages fate for that target.
  89
  90     There are two cases, where this setup may lead to inadvertently lost log messages:
  91     \li When using a library which does internally use the Logger but not initializing the logger in
  92         your application.
  93     \li When log messages are created during initialization of static objects.
  94     Since no route is set up in these cases, the messages will be dropped.
  95
  96     To counter this problem, the logger is initially in <em>fallback routing</em> state. If any log
  97     message arrives in this state, the message will be unconditionally logged to the console. The
  98     first routing statement on any target will take the logger out of this state and normal routing
  99     will take place.
 100
 101     \see \ref senf::log::Target
 102
 103     \section config_timesource Log message timing
 104
 105     One auxiliary aspect of logging is message timing. Each message is stamped with a time-stamp
 106     giving the exact time the message was created. How the current date/time value is created may be
 107     changed by setting a \e TimeSource. A TimeSource is an instance derived from
 108     senf::log::TimeSource which will return the current universal time (UTC) when called.
 109
 110     By default, the logging library will call gettimeofday() for each log message. To change the
 111     time source, just pass the new class or instance to senf::log::timeSource:
 112     \code
 113     // Use senf::Scheduler::instance().eventTime() to time log messages
 114     senf::log::timeSource<senf::SchedulerLogTimeSource>();
 115     \endcode
 116  */
 117
 118 namespace senf {
 119 namespace log {
 120
 121     ///\ingroup config
 122     ///\{
 123
 124 #   ifdef DOXYGEN
 125
 126     /** \brief Compile time configuration
 127
 128         This define symbol sets the compile time logger configuration. This symbol should normally
 129         be set on the compiler command line.
 130
 131         The formal syntax of this option is:
 132
 133         \par ""
 134             <table class="ebnf">
 135             <tr><td>conf</td>         <td>::= \e element \e element* \n</td></tr>
 136             <tr><td>element</td>      <td>::= <tt>((</tt> \e stream <tt>,</tt> \e optional_area <tt>,</tt> \e level <tt>))</tt> \n</td></tr>
 137             <tr><td>stream</td>       <td>::= \e scope_seq \n</td></tr>
 138             <tr><td>optional_area</td><td>::= <tt>(_)</tt> | \e scope_seq \n</td></tr>
 139             <tr><td>level</td>        <td>::= \c VERBOSE | \c NOTICE | \c MESSAGE | \c IMPORTANT | \c CRITICAL | \c DISABLED \n</td></tr>
 140             <tr><td>scope_seq</td>    <td>::= \e scope \e scope \e scope* \n</td></tr>
 141             <tr><td>scope</td>        <td>::= <tt>(</tt> \e name <tt>)</tt> \n</td></tr>
 142             <tr><td>name</td>         <td>::= arbitrary C++ identifier</td></tr>
 143             </table>
 144
 145         \ref SENF_LOG_CONF is a Boost.Preprocessor style sequence of 3-tuples. Each tuple applies to
 146         a specific stream which is defined by the first tuple element \e stream.
 147
 148         The next tuple element, \e optional_area optionally restricts the entry to match only the
 149         given area.
 150
 151         The last tuple element \e level defines the compile time log level. Messages with a level
 152         below this are discarded at compile time.
 153
 154         Both \e stream and \e optional_area are given as a \e scope_seq. A scope sequence is a fully
 155         qualified C++ identifier placed into a sequence: <tt>foo::bar::baz</tt> is represented by
 156         <tt>(foo)(bar)(baz)</tt>.
 157      */
 158 #   define SENF_LOG_CONF
 159
 160 #   endif
 161
 162     /** \brief Check, if logging is enabled for stream/area/level tuple
 163
 164         This is a template meta-function which will check, whether logging to the given combination
 165         of parameters \a Stream, \a Area and \a Level is compile-time enabled. The logging might
 166         still be disabled at runtime.
 167         \code
 168         if (senf::log::Enabled<senf::log::Debug,
 169                                senf::log::DefaultArea,
 170                                senf::log::VERBOSE>::value) {
 171             // ...
 172         }
 173         \endcode
 174
 175         Since the \e value member is a compile time constant, the compiler will completely optimize
 176         away this block of code when logging is disabled.
 177      */
 178     template <class Stream, class Area, class Level>
 179     struct Enabled
 180     {
 181         static const bool value = (
 182             (Level::value == NONE::value ? Stream::defaultLevel::value : Level::value)
 183                 >= detail::Config<Stream,Area>::compileLimit::value );
 184     };
 185
 186     ///\}
 187
 188 }}
 189
 190 ///////////////////////////////hh.e////////////////////////////////////////
 191 //#include "Config.cci"
 192 //#include "Config.ct"
 193 //#include "Config.cti"
 194 #endif
 195
 196 \f
 197 // Local Variables:
 198 // mode: c++
 199 // fill-column: 100
 200 // comment-column: 40
 201 // c-file-style: "senf"
 202 // indent-tabs-mode: nil
 203 // ispell-local-dictionary: "american"
 204 // compile-command: "scons -u test"
 205 // End: