/*
 * This file is part of the DXX-Rebirth project <https://www.dxx-rebirth.com/>.
 * It is copyright by its individual contributors, as recorded in the
 * project's Git history.  See COPYING.txt at the top level for license
 * terms and a link to the Git history.
 */
#pragma once

/* Define a utility macro `cf_assert` that, like `assert`, is meant to
 * check invariants.  Unlike `assert`, it has a small but configurable
 * effect on NDEBUG builds.
 *
 * This macro is mainly used to try to hint to gcc that it is
 * excessively cautious in determining whether a
 * -Wformat-truncation warning is appropriate.
 *
 * Unless proved otherwise by control flow analysis, gcc will assume
 * that a variable to be formatted could have any value that fits in the
 * underlying type, and then gcc will warn if any of those values does
 * not fit.  In most cases, program logic constrains the value to a
 * smaller range than the underlying type supports.  Correct placement
 * of this macro can inform the compiler that a variable's actual range
 * is less than the full supported range of the underlying type.  For
 * example, a player counter should never exceed MAX_PLAYERS, but
 * MAX_PLAYERS is far less than MAX_UCHAR.
 *
 * Unfortunately, in tested versions of gcc-8, the compiler's range
 * propagation pass is hampered by strange rules in the flow control
 * logic.  Consider:

	unsigned var = unconstrained_expression();
	// var can now be anything in [0, UINT_MAX]
	cf_assert(var <= 8);
	// If execution gets here, `var <= 8` is true.
	snprintf(..., var);

 * Suppose cf_assert(X) is defined as `((X) || (assert(X),
 * __builtin_unreachable()))`, so the above becomes:

	unsigned var = unconstrained_expression();
	if (var <= 8) {
	}
	else {
		assert_fail(...);
		__builtin_unreachable();
	}
	snprintf(..., var);

 * In testing, gcc deleted __builtin_unreachable (probably because
 * assert_fail is noreturn), then warned because, without the
 * __builtin_unreachable, flow control decides the snprintf is reachable
 * (even though assert_fail is noreturn) on the else path and would
 * misbehave if reached.  Remove the call to `assert` so that you have
 * `else { __builtin_unreachable(); }` and gcc will retain the
 * `__builtin_unreachable` and not warn.
 *
 * For an even more bizarre result:

	if (var <= 8) {
		snprintf(..., var);
	} else {
		assert(var <= 8);	// always fails
		__builtin_unreachable();
	}

 * This block warns that `var` is out of range.  Comment out the
 * `assert`, which cannot influence whether `snprintf` is reached, and
 * the warning goes away.
 *
 * --
 *
 * Leave cf_assert set as an alias for (X || __builtin_unreachable())
 * unless you know what you are doing and are prepared for the warnings
 * that will arise.
 */
#include <cassert>
#if defined(DXX_CF_ASSERT_ASSERT)
#define cf_assert	assert
#else
#ifdef DXX_CF_ASSERT_TRAP
#define cf_assert_fail	__builtin_trap
#else
#define cf_assert_fail	__builtin_unreachable
#endif
#define cf_assert(X)	((X) ? static_cast<void>(0) : (cf_assert_fail()))
#endif