HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
macros.h
Go to the documentation of this file.
1 // Copyright (c) Microsoft Corporation. All rights reserved.
2 // Licensed under the MIT License.
3 
4 #pragma once
5 // NOTE: Don't include this file directly. Include logging.h
6 
7 #define CREATE_MESSAGE(logger, severity, category, datatype) \
8  ::onnxruntime::logging::Capture(logger, ::onnxruntime::logging::Severity::k##severity, category, datatype, ORT_WHERE)
9 
10 /*
11  Both printf and stream style logging are supported.
12  Not that printf currently has a 2K limit to the message size.
13 
14  LOGS_* macros are for stream style
15  LOGF_* macros are for printf style
16 
17  The Message class captures the log input, and pushes it through the logger in its destructor.
18 
19  Use the *FATAL* macros if you want a Severity::kFatal message to also throw.
20 
21  There are a few variants to minimize the length of the macro name required in the calling code.
22  They are optimized so the shortest names are for the (expected) most common usage. This can be
23  tweaked if needed.
24 
25  Explicit logger vs LoggingManager::DefaulLogger()
26  Default is for a logger instance to be explicitly passed in.
27  The logger instance provides an identifier so that log messages from different runs can be separated.
28 
29  Variants with DEFAULT in the macro name use the default logger provided by logging manager. This is
30  static so accessible from any code, provided a LoggingManager instance created with InstanceType::Default
31  exists somewhere. See logging.h for further explanation of the expected setup.
32 
33  DataType
34  Default uses DataType::SYSTEM.
35 
36  Variants with USER in the macro name use DataType::USER. This is data that could be PII, and may need to
37  be filtered from output. LoggingManager applies this filtering.
38 
39  Category
40  Default category is ::onnxruntime::Logging::Category::onnxruntime.
41 
42  If you wish to provide a different category, use variants with CATEGORY in the macro name
43 
44 */
45 
46 /**
47  * Note:
48  * The stream style logging macros (something like `LOGS() << message`) are designed to be appended to.
49  * Normally, we can isolate macro code in a separate scope (e.g., `do {...} while(0)`), but here we need the macro code
50  * to interact with subsequent code (i.e., the values to log).
51  *
52  * When an unisolated conditional is involved, extra care needs to be taken to avoid unexpected parsing behavior.
53  * For example:
54  *
55  * if (enabled)
56  * Capture().Stream()
57  *
58  * is more direct, but
59  *
60  * if (!enabled) {
61  * } else Capture().Stream()
62  *
63  * ensures that the `if` does not unintentionally associate with a subsequent `else`.
64  */
65 
66 // Logging with explicit category
67 
68 // iostream style logging. Capture log info in Message, and push to the logger in ~Message.
69 #define LOGS_CATEGORY(logger, severity, category) \
70  if (!(logger).OutputIsEnabled(::onnxruntime::logging::Severity::k##severity, \
71  ::onnxruntime::logging::DataType::SYSTEM)) { \
72  /* do nothing */ \
73  } else \
74  CREATE_MESSAGE(logger, severity, category, ::onnxruntime::logging::DataType::SYSTEM).Stream()
75 
76 #define LOGS_USER_CATEGORY(logger, severity, category) \
77  if (!(logger).OutputIsEnabled(::onnxruntime::logging::Severity::k##severity, \
78  ::onnxruntime::logging::DataType::USER)) { \
79  /* do nothing */ \
80  } else \
81  CREATE_MESSAGE(logger, severity, category, ::onnxruntime::logging::DataType::USER).Stream()
82 
83 // printf style logging. Capture log info in Message, and push to the logger in ~Message.
84 #define LOGF_CATEGORY(logger, severity, category, format_str, ...) \
85  do { \
86  if ((logger).OutputIsEnabled(::onnxruntime::logging::Severity::k##severity, \
87  ::onnxruntime::logging::DataType::SYSTEM)) \
88  CREATE_MESSAGE(logger, severity, category, ::onnxruntime::logging::DataType::SYSTEM) \
89  .CapturePrintf(format_str, ##__VA_ARGS__); \
90  } while (0)
91 
92 #define LOGF_USER_CATEGORY(logger, severity, category, format_str, ...) \
93  do { \
94  if ((logger).OutputIsEnabled(::onnxruntime::logging::Severity::k##severity, \
95  ::onnxruntime::logging::DataType::USER)) \
96  CREATE_MESSAGE(logger, severity, category, ::onnxruntime::logging::DataType::USER) \
97  .CapturePrintf(format_str, ##__VA_ARGS__); \
98  } while (0)
99 
100 // Logging with category of "onnxruntime"
101 
102 #define LOGS(logger, severity) \
103  LOGS_CATEGORY(logger, severity, ::onnxruntime::logging::Category::onnxruntime)
104 
105 #define LOGS_USER(logger, severity) \
106  LOGS_USER_CATEGORY(logger, severity, ::onnxruntime::logging::Category::onnxruntime)
107 
108 // printf style logging. Capture log info in Message, and push to the logger in ~Message.
109 #define LOGF(logger, severity, format_str, ...) \
110  LOGF_CATEGORY(logger, severity, ::onnxruntime::logging::Category::onnxruntime, format_str, ##__VA_ARGS__)
111 
112 #define LOGF_USER(logger, severity, format_str, ...) \
113  LOGF_USER_CATEGORY(logger, severity, ::onnxruntime::logging::Category::onnxruntime, format_str, ##__VA_ARGS__)
114 
115 /*
116  Macros that use the default logger.
117  A LoggingManager instance must be currently valid for the default logger to be available.
118 */
119 
120 // Logging with explicit category
121 
122 #define LOGS_DEFAULT_CATEGORY(severity, category) \
123  LOGS_CATEGORY(::onnxruntime::logging::LoggingManager::DefaultLogger(), severity, category)
124 
125 #define LOGS_USER_DEFAULT_CATEGORY(severity, category) \
126  LOGS_USER_CATEGORY(::onnxruntime::logging::LoggingManager::DefaultLogger(), severity, category)
127 
128 #define LOGF_DEFAULT_CATEGORY(severity, category, format_str, ...) \
129  LOGF_CATEGORY(::onnxruntime::logging::LoggingManager::DefaultLogger(), severity, category, format_str, ##__VA_ARGS__)
130 
131 #define LOGF_USER_DEFAULT_CATEGORY(severity, category, format_str, ...) \
132  LOGF_USER_CATEGORY(::onnxruntime::logging::LoggingManager::DefaultLogger(), severity, category, format_str, ##__VA_ARGS__)
133 
134 // Logging with category of "onnxruntime"
135 
136 #define LOGS_DEFAULT(severity) \
137  LOGS_DEFAULT_CATEGORY(severity, ::onnxruntime::logging::Category::onnxruntime)
138 
139 #define LOGS_USER_DEFAULT(severity) \
140  LOGS_USER_DEFAULT_CATEGORY(severity, ::onnxruntime::logging::Category::onnxruntime)
141 
142 #define LOGF_DEFAULT(severity, format_str, ...) \
143  LOGF_DEFAULT_CATEGORY(severity, ::onnxruntime::logging::Category::onnxruntime, format_str, ##__VA_ARGS__)
144 
145 #define LOGF_USER_DEFAULT(severity, format_str, ...) \
146  LOGF_USER_DEFAULT_CATEGORY(severity, ::onnxruntime::logging::Category::onnxruntime, format_str, ##__VA_ARGS__)
147 
148 /*
149  Conditional logging
150 */
151 
152 // Logging with explicit category
153 
154 #define LOGS_CATEGORY_IF(boolean_expression, logger, severity, category) \
155  if (!((boolean_expression) == true)) { \
156  /* do nothing */ \
157  } else \
158  LOGS_CATEGORY(logger, severity, category)
159 
160 #define LOGS_DEFAULT_CATEGORY_IF(boolean_expression, severity, category) \
161  if (!((boolean_expression) == true)) { \
162  /* do nothing */ \
163  } else \
164  LOGS_DEFAULT_CATEGORY(severity, category)
165 
166 #define LOGS_USER_CATEGORY_IF(boolean_expression, logger, severity, category) \
167  if (!((boolean_expression) == true)) { \
168  /* do nothing */ \
169  } else \
170  LOGS_USER_CATEGORY(logger, severity, category)
171 
172 #define LOGS_USER_DEFAULT_CATEGORY_IF(boolean_expression, severity, category) \
173  if (!((boolean_expression) == true)) { \
174  /* do nothing */ \
175  } else \
176  LOGS_USER_DEFAULT_CATEGORY(severity, category)
177 
178 #define LOGF_CATEGORY_IF(boolean_expression, logger, severity, category, format_str, ...) \
179  do { \
180  if ((boolean_expression) == true) LOGF_CATEGORY(logger, severity, category, format_str, ##__VA_ARGS__); \
181  } while (0)
182 
183 #define LOGF_DEFAULT_CATEGORY_IF(boolean_expression, severity, category, format_str, ...) \
184  do { \
185  if ((boolean_expression) == true) LOGF_DEFAULT_CATEGORY(severity, category, format_str, ##__VA_ARGS__); \
186  } while (0)
187 
188 #define LOGF_USER_CATEGORY_IF(boolean_expression, logger, severity, category, format_str, ...) \
189  do { \
190  if ((boolean_expression) == true) LOGF_USER_CATEGORY(logger, severity, category, format_str, ##__VA_ARGS__); \
191  } while (0)
192 
193 #define LOGF_USER_DEFAULT_CATEGORY_IF(boolean_expression, severity, category, format_str, ...) \
194  do { \
195  if ((boolean_expression) == true) LOGF_USER_DEFAULT_CATEGORY(severity, category, format_str, ##__VA_ARGS__); \
196  } while (0)
197 
198 // Logging with category of "onnxruntime"
199 
200 #define LOGS_IF(boolean_expression, logger, severity) \
201  LOGS_CATEGORY_IF(boolean_expression, logger, severity, ::onnxruntime::logging::Category::onnxruntime)
202 
203 #define LOGS_DEFAULT_IF(boolean_expression, severity) \
204  LOGS_DEFAULT_CATEGORY_IF(boolean_expression, severity, ::onnxruntime::logging::Category::onnxruntime)
205 
206 #define LOGS_USER_IF(boolean_expression, logger, severity) \
207  LOGS_USER_CATEGORY_IF(boolean_expression, logger, severity, ::onnxruntime::logging::Category::onnxruntime)
208 
209 #define LOGS_USER_DEFAULT_IF(boolean_expression, severity) \
210  LOGS_USER_DEFAULT_CATEGORY_IF(boolean_expression, severity, ::onnxruntime::logging::Category::onnxruntime)
211 
212 #define LOGF_IF(boolean_expression, logger, severity, format_str, ...) \
213  LOGF_CATEGORY_IF(boolean_expression, logger, severity, ::onnxruntime::logging::Category::onnxruntime, format_str, ##__VA_ARGS__)
214 
215 #define LOGF_DEFAULT_IF(boolean_expression, severity, format_str, ...) \
216  LOGF_DEFAULT_CATEGORY_IF(boolean_expression, severity, ::onnxruntime::logging::Category::onnxruntime, format_str, ##__VA_ARGS__)
217 
218 #define LOGF_USER_IF(boolean_expression, logger, severity, format_str, ...) \
219  LOGF_USER_CATEGORY_IF(boolean_expression, logger, severity, ::onnxruntime::logging::Category::onnxruntime, \
220  format_str, ##__VA_ARGS__)
221 
222 #define LOGF_USER_DEFAULT_IF(boolean_expression, severity, format_str, ...) \
223  LOGF_USER_DEFAULT_CATEGORY_IF(boolean_expression, severity, ::onnxruntime::logging::Category::onnxruntime, \
224  format_str, ##__VA_ARGS__)
225 
226 /*
227  Debug verbose logging of caller provided level.
228  Disabled in Release builds.
229  Use the _USER variants for VLOG statements involving user data that may need to be filtered.
230 */
231 #ifndef NDEBUG
232 #define VLOGS(logger, level) \
233  if (!(::onnxruntime::logging::vlog_enabled && level <= (logger).VLOGMaxLevel())) { \
234  /* do nothing */ \
235  } else \
236  LOGS_CATEGORY(logger, VERBOSE, "VLOG" #level)
237 
238 #define VLOGS_USER(logger, level) \
239  if (!(::onnxruntime::logging::vlog_enabled && level <= (logger).VLOGMaxLevel())) { \
240  /* do nothing */ \
241  } else \
242  LOGS_USER_CATEGORY(logger, VERBOSE, "VLOG" #level)
243 
244 #define VLOGF(logger, level, format_str, ...) \
245  do { \
246  if (::onnxruntime::logging::vlog_enabled && level <= (logger).VLOGMaxLevel()) \
247  LOGF_CATEGORY(logger, VERBOSE, "VLOG" #level, format_str, ##__VA_ARGS__); \
248  } while (0)
249 
250 #define VLOGF_USER(logger, level, format_str, ...) \
251  do { \
252  if (::onnxruntime::logging::vlog_enabled && level <= (logger).VLOGMaxLevel()) \
253  LOGF_USER_CATEGORY(logger, VERBOSE, "VLOG" #level, format_str, ##__VA_ARGS__); \
254  } while (0)
255 #else
256 // Disabled in Release builds.
257 #define VLOGS(logger, level) \
258  if constexpr (true) { \
259  } else \
260  LOGS_CATEGORY(logger, VERBOSE, "VLOG" #level)
261 #define VLOGS_USER(logger, level) \
262  if constexpr (true) { \
263  } else \
264  LOGS_USER_CATEGORY(logger, VERBOSE, "VLOG" #level)
265 #define VLOGF(logger, level, format_str, ...)
266 #define VLOGF_USER(logger, level, format_str, ...)
267 #endif
268 
269 // Default logger variants
270 #define VLOGS_DEFAULT(level) \
271  VLOGS(::onnxruntime::logging::LoggingManager::DefaultLogger(), level)
272 
273 #define VLOGS_USER_DEFAULT(level) \
274  VLOGS_USER(::onnxruntime::logging::LoggingManager::DefaultLogger(), level)
275 
276 #define VLOGF_DEFAULT(level, format_str, ...) \
277  VLOGF(::onnxruntime::logging::LoggingManager::DefaultLogger(), level, format_str, ##__VA_ARGS__)
278 
279 #define VLOGF_USER_DEFAULT(level, format_str, ...) \
280  VLOGF_USER(::onnxruntime::logging::LoggingManager::DefaultLogger(), level, format_str, ##__VA_ARGS__)