carb::assert::IAssert

Defined in carb/assert/IAssert.h

struct carb::assert::IAssert

Interface to provide functionality to display assertion failures in greater detail.

This provides a way to encapsulate OS specific functionality for gathering additional information, displaying dialogs, and providing additional debugging functionality. Without this interface, assertion failure reports are only really limited to log messages and software breakpoints.

Public Functions

inline bool reportFailedAssertion(const char *condition, const char *file, const char *func, int32_t line, const char *fmt = nullptr, ...)

Reports the failure of an assertion condition to all applicable destinations.

Remark

This handles displaying an assertion failure message to the user. The failure message will be unconditionally written to the attached console and the debugger output window (if running on Windows under a debugger). If no debugger is attached to the process, a simple message box will be shown to the user indicating that an assertion failure occurred and allowing them to choose how to proceed. If a debugger is attached, the default behaviour is to break into the debugger unconditionally.

Note

If running under the MSVC debugger, double clicking on the assertion failure text in the MSVC output window will jump to the source file and line containing the failed assertion.

Note

This variant of the function is present to allow the fmt parameter to default to nullptr so that it can be used with a version of the CARB_ASSERT() macro that doesn’t pass any message.

Parameters

  • condition – [in] The text describing the failed assertion condition. This may not be nullptr.

  • file – [in] The name of the file that the assertion is in. This may not be nullptr.

  • func – [in] The name of the function that the assertion is in. This may not be nullptr.

  • line – [in] The line number that the assertion failed in.

  • fmt – [in] A printf() style format string providing more information for the failed assertion. This may be nullptr if no additional information is necessary or provided.

  • ... – [in] Additional arguments required to fulfill the format string’s needs.

Returns

true if a software breakpoint should be triggered.

Returns

false if the assertion should attempt to be ignored.

Public Members

AssertFlags (*setAssertionFlags)(AssertFlags set, AssertFlags clear)

Sets, clears, or retrieves the assertion behavioral flags.

Note

This is always thread safe; changes are applied atomically. Also, set and clear can be 0 to retrieve the current set of flags.

Parameters

  • set – [in] A mask of zero or more flags to enable. This may be 0 to indicate that no new flags should be set. This is a combination of the fAssert* flags.

  • clear – [in] A mask of zero or more flags to disable. This may be 0 to indicate that no new flags should be cleared. This is a combination of the fAssert* flags.

Returns

The flags immediately before set/clear changes were applied.

uint64_t (*getAssertionFailureCount)()

Retrieves the count of how many assertions have failed.

Remark

This retrieves the current number of assertion failures that have occurred in the calling process. This may be combined with using the fAssertSkipBreakpoint and fAssertSkipDialog flags to allow certain assertions to continue in a ‘headless’ mode whose behaviour can then be monitored externally.

Returns

The number of assertions that have failed in the calling process.

bool (*reportFailedAssertionV)(const char *condition, const char *file, const char *func, int32_t line, const char *fmt, ...)

Reports the failure of an assertion condition to all applicable destinations.

Remark

This handles displaying an assertion failure message to the user. The failure message will be unconditionally written to the attached console and the debugger output window (if running on Windows under a debugger). If no debugger is attached to the process, a simple message box will be shown to the user indicating that an assertion failure occurred and allowing them to choose how to proceed. If a debugger is attached, the default behaviour is to break into the debugger unconditionally.

Note

If running under the MSVC debugger, double clicking on the assertion failure text in the MSVC output window will jump to the source file and line containing the failed assertion.

Parameters

  • condition – [in] The text describing the failed assertion condition. This may not be nullptr.

  • file – [in] The name of the file that the assertion is in. This may not be nullptr.

  • func – [in] The name of the function that the assertion is in. This may not be nullptr.

  • line – [in] The line number that the assertion failed in.

  • fmt – [in] A printf() style format string providing more information for the failed assertion. This may be nullptr if no additional information is necessary or provided.

  • ... – [in] Additional arguments required to fulfill the format string’s needs. Note that this is expected to be a single va_list object containing the arguments. For this reason, the reportFailedAssertion() variant is expected to be the one that is called instead of the ‘V’ one being called directly.

Returns

true if a software breakpoint should be triggered.

Returns

false if the assertion should attempt to be ignored.

Public Static Functions

static inline carb::InterfaceDesc getInterfaceDesc()

Returns

The carb::InterfaceDesc struct with information about this interface.