iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Log.H
Go to the documentation of this file.
1 /*! @file
2  @author Laurent Itti
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 #ifndef INCLUDE_NRT_CORE_DEBUGGING_LOG_H
36 #define INCLUDE_NRT_CORE_DEBUGGING_LOG_H
37 
38 #include <nrt/config.h>
41 
42 namespace nrt
43 {
44  class Component;
45 
46  //! Current log level, default is 6 (LOG_INFO)
47  /*! The log level is set by changing the value of this global variable. The default value is LOG_WARNING=4, and other
48  valid values include LOG_INFO=6, LOG_DEBUG=7, LOG_BBDEBUG=8. To change the log level, one would simply write, for
49  example in your main function:
50  \code
51  currentLogLevel = 7; // switch to verbose LOG_DEBUG log level
52  \endcode
53 
54  \ingroup logging */
55  extern int currentLogLevel;
56 }
57 
58 /*! \defgroup debugging Debugging support functions and facilities
59 
60  Provides support for logging, CPU time measurement, profiling, etc
61 
62  \ingroup core */
63 
64 
65 /*! \defgroup logging Logging and error/information message facility
66 
67  Logging functions provide facilities o very easily issue messages to the console or other stream. These messages can
68  inform the user or can be used during code development for debugging purposes.
69 
70  \ingroup debugging */
71 
72 /*! @{ */ // **********************************************************************
73 
74 
75 //! Global shadow variable for log messages issued outside of nrt::Component objects
76 /*! This global variable is only necessary to perform some trickery with the above logging functions. If any of these
77  logging functions are called from within a Component, there is a public member Component* called
78  nrt_component_this that will be passed into the GenericLog constructor. If the logging functions are called from
79  outside of a Component, then this global nrt_component_this will be in scope, and will be inserted instead. */
80 extern nrt::Component * const nrt_component_this;
81 
82 //! Convenience macro for users to print out console messages, DEBUG level
83 /*! \def NRT_DEBUG(msg)
84  \hideinitializer
85 
86  This macro is intended to be used with a stream-oriented syntax for everything that is passed as argument to the
87  macro. The syntax is a bit strange at first but you will rapidly get used to it. This allows any datatype that has
88  an operator<< defined to be printed out in a log (contrary to printf-style syntax). For example:
89 
90  @code
91  int x = 3; std::string str = "hello"; nrt::Rectangle<int> rect;
92  NRT_DEBUG("x=" << x << " and str=" << str << " and rect=" << rect);
93  @endcode
94 
95  \note This is the preferred way to issue messages in NRT. Do you use printf, do not use cout<<"blah", etc.
96 
97  By design, your log message will not be evaluated if the current log level is below (stronger) than the debug
98  level. This means that you should not be afraid of wasting CPU computing messages that will not be output; for
99  example:
100 
101  @code
102  NRT_DEBUG("CPU-intensive function says: " << cpu_intensive_function());
103  @endcode
104 
105  will not run the cpu-intensive function if the current log level is warning. This also means that you should never
106  assume that your log message will be evaluated. For example:
107 
108  @code
109  int x = 42;
110  NRT_DEBUG("x = " << (x++) );
111  // x may now be 43 or 42 depending on current log level...
112  @endcode */
113 #define NRT_DEBUG(msg) do { if (nrt::currentLogLevel >= nrt::DebugLevelPolicy::level) \
114  { nrt::GenericLog<nrt::DebugLevelPolicy>(__FILE__, __FUNCTION__, nrt_component_this) << msg; } } while(false)
115 
116 //! Convenience macro for users to print out console messages, INFO level
117 /*! \def NRT_INFO(msg)
118  \hideinitializer
119 
120  Usage syntax is the same as for #NRT_DEBUG(msg) */
121 #define NRT_INFO(msg) do { if (nrt::currentLogLevel >= nrt::InfoLevelPolicy::level) \
122  { nrt::GenericLog<nrt::InfoLevelPolicy> (__FILE__, __FUNCTION__, nrt_component_this) << msg; } } while(false)
123 
124 //! Convenience macro for users to print out console messages, WARNING level
125 /*! \def NRT_WARNING(msg)
126  \hideinitializer
127 
128  Usage syntax is the same as for #NRT_DEBUG(msg) */
129 #define NRT_WARNING(msg) do { if (nrt::currentLogLevel >= nrt::WarnLevelPolicy::level) \
130  { nrt::GenericLog<nrt::WarnLevelPolicy> (__FILE__, __FUNCTION__, nrt_component_this) << msg; } } while(false)
131 
132 //! Convenience macro for users to print out console messages, FATAL level
133 /*! \def NRT_FATAL(msg)
134  \hideinitializer
135 
136  Usage syntax is the same as for #NRT_DEBUG(msg)
137  \note After printing the message, this also throws nrt::exception::FatalException */
138 #define NRT_FATAL(msg) do { if (nrt::currentLogLevel >= nrt::FatalLevelPolicy::level) \
139  { nrt::GenericLog<nrt::FatalLevelPolicy>(__FILE__, __FUNCTION__, nrt_component_this) << msg; } } while(false)
140 
141 
142 //! Convenience macro to print out a log message using printf syntax, DEBUG level
143 /*! \def NRT_FMT_DEBUG(FORMAT, ...)
144  \hideinitializer
145 
146  This macro behaves like printf, for example:
147 
148  @code
149  int x = 3; float y = 2.0F;
150  NRT_FMT_DEBUG("x=%d and y=%f", x, y);
151  @endcode
152 
153  \note In general, #NRT_DEBUG(msg) is preferred as it can handle any C++ type that has a conversion to string, as
154  opposed to only the few POD types supported by the printf syntax. */
155 #define NRT_FMT_DEBUG(FORMAT, ...) \
156  NRT_DEBUG(nrt::sformat(FORMAT,##__VA_ARGS__))
157 
158 //! Convenience macro to print out a log message using printf syntax, INFO level
159 /*! \def NRT_FMT_INFO(FORMAT, ...)
160  \hideinitializer
161 
162  Usage syntax is the same as for #NRT_FMT_DEBUG(FORMAT, ...) */
163 #define NRT_FMT_INFO(FORMAT, ...) \
164  NRT_INFO(nrt::sformat(FORMAT,##__VA_ARGS__))
165 
166 //! Convenience macro to print out a log message using printf syntax, WARNING level
167 /*! \def NRT_FMT_WARNING(FORMAT, ...)
168  \hideinitializer
169 
170  Usage syntax is the same as for #NRT_FMT_DEBUG(FORMAT, ...) */
171 #define NRT_FMT_WARNING(FORMAT, ...) \
172  NRT_WARNING(nrt::sformat(FORMAT,##__VA_ARGS__))
173 
174 //! Convenience macro to print out a log message using printf syntax, FATAL level
175 /*! \def NRT_FMT_FATAL(FORMAT, ...)
176  \hideinitializer
177 
178  Usage syntax is the same as for #NRT_FMT_DEBUG(FORMAT, ...)
179  \note After printing the message, this also throws nrt::exception::FatalException */
180 #define NRT_FMT_FATAL(FORMAT,...) \
181  NRT_FATAL(nrt::sformat(FORMAT,##__VA_ARGS__))
182 
183 //! Debugging macro use internally by core model-related code
184 /*! \def NRT_MODDEBUG(msg)
185 
186  To see debug messages that are internal to Model Component/Parameter operations, define NRT_MODDEBUG to not be
187  commented out. You need to clean and recompile everything for and change in the definition to take effect. \note
188  Only people writing core Model-related code should use NRT_MODDEBUG(), all others use NRT_DEBUG(msg). */
189 //#define NRT_MODDEBUG(msg) /* */
190 #define NRT_MODDEBUG(msg) do { if (nrt::currentLogLevel >= nrt::BBDebugLevelPolicy::level) \
191  { nrt::GenericLog<nrt::BBDebugLevelPolicy>(__FILE__, __FUNCTION__, nrt_component_this) << msg; } } while(false)
192 
193 //! Debugging macro used internally by core blackboard-related code
194 /*! \def NRT_BBDEBUG(msg)
195 
196  To see debug messages that are internal to the Blackboard's operation, define NRT_BBDEBUG to not be commented out.
197  You need to clean and recompile everything for and change in the definition to take effect. \note Only people
198  writing core Blackboard-related code should use NRT_BBDEBUG(), all others use NRT_DEBUG(msg). */
199 //#define NRT_BBDEBUG(msg) /* */
200 #define NRT_BBDEBUG(msg) do { if (nrt::currentLogLevel >= nrt::BBDebugLevelPolicy::level) \
201  { nrt::GenericLog<nrt::BBDebugLevelPolicy>(__FILE__, __FUNCTION__, nrt_component_this) << msg; } } while(false)
202 
203 /*! @} */ // **********************************************************************
204 
205 #endif // INCLUDE_NRT_CORE_DEBUGGING_LOG_H