carb::assert::IAssert

struct 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 dialogues, 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 behavior 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.

Param 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.
Param 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.
Return: 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 behavior can then be monitored externally.

Return: 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 behavior 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.

Param condition: [in] The text describing the failed assertion condition. This may not be nullptr.
Param file: [in] The name of the file that the assertion is in. This may not be nullptr.
Param func: [in] The name of the function that the assertion is in. This may not be nullptr.
Param line: [in] The line number that the assertion failed in.
Param 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.
Param …: [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.
Return: true if a software breakpoint should be triggered.
Return: false if the assertion should attempt to be ignored.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

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

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.