Add internal BT_ASSERT() and BT_ASSERT_PRE() helpers
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Wed, 28 Feb 2018 23:37:08 +0000 (18:37 -0500)
committerPhilippe Proulx <eeppeliteloop@gmail.com>
Thu, 2 May 2019 03:32:03 +0000 (23:32 -0400)
commit464ebc311d460b29f681703aea0aa00eef9e6475
treeceb3f6629e316941edd585e8a02cdbb4405fe475
parent476ef9815a2852d362ebc3b090f9535eb0227189
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>
configure.ac
include/Makefile.am
include/babeltrace/assert-internal.h [new file with mode: 0644]
include/babeltrace/assert-pre-internal.h [new file with mode: 0644]
lib/logging.c
This page took 0.024765 seconds and 4 git commands to generate.