Skip to content
Navigation Menu
{{ message }}
forked from DFHack/dfhack
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathDebug.h
More file actions
373 lines (338 loc) · 13.1 KB
/
Copy pathDebug.h
File metadata and controls
373 lines (338 loc) · 13.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
/**
Copyright © 2018 Pauli <suokkos\gmail.com>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any
damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim that you wrote the original software. If you use this
software in a product, an acknowledgment in the product
documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and
must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source
distribution.
*/
#pragma once
#include "ColorText.h"
#include <atomic>
#include "Core.h"
namespace DFHack {
/*! \file Debug.h
* Light weight wrappers for runtime debug output filtering. The idea is to add
* as little as possible code compared to debug output without filtering. The
* effect is archived using #TRACE, #DEBUG, #INFO, #WARN and #ERR macros. They
* "return" color_ostream object or reference that can be then used normally for
* either printf or stream style debug output.
*
* Internally macros do inline filtering check which allows compiler to have a
* fast path when output is disabled. However, if output is enabled then
* parameters are evaluated and the printing function is called. The macro setup
* code will also print a standard header for each log message, including
* timestamp, plugin name, and category name.
*
* \code{.cpp}
* #include "Debug.h"
* DBG_DECLARE(myplugin,init);
*
* DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
* {
* command_result rv = CR_OK;
* DEBUG(init, out).print("initializing\n")
* if ((rv = initWork()) != CR_OK) {
* ERR(init, out) << "initWork failed with "
* << rv << " error code" << std::endl;
* return rv;
* }
* return rv
* }
* \endcode
*
* The debug print filtering levels can be changed using a debugger. The
* following gdb example will automatically setup core/init and core/render to
* trace level when SDL_init is called.
*
* \code{.unparsed}
* break SDL_init
* commands
* silent
* p DFHack::debug::core::debug_init.allowed_ = 0
* p DFHack::debug::core::debug_render.allowed_ = 0
* c
* end
* \endcode
*
*/
#ifndef __has_cpp_attribute
#define __has_cpp_attribute(x) 0
#endif
/*!
* \defgroup debug_branch_prediction Branch prediction helper macros
* Helper macro tells compiler that debug output branch is unlikely and should
* be optimized to cold section of the function.
* \{
*/
#if __cplusplus >= 202000L || __has_cpp_attribute(likely)
// c++20 will have standard branch prediction hint attributes
#define likely(x) (x) [[likely]]
#define unlikely(x) (x) [[unlikely]]
#elif defined(__GNUC__)
// gcc has builtin functions that give hints to the branch prediction
#define likely(x) (__builtin_expect(!!(x), 1))
#define unlikely(x) (__builtin_expect(!!(x), 0))
#else
#define likely(x) (x)
#define unlikely(x) (x)
#endif
//! \}
#ifdef NDEBUG
/*!
* This is here so we can reduce minimum compiled in debug levels if NDEBUG is
* defined if we want to. If LTRACE slows down the binary, we can change it to
* LDEBUG (but no lower than that so users can usefully increase logging levels
*for bug reports).
*/
#define DBG_FILTER DFHack::DebugCategory::LTRACE
#else
//! Set default compiled in debug levels to include all prints
#define DBG_FILTER DFHack::DebugCategory::LTRACE
#endif
/*!
* DebugCategory is used to enable and disable debug messages in runtime.
* Declaration and definition are handled by #DBG_DECLARE and #DBG_DEFINE
* macros. Runtime filtering support is handled by #TRACE, #DEBUG, #INFO, #WARN
* and #ERR macros.
*/
class DFHACK_EXPORT DebugCategory final {
public:
//! type helper to maybe make it easier to convert to std::string_view when
//! c++17 can be required.
using cstring = const char*;
using cstring_ref = const char*;
/*!
* Debug level enum for message filtering
*/
enum level {
LTRACE = 0,
LDEBUG = 1,
LINFO = 2,
LWARNING = 3,
LERROR = 4,
};
/*!
* \param plugin the name of plugin the category belongs to
* \param category the name of category
* \param defaultLevel optional default filtering level for the category
*/
constexpr DebugCategory(cstring_ref plugin,
cstring_ref category,
level defaultLevel = LWARNING) noexcept :
plugin_{plugin},
category_{category},
allowed_{defaultLevel}
{}
DebugCategory(const DebugCategory&) = delete;
DebugCategory(DebugCategory&&) = delete;
DebugCategory& operator=(DebugCategory) = delete;
DebugCategory& operator=(DebugCategory&&) = delete;
/*!
* Used by debug macros to check if message should be printed.
*
* It is defined in the header to allow compiler inline it and make disabled
* state a fast path without function calls.
*
* \param msgLevel the debug message level the following print belongs to
* \return boolean with true indicating that message should be printed
*/
bool isEnabled(const level msgLevel) const noexcept {
const uint32_t intLevel = static_cast<uint32_t>(msgLevel);
// Compile time filtering to allow compiling out debug checks prints
// from binary.
return static_cast<uint32_t>(DBG_FILTER) <= intLevel &&
// Runtime filtering for debug messages
static_cast<uint32_t>(allowed_.load(std::memory_order_relaxed)) <= intLevel;
}
struct DFHACK_EXPORT ostream_proxy_prefix : public color_ostream_proxy {
ostream_proxy_prefix(const DebugCategory& cat,
color_ostream& target,
DebugCategory::level level);
~ostream_proxy_prefix() {
flush();
}
};
/*!
* Fetch a steam object proxy object for output. It also adds standard
* message components like time and plugin and category names to the line.
*
* User must make sure that the line is terminated with a line end.
*
* \param msgLevel Specifies the level which next debug message belongs
* \return color_ostream_proxy that can be used to print the message
* \sa DFHack::Core::getConsole()
*/
ostream_proxy_prefix getStream(const level msgLevel) const
{
return {*this,Core::getInstance().getConsole(),msgLevel};
}
/*!
* Add standard message components to existing output stream object to begin
* a new message line to an shared buffered object.
*
* \param msgLevel Specifies the level which next debug message belongs
* \param target An output stream object where a debug output is printed
* \return color_ostream reference that was passed as second parameter
*/
ostream_proxy_prefix getStream(const level msgLevel, color_ostream& target) const
{
return {*this,target,msgLevel};
}
/*!
* \brief Allow management code to set a new filtering level
* Caller must have locked DebugManager::access_mutex_.
*/
void allowed(level value) noexcept;
//! Query current filtering level
level allowed() const noexcept;
//! Query plugin name
cstring_ref plugin() const noexcept;
//! Query category name
cstring_ref category() const noexcept;
private:
cstring plugin_;
cstring category_;
std::atomic<level> allowed_;
#if __cplusplus >= 201703L || __cpp_lib_atomic_is_always_lock_free >= 201603
static_assert(std::atomic<level>::is_always_lock_free,
"std::atomic<level> should be lock free. You are using a very old CPU or code needs to use std::atomic<int>");
#endif
};
/**
* Handle actual registering wrong template parameter generated pointer
* calculation.
*/
class DFHACK_EXPORT DebugRegisterBase {
protected:
DebugRegisterBase(DebugCategory* category);
void unregister(DebugCategory* category);
};
/**
* Register DebugCategory to DebugManager
*/
template<DebugCategory* category>
class DebugRegister final : public DebugRegisterBase {
public:
DebugRegister() :
DebugRegisterBase{category}
{}
~DebugRegister() {
unregister(category);
}
};
#define DBG_NAME(category) debug_ ## category
/*!
* Declares a debug category. There must be only one declaration per category.
* Declaration should be in same plugin where it is used. If same category name
* is used in core and multiple plugins they all are changed with same command
* unless user explicitly specifies a plugin name.
*
* Must be used in one translation unit only.
*
* \param plugin the name of plugin where debug category is used
* \param category the name of category
* \param level the initial DebugCategory::level filtering level.
*/
#define DBG_DECLARE(plugin,category, ...) \
namespace debug { namespace plugin { \
DebugCategory DBG_NAME(category){#plugin,#category,__VA_ARGS__}; \
DebugRegister<&DBG_NAME(category)> register_ ## category; \
} } \
using debug::plugin::DBG_NAME(category)
/*!
* Can be used to access a shared DBG_DECLARE category. But may not be used from
* static initializer because translation unit order is undefined.
*
* Can be used in shared headers to gain access to one definition from
* DBG_DECLARE.
* \param plugin The plugin name that must match DBG_DECLARE
* \param category The category name that must matnch DBG_DECLARE
*/
#define DBG_EXTERN(plugin,category) \
namespace debug { namespace plugin { \
extern DFHack::DebugCategory DBG_NAME(category); \
} } \
using debug::plugin::DBG_NAME(category)
#define DBG_PRINT(category,pred,level,...) \
if pred(!DFHack::DBG_NAME(category).isEnabled(level)) \
; /* nop fast path when debug category is disabled */ \
else /* else to allow macro use in if-else branches */ \
DFHack::DBG_NAME(category).getStream(level, ## __VA_ARGS__) \
/* end of DBG_PRINT */
/*!
* Open a line for trace level debug output if enabled
*
* Preferred category for inside loop debug messages or callbacks/methods called
* multiple times per second. Good example would be render or onUpdate methods.
*
* \param category the debug category
* \param optional the optional second parameter is an existing
* color_ostream_proxy object
* \return color_ostream object that can be used for stream output
*/
#define TRACE(category, ...) DBG_PRINT(category, likely, \
DFHack::DebugCategory::LTRACE, ## __VA_ARGS__)
/*!
* Open a line for debug level debug output if enabled
*
* Preferred place to use it would be commonly called functions that don't fall
* into trace category.
*
* \param category the debug category
* \param optional the optional second parameter is an existing
* color_ostream_proxy object
* \return color_ostream object that can be used for stream output
*/
#define DEBUG(category, ...) DBG_PRINT(category, likely, \
DFHack::DebugCategory::LDEBUG, ## __VA_ARGS__)
/*!
* Open a line for info level debug output if enabled
*
* Important debug messages when some rarely changed state changes. Example
* would be when a debug category filtering level changes.
*
* \param category the debug category
* \param optional the optional second parameter is an existing
* color_ostream_proxy object
* \return color_ostream object that can be used for stream output
*/
#define INFO(category, ...) DBG_PRINT(category, likely, \
DFHack::DebugCategory::LINFO, ## __VA_ARGS__)
/*!
* Open a line for warning level debug output if enabled
*
* Warning category is for recoverable errors. This generally signals that
* something unusual happened but there is code handling the error which should
* allow df continue running without issues.
*
* \param category the debug category
* \param optional the optional second parameter is an existing
* color_ostream_proxy object
* \return color_ostream object that can be used for stream output
*/
#define WARN(category, ...) DBG_PRINT(category, unlikely, \
DFHack::DebugCategory::LWARNING, ## __VA_ARGS__)
/*!
* Open a line for error level error output if enabled
*
* Errors should be printed only for cases where plugin or dfhack can't recover
* from reported error and it requires manual handling from the user.
*
* \param category the debug category
* \param optional the optional second parameter is an existing
* color_ostream_proxy object
* \return color_ostream object that can be used for stream output
*/
#define ERR(category, ...) DBG_PRINT(category, unlikely, \
DFHack::DebugCategory::LERROR, ## __VA_ARGS__)
}
You can’t perform that action at this time.