sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Assert

Description

A helpful assertion macro!

SDL assertions operate like your usual assert macro, but with some added features:

  • It uses a trick with the 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.
  • It is safe to use with a dangling-else: if (x) SDL_assert(y); else do_something();
  • It works the same everywhere, instead of counting on various platforms' compiler and C runtime to behave.
  • It provides multiple levels of assertion (SDL_assert, SDL_assert_release, SDL_assert_paranoid) instead of a single all-or-nothing option.
  • It offers a variety of responses when an assertion fails (retry, trigger the debugger, abort the program, ignore the failure once, ignore it for the rest of the program's run).
  • It tries to show the user a dialog by default, if possible, but the app can provide a callback to handle assertion failures however they like.
  • It lets failed assertions be retried. Perhaps you had a network failure and just want to retry the test after plugging your network cable back in? You can.
  • It lets the user ignore an assertion failure, if there's a harmless problem that one can continue past.
  • It lets the user mark an assertion as ignored for the rest of the program's run; if there's a harmless problem that keeps popping up.
  • It provides statistics and data on all failed assertions to the app.
  • It allows the default assertion handler to be controlled with environment variables, in case an automated script needs to control it.
  • It can be used as an aid to Clang's static analysis; it will treat SDL assertions as universally true (under the assumption that you are serious about the asserted claims and that your debug builds will detect when these claims were wrong). This can help the analyzer avoid false positives.

To use it: compile a debug build and just sprinkle around tests to check your code!

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Assert.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

Full conventions: SDL3.Sys.

Synopsis

Documentation

module SDL3.Sys.Bindgen.Assert

Function aliases

reportAssertion Source #

Arguments

:: Ptr SDL_AssertData
data
assert data structure.
-> PtrConst CChar
func
function name.
-> PtrConst CChar
file
file name.
-> Int32
line
line number.
-> IO SDL_AssertState 

Never call this directly.

Use the SDL_assert macros instead.

Returns
assert state.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_ReportAssertion. The safe flavor is reportAssertionSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ReportAssertion, defined at SDL3/SDL_assert.h 363:45

Since: 3.2.0

reportAssertionSafe Source #

Arguments

:: Ptr SDL_AssertData
data
assert data structure.
-> PtrConst CChar
func
function name.
-> PtrConst CChar
file
file name.
-> Int32
line
line number.
-> IO SDL_AssertState 

Never call this directly.

Use the SDL_assert macros instead.

Returns
assert state.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_ReportAssertion. The unsafe flavor is reportAssertion .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ReportAssertion, defined at SDL3/SDL_assert.h 363:45

Since: 3.2.0

setAssertionHandler Source #

Arguments

:: SDL_AssertionHandler
handler
the SDL_AssertionHandler function to call when an assertion fails or NULL for the default handler.
-> Ptr Void
userdata
a pointer that is passed to handler.
-> IO () 

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 quit!

Thread safety
It is safe to call this function from any thread.
See also
getAssertionHandler

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetAssertionHandler. The safe flavor is setAssertionHandlerSafe : registration; the handler fires from failed SDL assertions.
C declaration
SDL_SetAssertionHandler, defined at SDL3/SDL_assert.h 604:34

Since: 3.2.0

setAssertionHandlerSafe Source #

Arguments

:: SDL_AssertionHandler
handler
the SDL_AssertionHandler function to call when an assertion fails or NULL for the default handler.
-> Ptr Void
userdata
a pointer that is passed to handler.
-> IO () 

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 quit!

Thread safety
It is safe to call this function from any thread.
See also
getAssertionHandler

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetAssertionHandler. The unsafe flavor is setAssertionHandler : registration; the handler fires from failed SDL assertions.
C declaration
SDL_SetAssertionHandler, defined at SDL3/SDL_assert.h 604:34

Since: 3.2.0

getDefaultAssertionHandler :: IO SDL_AssertionHandler Source #

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 setAssertionHandler hasn't been used to provide a different function.

Returns
the default SDL_AssertionHandler that is called when an assert triggers.
Thread safety
It is safe to call this function from any thread.
See also
getAssertionHandler

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetDefaultAssertionHandler. The safe flavor is getDefaultAssertionHandlerSafe .
C declaration
SDL_GetDefaultAssertionHandler, defined at SDL3/SDL_assert.h 625:50

Since: 3.2.0

getDefaultAssertionHandlerSafe :: IO SDL_AssertionHandler Source #

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 setAssertionHandler hasn't been used to provide a different function.

Returns
the default SDL_AssertionHandler that is called when an assert triggers.
Thread safety
It is safe to call this function from any thread.
See also
getAssertionHandler

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetDefaultAssertionHandler. The unsafe flavor is getDefaultAssertionHandler .
C declaration
SDL_GetDefaultAssertionHandler, defined at SDL3/SDL_assert.h 625:50

Since: 3.2.0

getAssertionHandler Source #

Arguments

:: Ptr (Ptr Void)
puserdata
pointer which is filled with the "userdata" pointer that was passed to setAssertionHandler.
-> IO SDL_AssertionHandler 

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 setAssertionHandler, or if no application-specified function is set, is equivalent to calling getDefaultAssertionHandler.

The parameter puserdata is a pointer to a void*, which will store the "userdata" pointer that was passed to 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.

Returns
the SDL_AssertionHandler that is called when an assert triggers.
Thread safety
It is safe to call this function from any thread.
See also
setAssertionHandler

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetAssertionHandler. The safe flavor is getAssertionHandlerSafe .
C declaration
SDL_GetAssertionHandler, defined at SDL3/SDL_assert.h 650:50

Since: 3.2.0

getAssertionHandlerSafe Source #

Arguments

:: Ptr (Ptr Void)
puserdata
pointer which is filled with the "userdata" pointer that was passed to setAssertionHandler.
-> IO SDL_AssertionHandler 

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 setAssertionHandler, or if no application-specified function is set, is equivalent to calling getDefaultAssertionHandler.

The parameter puserdata is a pointer to a void*, which will store the "userdata" pointer that was passed to 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.

Returns
the SDL_AssertionHandler that is called when an assert triggers.
Thread safety
It is safe to call this function from any thread.
See also
setAssertionHandler

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetAssertionHandler. The unsafe flavor is getAssertionHandler .
C declaration
SDL_GetAssertionHandler, defined at SDL3/SDL_assert.h 650:50

Since: 3.2.0

getAssertionReport :: IO (PtrConst SDL_AssertData) Source #

Get a list of all assertion failures.

This function gets all assertions triggered since the last call to resetAssertionReport, or the start of the program.

The proper way to examine this data looks something like this:

    const SDL_AssertData *item = SDL_GetAssertionReport();
    while (item) {
       printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
              item->condition, item->function, item->filename,
              item->linenum, item->trigger_count,
              item->always_ignore ? "yes" : "no");
       item = item->next;
    }
Returns
a list of all failed assertions or NULL if the list is empty. This memory should not be modified or freed by the application. This pointer remains valid until the next call to quit or resetAssertionReport.
Thread safety
This function is not thread safe. Other threads calling resetAssertionReport simultaneously, may render the returned pointer invalid.
See also
resetAssertionReport

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetAssertionReport. The safe flavor is getAssertionReportSafe .
C declaration
SDL_GetAssertionReport, defined at SDL3/SDL_assert.h 684:52

Since: 3.2.0

getAssertionReportSafe :: IO (PtrConst SDL_AssertData) Source #

Get a list of all assertion failures.

This function gets all assertions triggered since the last call to resetAssertionReport, or the start of the program.

The proper way to examine this data looks something like this:

    const SDL_AssertData *item = SDL_GetAssertionReport();
    while (item) {
       printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
              item->condition, item->function, item->filename,
              item->linenum, item->trigger_count,
              item->always_ignore ? "yes" : "no");
       item = item->next;
    }
Returns
a list of all failed assertions or NULL if the list is empty. This memory should not be modified or freed by the application. This pointer remains valid until the next call to quit or resetAssertionReport.
Thread safety
This function is not thread safe. Other threads calling resetAssertionReport simultaneously, may render the returned pointer invalid.
See also
resetAssertionReport

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetAssertionReport. The unsafe flavor is getAssertionReport .
C declaration
SDL_GetAssertionReport, defined at SDL3/SDL_assert.h 684:52

Since: 3.2.0

resetAssertionReport :: IO () Source #

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, 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.

Thread safety
This function is not thread safe. Other threads triggering an assertion, or simultaneously calling this function may cause memory leaks or crashes.
See also
getAssertionReport

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_ResetAssertionReport. The safe flavor is resetAssertionReportSafe .
C declaration
SDL_ResetAssertionReport, defined at SDL3/SDL_assert.h 702:34

Since: 3.2.0

resetAssertionReportSafe :: IO () Source #

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, 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.

Thread safety
This function is not thread safe. Other threads triggering an assertion, or simultaneously calling this function may cause memory leaks or crashes.
See also
getAssertionReport

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_ResetAssertionReport. The unsafe flavor is resetAssertionReport .
C declaration
SDL_ResetAssertionReport, defined at SDL3/SDL_assert.h 702:34

Since: 3.2.0