[thirdparty/squid.git] / src / base / Assure.h

/*
 * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */

#ifndef SQUID_SRC_BASE_ASSURE_H
#define SQUID_SRC_BASE_ASSURE_H

#include "base/Here.h"

/// Reports the description (at the given debugging level) and throws
/// the corresponding exception. Reduces compiled code size of Assure() and
/// Must() callers. Do not call directly; use Assure() instead.
/// \param description explains the condition (i.e. what MUST happen)
[[ noreturn ]] void ReportAndThrow_(int debugLevel, const char *description, const SourceLocation &);

/// Calls ReportAndThrow() if needed. Reduces caller code duplication.
/// Do not call directly; use Assure() instead.
/// \param description c-string explaining the condition (i.e. what MUST happen)
#define Assure_(debugLevel, condition, description, location) \
    while (!(condition)) \
        ReportAndThrow_((debugLevel), (description), (location))

#if !defined(NDEBUG)

/// Like assert() but throws an exception instead of aborting the process. Use
/// this macro to detect code logic mistakes (i.e. bugs) where aborting the
/// current AsyncJob or a similar task is unlikely to jeopardize Squid service
/// integrity. For example, this macro is _not_ appropriate for detecting bugs
/// that indicate a dangerous global state corruption which may go unnoticed by
/// other jobs after the current job or task is aborted.
#define Assure(condition) \
        Assure2((condition), #condition)

/// Like Assure() but allows the caller to customize the exception message.
/// \param description string literal describing the condition (i.e. what MUST happen)
#define Assure2(condition, description) \
        Assure_(0, (condition), ("assurance failed: " description), Here())

#else

/* do-nothing implementations for NDEBUG builds */
#define Assure(condition) ((void)0)
#define Assure2(condition, description) ((void)0)

#endif /* NDEBUG */

#endif /* SQUID_SRC_BASE_ASSURE_H */
Commit	Line	Data
b9a1bbfb	1	/*
b8ae064d	2	* Copyright (C) 1996-2023 The Squid Software Foundation and contributors
b9a1bbfb AR	3	*
	4	* Squid software is distributed under GPLv2+ license and includes
	5	* contributions from numerous individuals and organizations.
	6	* Please see the COPYING and CONTRIBUTORS files for details.
	7	*/
	8
	9	#ifndef SQUID_SRC_BASE_ASSURE_H
	10	#define SQUID_SRC_BASE_ASSURE_H
	11
	12	#include "base/Here.h"
	13
	14	/// Reports the description (at the given debugging level) and throws
	15	/// the corresponding exception. Reduces compiled code size of Assure() and
	16	/// Must() callers. Do not call directly; use Assure() instead.
	17	/// \param description explains the condition (i.e. what MUST happen)
	18	[[ noreturn ]] void ReportAndThrow_(int debugLevel, const char *description, const SourceLocation &);
	19
	20	/// Calls ReportAndThrow() if needed. Reduces caller code duplication.
	21	/// Do not call directly; use Assure() instead.
	22	/// \param description c-string explaining the condition (i.e. what MUST happen)
	23	#define Assure_(debugLevel, condition, description, location) \
	24	while (!(condition)) \
	25	ReportAndThrow_((debugLevel), (description), (location))
	26
	27	#if !defined(NDEBUG)
	28
	29	/// Like assert() but throws an exception instead of aborting the process. Use
	30	/// this macro to detect code logic mistakes (i.e. bugs) where aborting the
	31	/// current AsyncJob or a similar task is unlikely to jeopardize Squid service
	32	/// integrity. For example, this macro is _not_ appropriate for detecting bugs
	33	/// that indicate a dangerous global state corruption which may go unnoticed by
	34	/// other jobs after the current job or task is aborted.
	35	#define Assure(condition) \
	36	Assure2((condition), #condition)
	37
	38	/// Like Assure() but allows the caller to customize the exception message.
	39	/// \param description string literal describing the condition (i.e. what MUST happen)
	40	#define Assure2(condition, description) \
	41	Assure_(0, (condition), ("assurance failed: " description), Here())
	42
	43	#else
	44
	45	/* do-nothing implementations for NDEBUG builds */
	46	#define Assure(condition) ((void)0)
	47	#define Assure2(condition, description) ((void)0)
	48
	49	#endif /* NDEBUG */
	50
	51	#endif /* SQUID_SRC_BASE_ASSURE_H */
	52