IAssert#

Fully qualified name: 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, ..., )#

Report that an assertion failed and calls vectored assertion handlers.

See the article about default assertion behavior .

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 default assertion handler 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, ...)#

Report that an assertion failed and calls vectored assertion handlers.

See the article about default assertion behavior . If no vectored assertion handlers are registered, the default assertion behavior occurs.

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.

bool (*reportFailedAssertion2)(const AssertEntry &entry, const char *fmt, std::va_list *ap)#

Report that an assertion failed and calls vectored assertion handlers.

See the article about default assertion behavior .

Param entry:: The AssertEntry with information about the assertion failure.
Param fmt:: May be nullptr. If non-nullptr, a printf-style format string with additional information about the assertion failure.
Param …:: Printf-style arguments matching format specifiers in fmt.
Retval true:: An assertion handler returned Result::eHalt indicating that execution should be stopped.
Retval false:: An assertion handler returned Result::eContinueExecution indicating that execution should be continued.

Handle (*registerAssertionHandler)(bool first, VectoredAssertionHandler handler, void *userData)#

Adds a new assertion handler.

If an assertion handler is added from an assertion handler (i.e. while handling an assertion failure) and first is false, the new assertion handler will be added to the list of handlers to be called during the current assertion handler traversal.

Thread Safety: This function is safe to call at any point by any thread, including to add assertion handlers while assertion handlers are being called.

Note

When assertion failure occurs, assertion handlers are called in a first-to-last order until an assertion handler returns a value other than Result::eCallNext. Therefore it is possible that an assertion handler is never called.

Param first:: If true, the new assertion handler is pushed to the front of the list of vectored assertion handlers. Otherwise, the new assertion handler is pushed to the back of the list. When an assertion failure occurs, assertion handlers are called in first-to-last order.
Param handler:: The handler function that will be called when an assertion failure occurs.
Param userData:: An opaque information pointer that is passed to handler when it is called.
Return:: A Handle representing the registered assertion handler. To unregister, this can be passed to unregisterAssertionHandler.

bool (*unregisterAssertionHandler)(Handle h)#

Removes a previously-registered assertion handler.

If assertion handlers are currently being called by another thread due to an assertion failure, this function will not return until it can be guaranteed that the handler to be removed has finished being called or will not be called.

Thread Safety: This function is safe to call at any point by any thread, including to remove either the current assertion handler (during assertion failure processing) or an upcoming assertion handler.

Param h:: The handle from a previous call to registerAssertionHandler.
Return:: true if the assertion handler was found and unregistered; false otherwise.

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.