1 | /* |
2 | Simple DirectMedia Layer |
3 | Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org> |
4 | |
5 | This software is provided 'as-is', without any express or implied |
6 | warranty. In no event will the authors be held liable for any damages |
7 | arising from the use of this software. |
8 | |
9 | Permission is granted to anyone to use this software for any purpose, |
10 | including commercial applications, and to alter it and redistribute it |
11 | freely, subject to the following restrictions: |
12 | |
13 | 1. The origin of this software must not be misrepresented; you must not |
14 | claim that you wrote the original software. If you use this software |
15 | in a product, an acknowledgment in the product documentation would be |
16 | appreciated but is not required. |
17 | 2. Altered source versions must be plainly marked as such, and must not be |
18 | misrepresented as being the original software. |
19 | 3. This notice may not be removed or altered from any source distribution. |
20 | */ |
21 | |
22 | #ifndef SDL_assert_h_ |
23 | #define SDL_assert_h_ |
24 | |
25 | #include "SDL_stdinc.h" |
26 | |
27 | #include "begin_code.h" |
28 | /* Set up for C function definitions, even when using C++ */ |
29 | #ifdef __cplusplus |
30 | extern "C" { |
31 | #endif |
32 | |
33 | #ifndef SDL_ASSERT_LEVEL |
34 | #ifdef SDL_DEFAULT_ASSERT_LEVEL |
35 | #define SDL_ASSERT_LEVEL SDL_DEFAULT_ASSERT_LEVEL |
36 | #elif defined(_DEBUG) || defined(DEBUG) || \ |
37 | (defined(__GNUC__) && !defined(__OPTIMIZE__)) |
38 | #define SDL_ASSERT_LEVEL 2 |
39 | #else |
40 | #define SDL_ASSERT_LEVEL 1 |
41 | #endif |
42 | #endif /* SDL_ASSERT_LEVEL */ |
43 | |
44 | /* |
45 | These are macros and not first class functions so that the debugger breaks |
46 | on the assertion line and not in some random guts of SDL, and so each |
47 | assert can have unique static variables associated with it. |
48 | */ |
49 | |
50 | #if defined(_MSC_VER) |
51 | /* Don't include intrin.h here because it contains C++ code */ |
52 | extern void __cdecl __debugbreak(void); |
53 | #define SDL_TriggerBreakpoint() __debugbreak() |
54 | #elif _SDL_HAS_BUILTIN(__builtin_debugtrap) |
55 | #define SDL_TriggerBreakpoint() __builtin_debugtrap() |
56 | #elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) ) |
57 | #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) |
58 | #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) |
59 | #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "ebreak\n\t" ) |
60 | #elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */ |
61 | #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" ) |
62 | #elif defined(__APPLE__) && defined(__arm__) |
63 | #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" ) |
64 | #elif defined(__386__) && defined(__WATCOMC__) |
65 | #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } |
66 | #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__) |
67 | #include <signal.h> |
68 | #define SDL_TriggerBreakpoint() raise(SIGTRAP) |
69 | #else |
70 | /* How do we trigger breakpoints on this platform? */ |
71 | #define SDL_TriggerBreakpoint() |
72 | #endif |
73 | |
74 | #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ |
75 | # define SDL_FUNCTION __func__ |
76 | #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__)) |
77 | # define SDL_FUNCTION __FUNCTION__ |
78 | #else |
79 | # define SDL_FUNCTION "???" |
80 | #endif |
81 | #define SDL_FILE __FILE__ |
82 | #define SDL_LINE __LINE__ |
83 | |
84 | /* |
85 | sizeof (x) makes the compiler still parse the expression even without |
86 | assertions enabled, so the code is always checked at compile time, but |
87 | doesn't actually generate code for it, so there are no side effects or |
88 | expensive checks at run time, just the constant size of what x WOULD be, |
89 | which presumably gets optimized out as unused. |
90 | This also solves the problem of... |
91 | |
92 | int somevalue = blah(); |
93 | SDL_assert(somevalue == 1); |
94 | |
95 | ...which would cause compiles to complain that somevalue is unused if we |
96 | disable assertions. |
97 | */ |
98 | |
99 | /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking |
100 | this condition isn't constant. And looks like an owl's face! */ |
101 | #ifdef _MSC_VER /* stupid /W4 warnings. */ |
102 | #define SDL_NULL_WHILE_LOOP_CONDITION (0,0) |
103 | #else |
104 | #define SDL_NULL_WHILE_LOOP_CONDITION (0) |
105 | #endif |
106 | |
107 | #define SDL_disabled_assert(condition) \ |
108 | do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) |
109 | |
110 | typedef enum |
111 | { |
112 | SDL_ASSERTION_RETRY, /**< Retry the assert immediately. */ |
113 | SDL_ASSERTION_BREAK, /**< Make the debugger trigger a breakpoint. */ |
114 | SDL_ASSERTION_ABORT, /**< Terminate the program. */ |
115 | SDL_ASSERTION_IGNORE, /**< Ignore the assert. */ |
116 | SDL_ASSERTION_ALWAYS_IGNORE /**< Ignore the assert from now on. */ |
117 | } SDL_AssertState; |
118 | |
119 | typedef struct SDL_AssertData |
120 | { |
121 | int always_ignore; |
122 | unsigned int trigger_count; |
123 | const char *condition; |
124 | const char *filename; |
125 | int linenum; |
126 | const char *function; |
127 | const struct SDL_AssertData *next; |
128 | } SDL_AssertData; |
129 | |
130 | /* Never call this directly. Use the SDL_assert* macros. */ |
131 | extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *, |
132 | const char *, |
133 | const char *, int) |
134 | #if defined(__clang__) |
135 | #if __has_feature(attribute_analyzer_noreturn) |
136 | /* this tells Clang's static analysis that we're a custom assert function, |
137 | and that the analyzer should assume the condition was always true past this |
138 | SDL_assert test. */ |
139 | __attribute__((analyzer_noreturn)) |
140 | #endif |
141 | #endif |
142 | ; |
143 | |
144 | /* the do {} while(0) avoids dangling else problems: |
145 | if (x) SDL_assert(y); else blah(); |
146 | ... without the do/while, the "else" could attach to this macro's "if". |
147 | We try to handle just the minimum we need here in a macro...the loop, |
148 | the static vars, and break points. The heavy lifting is handled in |
149 | SDL_ReportAssertion(), in SDL_assert.c. |
150 | */ |
151 | #define SDL_enabled_assert(condition) \ |
152 | do { \ |
153 | while ( !(condition) ) { \ |
154 | static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \ |
155 | const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \ |
156 | if (sdl_assert_state == SDL_ASSERTION_RETRY) { \ |
157 | continue; /* go again. */ \ |
158 | } else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \ |
159 | SDL_TriggerBreakpoint(); \ |
160 | } \ |
161 | break; /* not retrying. */ \ |
162 | } \ |
163 | } while (SDL_NULL_WHILE_LOOP_CONDITION) |
164 | |
165 | /* Enable various levels of assertions. */ |
166 | #if SDL_ASSERT_LEVEL == 0 /* assertions disabled */ |
167 | # define SDL_assert(condition) SDL_disabled_assert(condition) |
168 | # define SDL_assert_release(condition) SDL_disabled_assert(condition) |
169 | # define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) |
170 | #elif SDL_ASSERT_LEVEL == 1 /* release settings. */ |
171 | # define SDL_assert(condition) SDL_disabled_assert(condition) |
172 | # define SDL_assert_release(condition) SDL_enabled_assert(condition) |
173 | # define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) |
174 | #elif SDL_ASSERT_LEVEL == 2 /* normal settings. */ |
175 | # define SDL_assert(condition) SDL_enabled_assert(condition) |
176 | # define SDL_assert_release(condition) SDL_enabled_assert(condition) |
177 | # define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) |
178 | #elif SDL_ASSERT_LEVEL == 3 /* paranoid settings. */ |
179 | # define SDL_assert(condition) SDL_enabled_assert(condition) |
180 | # define SDL_assert_release(condition) SDL_enabled_assert(condition) |
181 | # define SDL_assert_paranoid(condition) SDL_enabled_assert(condition) |
182 | #else |
183 | # error Unknown assertion level. |
184 | #endif |
185 | |
186 | /* this assertion is never disabled at any level. */ |
187 | #define SDL_assert_always(condition) SDL_enabled_assert(condition) |
188 | |
189 | |
190 | /** |
191 | * A callback that fires when an SDL assertion fails. |
192 | * |
193 | * \param data a pointer to the SDL_AssertData structure corresponding to the |
194 | * current assertion |
195 | * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler() |
196 | * \returns an SDL_AssertState value indicating how to handle the failure. |
197 | */ |
198 | typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( |
199 | const SDL_AssertData* data, void* userdata); |
200 | |
201 | /** |
202 | * Set an application-defined assertion handler. |
203 | * |
204 | * This function allows an application to show its own assertion UI and/or |
205 | * force the response to an assertion failure. If the application doesn't |
206 | * provide this, SDL will try to do the right thing, popping up a |
207 | * system-specific GUI dialog, and probably minimizing any fullscreen windows. |
208 | * |
209 | * This callback may fire from any thread, but it runs wrapped in a mutex, so |
210 | * it will only fire from one thread at a time. |
211 | * |
212 | * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! |
213 | * |
214 | * \param handler the SDL_AssertionHandler function to call when an assertion |
215 | * fails or NULL for the default handler |
216 | * \param userdata a pointer that is passed to `handler` |
217 | * |
218 | * \since This function is available since SDL 2.0.0. |
219 | * |
220 | * \sa SDL_GetAssertionHandler |
221 | */ |
222 | extern DECLSPEC void SDLCALL SDL_SetAssertionHandler( |
223 | SDL_AssertionHandler handler, |
224 | void *userdata); |
225 | |
226 | /** |
227 | * Get the default assertion handler. |
228 | * |
229 | * This returns the function pointer that is called by default when an |
230 | * assertion is triggered. This is an internal function provided by SDL, that |
231 | * is used for assertions when SDL_SetAssertionHandler() hasn't been used to |
232 | * provide a different function. |
233 | * |
234 | * \returns the default SDL_AssertionHandler that is called when an assert |
235 | * triggers. |
236 | * |
237 | * \since This function is available since SDL 2.0.2. |
238 | * |
239 | * \sa SDL_GetAssertionHandler |
240 | */ |
241 | extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void); |
242 | |
243 | /** |
244 | * Get the current assertion handler. |
245 | * |
246 | * This returns the function pointer that is called when an assertion is |
247 | * triggered. This is either the value last passed to |
248 | * SDL_SetAssertionHandler(), or if no application-specified function is set, |
249 | * is equivalent to calling SDL_GetDefaultAssertionHandler(). |
250 | * |
251 | * The parameter `puserdata` is a pointer to a void*, which will store the |
252 | * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value |
253 | * will always be NULL for the default handler. If you don't care about this |
254 | * data, it is safe to pass a NULL pointer to this function to ignore it. |
255 | * |
256 | * \param puserdata pointer which is filled with the "userdata" pointer that |
257 | * was passed to SDL_SetAssertionHandler() |
258 | * \returns the SDL_AssertionHandler that is called when an assert triggers. |
259 | * |
260 | * \since This function is available since SDL 2.0.2. |
261 | * |
262 | * \sa SDL_SetAssertionHandler |
263 | */ |
264 | extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata); |
265 | |
266 | /** |
267 | * Get a list of all assertion failures. |
268 | * |
269 | * This function gets all assertions triggered since the last call to |
270 | * SDL_ResetAssertionReport(), or the start of the program. |
271 | * |
272 | * The proper way to examine this data looks something like this: |
273 | * |
274 | * ```c |
275 | * const SDL_AssertData *item = SDL_GetAssertionReport(); |
276 | * while (item) { |
277 | * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n", |
278 | * item->condition, item->function, item->filename, |
279 | * item->linenum, item->trigger_count, |
280 | * item->always_ignore ? "yes" : "no"); |
281 | * item = item->next; |
282 | * } |
283 | * ``` |
284 | * |
285 | * \returns a list of all failed assertions or NULL if the list is empty. This |
286 | * memory should not be modified or freed by the application. |
287 | * |
288 | * \since This function is available since SDL 2.0.0. |
289 | * |
290 | * \sa SDL_ResetAssertionReport |
291 | */ |
292 | extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); |
293 | |
294 | /** |
295 | * Clear the list of all assertion failures. |
296 | * |
297 | * This function will clear the list of all assertions triggered up to that |
298 | * point. Immediately following this call, SDL_GetAssertionReport will return |
299 | * no items. In addition, any previously-triggered assertions will be reset to |
300 | * a trigger_count of zero, and their always_ignore state will be false. |
301 | * |
302 | * \since This function is available since SDL 2.0.0. |
303 | * |
304 | * \sa SDL_GetAssertionReport |
305 | */ |
306 | extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void); |
307 | |
308 | |
309 | /* these had wrong naming conventions until 2.0.4. Please update your app! */ |
310 | #define SDL_assert_state SDL_AssertState |
311 | #define SDL_assert_data SDL_AssertData |
312 | |
313 | |
314 | /* Ends C function definitions when using C++ */ |
315 | #ifdef __cplusplus |
316 | } |
317 | #endif |
318 | #include "close_code.h" |
319 | |
320 | #endif /* SDL_assert_h_ */ |
321 | |
322 | /* vi: set ts=4 sw=4 expandtab: */ |
323 | |