SDL 3.0
|
Go to the source code of this file.
Data Structures | |
struct | SDL_AssertData |
Macros | |
#define | SDL_ASSERT_LEVEL 1 |
#define | SDL_TriggerBreakpoint() |
#define | SDL_FUNCTION "???" |
#define | SDL_FILE __FILE__ |
#define | SDL_LINE __LINE__ |
#define | SDL_NULL_WHILE_LOOP_CONDITION (0) |
#define | SDL_disabled_assert(condition) do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) |
#define | SDL_AssertBreakpoint() SDL_TriggerBreakpoint() |
#define | SDL_enabled_assert(condition) |
#define | SDL_assert(condition) SDL_disabled_assert(condition) |
#define | SDL_assert_release(condition) SDL_enabled_assert(condition) |
#define | SDL_assert_paranoid(condition) SDL_disabled_assert(condition) |
#define | SDL_assert_always(condition) SDL_enabled_assert(condition) |
Typedefs | |
typedef SDL_AssertState(* | SDL_AssertionHandler) (const SDL_AssertData *data, void *userdata) |
Enumerations | |
enum | SDL_AssertState { SDL_ASSERTION_RETRY , SDL_ASSERTION_BREAK , SDL_ASSERTION_ABORT , SDL_ASSERTION_IGNORE , SDL_ASSERTION_ALWAYS_IGNORE } |
Functions | |
SDL_AssertState | SDL_ReportAssertion (SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN |
void | SDL_SetAssertionHandler (SDL_AssertionHandler handler, void *userdata) |
SDL_AssertionHandler | SDL_GetDefaultAssertionHandler (void) |
SDL_AssertionHandler | SDL_GetAssertionHandler (void **puserdata) |
const SDL_AssertData * | SDL_GetAssertionReport (void) |
void | SDL_ResetAssertionReport (void) |
#define SDL_assert | ( | condition | ) | SDL_disabled_assert(condition) |
Definition at line 384 of file SDL_assert.h.
#define SDL_assert_always | ( | condition | ) | SDL_enabled_assert(condition) |
An assertion test that is always performed.
This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You almost never want to use this, as it could trigger on an end-user's system, crashing your program.
One can set the environment variable "SDL_ASSERT" to one of several strings ("abort", "break", "retry", "ignore", "always_ignore") to force a default behavior, which may be desirable for automation purposes. If your platform requires GUI interfaces to happen on the main thread but you're debugging an assertion in a background thread, it might be desirable to set this to "break" so that your debugger takes control as soon as assert is triggered, instead of risking a bad UI interaction (deadlock, etc) in the application.
condition | boolean value to test. |
\threadsafety It is safe to call this macro from any thread.
Definition at line 420 of file SDL_assert.h.
#define SDL_ASSERT_LEVEL 1 |
A helpful assertion macro!
SDL assertions operate like your usual assert
macro, but with some added features:
sizeof
operator, so disabled assertions vaporize out of the compiled code, but variables only referenced in the assertion won't trigger compiler warnings about being unused.if (x) SDL_assert(y); else do_something();
To use it: do a debug build and just sprinkle around tests to check your code!
Definition at line 98 of file SDL_assert.h.
#define SDL_assert_paranoid | ( | condition | ) | SDL_disabled_assert(condition) |
Definition at line 386 of file SDL_assert.h.
#define SDL_assert_release | ( | condition | ) | SDL_enabled_assert(condition) |
Definition at line 385 of file SDL_assert.h.
#define SDL_AssertBreakpoint | ( | ) | SDL_TriggerBreakpoint() |
Definition at line 257 of file SDL_assert.h.
#define SDL_disabled_assert | ( | condition | ) | do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) |
Definition at line 187 of file SDL_assert.h.
#define SDL_enabled_assert | ( | condition | ) |
Definition at line 268 of file SDL_assert.h.
#define SDL_FILE __FILE__ |
Definition at line 161 of file SDL_assert.h.
#define SDL_FUNCTION "???" |
Definition at line 159 of file SDL_assert.h.
#define SDL_LINE __LINE__ |
Definition at line 162 of file SDL_assert.h.
#define SDL_NULL_WHILE_LOOP_CONDITION (0) |
Definition at line 184 of file SDL_assert.h.
#define SDL_TriggerBreakpoint | ( | ) |
Definition at line 151 of file SDL_assert.h.
typedef SDL_AssertState(* SDL_AssertionHandler) (const SDL_AssertData *data, void *userdata) |
A callback that fires when an SDL assertion fails.
data | a pointer to the SDL_AssertData structure corresponding to the current assertion. |
userdata | what was passed as userdata to SDL_SetAssertionHandler(). |
\threadsafety This callback may be called from any thread that triggers an assert at any time.
Definition at line 436 of file SDL_assert.h.
enum SDL_AssertState |
Possible outcomes from a triggered assertion.
When an enabled assertion triggers, it may call the assertion handler (possibly one provided by the app via SDL_SetAssertionHandler), which will return one of these values, possibly after asking the user.
Then SDL will respond based on this outcome (loop around to retry the condition, try to break in a debugger, kill the program, or ignore the problem).
Definition at line 203 of file SDL_assert.h.
SDL_AssertionHandler SDL_GetAssertionHandler | ( | void ** | puserdata | ) |
Get the current assertion handler.
This returns the function pointer that is called when an assertion is triggered. This is either the value last passed to SDL_SetAssertionHandler(), or if no application-specified function is set, is equivalent to calling SDL_GetDefaultAssertionHandler().
The parameter puserdata
is a pointer to a void*, which will store the "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value will always be NULL for the default handler. If you don't care about this data, it is safe to pass a NULL pointer to this function to ignore it.
puserdata | pointer which is filled with the "userdata" pointer that was passed to SDL_SetAssertionHandler(). |
\threadsafety It is safe to call this function from any thread.
const SDL_AssertData * SDL_GetAssertionReport | ( | void | ) |
Get a list of all assertion failures.
This function gets all assertions triggered since the last call to SDL_ResetAssertionReport(), or the start of the program.
The proper way to examine this data looks something like this:
\threadsafety This function is not thread safe. Other threads calling SDL_ResetAssertionReport() simultaneously, may render the returned pointer invalid.
SDL_AssertionHandler SDL_GetDefaultAssertionHandler | ( | void | ) |
Get the default assertion handler.
This returns the function pointer that is called by default when an assertion is triggered. This is an internal function provided by SDL, that is used for assertions when SDL_SetAssertionHandler() hasn't been used to provide a different function.
\threadsafety It is safe to call this function from any thread.
SDL_AssertState SDL_ReportAssertion | ( | SDL_AssertData * | data, |
const char * | func, | ||
const char * | file, | ||
int | line | ||
) |
Never call this directly.
Use the SDL_assert* macros instead.
data | assert data structure. |
func | function name. |
file | file name. |
line | line number. |
\threadsafety It is safe to call this function from any thread.
void SDL_ResetAssertionReport | ( | void | ) |
Clear the list of all assertion failures.
This function will clear the list of all assertions triggered up to that point. Immediately following this call, SDL_GetAssertionReport will return no items. In addition, any previously-triggered assertions will be reset to a trigger_count of zero, and their always_ignore state will be false.
\threadsafety This function is not thread safe. Other threads triggering an assertion, or simultaneously calling this function may cause memory leaks or crashes.
void SDL_SetAssertionHandler | ( | SDL_AssertionHandler | handler, |
void * | userdata | ||
) |
Set an application-defined assertion handler.
This function allows an application to show its own assertion UI and/or force the response to an assertion failure. If the application doesn't provide this, SDL will try to do the right thing, popping up a system-specific GUI dialog, and probably minimizing any fullscreen windows.
This callback may fire from any thread, but it runs wrapped in a mutex, so it will only fire from one thread at a time.
This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
handler | the SDL_AssertionHandler function to call when an assertion fails or NULL for the default handler. |
userdata | a pointer that is passed to handler . |
\threadsafety It is safe to call this function from any thread.