CTR Pia  4.11.3
Game Communication Engine
common_Log.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_Log.h
4 
5  Copyright Nintendo. All rights reserved.
6 
7  These coded instructions, statements, and computer programs contain
8  proprietary information of Nintendo of America Inc. and/or Nintendo
9  Company Ltd., and are protected by Federal copyright law. They may
10  not be disclosed to third parties or copied or duplicated in any form,
11  in whole or in part, without the prior written consent of Nintendo.
12  *---------------------------------------------------------------------------*/
13 
14 
15 #pragma once
16 
17 #include <pia/common/common_RootObject.h>
18 #include <pia/common/common_Time.h>
19 
20 namespace nn
21 {
22 namespace pia
23 {
24 namespace common
25 {
26 
27 
28 /*!
29  @brief This class is used for logging.
30 
31  @details You can set a level for the log and switch between
32  showing and hiding the log for each level.
33 
34  @date 2015-06-19 Added the <tt>PIA_LOG_EX()</tt> macro.
35  @date 2012-05-30 Times can now also be printed.
36  @date 2012-05-30 Made the <tt>Write()</tt> function private.
37  @date 2012-04-19 Initial version.
38 */
39 class Log : public RootObject
40 {
41 public:
42  // Specifies a bit mask representing the log level.
43  static const u32 LEVEL_DEBUG = 0x00000001 << 0; //!< Specifies the debug information level used inside Pia.
44  static const u32 LEVEL_INFO = 0x00000001 << 1; //!< Specifies the detailed information level used inside Pia.
45  static const u32 LEVEL_WARNING = 0x00000001 << 2; //!< Specifies the warning level. (This should be changed, but can be ignored.)
46  static const u32 LEVEL_ERROR = 0x00000001 << 3; //!< Specifies the error level (recoverable).
47  static const u32 LEVEL_FATAL = 0x00000001 << 4; //!< Specifies the error level (irrecoverable).
48  static const u32 LEVEL_ALWAYS = 0x00000001 << 5; //!< Specifies the log level that is constantly displayed.
49 
50  //n1589: Optimized code for checking <tt>IsFlagSet</tt>.
51 /*!
52  @cond PRIVATE
53 */
54  static bool IsFlagSetStatic(u64 flag)
55  {
56 #if NN_PIA_RELEASE
57  NN_PIA_DUMMY_PARAM_IN_RELEASE(flag);
58  return false;
59 #else
60  if (GetGlobalObject() == NULL)
61  {
62  return false;
63  }
64 
65  return GetGlobalObject()->IsFlagSet(flag);
66 #endif
67  }
68  //! @endcond
69 
70 /*!
71  @brief The constructor. Objects are constructed with all bits of the log level bit mask set to 1.
72 */
73  Log(void);
74 
75 /*!
76  @brief The constructor. A mask representing the log level can be specified as a parameter.
77 
78  @param[in] mask Specifies a bit mask representing the log level.
79 */
80  explicit Log(u32 mask);
81 
82 /*!
83  @brief The destructor.
84 */
85  ~Log();
86 
87 /*!
88  @brief Sets the mask. This allows you to suppress log messages of a particular level.
89 
90  @details This member function allows you to filter log information being output.
91  Note that a log for which <tt>LEVEL_ALWAYS</tt> has been specified is
92  always output regardless of the mask set by this member function.
93 
94  @param[in] mask Specifies a bit mask representing the log level.
95 */
96  void SetMask(u32 mask)
97  {
98  m_mask = mask;
99  }
100 
101 /*!
102  @brief Indicates whether the specified flags are set.
103 
104  @details The result of <tt>IsFlagSet(TRACE_FLAG_NEVER)</tt> is <tt>true</tt>.
105 
106  @return Returns <tt>true</tt> if the particular flag is set, or <tt>false</tt> otherwise.
107 
108  @param[in] flag Specifies the trace flags to query.
109 */
110  bool IsFlagSet(u64 flag) const
111  {
112 #if NN_PIA_RELEASE
113  NN_PIA_DUMMY_PARAM_IN_RELEASE(flag);
114  return false;
115 #else
116  return (m_mask & flag) == flag;
117 #endif
118  }
119 
120 /*!
121  @cond PRIVATE
122  @brief Writes text strings to the console. There is support for variable arguments.
123 
124  @param[in] mask Specifies a bit mask representing the log level.
125  @param[in] pStr Specifies a string having the same format as that used by the standard C library function <tt>printf</tt>.
126 */
127  void Write(u32 mask, const char* pStr, ...);
128  //! @endcond
129 
130 
131 /*!
132  @cond PRIVATE
133  @brief Writes caption text strings to the console.
134 
135  @param[in] mask Specifies a bit mask representing the log level.
136 */
137  void WriteCaption(u32 mask);
138  //! @endcond
139 
140 
141 /*!
142  @brief Enables and disables the time display.
143  @details When enabled, it displays the time passed from the base time in units of milliseconds, such as "[Pia:12345]..."
144  @param[in] isPrint Specify <tt>true</tt> to display the time.
145 */
146  void SetPrintTime(bool isPrint)
147  {
148  m_IsPrintTime = isPrint;
149  }
150 
151 
152 /*!
153  @brief Gets whether time display is enabled or disabled.
154  @return Returns <tt>true</tt> if times are printed.
155 */
156  bool IsPrintTime() const
157  {
158  return m_IsPrintTime;
159  }
160 
161 
162 /*!
163  @brief Resets the base time for the time display to the current time.
164 */
166  {
167  m_BaseTime.SetNow();
168  }
169 
170 
171 /*!
172  @brief Registers a global log object.
173 
174  @details This function registers the specified <tt>Log</tt> object as a global log object.
175  The <tt>PIA_LOG()</tt> macro outputs a log using the <tt>Log</tt> object registered by this function.
176 
177  @param[in] pLog Specifies a pointer to the <tt>Log</tt> object to be registered.
178 */
179  static void SetGlobalObject(Log* pLog)
180  {
181  s_pLog = pLog;
182  }
183 
184 /*!
185  @brief Gets a pointer to the <tt>Log</tt> object set using <tt>SetGlobalObject()</tt>.
186 
187  @details Calling <tt>nn::pia::common::Initialize()</tt> implicitly creates a <tt>Log</tt> instance
188  internally and sets this instance as the global log object.
189 
190  @return Returns a pointer to the instance registered as the global log object.
191 */
192  static Log* GetGlobalObject(void)
193  {
194  return s_pLog;
195  }
196 
197 
198 private:
199 /*!
200  @brief This copy constructor is private.
201 */
202  Log(const Log&);
203 
204 /*!
205  @brief This assignment operator is private.
206 */
207  Log& operator=(const Log&);
208 
209 
210  // The pointer indicating the global object.
211  static Log* s_pLog;
212 
213  // Mask settings are maintained for each <tt>Log</tt> instance.
214  u32 m_mask;
215 
216  Time m_BaseTime;
217  bool m_IsPrintTime;
218 };
219 
220 
221 /*!
222  @brief This macro is provided to output a simple log.
223 
224  @details This macro uses the <tt>Log</tt> object set as the global log object to output log information.
225  It automatically adds line headings and newline characters.
226 
227  @param[in] mask Specifies a bit mask representing the log.
228 */
229 #if NN_PIA_UNDER_DEVELOP
230 #define PIA_LOG(mask, ...) \
231  \
232 { \
233  nn::pia::common::Log* pPiaLog = nn::pia::common::Log::GetGlobalObject(); \
234  if (pPiaLog) \
235  { \
236  pPiaLog->WriteCaption(mask); \
237  pPiaLog->Write(mask, __VA_ARGS__); \
238  pPiaLog->Write(mask, "\n"); \
239  } \
240  \
241 }
242 #else
243 #define PIA_LOG(mask, ...) {}
244 #endif
245 
246 /*!
247  @brief This macro is provided to output a log including filenames and function names.
248 
249  @details This macro uses the <tt>Log</tt> object set as the global log object to output log information.
250  It automatically adds line headings and newline characters.
251 
252  @param[in] mask Specifies a bit mask representing the log.
253 */
254 #if NN_PIA_UNDER_DEVELOP
255 #define PIA_LOG_EX(mask, ...) \
256 { \
257  nn::pia::common::Log* pPiaLog = nn::pia::common::Log::GetGlobalObject(); \
258  if (pPiaLog) \
259  { \
260  pPiaLog->WriteCaption(mask); \
261  pPiaLog->Write(mask, "%s %s:", PIA_CODE_POSITION_FILE, PIA_CODE_POSITION_FUNC); \
262  pPiaLog->Write(mask, __VA_ARGS__); \
263  pPiaLog->Write(mask, "\n"); \
264  } \
265 }
266 #else
267 #define PIA_LOG_EX(mask, ...) {}
268 #endif
269 
270 
271 // Macro to collect <tt>return</tt> from <tt>Result</tt> and log outputs.
272 // The log level is constantly <tt>LEVEL_ERROR</tt>. Only pass <tt>Result</tt> values
273 // that are equivalent to programming errors to this macro.
274 // This macro only returns the result in the release build.
275 #if NN_PIA_UNDER_DEVELOP
276 #define PIA_RETURN_RESULT_WITH_LOG(result, ...) \
277 { \
278  nn::pia::common::Log* pPiaLog = nn::pia::common::Log::GetGlobalObject(); \
279  if (pPiaLog) \
280  { \
281  u32 logLevelError_ = nn::pia::common::Log::LEVEL_ERROR; \
282  pPiaLog->WriteCaption(logLevelError_); \
283  pPiaLog->Write(logLevelError_, "[%s] %s %s:", #result, PIA_CODE_POSITION_FILE, PIA_CODE_POSITION_FUNC); \
284  pPiaLog->Write(logLevelError_, __VA_ARGS__); \
285  pPiaLog->Write(logLevelError_, "\n"); \
286  } \
287  PIA_RETURN_RESULT(result); \
288 }
289 #else
290 #define PIA_RETURN_RESULT_WITH_LOG(result, ...) { return result(); }
291 #endif
292 
293 }
294 }
295 } // end of namespace nn::pia::common
static const u32 LEVEL_INFO
Specifies the detailed information level used inside Pia.
Definition: common_Log.h:44
static const u32 LEVEL_ALWAYS
Specifies the log level that is constantly displayed.
Definition: common_Log.h:48
This class is used for logging.
Definition: common_Log.h:39
Class that represents time.
Definition: common_Time.h:39
Definition: assert.h:115
bool IsPrintTime() const
Gets whether time display is enabled or disabled.
Definition: common_Log.h:156
Log(void)
The constructor. Objects are constructed with all bits of the log level bit mask set to 1...
static const u32 LEVEL_WARNING
Specifies the warning level. (This should be changed, but can be ignored.)
Definition: common_Log.h:45
~Log()
The destructor.
static void SetGlobalObject(Log *pLog)
Registers a global log object.
Definition: common_Log.h:179
static const u32 LEVEL_DEBUG
Specifies the debug information level used inside Pia.
Definition: common_Log.h:43
static const u32 LEVEL_FATAL
Specifies the error level (irrecoverable).
Definition: common_Log.h:47
void SetNow()
Makes this object represent the current time.
void SetMask(u32 mask)
Sets the mask. This allows you to suppress log messages of a particular level.
Definition: common_Log.h:96
void ResetBaseTime()
Resets the base time for the time display to the current time.
Definition: common_Log.h:165
void SetPrintTime(bool isPrint)
Enables and disables the time display.
Definition: common_Log.h:146
bool IsFlagSet(u64 flag) const
Indicates whether the specified flags are set.
Definition: common_Log.h:110
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40
static Log * GetGlobalObject(void)
Gets a pointer to the Log object set using SetGlobalObject().
Definition: common_Log.h:192
static const u32 LEVEL_ERROR
Specifies the error level (recoverable).
Definition: common_Log.h:46