Add internal BT_ASSERT() and BT_ASSERT_PRE() helpers
This patch adds new internal assertion macros to control what is
asserted. The ultimate purpose of this is to disable logic/postcondition
assertions and run-time precondition checks in a production build to
optimize the project.
`configure.ac` is modified so that it handles two new environment
variables:
`BABELTRACE_DEBUG_MODE`:
When set to `1`: enables the Babeltrace debugging mode. This enables
internal assertions which validate logic and postconditions with the
BT_ASSERT() macro. This defines `BT_DEBUG_MODE` in sources.
As of this patch, when in debugging mode, BT_ASSERT() is the
equivalent of assert(). However, assert() is enabled by not passing
`-DNDEBUG` to the compiler, while BT_ASSERT() is enabled by passing
`-DBT_DEBUG_MODE`.
Because the build is not in debugging mode by default, even if
`-DNDEBUG` is not passed to the compiler (thus not enabling
assert()), neither is `-DBT_DEBUG_MODE`, so all logic/postcondition
assertions are disabled in production.
You can use BT_ASSERT() anywhere in the whole project by including
<babeltrace/assert-internal.h>.
If a function is to be used only within a BT_ASSERT() context,
then the compiler would complain that it is unused in non-debugging
mode. You can tag the function with `BT_ASSERT_FUNC` for this.
`BABELTRACE_DEV_MODE`:
When set to `1`: enables the Babeltrace developer mode. This enables
precondition assertions in the library. This defines `BT_DEV_MODE`
in sources.
A lot of run-time checks can be avoided in production once you know
that the code is correct, i.e. that it won't perform anything
illegal, whatever the end user does. Some examples are NULL checks,
frozen checks, and bound checks.
The developer mode allows run-time precondition checks to be
performed with BT_ASSERT_PRE(). This macro expects the condition to
check as well as a message. In developer mode, when the condition is
false, the message is printed with BT_LIB_LOGF(), indicating that a
library precondition was not satisfied at this point, and then
abort() is called.
The developer mode is a trade-off between strictness and
performance: you can get a very strict library with a developer mode
build, and a more efficient library with a non-developer mode build.
If a function is to be used only within a BT_ASSERT_PRE() context,
then the compiler would complain that it is unused in non-developer
mode. You can tag the function with `BT_ASSERT_PRE_FUNC` for this.
In such a function, use BT_ASSERT_PRE_MSG() to log any additional
information without aborting (since you know the process will abort
thanks to BT_ASSERT_PRE()).
BT_ASSERT_PRE_NON_NULL() is a helper which does a non-NULL
precondition check.
BT_ASSERT_PRE_HOT() is a helper which does a non-frozen precondition
check.
`lib/logging.c` is modified so that, in developer mode, the
library's default log level is FATAL and you cannot set it to NONE.
This is important because BT_ASSERT_PRE() and BT_ASSERT_PRE_MSG()
use BT_LIB_LOGF() to print messages.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
This page took 0.025053 seconds and 4 git commands to generate.