asserter.h File Reference

#include <stdint.h>
#include "ecu/attributes.h"

Include dependency graph for asserter.h:

Go to the source code of this file.

Macros
Static Assert
#define	ECU_STATIC_ASSERT(check_, msg_)
	Portable static assert macro. Expands to appropriate static assert variant based on the C/C++ standard being used. More...
Runtime Assert
#define	ECU_ASSERT(check_)
	Assert condition is true at run-time. Expands differently depending on whether asserts are enabled: More...
#define	ECU_ASSERT_DEFINE_FILE(name_)
	Defines file name ECU_ASSERT() uses if assertion fires. This is a more memory-efficient alternative to the __FILE__ macro. Expands differently depending on whether asserts are enabled. More...

Functions
ECU_ATTRIBUTE_NORETURN void	ecu_assert_handler (const char *file, int line)
	User-defined system response under an assert condition. Called by ECU_ASSERT() when an assertion fires. More...

Detailed Description

See asserter.h section in Sphinx documentation.

Author

Ian Ress

Version

0.1

Date

2024-03-02

Copyright

Copyright (c) 2024

Macro Definition Documentation

ECU_ASSERT

#define ECU_ASSERT

(

check_

)

Assert condition is true at run-time. Expands differently depending on whether asserts are enabled:

Precondition

ECU_ASSERT_DEFINE_FILE() called at start of file.

1. If asserts are enabled (ECU_DISBALE_RUNTIME_ASSERTS is NOT defined) then this macro calls a custom-defined handler when an assertion fires and expands to:

   define ECU_ASSERT(check_) \
        ((check_) ? ((void)0) : ecu_assert_handler(&ecu_file_name_[0], __LINE__))

2. If asserts are disabled (ECU_DISABLE_ASSERTS is defined) then this macro does nothing:

   define ECU_ASSERT(check_) \
        ((void)0)

Parameters

check_

Condition to check. Assert passes if this is true. Assert fires if this is false.

ECU_ASSERT_DEFINE_FILE

#define ECU_ASSERT_DEFINE_FILE

(

name_

)

Defines file name ECU_ASSERT() uses if assertion fires. This is a more memory-efficient alternative to the __FILE__ macro. Expands differently depending on whether asserts are enabled.

1. If asserts are enabled (ECU_DISBALE_RUNTIME_ASSERTS is NOT defined) then this expands to:

   #define ECU_ASSERT_DEFINE_FILE(name_) \
        static const char ecu_file_name_[] = name_;

2. If asserts are disabled (ECU_DISABLE_ASSERTS is defined) then this expands to nothing:

   #define ECU_ASSERT_DEFINE_FILE(name_)

Warning

Do NOT terminate this macro with a semicolon.

Parameters

name_

string literal representing source file name.

ECU_STATIC_ASSERT

#define ECU_STATIC_ASSERT	(		check_,
			msg_
	)

Portable static assert macro. Expands to appropriate static assert variant based on the C/C++ standard being used.

1. Expands to this when compiling with C++11 and greater. Uses static_assert() which is natively supported by this standard.

   #define ECU_STATIC_ASSERT(check_, msg_) \
        static_assert((check_), msg_)

2. Expands to this when compiling with C11 and greater (before C23). Uses _Static_assert() which is natively supported by this standard.

   #define ECU_STATIC_ASSERT(check_, msg_) \
        _Static_assert((check_), msg_)

3. Expands to this when compiling with C23 and greater. Uses static_assert() which is natively supported by this standard.

   #define ECU_STATIC_ASSERT(check_, msg_) \
        static_assert((check_), msg_)

4. Expands to this when using C/C++ standard that does not support static asserts. If an assert fires, this macro produces a compilation error by referencing a symbol that is a negative-sized array. msg_ is not used in this case. Note however that msg_ must still be supplied by the caller for backwards compatibility.

   #define ECU_STATIC_ASSERT(check_, msg_) \
        extern const char ecu_static_assert_fired_[(check_) ? 1 : -1]

Parameters

check_	Condition to check. If this is true the assertion passes. If this is false the assertion fails and triggers a compilation error. This must be an expression that can be evaluated at compile-time.
msg_	Message shown in console if static assert fires. Unused if using pre-C11 or pre-C++11 standard but still required by caller to maintain backwards compatibility.

Function Documentation

ecu_assert_handler()

ECU_ATTRIBUTE_NORETURN void ecu_assert_handler	(	const char *	file,
		int	line
	)

User-defined system response under an assert condition. Called by ECU_ASSERT() when an assertion fires.

Warning

This function MUST be defined by the user since system response is a property of the application. A linker error will occur if this is not defined.

Note

Declared with the noreturn attribute to inform the compiler this function never returns. This may cause the compiler to generate different code for this function and informs static analyzers to not return from false branches of ECU_ASSERT().

Parameters

file	File name the assert fired in. This is the string literal passed into ECU_ASSERT_DEFINE_FILE().
line	Line number where the assert fired.