Skip to content

These module docs are in beta and may be incomplete.

modm:architecture:assert: Assertions

These functions allow you to assert a condition at runtime and define failure handlers in your application that can decide what to do with this assertion and provide custom functionality.

Each assertion has the form modm_assert(condition, module, location, failure), where the condition is a boolean and rest are strings, so that a simple string compare can be used to match for module, location or failure. For example, the identifier "can", "init", "timeout" describes a timeout failure in the CAN initializer function. The assert modm_assert_debug(condition, module, location, failure) is only available on debug builds and is removed from the code for a release build.

The user can define one or multiple assertion handlers in any part of the application using the MODM_ASSERTION_HANDLER(function) macro. All assertion handlers will be executed when an assertion fails anywhere in the code and get passed the identifier string.

Note

The order of assertion handler execution is undefined and must not been relied upon for any functionality!

Warning

Assertion handlers may be executed in interrupt context!

Depending on the information in the failure identifier, the assertion handler returns Abandonment::DontCare if the failure is not of interest, or Abandonment::Ignore for recoverable failures, or Abandonment::Fail for failures that do not allow normal program continuation. The program is aborted, if any assertion handler returns Abandonment::Fail, all assertion handlers return Abandonment::DontCare or no assertion handlers have been defined in the application. Only if one or many assertion handlers return Abandonment::Ignore and the remainder returns Abandonment::DontCare, only then is the assertion ignored.

Note

It is intended that the assertion handlers do not block (forever), so that all assertion handlers can get called.

On program abandonment modm_abandon(module, location, failure) is called, which exits the program silently by default. Only on hosted an formatted error string is output by default. It is therefore recommended to overwrite this function on embedded targets for custom behavior like blinking an LED and printing to a serial connection.

Warning

The abandonment handler may also be executed in interrupt context!

Content

// Function
bool modm_assert(bool condition, const char *module, const char *location, const char *failure);
bool modm_assert(bool condition, const char *module, const char *location, const char *failure, uintptr_t context);
bool modm_assert_debug(bool condition, const char *module, const char *location, const char *failure);
bool modm_assert_debug(bool condition, const char *module, const char *location, const char *failure, uintptr_t context);
void modm_abandon(const char *module, const char *location, const char *failure, uintptr_t context) modm_weak;

// Enum
enum class Abandonment;

// Typedef
using modm::AssertionHandler = typedef Abandonment (*)(const char * module, const char * location, const char * failure, uintptr_t context);

// Define
#define MODM_ASSERTION_HANDLER(handler)

Dependencies

modm:architecture:assert modm_architecture_assert modm: architecture: assert modm_architecture modm: architecture modm_architecture_assert->modm_architecture modm_architecture_accessor modm: architecture: accessor modm_architecture_assert->modm_architecture_accessor modm_utils modm: utils modm_architecture_assert->modm_utils modm_driver_mcp2515 modm: driver: mcp2515 modm_driver_mcp2515->modm_architecture_assert modm_platform_can modm: platform: can modm_platform_can->modm_architecture_assert modm_platform_core modm: platform: core modm_platform_core->modm_architecture_assert modm_processing_resumable modm: processing: resumable modm_processing_resumable->modm_architecture_assert