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     \see
  33         \ref logging \n
  34         \ref config \n
  35
  36     \section logging_tutorial Tutorial introduction
  37
  38     Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
  39     some other helpers used to simplify specifying parameters.
  40
  41     \code
  42     namespace foo {
  43
  44         // Define a new log stream with default level, runtime limit and compile time limit
  45         // set to senf::log::MESSAGE
  46         SENF_LOG_DEF_STREAM( UserLog, senf::log::MESSAAGE, senf::log::MESSAGE, senf::log::MESSAGE );
  47
  48         class Froblizer
  49         {
  50             // Define a log area which will automatically be used by all members of this class.
  51             // This is a combination of SENF_LOG_DEF_AREA and SENF_LOG_DEFAULT_AREA.
  52             SENF_LOG_CLASS_AREA();
  53
  54             // Set default log parameters for this scope. The values here are not really
  55             // necessary since these are the global default values
  56             SENF_LOG_DEFAULT_STREAM(foo::UserLog);
  57             SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
  58
  59             // Define an alias for emergency debug messages
  60             // The log area is inherited from the default at the place, where this
  61             // alias is used *not* where it is defined
  62             SENF_LOG_DEF_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
  63
  64             void test();
  65
  66         public:
  67             void froblize();
  68         };
  69     }
  70
  71     void foo::Froblizer::froblize()
  72     {
  73         SENF_LOG(("This is the UserLog at level NOTICE in the FroblizeArea"));
  74         SENF_LOG((senf::log::WARNING) ("Same stream and area but at warning level"));
  75         SENF_LOG((LogEmerg) ("This goes to the DebugLog at level CRITICAL in the FroblizerArea"));
  76     }
  77
  78     void foo::Froblizer::test()
  79     {
  80         // Change the default log level for this method. stream and area are taken
  81         // from the next scope up
  82         SENF_LOG_DEFAULT_LEVEL(senf::log::VERBOSE);
  83
  84         SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
  85     }
  86     \endcode
  87
  88     \implementation I would have much preferred a more C++ like implementation. However given the
  89         design goals
  90         \li Flexible configuration at compile and runtime
  91         \li Concise usage and simple interface
  92         \li Zero overhead for compile-time disabled log messages I did not find any non-mcaro
  93         implementation which was not either completely convoluted, unusable or slow. So I turned to
  94         a macro based implementation which can provide all the design goals stated above.
  95  */
  96
  97 \f
  98 // Local Variables:
  99 // mode: c++
 100 // fill-column: 100
 101 // comment-column: 40
 102 // c-file-style: "senf"
 103 // indent-tabs-mode: nil
 104 // ispell-local-dictionary: "american"
 105 // compile-command: "scons -u test"
 106 // mode: flyspell
 107 // mode: auto-fill
 108 // End: