qxLib
asserts_manager.h
Go to the documentation of this file.
1 /**
2 
3  @file asserts_manager.h
4  @author Khrapov
5  @date 27.12.2025
6  @copyright © Nick Khrapov, 2025. All right reserved.
7 
8 **/
9 #pragma once
10 
11 #include <qx/algo/predicates.h>
15 #include <qx/logger/logger.h>
17 #include <qx/windows.h>
18 
19 #include <shared_mutex>
20 #include <vector>
21 
22 #if QX_LINUX
23  #include <cstdio>
24 #elif QX_MACOS && (QX_WITH_DEBUG_INFO)
25  #include <sys/sysctl.h>
26  #include <sys/types.h>
27  #include <unistd.h>
28 #endif
29 
30 namespace qx
31 {
32 
33 /**
34  @brief Check whether the current process or thread is being traced by a debugger.
35  @details Detection is supported on Windows, Linux and debug-info builds on macOS. Linux uses procfs;
36  a non-debugger tracer also counts. An unavailable query or unsupported platform returns false.
37  @return - true when tracing is detected, otherwise false
38 **/
39 bool is_debugger_present() noexcept;
40 
41 enum class assert_type
42 {
43  assert,
44  verify,
45  expect,
46  ensure
47 };
48 
49 /**
50 
51  @class asserts_manager
52  @brief Determines assertions behavior
53  @author Khrapov
54  @date 4.01.2026
55 
56 **/
57 class asserts_manager final : public singleton<asserts_manager>
58 {
59 public:
60  using exit_func = std::function<void(const category& category, assert_type eAssertType)>;
61  using verbosity_func = std::function<verbosity(assert_type eAssertType)>;
62  using assertion_func = std::function<void(
63  string_view svCondition,
64  const category& category,
65  assert_type eAssertType,
66  string_view svUserMessage,
67  string_view svFunction,
68  string_view svFile,
69  i32 nLine)>;
70 
71  struct config
72  {
73  exit_func onExit = [](const category& category, assert_type eAssertType)
74  {
75  // Configurable fatal-assertion handler exits normally to avoid a second report.
76  std::exit(0); //-V2014
77  };
78 
79  verbosity_func getVerbosity = [](assert_type eAssertType)
80  {
81  switch (eAssertType)
82  {
83  case assert_type::assert:
84  case assert_type::verify:
85  return verbosity::critical;
86 
87  case assert_type::expect:
88  case assert_type::ensure:
89  default:
90  return verbosity::error;
91  }
92  };
93 
94  assertion_func onAssertion;
95 
96  bool bLogAssertion = true;
97  };
98 
99  using interceptor_func = std::function<bool(
100  string_view svCondition,
101  const category& category,
102  assert_type eAssertType,
103  string_view svUserMessage,
104  string_view svFunction,
105  string_view svFile,
106  i32 nLine)>;
107 
109  {
110  const void* pOwner;
111  interceptor_func callback;
112  };
113 
114 public:
115  /**
116  @brief An entry point for all assertions
117  @param svCondition - a string representation of the condition
118  @param category - a category of the assertion (file wide or manually specified)
119  @param eAssertType - an assertion type
120  @param sUserMessage - formatted user message, if specified
121  @param svFunction - assert location function
122  @param svFile - assert location file
123  @param nLine - assert location line number
124  @return - true if debug break is required
125  **/
126  bool do_assert(
127  string_view svCondition,
128  const category& category,
129  assert_type eAssertType,
130  string sUserMessage,
131  string_view svFunction,
132  string_view svFile,
133  i32 nLine);
134 
135  /**
136  @brief Called in fatal assertions to exit the application
137  @param category - a category of the assertion (file wide or manually specified)
138  @param eAssertType - an assertion type
139  **/
140  void exit(const category& category, assert_type eAssertType);
141 
142  /**
143  @brief Get config
144  @return - a thread-safe copy of the current configuration
145  **/
146  config get_config() const;
147 
148  /**
149  @brief Set config
150  @param config - new config
151  **/
152  void set_config(config config);
153 
154  /**
155  @brief Register an assertion interceptor.
156  @details Interceptors are tried in registration order before normal assertion handling. A matching
157  interceptor suppresses logging, the callback and debug break. Fatal assertions still call onExit. It must not
158  modify the interceptor list or the manager configuration from its callback.
159  @param pOwner - unique identity used to remove the interceptor
160  @param interceptor - returns true when the assertion is handled
161  **/
162  void add_interceptor(const void* pOwner, interceptor_func interceptor);
163 
164  /**
165  @brief Remove an interceptor, waiting for callbacks already in progress.
166  @param pOwner - identity supplied when registering the interceptor
167  **/
168  void remove_interceptor(const void* pOwner);
169 
170 private:
171  mutable std::shared_mutex m_Mutex;
172  config m_Config;
173  std::vector<interceptor_entry> m_Interceptors;
174 };
175 
176 } // namespace qx
177 
178 #if QX_MSVC_COMPATIBLE
179  #define QX_DETAILS_DEBUG_BREAK() __debugbreak()
180 #elif QX_CLANG || QX_APPLE_CLANG
181  #define QX_DETAILS_DEBUG_BREAK() __builtin_debugtrap()
182 #elif QX_GNU
183  #include <signal.h>
184  #define QX_DETAILS_DEBUG_BREAK() static_cast<void>(raise(SIGTRAP))
185 #else
186  #define QX_DETAILS_DEBUG_BREAK() QX_EMPTY_MACRO
187 #endif
188 
189 #ifndef QX_DEBUG_BREAK
190  /**
191  @brief Interrupt execution for a debugger using the platform's debug trap.
192  **/
193  #define QX_DEBUG_BREAK() QX_DETAILS_DEBUG_BREAK()
194 #endif
195 
196 #define QX_DETAILS_COMMON_ASSERT(condition, category, assert_type, after_debug_break, result_t, ...) \
197  static_cast<result_t>( \
198  qx::predicates::is_valid(condition) \
199  || (qx::asserts_manager::get_instance().do_assert( \
200  qx::details::get_assert_condition_string<QXT(#condition)>(condition), \
201  category, \
202  assert_type, \
203  std::move( \
204  QX_DETAILS_MACRO_USER_MESSAGE(static_cast<qx::string_pool<>*>(nullptr) __VA_OPT__(, ) __VA_ARGS__) \
205  .sValue), \
206  qx::convert_string_literal<qx::char_type, __FUNCTION__>(), \
207  QXT(__FILE__), \
208  QX_LINE) \
209  ? QX_DEBUG_BREAK() \
210  : (void)0, \
211  after_debug_break(category, assert_type), \
212  false))
213 
214 #ifndef QX_DETAILS_ASSERT_AFTER_DEBUG_BREAK_FATAL
215  #define QX_DETAILS_ASSERT_AFTER_DEBUG_BREAK_FATAL(category, assert_type) \
216  qx::asserts_manager::get_instance().exit(category, assert_type)
217 #endif
218 
219 #ifndef QX_DETAILS_ASSERT_AFTER_DEBUG_BREAK_NON_FATAL
220  #define QX_DETAILS_ASSERT_AFTER_DEBUG_BREAK_NON_FATAL(category, assert_type) false
221 #endif
222 
223 #ifndef QX_WITH_DEBUG_ASSERTS
224  #define QX_WITH_DEBUG_ASSERTS QX_WITH_DEBUG_INFO
225 #endif
226 
227 template<class char_t>
228 struct QX_FMT_NS::formatter<qx::assert_type, char_t> : qx::basic_formatter<char_t>
229 {
230  template<class format_context_t>
231  constexpr auto format(qx::assert_type eType, format_context_t& ctx) const -> decltype(ctx.out())
232  {
233  qx::basic_string_view<char_t> svName;
234  switch (eType)
235  {
236  case qx::assert_type::assert:
237  svName = QX_STR_PREFIX(char_t, "assert");
238  break;
239 
240  case qx::assert_type::verify:
241  svName = QX_STR_PREFIX(char_t, "verify");
242  break;
243 
244  case qx::assert_type::expect:
245  svName = QX_STR_PREFIX(char_t, "expect");
246  break;
247 
248  case qx::assert_type::ensure:
249  svName = QX_STR_PREFIX(char_t, "ensure");
250  break;
251  }
252 
253  return QX_FMT_NS::format_to(ctx.out(), QX_STR_PREFIX(char_t, "{}"), svName);
254  }
255 };
256 
bool is_debugger_present() noexcept
Check whether the current process or thread is being traced by a debugger.
Determines assertions behavior.
void set_config(config config)
Set config.
void exit(const category &category, assert_type eAssertType)
Called in fatal assertions to exit the application.
void add_interceptor(const void *pOwner, interceptor_func interceptor)
Register an assertion interceptor.
void remove_interceptor(const void *pOwner)
Remove an interceptor, waiting for callbacks already in progress.
bool do_assert(string_view svCondition, const category &category, assert_type eAssertType, string sUserMessage, string_view svFunction, string_view svFile, i32 nLine)
An entry point for all assertions.
config get_config() const
Get config.
A category is a class that identifies a particular piece of code. This code can be located in differe...
Definition: category.h:63
Inherit the necessary singleton class from this.
#define QX_STR_PREFIX(value_t, str)
Chose witch of prefixes add to string : L or none.
Definition: string_utils.h:120
std::int32_t i32
− 9 223 372 036 854 775 808 .. 9 223 372 036 854 775 807
Definition: typedefs.h:32