1/* (c) Magnus Auvinen. See licence.txt in the root of the distribution for more information. */
2/* If you are missing that file, acquire a complete release at teeworlds.com. */
3
4#ifndef BASE_DBG_H
5#define BASE_DBG_H
6
7#include <functional>
8
9/**
10 * Utilities for debugging.
11 *
12 * @defgroup Debug Debugging
13 */
14
15/**
16 * Breaks into the debugger based on a test.
17 *
18 * @ingroup Debug
19 *
20 * @param test Result of the test.
21 * @param fmt A printf styled format message that should be printed if the test fails.
22 *
23 * @remark Also works in release mode.
24 *
25 * @see dbg_break
26 */
27#define dbg_assert(test, fmt, ...) \
28 do \
29 { \
30 if(!(test)) \
31 { \
32 dbg_assert_imp(__FILE__, __LINE__, fmt, ##__VA_ARGS__); \
33 } \
34 } while(false)
35
36/**
37 * Breaks into the debugger with a message.
38 *
39 * @ingroup Debug
40 * @param fmt A printf styled format message that should be printed in case the
41 * code is reached.
42 *
43 * @remark Also works in release mode.
44 *
45 * @see dbg_break
46 */
47#define dbg_assert_failed(fmt, ...) dbg_assert_imp(__FILE__, __LINE__, fmt, ##__VA_ARGS__)
48
49/**
50 * Use the @link dbg_assert @endlink function instead!
51 *
52 * @ingroup Debug
53 *
54 * @see dbg_assert
55 */
56[[gnu::format(printf, 3, 4)]] [[noreturn]] void
57dbg_assert_imp(const char *filename, int line, const char *fmt, ...);
58
59/**
60 * Checks whether the program is currently shutting down due to a failed
61 * assert.
62 *
63 * @ingroup Debug
64 *
65 * @return indication whether the program is currently shutting down due to a
66 * failed assert.
67 *
68 * @see dbg_assert
69 */
70bool dbg_assert_has_failed();
71
72/**
73 * Breaks into the debugger.
74 *
75 * @ingroup Debug
76 *
77 * @remark Also works in release mode.
78 *
79 * @see dbg_assert
80 */
81[[noreturn]] void dbg_break();
82
83/**
84 * Callback function type for @link dbg_assert_set_handler @endlink.
85 *
86 * @ingroup Debug
87 *
88 * @param message The message that a @link dbg_assert @endlink is failing with.
89 *
90 * @see dbg_assert_set_handler
91 */
92typedef std::function<void(const char *message)> DBG_ASSERT_HANDLER;
93
94/**
95 * Sets a callback function that will be invoked before breaking into the
96 * debugger in @link dbg_assert @endlink.
97 *
98 * @ingroup Debug
99 *
100 * @remark Also works in release mode.
101 *
102 * @see dbg_assert
103 */
104void dbg_assert_set_handler(DBG_ASSERT_HANDLER handler);
105
106/**
107 * Prints a debug message.
108 *
109 * @ingroup Debug
110 *
111 * @param sys A string that describes what system the message belongs to.
112 * @param fmt A printf styled format string.
113 *
114 * @remark Also works in release mode.
115 *
116 * @deprecated Use `log_*` functions with appropriate severity instead.
117 */
118[[gnu::format(printf, 2, 3)]] void dbg_msg(const char *sys, const char *fmt, ...);
119
120#endif
121