Utils/Logger/Mainpage.dox

   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 /** \mainpage The SENF Logging library
  24
  25     The Loggger infrastructure implements a highly flexible compile- and run-time configurable
  26     logging infrastructure supporting multiple streams, user definable log areas and fine grained
  27     log levels. Logging can be configured at compile and runtime on any combination of above
  28     parameters. The library supports a host of log targets and messages can be routed into multiple
  29     targets at the same time. To allow concise usage of the library, a utility to define logging
  30     defaults for any scope is provided.
  31
  32     An important basic concept of the library is, that most of the macros take a variable number of
  33     arguments. Since this is not supported in the needed manner by the C++ preprocessor, the
  34     arguments are encoded into a <a
  35     href="http://www.boost.org/libs/preprocessor/doc/index.html">Boost.Preprocessor</a> like
  36     sequence:
  37
  38     \code
  39     SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") );
  40     \endcode
  41
  42     The last sequence element always is the log message. Before that we have a number of log
  43     parameters <i>in arbitrary order</i>. Since giving all the parameters in every log message is to
  44     verbose, there are two helpful constructs to reduce the verbosity. Using \ref
  45     SENF_LOG_DEFAULT_STREAM, \ref SENF_LOG_DEFAULT_AREA and \ref SENF_LOG_DEFAULT_LEVEL it is
  46     possible to define the default logging parameters to be used within a given scope. Using \ref
  47     SENF_LOG_DEF_ALIAS you can define an alias (which is a scoped symbol) as an arbitrary
  48     combination of parameters.
  49
  50     \code
  51     SENF_LOG_DEF_STREAM( userLog, senf::log::MESSAGE, senf::log::MESSAGE );
  52
  53     class Froblizer
  54     {
  55         // Define a new log area
  56         SENF_LOG_DEF_AREA(FroblizerArea);
  57
  58         // Set default log parameters for this scope
  59         SENF_LOG_DEFAULTS((senf::log::Debug)(senf::log::NOTICE)(FroblizerArea));
  60
  61         // Define an alias for emergency messages to the sysadmin.
  62         // The log area is inherited from the default at the place, where this
  63         // alias is used *not* where it is defined
  64         SENF_LOG_DEF_ALIAS(LogEmerg, (userLog)(senf::log::CRITICAL));
  65
  66         void test();
  67
  68     public:
  69         void froblize();
  70     };
  71
  72     void Froblizer::froblize()
  73     {
  74         SENF_LOG(("This is the Debug stream at level NOTICE in the FroblizeArea"));
  75         SENF_LOG((senf::log::WARNING) ("Same stream and area but at warning level"));
  76         SENF_LOG((LogEmerg) ("This goes to the userLog at level CRITICAL in the FroblizerArea"));
  77     }
  78
  79     void Froblizer::test()
  80     {
  81         // Change the default log level for this method. stream and area are taken
  82         // from the next scope up
  83         SENF_LOG_DEFAULTS((senf::log::VERBOSE));
  84
  85         SENF_LOG(("Log to Debug stream in Froblizer area however at VERBOSE level"));
  86     }
  87     \endcode
  88
  89     Currently, the library is not implemented in any way. The interface has been defined up to a
  90     point and we have dummy implementations of the 'in-code' part of the interface. This is the
  91     part, which is called throughout the code. The configuration API is defined but we don't even
  92     have a template implementation. However, this allows starting to use the SENF Logger in newly
  93     developed code. Even though this code will unconditionally log everything to \c std::cerr for
  94     now and errors in the parameter specification will not be caught (since they are just ignored)
  95     the logging should work automatically as advertised as soon as the logger is completely
  96     implemented.
  97
  98     I did not find any implementation which was not either completely convoluted, unusable or
  99     slow. So I turned to a macro based implementation which can provide all the design goals stated
 100     above.
 101
 102     \section logger_compile_conf Compile time configuration
 103
 104     The logger infrastructure allows to enable or disable log levels or areas at compile
 105     time. Levels or areas disabled at compile time do not generate any code. The compile time
 106     configuration is done in two parts: When defining log streams, default log levels and log level
 107     limits are defined. Additionally the \c SENF_LOG_CONF symbol can be defined to customize this
 108     default configuration.
 109
 110     The \c SENF_LOG_CONF symbol is a Boost.Preprocessor style sequence of sequences:
 111     <pre>
 112     g++ ... -DSENF_LOG_CONF="((senf::log::Debug)(_)(DISABLED)) \
 113                              ((senf::log::Debug)(foo::FooArea)(VERBOSE))" ...
 114     </pre>
 115     Each element defines the compile time limit for a stream and optional area.
 116
 117     \implementation I would have much preferred a more C++ like implementation. However given the
 118     design goals
 119     \li Flexible configuration at compile and runtime
 120     \li Concise usage and simple interface
 121     \li Zero overhead for compile-time disabled log messages
 122  */
 123
 124 \f
 125 // Local Variables:
 126 // mode: c++
 127 // fill-column: 100
 128 // comment-column: 40
 129 // c-file-style: "senf"
 130 // indent-tabs-mode: nil
 131 // ispell-local-dictionary: "american"
 132 // compile-command: "scons -u test"
 133 // mode: flyspell
 134 // mode: auto-fill
 135 // End: