Safe Haskell	None
Language	GHC2021

SDL3.Sys.Bindgen.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!

Synopsis

sDL_ASSERT_LEVEL :: CInt
sDL_NULL_WHILE_LOOP_CONDITION :: CInt
newtype SDL_AssertState = SDL_AssertState {
- unwrap :: CUInt
}
pattern SDL_ASSERTION_RETRY :: SDL_AssertState
pattern SDL_ASSERTION_BREAK :: SDL_AssertState
pattern SDL_ASSERTION_ABORT :: SDL_AssertState
pattern SDL_ASSERTION_IGNORE :: SDL_AssertState
pattern SDL_ASSERTION_ALWAYS_IGNORE :: SDL_AssertState
data SDL_AssertData = SDL_AssertData {
- always_ignore :: CBool
- trigger_count :: CUInt
- condition :: PtrConst CChar
- filename :: PtrConst CChar
- linenum :: CInt
- function :: PtrConst CChar
- next :: PtrConst SDL_AssertData
}
newtype SDL_AssertionHandler_Aux = SDL_AssertionHandler_Aux {
- unwrap :: PtrConst SDL_AssertData -> Ptr Void -> IO SDL_AssertState
}
newtype SDL_AssertionHandler = SDL_AssertionHandler {
- unwrap :: FunPtr SDL_AssertionHandler_Aux
}

Documentation

sDL_ASSERT_LEVEL :: CInt Source #

C declaration: macro SDL_ASSERT_LEVEL, defined at SDL3/SDL_assert.h 101:9

sDL_NULL_WHILE_LOOP_CONDITION :: CInt Source #

C declaration: macro SDL_NULL_WHILE_LOOP_CONDITION, defined at SDL3/SDL_assert.h 286:9

newtype SDL_AssertState Source #

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

C declaration: enum SDL_AssertState, defined at SDL3/SDL_assert.h 319:14

Since: 3.2.0

Constructors

SDL_AssertState
Fields unwrap :: CUInt

Instances

Instances details

Storable SDL_AssertState Source #

Instance details

SDL_AssertionHandler_Aux
Fields unwrap :: PtrConst SDL_AssertData -> Ptr Void -> IO SDL_AssertState

SDL_AssertionHandler
Fields unwrap :: FunPtr SDL_AssertionHandler_Aux