// bsls_assert.h -*-C++-*-
#ifndef INCLUDED_BSLS_ASSERT
#define INCLUDED_BSLS_ASSERT
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
//@PURPOSE: Provide build-specific, runtime-configurable assertion macros.
//
//@CLASSES:
// bsls::Assert: namespace for "assert" management functions
// bsls::AssertFailureHandlerGuard: scoped guard for changing handlers safely
// bsls::AssertViolation: attributes describing a failed assertion
//
//@MACROS:
// BSLS_ASSERT: runtime check typically enabled in non-opt build modes
// BSLS_ASSERT_SAFE: runtime check typically only enabled in safe build modes
// BSLS_ASSERT_OPT: runtime check typically enabled in all build modes
// BSLS_ASSERT_INVOKE: for directly invoking the current failure handler
// BSLS_ASSERT_INVOKE_NORETURN: direct invocation always marked to not return
//
//@SEE_ALSO: bsls_review, bsls_asserttest
//
//@DESCRIPTION: This component provides three "assert-like" macros,
// 'BSLS_ASSERT', 'BSLS_ASSERT_SAFE', and 'BSLS_ASSERT_OPT', that can be used
// to enable optional *redundant* runtime checks in corresponding build modes.
// If an assertion argument evaluates to 0, a runtime-configurable "handler"
// function is invoked with a 'bsls::AssertViolation', a value-semantic class
// that encapsulates the current filename, line number, level of failed check,
// and (0-valued expression) argument text.
//
// The class 'bsls::Assert' provides functions for manipulating the globally
// configured "handler". A scoped guard for setting and restoring the assert
// handler is provided by 'bsls::AssertFailureHandlerGuard'.
//
// An additional macro, 'BSLS_ASSERT_INVOKE', is provided for direct invocation
// of the current assertion failure handler. This macro is always enabled
// (i.e., regardless of build mode).
//
///Defensive Programming (DP)
///--------------------------
// Although there is no one agreed-upon definition, in this context we will use
// the term *Defensive* *Programming* (DP) to mean any attempt by the component
// author to provide (optional) runtime validation of the preconditions (or
// invariants) defined in the function-level documentation (contract) for that
// component. Note that DP is intended to help expose defects early in the
// development process, and *never* to mask or recover from them in production.
//
// Calling a function without satisfying its preconditions results in
// *undefined* *behavior*. Detecting and reporting undefined behavior due to
// client misuse can sometimes be very helpful at identifying subtle errors.
// Additionally, we may choose to embed redundant (i.e., logically superfluous)
// runtime checks -- both as a form of active documentation, and also to help
// expose our own, latent coding errors that have escaped detection during
// testing. In either case, these *defensive* (and other) runtime checks can
// add significant overhead. Hence, this extra runtime overhead should not
// necessarily be incorporated for every build target and assertion mode (see
// "Build Modes" below). Moreover, the extent of these checks may change
// (i.e., for a particular build mode) from one release to the next.
// Therefore, any defensive (or other redundant) checks provided for a
// particular build mode are *NEVER* part of the function-level contract -- and
// remain solely what is known as a *Quality-of-Implementation* (QoI) issue.
//
///Assertion Semantics
///-------------------
// There are three important aspects of assertions: (1) !Every! !assertion!
// !is! !redundant!; it is essential that if all assertions are compiled out of
// a program that is defect-free, apart from improved runtime performance, the
// program behaves identically. Hence, (2) !each! !boolean-valued! !assert!
// !argument! !must! !have! !no! !side-effects!. Finally, (3) !assertions!
// !do! !not! !affect! !binary! !compatibility!; hence, translation units with
// different assertion levels (but not necessarily build targets) can safely be
// combined into a single program (see "Build Modes" and "Assertions in Header
// Files" below). Note that the build target 'BDE_BUILD_TARGET_SAFE_2' does
// permit binary incompatibility for conditionally compiled source code, but
// there is no corresponding 'BSLS_ASSERT_SAFE_2' assertion macro (see {Usage}
// below).
//
///Assertion Modes
///---------------
// Depending on the build, assertion macros can expand in 3 different ways:
//
//: 1 A 'bsls_assert' macro is "enabled in assert mode", or simply "enabled" if
//: it expands to check its predicate and call the assert failure handler
//: when it is false.
//:
//: 2 A 'bsls_assert' macro is "enabled in review mode", or simply "in review
//: mode" if it expands to check its predicate and call the *review* failure
//: handler when it is false. This is identical to a 'bsls_review' macro of
//: the same level when it is enabled.
//:
//: 3 A 'bsls_assert' macro is "disabled" if it expands to do nothing,
//: producing no executed code in the compiled program.
//
///Review Mode
///-----------
// The ability to enable assertions in review mode allows clients to easily and
// safely test, in a production environment, whether assertions having a lower
// threshold than what they currently have deployed are being triggered
// (without terminating the application). It is intended as an interim step
// towards lowering the assertion level threshold for an existing application.
// See {'bsls_review'} for a more detailed description of the behavior of
// assertions in review mode and suggested workflows for using this behavior.
//
///Detailed Behavior
///-----------------
// If an assertion fires (i.e., due to a 0-valued expression argument in an
// assert macro that is enabled or in review mode), there is a violation of the
// contract that the assertion is checking. If the assertion is enabled, the
// goal of the assertion is to report the precise location and nature of the
// defect *quickly* and *loudly* and prevent continued execution of the calling
// function past that point. If the assertion is in review mode then the
// behavior will match the corresponding 'bsls_review' macro and execution
// might continue, which has a priority of just logging the failure location.
//
// When enabled, the assert macros will all do essentially the same thing: Each
// macro tests the predicate expression 'X', and if '!(X)' is 'true', invokes
// the currently installed assertion failure handler. An instance of
// 'bsls::AssertViolation' will be created and populated with a textual
// rendering of the predicate ('#X'), the current '__FILE__', the current
// '__LINE__', and a string representing which particular type of assertion has
// failed. This 'violation' is then passed to the currently installed
// assertion failure handler (a function pointer with the type
// 'bsls::Assert::ViolationHandler' having the signature:
//..
// void(const bsls::AssertViolation&);
//..
//
// On some (currently experimental) platforms with support for some form of the
// upcoming language-level contract facilities there is also the ability to
// configure the assertion macros to introduce an assumption of the truth of
// their predicate. With this option the predicate will not neccesarily even
// be evaluated, and if it were to return false the compiler will treat the
// situation as undefined behavior ("impossible"). This mode for assertions
// can lead to improved code generation, but be aware that the potential
// downside of being wrong about the truth of your assertions is unbounded, and
// so deploying applications built with any assertions assumed should be done
// with great care - there are no guarantees about anything a program will do
// when an assumed assertion is violated.
//
///Selecting Which ASSERT Macro to Use
///-----------------------------------
// The choice of which specific macro to use is governed primarily by the
// impact that enabling the assertion (in either assert mode or review mode)
// will have on the runtime performance of the function, and in some cases on
// the size of the function.
//
//: 1 BSLS_ASSERT_SAFE - This macro should be reserved for tests incurring an
//: expensive change to the performance of a function, either a very high
//: constant time increase in execution time of the function, or an increase
//: in the algorithmic complexity of a function. Note especially that a
//: change in algorithmic complexity breaks the documented contract of many
//: functions (e.g., an 'O(n)' check in a function with a documented
//: 'O(log(n))' runtime speed) and so checks with that level of cost should
//: be reserved for diagnostic use in "safe" builds.
//:
//: 2 BSLS_ASSERT - For "inexpensive" checks with only a constant factor
//: overhead. The majority of checks should fall into this category.
//:
//: 3 BSLS_ASSERT_OPT - For "negligible" checks that have little to no
//: measurable overhead on a function. This will often be the case for
//: argument checking in larger functions, or very simple checks in smaller
//: functions. Keep in mind that these checks will be enabled in all
//: typically deployed build modes, so they should be reserved for larger
//: functions and functions that will not be called in highly performance
//: critical code.
//
///Assertion and Review Levels
///---------------------------
// There are a few macros available to control which of the 'bsls_assert'
// macros are disabled, enabled in review mode, or enabled in assert mode (see
// {Assertion Modes} above). These macros are for the compilation and build
// environment to provide and are not themselves defined by BDE code -- e.g.,
// by supplying one or more of these macros with '-D' options on the compiler
// command line. In general, these macros are used to determine an
// 'ASSERT_LEVEL' that can be (from most aggressive/optimized to safest)
// 'ASSUME_SAFE', 'ASSUME_ASSERT', 'ASSUME_OPT', 'NONE', 'ASSERT_OPT',
// 'ASSERT', or 'ASSERT_SAFE'. Separately, a 'REVIEW_LEVEL' is determined that
// can be 'NONE', 'REVIEW_OPT', 'REVIEW', or 'REVIEW_SAFE'. Depending on these
// levels, the various 'bsls_assert' macros will be enabled, in review mode,
// assumed, or disabled. Macros up to the assert level will be enabled. If
// the review level is higher than the assert level then macros up to the
// review level (and above the assert level) will be enabled in review mode.
// Finally, macros higher than both the review level and the assert level will
// be disabled. If the review level is 'NONE' and the assert level is set to
// one of the assume levels, then macros that would be disabled up to the
// assumed level are instead assumed. If there is a review level set then no
// macros will ever be assumed. The following table illustrates this:
//..
// ===========================================
// Macro Instantiation Based on Review Level
// ===========================================
// ENABLED - Assertion is enabled (in "assert mode")
// REVIEW - Assertion is enabled (in "review mode")
// ASSUMED - Assertion is assumed (if supported)
// <blank> - Assertion is ignored
// -----------BSLS... LEVELS---------- ----------BSLS_.. MACROS---------
// BSLS_ASSERT_LEVEL BSLS_REVIEW_LEVEL ASSERT_OPT ASSERT ASSERT_SAFE
// ----------------- ----------------- ---------- ---------- -----------
// ASSUME_SAFE NONE ASSUMED ASSUMED ASSUMED
// ASSUME_ASSERT NONE ASSUMED ASSUMED
// ASSUME_OPT NONE ASSUMED
// NONE NONE
// NONE (or ASSUME*) REVIEW_OPT REVIEW
// NONE (or ASSUME*) REVIEW REVIEW REVIEW
// NONE (or ASSUME*) REVIEW_SAFE REVIEW REVIEW REVIEW
// ASSERT_OPT NONE ENABLED
// ASSERT_OPT REVIEW_OPT ENABLED
// ASSERT_OPT REVIEW ENABLED REVIEW
// ASSERT_OPT REVIEW_SAFE ENABLED REVIEW REVIEW
// ASSERT NONE ENABLED ENABLED
// ASSERT REVIEW_OPT ENABLED ENABLED
// ASSERT REVIEW ENABLED ENABLED
// ASSERT REVIEW_SAFE ENABLED ENABLED REVIEW
// ASSERT_SAFE NONE ENABLED ENABLED ENABLED
// ASSERT_SAFE REVIEW_OPT ENABLED ENABLED ENABLED
// ASSERT_SAFE REVIEW ENABLED ENABLED ENABLED
// ASSERT_SAFE REVIEW_SAFE ENABLED ENABLED ENABLED
//..
// See {'bsls_review'} for the logic that determines the review level. The
// logic that determines the assertion level checks a few different macros.
// The first check is for one of the 7 mutually exclusive 'BSLS_ASSERT_LEVEL'
// macros that can explicitly set the assert level:
//..
// MACRO BSLS_ASSERT_LEVEL
// ----- ----------------
// BSLS_ASSERT_LEVEL_ASSUME_SAFE ASSUME_SAFE
// BSLS_ASSERT_LEVEL_ASSUME_ASSERT ASSUME_ASSERT
// BSLS_ASSERT_LEVEL_ASSUME_OPT ASSUME_OPT
// BSLS_ASSERT_LEVEL_NONE NONE
// BSLS_ASSERT_LEVEL_ASSERT_OPT ASSERT_OPT
// BSLS_ASSERT_LEVEL_ASSERT ASSERT
// BSLS_ASSERT_LEVEL_ASSERT_SAFE ASSERT_SAFE
//..
// If none of these are defined, the assert level is determined by the build
// mode. With "safer" build modes we incorporate higher level defensive
// checks. A particular build mode is implied by the relevant (BDE) build
// targets that are defined at compilation (preprocessing) time. The following
// table shows the three (BDE) build targets that can affect the assertion and
// review levels:
//..
// (BDE) Build Targets
// -----------------------
// (A) BDE_BUILD_TARGET_SAFE_2
// (B) BDE_BUILD_TARGET_SAFE
// (C) BDE_BUILD_TARGET_OPT
//..
// *Any* of the 8 possible combinations of the three build targets is valid:
// e.g., 'BDE_BUILD_TARGET_OPT' and 'BDE_BUILD_TARGET_SAFE_2' may both be
// defined. The following table shows the assert level that is set depending
// on which combination of build target macros have been set:
//..
// =========================================================
// "ASSERT" Level Set With no Level-Overriding Flags defined
// =========================================================
// --- BDE_BUILD_TARGET ---- BSLS_ASSERT_LEVEL
// _SAFE_2 _SAFE _OPT
// ------- ------- ------- -----------------
// ASSERT
// DEFINED ASSERT_OPT
// DEFINED ASSERT_SAFE
// DEFINED DEFINED ASSERT_SAFE
// DEFINED ASSERT_SAFE
// DEFINED DEFINED ASSERT_SAFE
// DEFINED DEFINED ASSERT_SAFE
// DEFINED DEFINED DEFINED ASSERT_SAFE
//..
// As the table above illustrates, with no build target explicitly defined the
// assert level defaults to 'ASSERT'. If only 'BDE_BUILD_TARGET_OPT' is
// defined, the assert level will be set to 'ASSERT_OPT'. If either
// 'BDE_BUILD_TARGET_SAFE' or 'BDE_BUILD_TARGET_SAFE_2' is defined then the
// assert level is set to 'ASSERT_SAFE' and ALL assert macros will be enabled.
//
///Runtime-Configurable Assertion-Failure Behavior
///-----------------------------------------------
// In addition to the three (BSLS) "ASSERT" macros, 'BSLS_ASSERT',
// 'BSLS_ASSERT_SAFE', and 'BSLS_ASSERT_OPT', and the immediate invocation
// macro 'BSLS_ASSERT_INVOKE', this component provides (1) an 'invokeHandler'
// method used (primarily) to implement these "ASSERT" macros and enable their
// runtime configuration, (2) administration methods to configure, at runtime,
// the behavior resulting from an assertion failure (i.e., by installing an
// appropriate assertion-failure handler function), and (3) a suite of standard
// ("off-the-shelf") assertion-failure handler functions, to be installed via
// the administrative methods (if desired), and invoked by the 'invokeHandler'
// method on an assertion failure.
//
// When an enabled assertion fails, the currently installed *failure* *handler*
// ("callback") function is invoked. The default handler is the ('static')
// 'bsls::Assert::failByAbort' method; a user may replace this default handler
// by using the ('static') 'bsls::Assert::setViolationHandler' administrative
// method and passing it (the address of) a function whose signature conforms
// to the 'bsls::Assert::ViolationHandler' 'typedef'. This handler may be one
// of the other handler methods provided in 'bsls::Assert', or a new "custom"
// function, written by the user (see {Usage} below).
//
///Exception-Throwing Failure Handlers and 'bsls::AssertFailureHandlerGuard'
///-------------------------------------------------------------------------
// Among the failure handlers provided is 'bsls::Assert::failByThrow', which
// throws a 'bsls::AssertTestException' object. Throwing an exception,
// however, is not safe in all environments and deliberately aborting is more
// useful in a debugging context than throwing an unhandled exception. Hence,
// in order for an 'bsls::AssertTestException' object to be thrown on an
// assertion failure, the user must first install the
// 'bsls::Assert::failByThrow' handler (or another exception-throwing handler)
// explicitly.
//
// Note that an object of type 'bsls::AssertFailureHandlerGuard' can be used to
// temporarily set an exception-throwing handler within a 'try' block,
// automatically restoring the previous handler when the 'try' block exits (see
// {Usage} below).
//
///Assertion Handler Policy
///------------------------
// Bloomberg policy is that (by default) tasks may not install an assertion
// handler that returns control to the point immediately following the
// detection of a failed assertion. So an assertion handler may, for example,
// terminate the task or throw an exception, but may not log the problem and
// return. 'bsls_assert', by default, enforces that policy by terminating the
// task if an installed assertion handler function chooses to returns normally.
//
///Configuring an Exception to the Assertion Handler Policy
/// - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// 'bsls_assert' provides a two-part mechanism to permit returning after the
// detection of failed assertions.
//
// It is a violation of Bloomberg policy to modify this default configuration
// without permission from senior management. (Internal Bloomberg users should
// contact the BDE team if you feel your application needs an exception to this
// policy).
//
// The intention is to provide a means to override the assertion failure policy
// that can be enabled quickly, but requires the explicit (and obvious) choice
// from both the owner of the application's 'main' function, and the person
// responsible for building the application. In order to enable a policy
// exception, 'permitOutOfPolicyReturningFailureHandler' must be called, and
// the task must be linked with a special build of 'bsls_assert.o' (in which
// the 'k_permitOutOfPolicyReturningAssertionBuildKey' constant has the value
// "bsls-PermitOutOfPolicyReturn").
//
///Legacy Handler Functions
///------------------------
// Prior to the introduction of 'bsls::AssertViolation', the signature for
// 'bsls::Assert::ViolationHandler' was this:
//..
// void(const char*, const char*,int)
//..
// This signature for a handler is still supported (though deprecated) under
// its original name 'bsls::Assert::Handler'. Overloads that take a
// 'bsls::Assert::Handler' exist for 'bsls::AssertFailureHandler' and the
// constructor for 'bsls::AssertFailureHandlerGuard', so code that uses the old
// handler signature should work without changes.
//
// If a legacy handler is set as the current handler, the function
// 'bsls::Assert::failureHandler()' will return a pointer to that function,
// while 'bsls::Assert::violationHandler()' will return an internal function
// that extracts the appropriate arguments from the generated
// 'bsls::AssertViolation' object and passes them to the installed 'Handler'.
//
///Assertions in Header Files (Mixing Build Options Across Translation Units)
///--------------------------------------------------------------------------
// Mixing build modes across translation units, although not strictly
// conformant with the C++ language standard, is permissible in practice;
// however, the defensive checks that are enabled may be unpredictable. The
// *one-definition* *rule* states that if there are multiple definitions of an
// object or function within a program, these definitions *must* be identical
// or else the program is *ill-formed*. Unfortunately, definitions in header
// files may not be identical across object ('.o') files if the build targets
// or assertion-level flags defined during translation (preprocessing) are not
// the same.
//
// For example, consider an 'inline' function that sets the width of a 'Square'
// and optionally checks for (defends against) a negative 'width' argument:
//..
// // our_square.h
// // ...
//
// inline
// void Square::setWidth(int width)
// {
// BSLS_ASSERT_SAFE(width >= 0);
//
// d_width = width;
// }
//..
// Now consider a client that uses this 'setWidth' method:
//..
// // my_client.cpp
// // ...
// void f()
// {
// Square s;
// s.setWidth(-5);
// }
//..
// We can build the 'our_square' component in "safe mode" -- e.g., by
// incorporating '-DBSLS_ASSERT_LEVEL_ASSERT_SAFE' on the (Unix) command line.
// Notice, however, that building client software against a version of
// 'our_square.o' compiled in "safe mode" does *not* ensure that all of the
// 'BSLS_ASSERT_SAFE' macros will be active (will instantiate); instead, the
// client's build mode will (most likely) govern those instantiations of the
// 'BSLS_ASSERT_SAFE' macro located within the library. The only way to ensure
// that all of the 'BSLS_ASSERT_SAFE' macros instantiate is to build the
// *client* as well as the library software in "safe mode".
//
// Inline functions are not the only source of multiple inconsistent
// definitions. Consider a non-'inline' method 'reserveCapacity' on a 'List'
// template, parameterized by element 'TYPE':
//..
// // our_list.h
// // ...
//
// template <class TYPE>
// void List<TYPE>::reserveCapacity(int numElements)
// {
// BSLS_ASSERT(numElements >= 0);
// // ...
// }
//..
// Each different translation unit that invokes 'reserveCapacity' potentially
// generates another instantiation of this function template. Those
// translation units that are compiled in "debug mode" (or "safe mode") --
// e.g., with 'BSLS_ASSERT_LEVEL_ASSERT' (or 'BSLS_ASSERT_LEVEL_ASSERT_SAFE')
// defined -- will incorporate code corresponding to each use of the
// 'BSLS_ASSERT' macro therein; the rest will not. Which one of these template
// instantiations the linker uses in the final program is undefined and highly
// unpredictable.
//
// The bottom line is that, unless clients of a library are compiled with (at
// least) the same level of assertion enabling as the library itself, not all
// of the library's defensive checking (for the assertion-level for which the
// library was compiled) will necessarily be incorporated into the client code.
// Similarly, compiling a client in a higher-level of defensive checking (e.g.,
// "safe mode") than the library was compiled (e.g., "debug mode") may result
// in additional defensive checks beyond what the library author intended for
// the mode (e.g., "debug mode") in which the library was compiled.
//
// Note that all build modes (except for when 'BDE_BUILD_TARGET_SAFE_2' is
// defined, see below) are required to be binary compatible (e.g., fields
// cannot be added to the middle of a 'struct'). Since a component's contract
// makes no explicit promise about what checking will occur, that contract is
// not violated when different parts of a program are compiled with different
// levels of assertion-enabling build options. The only consequence is that a
// smaller (or larger) number of defensive checks may be active than might
// otherwise be expected.
//
///Conditional Compilation
///-----------------------
// To recap, there are three (mutually compatible) general *build* *targets*:
//: o 'BDE_BUILD_TARGET_OPT'
//: o 'BDE_BUILD_TARGET_SAFE'
//: o 'BDE_BUILD_TARGET_SAFE_2'
// seven (mutually exclusive) component-specific *assertion* *levels*:
//: o 'BSLS_ASSERT_LEVEL_ASSERT_SAFE'
//: o 'BSLS_ASSERT_LEVEL_ASSERT'
//: o 'BSLS_ASSERT_LEVEL_ASSERT_OPT'
//: o 'BSLS_ASSERT_LEVEL_NONE'
//: o 'BSLS_ASSERT_LEVEL_ASSUME_OPT'
//: o 'BSLS_ASSERT_LEVEL_ASSUME_ASSERT'
//: o 'BSLS_ASSERT_LEVEL_ASSUME_SAFE'
// and four (mutually exclusive) component-specific *review* *levels*:
//: o 'BSLS_REVIEW_LEVEL_REVIEW_SAFE'
//: o 'BSLS_REVIEW_LEVEL_REVIEW'
//: o 'BSLS_REVIEW_LEVEL_REVIEW_OPT'
//: o 'BSLS_REVIEW_LEVEL_NONE'
// The above macros can be defined (externally) by the build environment to
// affect which of the three *assert* *macros*:
//: o 'BSLS_ASSERT_SAFE(boolean-valued expression)'
//: o 'BSLS_ASSERT(boolean-valued expression)'
//: o 'BSLS_ASSERT_OPT(boolean-valued expression)'
// will be enabled in assert mode, which will be in review mode, which will be
// assumed, and which will be disabled.
//
// The public interface of this component also explicitly provides a number of
// additional intermediate macros to identify how the various 'BSLS_ASSERT'
// macros have been instantiated. These each exist for each level and have the
// following suffixes and meanings:
//: o 'IS_ACTIVE': Defined if the corresponding level is enabled in assert or
//: review mode. For example, 'BSLS_ASSERT_SAFE_IS_ACTIVE' is defined if
//: (and only if) the conditions expressed using 'BSLS_ASSERT_SAFE' will be
//: checked at runtime (either as assertions or reviews).
//: o 'IS_REVIEW': Defined if the corresponding level is enabled in review
//: mode.
//: o 'IS_ASSUMED': Defined if the corresponding level is assumed.
//: o 'IS_USED': Defined if assert expressions for the corresponding level need
//: to be valid (i.e., if they are "ODR-used"). For example,
//: 'BSLS_ASSERT_SAFE_IS_USED' is defined if (and only if) the conditions
//: expressed using 'BSLS_ASSERT_SAFE' will be compiled. Note that this is a
//: super-set of the cases where 'BSLS_ASSERT_SAFE_IS_ACTIVE' will be
//: defined, which is when the conditions will be checked at runtime, while
//: 'BSLS_ASSERT_SAFE_IS_USED' is also defined if the conditions are assumed
//: or if 'BSLS_ASSERT_VALIDATE_DISABLED_MACROS' is defined.
//
// Putting that together, these 3 macros are defined if the corresponding macro
// is in assert or review mode - and thus the expression will be checked and a
// violation handler will be invoked on failure:
//: o 'BSLS_ASSERT_SAFE_IS_ACTIVE'
//: o 'BSLS_ASSERT_IS_ACTIVE'
//: o 'BSLS_ASSERT_OPT_IS_ACTIVE'
// These three are defined if the corresponding macro is in review mode - and
// thus the expression will be checked and the review violation handler will be
// invoked on failure. These will be defined when the review level has been
// set to a level higher than the assert level:
//: o 'BSLS_ASSERT_SAFE_IS_REVIEW'
//: o 'BSLS_ASSERT_IS_REVIEW'
//: o 'BSLS_ASSERT_OPT_IS_REVIEW'
// These three are defined if the corresponding macro is being assumed, and it
// will be hard undefined behavior to violate these expressions:
//: o 'BSLS_ASSERT_SAFE_IS_ASSUMED'
//: o 'BSLS_ASSERT_IS_ASSUMED'
//: o 'BSLS_ASSERT_OPT_IS_ASSUMED'
//
// Finally, three more macros with the 'IS_USED' suffix are defined when the
// expression for the corresponding macro is going to be compiled. This will
// be true for macros in assert, review or assumed modes, and it will be true
// for all macros if 'BSLS_ASSERT_VALIDATE_DISABLED_MACROS' has been defined.
//: o 'BSLS_ASSERT_SAFE_IS_USED'
//: o 'BSLS_ASSERT_IS_USED'
//: o 'BSLS_ASSERT_OPT_IS_USED'
//
// Note that any of the 'IS_ACTIVE', 'IS_REVIEW", and 'IS_ASSUMED' macros being
// defined will imply that the corresponding 'IS_USED' macro is also defined.
//
// Which of these macros to use to conditionally compile supporting code is
// based on when that supporting code needs to be compiled:
//: o Use '#if defined(..._IS_USED)' when:
//: * Writing functions that are only accessible to and needed for assertions
//: of the corresponding level. This could be private member functions,
//: static functions, or functions in an anonymous namespace. See
//: {Example 8} for details on this use.
//: o Use '#if !defined(..._IS_ACTIVE) && !defined(..._IS_ASSUMED)' when:
//: * You are writing (test) code that will intentionally violate a contract
//: when there is not going to be any intrinsic ill effect to that
//: violation. Generally this should only be required when there is a need
//: to validate out-of-contract behavior of a component from within its own
//: test driver.
//: o Use '#if defined(...IS_ACTIVE)' when:
//: * You are doing negative testing and want to be sure that when you call
//: your function out of contract that the violation handler will be
//: invoked. See {'bsls_asserttest'} for tools to do this without having
//: to manually check these macros.
//: * Writing redundant defensive code that should only execute when the
//: corresponding assertions are going to be enabled. The assertion itself
//: should also be included in the same preprocessor block. See
//: {Example 9} for details on this use.
//: * Note that historically this was the only macro available, and it is
//: often used for blocks of code where the checks above would be more
//: appropriate. This can often lead to code that fails to compile with
//: 'BSLS_ASSERT_VALIDATE_DISABLED_MACROS' enabled or which will not work
//: correctly when assumptions are turned on.
//
// See {Example 6} and {Example 7}, respectively, for how
// 'BDE_BUILD_TARGET_SAFE_2' and intermediate assertion predicate macros, such
// as 'BSLS_ASSERT_SAFE_IS_ACTIVE' (and even 'BSLS_ASSERT_OPT_IS_ACTIVE'), can
// be used profitably in practice.
//
///Validating Disabled Macro Expressions
///-------------------------------------
// An additional external macro, 'BSLS_ASSERT_VALIDATE_DISABLED_MACROS', can be
// defined to control the compile time behavior of 'bsls_assert'. Enabling
// this macro configures all *disabled* assert macros to still instantiate
// their predicates (in a non-evaluated context) to be sure that the predicate
// is still syntactically valid. This can be used to ensure assertions that
// are rarely enabled have valid expressions.
//
///Language-Level Contracts
///------------------------
// Contracts were proposed, accepted into the draft C++20 standard, and then
// removed. Implementations of that facility exist and it is expected future
// implementations will begin to arrive as work on new proposals comes to
// fruition. Defining the macro 'BSLS_ASSERT_USE_CONTRACTS' will cause all
// 'BSLS_ASSERT' (and, if possible, 'BSLS_REVIEW') macros to go through the
// language-level contract implementation if it is available (currently only on
// an experimental version of the gcc-compiler), otherwise a diagnostic will be
// issued.
//
// Note that mixing builds that do and do not use 'BSLS_ASSERT_USE_CONTRACTS'
// is not supported. Attempting to link against a library bult with a
// different mode for this option will cause a link-time error.
//
///Usage
///-----
// The following examples illustrate (1) when to use each of the three kinds of
// (BSLS) "ASSERT" macros, (2) when and how to call the 'invokeHandler' method
// directly, (3) how to configure, at runtime, the behavior resulting from an
// assertion failure using "off-the-shelf" handler methods, (4) how to create
// your own custom assertion-failure handler function, (5) proper use of
// 'bsls::AssertFailureHandlerGuard' to install, temporarily, an
// exception-producing assert handler, (6) how "ASSERT" macros would be used in
// conjunction with portions of the source code (affecting binary
// compatibility) that are incorporated only when 'BDE_BUILD_TARGET_SAFE_2' is
// defined, and (7) how assertion predicates (e.g.,
// 'BSLS_ASSERT_SAFE_IS_ACTIVE') are used to conditionally compile additional
// (redundant) defensive source code (not affecting binary compatibility)
// precisely when the corresponding (BSLS) "ASSERT" macro (e.g.,
// 'BSLS_ASSERT_SAFE') is active.
//
///Example 1: Using 'BSLS_ASSERT', 'BSLS_ASSERT_SAFE', and 'BSLS_ASSERT_OPT'
///- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// This component provides three different variants of (BSLS) "ASSERT" macros.
// This first usage example illustrates how one might select each of the
// particular variants, based on the runtime cost of the defensive check
// relative to that of the useful work being done.
//
// Use of the 'BSLS_ASSERT_SAFE' macro is often appropriate when the defensive
// check occurs within the body of an 'inline' function. The
// 'BSLS_ASSERT_SAFE' macro minimizes the impact on runtime performance as it
// is instantiated only when requested (i.e., by building in "safe mode"). For
// example, consider a light-weight point class 'Kpoint' that maintains 'x' and
// 'y' coordinates in the range '[-1000 .. 1000]':
//..
// my_kpoint.h
// ...
//
// class Kpoint {
// short int d_x;
// short int d_y;
// public:
// Kpoint(short int x, short int y);
// // ...
// // The behavior is undefined unless '-1000 <= x <= 1000' and
// // '-1000 <= y <= 1000'.
// // ...
// };
//
// ...
//..
// Since the cost of validation here is significant compared with the useful
// work being done, we might choose to implement defensive checks using
// 'BSLS_ASSERT_SAFE' as follows:
//..
// ...
//
// inline
// Kpoint::Kpoint(short int x, short int y)
// : d_x(x)
// , d_y(y)
// {
// BSLS_ASSERT_SAFE(-1000 <= x); BSLS_ASSERT_SAFE(x <= 1000);
// BSLS_ASSERT_SAFE(-1000 <= y); BSLS_ASSERT_SAFE(y <= 1000);
// }
//..
// For more substantial (non-'inline') functions, we would be more likely to
// use the 'BSLS_ASSERT' macro because the runtime overhead due to defensive
// checks is likely to be much less significant. For example, consider a
// hash-table class that allows the client to resize the underlying table:
//..
// my_hashtable.h
// ...
//
// class HashTable {
// // ...
// public:
// // ...
//
// void resize(double loadFactor);
// // Adjust the size of the underlying hash table to be approximately
// // the current number of elements divided by the specified
// // 'loadFactor'. The behavior is undefined unless
// // '0 < loadFactor'.
// };
//..
// Since the relative runtime cost of validating the input argument is quite
// small (e.g., less than 10%) compared to the typical work being done, we
// might choose to implement the defensive check using 'BSLS_ASSERT' as
// follows:
//..
// my_hashtable.cpp
// ...
//
// void HashTable::resize(double loadFactor)
// {
// BSLS_ASSERT(0 < loadFactor);
//
// // ...
// }
//..
// In some cases, the runtime cost of checking is always negligible when
// compared with the runtime cost of performing the useful work; moreover, the
// consequences of continuing in an undefined state for certain applications
// could be catastrophic. Instead of using 'BSLS_ASSERT' in such cases, we
// might consider using 'BSLS_ASSERT_OPT'. For example, suppose we have a
// financial application class 'TradingSystem' that performs trades:
//..
// my_tradingsystem.h
// ...
//
// class TradingSystem {
// // ...
// public:
// // ...
//..
// Further suppose that there is a particular method 'executeTrade' that takes,
// as a scaling factor, an integer that must be a multiple of 100 or the
// behavior is undefined (and might actually execute a trade):
//..
// void executeTrade(int scalingFactor);
// // Execute the current trade using the specified 'scalingFactor'.
// // The behavior is undefined unless '0 <= scalingFactor' and '100'
// // evenly divides 'scalingFactor'.
// // ...
// };
//..
// Because the cost of the two checks is likely not even measurable compared to
// the overhead of accessing databases and executing the trade, and because the
// consequences of specifying a bad scaling factor are virtually unbounded, we
// might choose to implement these defensive checks using 'BSLS_ASSERT_OPT' as
// follows:
//..
// my_tradingsystem.cpp
// ...
//
// void TradingSystem::executeTrade(int scalingFactor)
// {
// BSLS_ASSERT_OPT(0 <= scalingFactor);
// BSLS_ASSERT_OPT(0 == scalingFactor % 100);
//
// // ...
// }
//..
// Notice that in each case, the choice of which of the three (BSLS) "ASSERT"
// macros to use is governed primarily by the relative runtime cost compared
// with that of the useful work being done (and only secondarily by the
// potential consequences of continuing execution in an undefined state).
//
///Example 2: When and How to Call the 'invokeHandler' Method Directly
///- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// There *may* be times (but this is yet to be demonstrated) when we might
// reasonably choose to unconditionally invoke the currently installed
// assertion-failure handler directly -- i.e., instead of via one of the three
// (BSLS) "ASSERT" macros provided in this component. Suppose that we are
// currently in the body of some function 'someFunc' and, for whatever reason,
// feel compelled to invoke the currently installed assertion-failure handler
// based on some criteria other than the current build mode.
// 'BSLS_ASSERT_INVOKE' is provided for this purpose. The call might look as
// follows:
//..
// void someFunc(bool a, bool b, bool c)
// {
// bool someCondition = a && b && !c;
//
// if (someCondition) {
// BSLS_ASSERT_INVOKE("Bad News");
// }
// }
//..
// If presented with invalid arguments, 'someFunc' (above) will produce output
// similar to the following:
//..
// Assertion failed: Bad News, file bsls_assert.t.cpp, line 609
// Abort (core dumped)
//..
// If a piece of code needs to be guaranteed to not return, the additional
// macro 'BSLS_ASSERT_INVOKE_NORETURN' is also available. It behaves the same
// way as 'BSLS_ASSERT_INVOKE', but if the installed handler *does* return
// 'failByAbort' will be immediately called. On supported platforms it is
// marked appropriately to not return to support compiler requirements and
// static analysis tools.
//
///Example 3: Runtime Configuration of the 'bsls::Assert' Facility
///- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// By default, any assertion failure will result in the invocation of the
// 'bsls::Assert::failByAbort' handler function. We can replace this behavior
// with that of one of the other static failure handler methods supplied in
// 'bsls::Assert' as follows. Let's assume we are at the top of our
// application called 'myMain' (which would typically be 'main'):
//..
// void myMain()
// {
//..
// First observe that the default assertion-failure handler function is, in
// fact, 'bsls::Assert::failByAbort':
//..
// assert(&bsls::Assert::failByAbort == bsls::Assert::violationHandler());
//..
// Next, we install a new assertion-failure handler function,
// 'bsls::Assert::failBySleep', from the suite of "off-the-shelf" handlers
// provided as 'static' methods of 'bsls::Assert':
//..
// bsls::Assert::setViolationHandler(&bsls::Assert::failBySleep);
//..
// Observe that 'bsls::Assert::failBySleep' is the new, currently-installed
// assertion-failure handler:
//..
// assert(&bsls::Assert::failBySleep == bsls::Assert::violationHandler());
//..
// Note that if we were to explicitly invoke the current assertion-failure
// handler as follows:
//..
// BSLS_ASSERT_INVOKE("message"); // This will hang!
//..
// the program will hang since 'bsls::Assert::failBySleep' repeatedly sleeps
// for a period of time within an infinite loop. Thus, this assertion-failure
// handler is useful for hanging a process so that a debugger may be attached
// to it.
//
// We may now decide to disable the 'setViolationHandler' method using the
// 'bsls::Assert::lockAssertAdministration()' method to ensure that no one else
// will override our decision globally. Note, however, that the
// 'bsls::AssertFailureHandlerGuard' is not affected, and can still be used to
// supplant the currently installed handler (see below):
//..
// bsls::Assert::lockAssertAdministration();
//..
// Attempting to change the currently installed handler now will fail:
//..
// bsls::Assert::setViolationHandler(&bsls::Assert::failByAbort);
//
// assert(&bsls::Assert::failByAbort != bsls::Assert::violationHandler());
//
// assert(&bsls::Assert::failBySleep == bsls::Assert::violationHandler());
// }
//..
//
///Example 4: Creating a Custom Assertion Handler
/// - - - - - - - - - - - - - - - - - - - - - - -
// Sometimes, especially during testing, we may need to write our own custom
// assertion-failure handler function. The only requirements are that the
// function have the same prototype (i.e., the same respective parameter and
// return types) as the 'bsls::Assert::Handle' 'typedef', and that the function
// should not return (i.e., it must 'abort', 'exit', 'terminate', 'throw', or
// hang). To illustrate, we will create a 'static' method at file scope that
// conforms to the required structure (notice the explicit use of 'std::printf'
// from '<cstdio>' instead of 'std::cout' from '<iostream>' to avoid
// interaction with the C++ memory allocation layer):
//..
// static bool globalEnableOurPrintingFlag = true;
//
// static
// void ourFailureHandler(const bsls::AssertViolation& violation)
// // Print the expression 'comment', 'file' name, and 'line' number from
// // the specified 'violation' to 'stdout' as a comma-separated list,
// // replacing null string-argument values with empty strings (unless
// // printing has been disabled by the 'globalEnableOurPrintingFlag'
// // variable), then unconditionally abort.
// {
// const char *comment = violation.comment();
// if (!comment) {
// comment = "";
// }
// const char *file = violation.fileName();
// if (!file) {
// file = "";
// }
// int line = violation.lineNumber();
// if (globalEnableOurPrintingFlag) {
// std::printf("%s, %s, %d\n", comment, file, line);
// }
// std::abort();
// }
//..
// At the top level of our application we have the following:
//..
// void ourMain()
// {
//..
// First, let's observe that we can assign this new function to a function
// pointer of type 'bsls::Assert::Handler':
//..
// bsls::Assert::ViolationHandler f = &ourFailureHandler;
//..
// Now we can install it just as we would any other handler:
//..
// bsls::Assert::setViolationHandler(&ourFailureHandler);
//..
// We can now invoke the default handler directly:
//..
// BSLS_ASSERT_INVOKE("str1");
// }
//..
// With the resulting output something like as follows:
//..
// str1, my_file.cpp, 17
// Abort (core dumped)
//..
//
///Example 5: Using the 'bsls::AssertFailureHandlerGuard'
/// - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Sometimes we may want to replace, temporarily (i.e., within some local
// lexical scope), the currently installed assertion-failure handler function.
// In particular, we sometimes use the 'bsls::AssertFailureHandlerGuard' class
// to replace the current handler with one that throws an exception (because we
// know that such an exception is safe in the local context). Let's start with
// the simple factorial function below, which validates, in "debug mode" (or
// "safe mode"), that its input is non-negative:
//..
// double fact(int n)
// // Return 'n!'. The behavior is undefined unless '0 <= n'.
// {
// BSLS_ASSERT(0 <= n);
//
// double result = 1.0;
// while (n > 1) {
// result *= n--;
// }
// return result;
// }
//..
// Now consider the following integer-valued 'extern "C"' C++ function,
// 'wrapperFunc', which can be called from C and FORTRAN, as well as from C++:
//..
// extern "C" int wrapperFunc(bool verboseFlag)
// {
// enum { GOOD = 0, BAD } result = GOOD; (void) verboseFlag;
//..
// The purpose of this function is to allow assertion failures in subroutine
// calls below this function to be handled by throwing an exception, which is
// then caught by the wrapper and reported to the caller as a "bad" status.
// Hence, when within the runtime scope of this function, we want to install,
// temporarily, the assertion-failure handler 'bsls::Assert::failByThrow',
// which, when invoked, causes an 'bsls::AssertTestException' object to be
// thrown. (Note that we are not advocating this approach for "recovery", but
// rather for an orderly shut-down, or perhaps during testing.) The
// 'bsls::AssertFailureHandlerGuard' class is provided for just this purpose:
//..
// assert(&bsls::Assert::failByAbort == bsls::Assert::violationHandler());
//
// bsls::AssertFailureHandlerGuard guard(&bsls::Assert::failByThrow);
//
// assert(&bsls::Assert::failByThrow == bsls::Assert::violationHandler());
//..
// Next we open up a 'try' block, and somewhere within the 'try' we
// "accidentally" invoke 'fact' with an out-of-contract value (i.e., '-1'):
//..
// #ifdef BDE_BUILD_TARGET_EXC
// try
// #endif
// {
//
// // ...
//
// double d = fact(-1); // Out-of-contract call to 'fact'.
//
// // ...
// }
// #ifdef BDE_BUILD_TARGET_EXC
// catch (const bsls::AssertTestException& e) {
// result = BAD;
// if (verboseFlag) {
// std::printf( "Internal Error: %s, %s, %d\n",
// e.expression(),
// e.filename(),
// e.lineNumber() );
// }
// }
// #endif
// return result;
// }
//..
// Assuming exceptions are enabled (i.e., 'BDE_BUILD_TARGET_EXC' is defined),
// if an 'bsls::AssertTestException' occurs below this wrapper function, the
// exception will be caught, a message will be printed to 'stdout', e.g.,
//..
// Internal Error: bsls_assert.t.cpp:500: 0 <= n
//..
// and the 'wrapperFunc' function will return a bad status (i.e., 1) to its
// caller. Note that if exceptions are not enabled,
// 'bsls::Assert::failByThrow' will behave as 'bsls::Assert::failByAbort', and
// dump core immediately:
//..
// Assertion failed: 0 <= n, file bsls_assert.t.cpp, line 500
// Abort (core dumped)
//..
// Finally note that the 'bsls::AssertFailureHandlerGuard' is not thread-aware.
// In particular, a guard that is created in one thread will also affect the
// failure handlers that are used in other threads. Care should be taken when
// using this guard when more than a single thread is executing.
//
///Example 6: Using (BSLS) "ASSERT" Macros Along With 'BDE_BUILD_TARGET_SAFE_2'
/// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Recall that assertions do not affect binary compatibility; however, software
// built with 'BDE_BUILD_TARGET_SAFE_2' defined need not be binary compatible
// with software built otherwise. In this example, we look at how we might use
// the (BSLS) "ASSERT" family of macros in conjunction with code that is
// incorporated (at compile time) only when 'BDE_BUILD_TARGET_SAFE_2' is
// defined.
//
// As a simple example, let's consider an elided implementation of a
// singly-linked integer list and its iterator. Whenever
// 'BDE_BUILD_TARGET_SAFE_2' is defined, we want to defend against the
// possibility that a client mistakenly passes a 'ListIter' object into a
// 'List' object method (e.g., 'List::insert') where that 'ListIter' object did
// not originate from the same 'List' object.
//
// We'll start by defining a local helper 'List_Link' 'struct' as follows:
//..
// struct List_Link {
// List_Link *d_next_p;
// int d_data;
// List_Link(List_Link *next, int data) : d_next_p(next), d_data(data) { }
// };
//..
// Next, we'll define 'ListIter', which always identifies the current position
// in a sequence of links, but whenever 'BDE_BUILD_TARGET_SAFE_2' is defined,
// also maintains a pointer to its parent 'List' object:
//..
// class List; // Forward declaration.
//
// class ListIter {
// #ifdef BDE_BUILD_TARGET_SAFE_2
// List *d_parent_p; // Exists only in "safe 2 mode".
// #endif
// List_Link **d_current_p;
// friend class List;
// friend bool operator==(const ListIter&, const ListIter&);
// private:
// ListIter(List_Link **current,
// List *
// #ifdef BDE_BUILD_TARGET_SAFE_2
// parent // Not used unless in "safe 2 mode".
// #endif
// )
// : d_current_p(current)
// #ifdef BDE_BUILD_TARGET_SAFE_2
// , d_parent_p(parent) // Initialize only in "safe 2 mode".
// #endif
// { }
// public:
// ListIter& operator++() { /* ... */ return *this; }
// // ...
// };
// bool operator==(const ListIter& lhs, const ListIter& rhs);
// bool operator!=(const ListIter& lhs, const ListIter& rhs);
//..
// Finally we define the 'List' class itself with most of the operations
// elided; the methods of particular interest here are 'begin' and 'insert':
//..
//
// class List {
// List_Link *d_head_p;
// public:
// // CREATORS
// List() : d_head_p(0) { }
// List(const List&) { /* ... */ }
// ~List() { /* ... */ }
//
// // MANIPULATORS
// List& operator=(const List&) { /* ... */ return *this; }
//
// //| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
// //v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v
// //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
// ListIter begin()
// // Return an iterator referring to the beginning of this list.
// {
// return ListIter(&d_head_p, this);
// }
// //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
//
// //| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
// //v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v
// //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
// void insert(const ListIter& position, int data)
// // Insert the specified 'data' value into this list at the
// // specified 'position'.
// {
// #ifdef BDE_BUILD_TARGET_SAFE_2
// BSLS_ASSERT_SAFE(this == position.d_parent_p); // "safe 2 mode"
// #endif
// *position.d_current_p = new List_Link(*position.d_current_p, data);
// }
// //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
//
// // ACCESSORS
// void print()
// // Output the contents of this list to 'stdout'.
// {
// printf( "[" );
// for (List_Link *p = d_head_p; p; p = p->d_next_p) {
// printf( " %d", p->d_data );
// }
// printf(" ]\n");
// }
// };
//..
// Outside of "safe 2 mode", it is possible to pass an iterator object obtained
// from the 'begin' method of one 'List' object into the 'insert' method of
// another, having, perhaps, unexpected results:
//..
// void sillyFunc(bool printFlag)
// {
// List a;
// ListIter aIt = a.begin();
// a.insert(aIt, 1);
// a.insert(aIt, 2);
// a.insert(aIt, 3);
//
// if (printFlag) {
// std::printf( "a = "); a.print();
// }
//
// List b;
// ListIter bIt = b.begin();
// a.insert(bIt, 4); // Oops! Should have been: 'b.insert(bIt, 4);'
// a.insert(bIt, 5); // Oops! " " " ' " " 5 '
// a.insert(bIt, 6); // Oops! " " " ' " " 6 '
//
// if (printFlag) {
// std::printf( "a = "); a.print();
// std::printf( "b = "); b.print();
// }
// }
//..
// In the example above, we have "accidentally" passed the iterator 'bIt'
// obtained from 'List' object 'b' into the 'insert' method for 'List' object
// 'a'. The resulting undefined behavior (in other than "safe 2 mode") might
// produce output that looks as follows:
//..
// a = [ 3 2 1 ]
// a = [ 3 2 1 ]
// b = [ 6 5 4 ]
//..
// If the same 'sillyFunc' were compiled in "safe 2 mode" (i.e., with
// 'BDE_BUILD_TARGET_SAFE_2' defined) the undefined behavior would be detected
// and the output would, by default, look more like the following:
//..
// a = [ 3 2 1 ]
// FATAL my_list.cpp:56 Assertion failed: this == position.d_parent_p
// Abort (core dumped)
//..
// thereby quickly exposing the misuse by the client.
//
///Example 7: Conditional Compilation Associated with Enabled Assertion Levels
///- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// In cases where we want to tie code, other than just an assertion, to a
// specific level of enabled assertions, we will want to use the corresponding
// intermediate predicate that enables that level of assertions:
//
//: o For 'BSLS_ASSERT_SAFE', use 'BSLS_ASSERT_SAFE_IS_ACTIVE'.
//:
//: o For 'BSLS_ASSERT', use 'BSLS_ASSERT_IS_ACTIVE'.
//:
//: o For 'BSLS_ASSERT_OPT', use 'BSLS_ASSERT_OPT_IS_ACTIVE'.
//
// Suppose that we have a class such as 'MyDate' (below) that, except for
// checking its invariants, would have a trivial destructor. By not declaring
// a destructor at all, we may realize performance advantages, but then we lose
// the ability to validate our invariants in "debug" or "safe" mode. What we
// want to do is to declare (and later define) the destructor in precisely
// those build modes for which we would want to assert invariants.
//
// An elided class 'MyDate', which is based on a serial-date implementation, is
// provided for reference:
//..
// class MyDate {
// // This class implements a value-semantic "date" type representing
// // valid date values in the range '[ 0001Jan01 .. 9999Dec31 ]'.
//
// // DATA
// int d_serialDate; // sequential representation within a valid range
//
// public:
// // CLASS METHODS
//
// // ...
//
// // CREATORS
// MyDate();
// // Create a 'MyDate' object having the value '0001Jan01'.
//
// // ...
//
// MyDate(const MyDate& original);
// // Create a 'MyDate' object having the same value as the specified
// // 'original' object.
//
// #if defined(BSLS_ASSERT_SAFE_IS_ACTIVE)
// ~MyDate();
// // Destroy this object. Note that in some build modes the
// // destructor generated by the compiler is trivial.
// #endif
//
// // ...
// };
//
// ...
//
// ========================================================================
// INLINE FUNCTION DEFINITIONS
// ========================================================================
//
// ...
//
// CREATORS
// inline
// MyDate::MyDate()
// : d_serialDate(1) // 0001Jan01
// {
// }
//
// inline
// MyDate::MyDate(const MyDate& original)
// : d_serialDate(original.d_serialDate)
// {
// }
//
// ...
//
// #if defined(BSLS_ASSERT_SAFE_IS_ACTIVE)
// inline
// MyDate::~MyDate()
// {
// BSLS_ASSERT_SAFE(1 <= d_serialDate); // 0001Jan01
// BSLS_ASSERT_SAFE( d_serialDate <= 3652061); // 9999Dec31
// }
// #endif
//
// ...
//..
// In practice, however, we would probably implement an 'isValidSerialDate'
// method in a lower-level utility class, e.g., 'MyDateImpUtil', leading to
// code that is more fine-grained, modular, and hierarchically reusable:
//..
// struct MyDateImpUtil {
// static bool isValidSerialDate(int d_date);
// // Return 'true' if the specified 'd_date' represents a valid date
// // value, and 'false' otherwise.
// };
//
// inline
// bool MyDateImpUtil::isValidSerialDate(int d_date)
// {
// return 1 <= d_date && d_date <= 3652061;
// }
//..
// Like other aspects of 'BSLS_ASSERT_SAFE', the example above violates the
// one-definition rule for mixed-mode builds. Note that all code conditionally
// compiled based on 'BSLS_ASSERT_SAFE_IS_ACTIVE', 'BSLS_ASSERT_IS_ACTIVE', and
// 'BSLS_ASSERT_OPT_IS_ACTIVE' should be binary compatible for mixed-mode
// builds. If the conditionally-compiled code would not be binary compatible,
// use 'BDE_BUILD_TARGET_SAFE_2' instead.
//
// WARNING - In practice, declaring a destructor in some build modes but not
// others has led to subtle and difficult-to-diagnose failures. DON'T DO IT!
//
// Finally, in very rare cases, we may want to put in (redundant) defensive
// code (in the spirit of 'BSLS_ASSERT_OPT') that is not part of the
// component-level contract, yet (1) is known to have negligible runtime cost
// and (2) is deemed to be so important as to be necessary even for optimized
// builds.
//
// For example, consider again the 'MyDate' class above that now also declares
// a non-'inline' 'print' method to format the current date value in some
// human-readable, but otherwise unspecified format:
//..
// xyza_mydate.h
// ...
// class MyDate {
// // ...
//
// // DATA
// int d_serialDate; // sequential representation within a valid range
//
// public:
// // ...
// // ACCESSORS
// // ...
//
// std::ostream& print(std::ostream& stream, ...) const;
// // Write the value of this object to the specified output 'stream'
// // in some human-readable format, and return a reference to
// // 'stream'. Optionally specify ...
//
// // ...
//
// };
//..
// Successfully writing bad data is among the most insidious of bugs, because a
// latent error can persist and not be discovered until long after the program
// terminates. Writing the value of a corrupted 'MyDate' object in a
// *machine-readable* (binary) format is an error so serious as to warrant
// invoking
//..
// void testFunction(int d_serialDate) {
// BSLS_ASSERT_OPT(MyDateImpUtil::isValidSerialDate(d_serialDate));
// }
//..
// each time we attempt the output operation; however, printing the value in a
// human-readable format intended primarily for debugging purposes is another
// matter. In anything other than a safe build (which in this case would
// enforce essentially all method preconditions), it would be unfortunate if a
// developer, knowing that there was a problem involving the use of 'MyDate',
// inserted print statements to identify that problem, only to have the 'print'
// method itself ruthlessly invoke the assert handler, likely terminating the
// process). Moreover, it may also be unsafe even to attempt to format the
// value of a 'MyDate' object whose 'd_serialDate' value violates its
// invariants (e.g., due to a static table lookup). In such cases we may, as
// sympathetic library developers, choose to implement different undefined
// (undocumented) redundant defensive behaviors, depending on the desired level
// of assertions:
//..
// xyza_mydate.cpp
// ...
// #include <xyza_mydateimputil.h>
// ...
//
// std::ostream& MyDate::print(std::ostream& stream, ...) const
// {
// // BSLS_ASSERT(/* any *argument* preconditions for this function */);
//
// // Handle case where the invariants have been violated.
//
// #ifdef BSLS_ASSERT_OPT_IS_ACTIVE
// // Note that if 'BSLS_ASSERT_LEVEL_NONE' has been set, this code --
// // along with all 'BSLS_ASSERT_OPT' macros -- will not instantiate,
// // enabling us to verify that the combined runtime overhead of all such
// // (redundant) defensive code is at worst negligible, if not
// // unmeasurable.
//
// if (!MyDateImpUtil::isValidSerialDate(d_serialDate)) {
//
// // Our invariant is corrupted.
//
// #ifdef BSLS_ASSERT_IS_ACTIVE
// // Providing debugging information in this mode would be useful.
//
// std::cerr << "\nxyza::MyDate: Invalid internal serial date value "
// << d_serialDate << '.' << std::endl;
//
// #endif // BSLS_ASSERT_IS_ACTIVE
//
// // In safe mode, each of the 'MyClass' methods fully guards its
// // preconditions: There is simply no easy way to get here!
//
// BSLS_ASSERT_SAFE("Probable rogue memory overwrite!" && 0);
//
// // If we get here, we're corrupted, but not in safe mode!
//
// return stream << "(* Invalid 'MyDate' State "
// << d_serialDate
// << " *)" << std::flush; // RETURN
//
// }
// #endif // BSLS_ASSERT_OPT_IS_ACTIVE
//
// // If we get here in a production build, this object is "sane": Do
// // whatever this 'print' method would normally do, assuming that no
// // method preconditions or object invariants are violated.
//
// // ... <*** Your (Normal-Case) Formatting Code Here! ***>
//
// return stream;
// }
//..
///Example 8: Conditional Compilation of Support Functions
///- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Occasionally a function may exist only to support a specific set of
// assertions. Often this can happen when a large expression that captures a
// complicated precondition wants to be refactored into a distinct location to
// ease understanding of it. When this happens the function might still remain
// as a private implementation detail of the class.
//
// When the only assertion macros that use the function are disabled this can
// lead to a compiler warning about a function being unused, and the
// corresponding code bloat from having the function available might be an
// overhead that is not desired.
//
// In order to totally remove the function when it is not needed, the 'IS_USED'
// suffixed macros can be used to guard the declaration and definition of the
// function. Suppose we have a 'class' with a function having a complex
// precondition, and that precondition check is both private and only needed
// when the assertions that use it are enabled. In that case, we can guard the
// definitions and declarations against even being compiled like this:
//..
// class ComplexObject {
// // ...
// #if defined(BSLS_ASSERT_SAFE_IS_USED)
// bool isPurplish() const;
// // Return 'true' if the current state of this object fits within
// // the complex requirements of being sufficiently purple, false
// // otherwise.
// #endif
// // ...
// public:
// // MANIPULATORS
// void doSomethingPurpley();
// // Do something purpley. The behavior is undefined unless this
// // object is currently purplish (contact customer support to know
// // the current threshholds for purplishness).
// };
//
// #if defined(BSLS_ASSERT_SAFE_IS_USED)
// bool ComplexObject::isPurplish() const
// {
// // The real implementation would encode the complex logic of needing to
// // determine if this object feels purplish at the moment.
// return true;
// }
// #endif
//
// void ComplexObject::doSomethingPurpley()
// {
// BSLS_ASSERT_SAFE(isPurplish());
// }
//..
// Now, the 'ComplexObject::isPurplish' function will only exist in a subset of
// builds:
//: o When 'BSLS_ASSERT_SAFE' assertions are enabled in assert or review mode,
//: the function will be compiled and invoked.
//: o When 'BSLS_ASSERT_VALIDATE_DISABLED_MACROS' is defined the function will
//: be compiled. This will make sure that a future change does not
//: invalidate the implementation of 'isPurplish()' even though it is not
//: used.
//: o When 'BSLS_ASSERT_SAFE' assertions are assumed the function will be
//: compiled and might be invoked, or at least have its implementation
//: inspected by the compiler to improve code generation.
//
///Example 9: Conditional Compilation of Support Code
/// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Sometimes there is code that needs to run in a function before an assertion
// to gather information needed only by that assertion. Often this can be
// capturing input values or other system state before it is modified and
// verifying at the end of a function that the values are changed (or not)
// appropriately.
//
// When the corresponding assertion macro is not active in assert or review
// mode the supporting code should not be executed at all. Importantly,
// because the capturing of additional information is an extra cost, the
// assertion itself does not lend itself to being assumed.
//
// Suppose we have a function that wishes to swap the values of its input:
//..
// struct MySwapper {
// template <class T>
// static void swap(T& lhs, T& rhs)
// // Exchange the values of the specified 'lhs' and 'rhs'.
// {
// T tmp = lhs;
// lhs = rhs;
// rhs = tmp;
// }
// };
//..
// This works great as a simple 'swap' implementation, but we would like to
// assert in safe mode that it is doing the correct thing. In order to do that
// we need to capture the initial values of our inputs before doing anything
// else, and we want to do this only when the respective assertions are
// enabled. Here we would guard our code and our assertions in a check that
// 'BSLS_ASSERT_SAFE_IS_ACTIVE' is defined, like this:
//..
// struct MySwapper {
// template <class T>
// static void swap(T& lhs, T& rhs)
// // Exchange the values of the specified 'lhs' and 'rhs'.
// {
// #if defined(BSLS_ASSERT_SAFE_IS_ACTIVE)
// T origLhs(lhs);
// T origRhs(rhs);
// #endif
// T tmp = lhs;
// lhs = rhs;
// rhs = tmp;
// #if defined(BSLS_ASSERT_SAFE_IS_ACTIVE)
// BSLS_ASSERT_SAFE(rhs == origLhs);
// BSLS_ASSERT_SAFE(lhs == origRhs);
// #endif
// }
// };
//..
#include <bsls_annotation.h>
#include <bsls_assertimputil.h>
#include <bsls_buildtarget.h>
#include <bsls_compilerfeatures.h>
#include <bsls_keyword.h>
#include <bsls_performancehint.h>
#include <bsls_platform.h>
#include <bsls_review.h>
#ifdef BSLS_ASSERT_USE_CONTRACTS
#include <contract>
#endif
// =============================
// Checks for Pre-Defined macros
// =============================
#if defined(BSLS_ASSERT_OPT)
#error BSLS_ASSERT_OPT is already defined!
#endif
#if defined(BSLS_ASSERT_OPT_IS_ACTIVE)
#error BSLS_ASSERT_OPT_IS_ACTIVE is already defined!
#endif
#if defined(BSLS_ASSERT_OPT_IS_ASSUMED)
#error BSLS_ASSERT_OPT_IS_ASSUMED is already defined!
#endif
#if defined(BSLS_ASSERT_OPT_IS_REVIEW)
#error BSLS_ASSERT_OPT_IS_REVIEW is already defined!
#endif
#if defined(BSLS_ASSERT_OPT_IS_USED)
#error BSLS_ASSERT_OPT_IS_USED is already defined!
#endif
#if defined(BSLS_ASSERT)
#error BSLS_ASSERT is already defined!
#endif
#if defined(BSLS_ASSERT_IS_ACTIVE)
#error BSLS_ASSERT_IS_ACTIVE is already defined!
#endif
#if defined(BSLS_ASSERT_IS_ASSUMED)
#error BSLS_ASSERT_IS_ASSUMED is already defined!
#endif
#if defined(BSLS_ASSERT_IS_REVIEW)
#error BSLS_ASSERT_IS_REVIEW is already defined!
#endif
#if defined(BSLS_ASSERT_IS_USED)
#error BSLS_ASSERT_IS_USED is already defined!
#endif
#if defined(BSLS_ASSERT_SAFE)
#error BSLS_ASSERT_SAFE is already defined!
#endif
#if defined(BSLS_ASSERT_SAFE_IS_ACTIVE)
#error BSLS_ASSERT_SAFE_IS_ACTIVE is already defined!
#endif
#if defined(BSLS_ASSERT_SAFE_IS_ASSUMED)
#error BSLS_ASSERT_SAFE_IS_ASSUMED is already defined!
#endif
#if defined(BSLS_ASSERT_SAFE_IS_REVIEW)
#error BSLS_ASSERT_SAFE_IS_REVIEW is already defined!
#endif
#if defined(BSLS_ASSERT_SAFE_IS_USED)
#error BSLS_ASSERT_SAFE_IS_USED is already defined!
#endif
#if defined(BSLS_ASSERT_INVOKE)
#error BSLS_ASSERT_INVOKE is already defined!
#endif
#if defined(BSLS_ASSERT_INVOKE_NORETURN)
#error BSLS_ASSERT_INVOKE_NORETURN is already defined!
#endif
// =================================
// (BSLS) "ASSERT" Macro Definitions
// =================================
// Implementation Note: We wrap the 'if' statement below in a (seemingly
// redundant) do-while-false loop to require, syntactically, a trailing
// semicolon, and to ensure that the macro behaves properly in an if-then-else
// context -- even if one forgets to wrap, with curly braces, the body of an
// 'if' having just a single 'BSLS_ASSERT*' statement.
// =============================================
// Factored Implementation for Internal Use Only
// =============================================
#if !(defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) || \
defined(BSLS_ASSERT_LEVEL_ASSERT) || \
defined(BSLS_ASSERT_LEVEL_ASSERT_OPT) || \
defined(BSLS_ASSERT_LEVEL_NONE) || \
defined(BSLS_ASSERT_LEVEL_ASSUME_OPT) || \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT) || \
defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE))
#define BSLS_ASSERT_NO_ASSERTION_MACROS_DEFINED 1
#else
#define BSLS_ASSERT_NO_ASSERTION_MACROS_DEFINED 0
#endif
#ifdef BSLS_ASSERT_USE_CONTRACTS
#define BSLS_ASSERT_ASSERT_IMP(X,LVL) [[ assert check_never_continue : X ]]
#define BSLS_ASSERT_ASSUME_IMP(X,LVL) [[ assert assume : X ]]
#define BSLS_ASSERT_ASSUME_ENABLED
#ifdef BSLS_ASSERT_VALIDATE_DISABLED_MACROS
#define BSLS_ASSERT_DISABLED_IMP(X,LVL) [[ assert ignore : X ]]
#else
#define BSLS_ASSERT_DISABLED_IMP(X,LVL)
#endif
#else
#define BSLS_ASSERT_ASSERT_IMP(X,LVL) do { \
if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!(X))) { \
BSLS_PERFORMANCEHINT_UNLIKELY_HINT; \
BloombergLP::bsls::AssertViolation violation( \
#X, \
BSLS_ASSERTIMPUTIL_FILE, \
BSLS_ASSERTIMPUTIL_LINE, \
LVL); \
BloombergLP::bsls::Assert::invokeHandler(violation); \
} \
} while (false)
#if defined(BSLS_PLATFORM_CMP_CLANG)
#define BSLS_ASSERT_ASSUME_IMP(X,LVL) __builtin_assume((X)?true:false)
#define BSLS_ASSERT_ASSUME_ENABLED
#elif defined(BSLS_PLATFORM_CMP_GNU)
// While a common practice with GCC is to implement assumptions using an
// expression of the form 'if (!(X)) __builtin_unreachable();', this idiom
// relies on the expression 'X' being inline and truly sideeffect free before
// GCC will consistently elide the check itself, making this a pessimisation
// when used arbitrarily. Because of this we do not attempt to leverage
// assumption on GCC and leave the following commented out:
//..
// #define BSLS_ASSERT_ASSUME_IMP(X,LVL) if (!(X)) { __builtin_unreachable(); }
// #define BSLS_ASSERT_ASSUME_ENABLED
//..
#elif defined (BSLS_PLATFORM_CMP_MSVC)
#define BSLS_ASSERT_ASSUME_IMP(X,LVL) __assume((X)?true:false)
#define BSLS_ASSERT_ASSUME_ENABLED
#endif
#if !defined(BSLS_ASSERT_ASSUME_IMP)
// The above flavors of 'assumption' are the only available ones that we
// support, and the only platforms where we currently attempt to use
// assumption.
#define BSLS_ASSERT_ASSUME_IMP(X,LVL) BSLS_ASSERT_DISABLED_IMP(X,LVL)
#endif
#ifdef BSLS_ASSERT_VALIDATE_DISABLED_MACROS
#define BSLS_ASSERT_DISABLED_IMP(X,LVL) (void)sizeof((!(X))?true:false)
#else
#define BSLS_ASSERT_DISABLED_IMP(X,LVL)
#endif
#endif
// ================
// BSLS_ASSERT_SAFE
// ================
// Determine if 'BSLS_ASSERT_SAFE' should be active.
// Define the control macros, also usable from client code.
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) \
|| BSLS_ASSERT_NO_ASSERTION_MACROS_DEFINED && ( \
defined(BDE_BUILD_TARGET_SAFE_2) || \
defined(BDE_BUILD_TARGET_SAFE) )
#define BSLS_ASSERT_SAFE_IS_ACTIVE
#elif defined(BSLS_REVIEW_SAFE_IS_ACTIVE)
#define BSLS_ASSERT_SAFE_IS_REVIEW
#elif defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE) && \
!defined(BSLS_REVIEW_OPT_IS_ACTIVE) && \
!defined(BSLS_REVIEW_IS_ACTIVE) && \
!defined(BSLS_REVIEW_SAFE_IS_ACTIVE)
#define BSLS_ASSERT_SAFE_IS_ASSUMED
#endif
// Indicate when 'BSLS_ASSERT_SAFE' arguments will be ODR-used.
#if defined(BSLS_ASSERT_SAFE_IS_REVIEW) || \
defined(BSLS_ASSERT_SAFE_IS_ACTIVE) || \
(defined(BSLS_ASSERT_SAFE_IS_ASSUMED) \
&& defined(BSLS_ASSERT_ASSUME_ENABLED)) || \
defined(BSLS_ASSERT_VALIDATE_DISABLED_MACROS)
#define BSLS_ASSERT_SAFE_IS_USED
#endif
// Define 'BSLS_ASSERT_SAFE' accordingly.
#if defined(BSLS_ASSERT_SAFE_IS_ACTIVE)
#define BSLS_ASSERT_SAFE(X) BSLS_ASSERT_ASSERT_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_SAFE)
#elif defined(BSLS_ASSERT_SAFE_IS_REVIEW)
#define BSLS_ASSERT_SAFE(X) BSLS_REVIEW_REVIEW_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_SAFE)
#elif defined(BSLS_ASSERT_SAFE_IS_ASSUMED)
#define BSLS_ASSERT_SAFE(X) BSLS_ASSERT_ASSUME_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_SAFE)
#else
#define BSLS_ASSERT_SAFE(X) BSLS_ASSERT_DISABLED_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_SAFE)
#endif
// ===========
// BSLS_ASSERT
// ===========
// Determine if 'BSLS_ASSERT' should be active.
// Define the control macros, also usable from client code.
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) || \
defined(BSLS_ASSERT_LEVEL_ASSERT) \
|| BSLS_ASSERT_NO_ASSERTION_MACROS_DEFINED && ( \
defined(BDE_BUILD_TARGET_SAFE_2) || \
defined(BDE_BUILD_TARGET_SAFE) || \
!defined(BDE_BUILD_TARGET_OPT) )
#define BSLS_ASSERT_IS_ACTIVE
#elif defined(BSLS_REVIEW_IS_ACTIVE)
#define BSLS_ASSERT_IS_REVIEW
#elif (defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE) || \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT)) && \
!defined(BSLS_REVIEW_OPT_IS_ACTIVE) && \
!defined(BSLS_REVIEW_IS_ACTIVE) && \
!defined(BSLS_REVIEW_SAFE_IS_ACTIVE)
#define BSLS_ASSERT_IS_ASSUMED
#endif
// Indicate when 'BSLS_ASSERT' arguments will be ODR-used.
#if defined(BSLS_ASSERT_IS_REVIEW) || \
defined(BSLS_ASSERT_IS_ACTIVE) || \
(defined(BSLS_ASSERT_IS_ASSUMED) \
&& defined(BSLS_ASSERT_ASSUME_ENABLED)) || \
defined(BSLS_ASSERT_VALIDATE_DISABLED_MACROS)
#define BSLS_ASSERT_IS_USED
#endif
// Define 'BSLS_ASSERT' accordingly.
#if defined(BSLS_ASSERT_IS_ACTIVE)
#define BSLS_ASSERT(X) BSLS_ASSERT_ASSERT_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_ASSERT)
#elif defined(BSLS_ASSERT_IS_REVIEW)
#define BSLS_ASSERT(X) BSLS_REVIEW_REVIEW_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_ASSERT)
#elif defined(BSLS_ASSERT_IS_ASSUMED)
#define BSLS_ASSERT(X) BSLS_ASSERT_ASSUME_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_ASSERT)
#else
#define BSLS_ASSERT(X) BSLS_ASSERT_DISABLED_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_ASSERT)
#endif
// ===============
// BSLS_ASSERT_OPT
// ===============
// Determine if 'BSLS_ASSERT_OPT' should be active.
// Define the control macros, also usable from client code.
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) || \
defined(BSLS_ASSERT_LEVEL_ASSERT) || \
defined(BSLS_ASSERT_LEVEL_ASSERT_OPT) \
|| BSLS_ASSERT_NO_ASSERTION_MACROS_DEFINED
#define BSLS_ASSERT_OPT_IS_ACTIVE
#elif defined(BSLS_REVIEW_OPT_IS_ACTIVE)
#define BSLS_ASSERT_OPT_IS_REVIEW
#elif (defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE) || \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT) || \
defined(BSLS_ASSERT_LEVEL_ASSUME_OPT)) && \
!defined(BSLS_REVIEW_OPT_IS_ACTIVE) && \
!defined(BSLS_REVIEW_IS_ACTIVE) && \
!defined(BSLS_REVIEW_SAFE_IS_ACTIVE)
#define BSLS_ASSERT_OPT_IS_ASSUMED
#endif
// Indicate when 'BSLS_ASSERT_OPT' arguments will be ODR-used.
#if defined(BSLS_ASSERT_OPT_IS_REVIEW) || \
defined(BSLS_ASSERT_OPT_IS_ACTIVE) || \
(defined(BSLS_ASSERT_OPT_IS_ASSUMED) \
&& defined(BSLS_ASSERT_ASSUME_ENABLED)) || \
defined(BSLS_ASSERT_VALIDATE_DISABLED_MACROS)
#define BSLS_ASSERT_OPT_IS_USED
#endif
// Define 'BSLS_ASSERT_OPT' accordingly.
#if defined(BSLS_ASSERT_OPT_IS_ACTIVE)
#define BSLS_ASSERT_OPT(X) BSLS_ASSERT_ASSERT_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_OPT)
#elif defined(BSLS_ASSERT_OPT_IS_REVIEW)
#define BSLS_ASSERT_OPT(X) BSLS_REVIEW_REVIEW_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_OPT)
#elif defined(BSLS_ASSERT_OPT_IS_ASSUMED)
#define BSLS_ASSERT_OPT(X) BSLS_ASSERT_ASSUME_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_OPT)
#else
#define BSLS_ASSERT_OPT(X) BSLS_ASSERT_DISABLED_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_OPT)
#endif
// ==================
// BSLS_ASSERT_INVOKE
// ==================
// 'BSLS_ASSERT_INVOKE' is always active and never in review mode or disabled.
#define BSLS_ASSERT_INVOKE(X) do { \
BloombergLP::bsls::AssertViolation violation( \
X, \
BSLS_ASSERTIMPUTIL_FILE, \
BSLS_ASSERTIMPUTIL_LINE, \
BloombergLP::bsls::Assert::k_LEVEL_INVOKE); \
BloombergLP::bsls::Assert::invokeHandler(violation); \
} while (false)
// 'BSLS_ASSERT_INVOKE_NORETURN' is always active and guaranteed to never
// return (by calling 'bsls::Assert::failByAbort') even if the installed
// handler does return.
#define BSLS_ASSERT_INVOKE_NORETURN(X) do { \
BloombergLP::bsls::AssertViolation violation( \
X, \
BSLS_ASSERTIMPUTIL_FILE, \
BSLS_ASSERTIMPUTIL_LINE, \
BloombergLP::bsls::Assert::k_LEVEL_INVOKE); \
BloombergLP::bsls::Assert::invokeHandlerNoReturn(violation); \
} while (false)
// ===================================
// BSLS_ASSERT_NORETURN_INVOKE_HANDLER
// ===================================
#ifdef BSLS_ASSERT_ENABLE_NORETURN_FOR_INVOKE_HANDLER
#define BSLS_ASSERT_NORETURN_INVOKE_HANDLER BSLS_ANNOTATION_NORETURN
#else
#define BSLS_ASSERT_NORETURN_INVOKE_HANDLER
#endif
// A nested include guard is needed to support the test driver implementation.
#ifndef BSLS_ASSERT_RECURSIVELY_INCLUDED_TESTDRIVER_GUARD
#define BSLS_ASSERT_RECURSIVELY_INCLUDED_TESTDRIVER_GUARD
namespace BloombergLP {
namespace bsls {
// =====================
// class AssertViolation
// =====================
class AssertViolation {
// This class is an unconstrained *in-core* value-semantic class that
// characterizes the details of a assert failure that has occurred.
// DATA
const char *d_comment_p; // the comment associated with the violation,
// generally representing the expression that
// failed
const char *d_fileName_p; // the name of the file where the violation
// occurred
int d_lineNumber; // the line number where the violation
// occurred
const char *d_assertLevel_p; // the level and type of the violation that
// occurred, generally one of the 'k_LEVEL'
// constants defined in 'bsls::Review' or
// 'bsls::Assert'
public:
// CREATORS
BSLS_KEYWORD_CONSTEXPR
AssertViolation(const char *comment,
const char *fileName,
int lineNumber,
const char *assertLevel);
// Create a 'AssertViolation' with the specified 'comment', 'fileName',
// 'lineNumber', and 'assertLevel'. Note that the supplied
// 'assertLevel' will usually be one of the 'k_LEVEL' constants defined
// in 'bsls::Assert'
// ACCESSORS
const char *assertLevel() const;
// Return the 'assertLevel' attribute of this object.
const char *comment() const;
// Return the 'comment' attribute of this object.
const char *fileName() const;
// Return the 'fileName' attribute of this object.
int lineNumber() const;
// Return the 'lineNumber' attribute of this object.
};
// ============
// class Assert
// ============
class Assert {
// This "utility" class maintains a pointer containing the address of the
// current assertion-failure handler function (of type
// 'Assert::ViolationHandler') and provides methods to administer this
// function pointer. The 'invokeHandler' method calls the
// currently-installed failure handler. This class also provides a suite
// of standard failure-handler functions that are suitable to be installed
// as the current 'Assert::ViolationHandler' function. Note that clients
// are free to install any of these ("off-the-shelf") handlers, or to
// provide their own ("custom") assertion-failure handler functions when
// using this facility. Also note that assertion-failure handler functions
// must not return (i.e., they must 'abort', 'exit', 'terminate', 'throw',
// or hang).
//
// Finally, this class defines the constant strings that are passed as the
// 'reviewLevel' to the 'bsls_review' handler for checks that failed in
// "review mode" (see {Assertion Modes}).
public:
// TYPES
typedef void (*ViolationHandler)(const AssertViolation&);
// 'ViolationHandler' is an alias for a pointer to a function returning
// 'void', and taking, as a parameter a single 'const' reference to a
// 'bsls::AssertViolation' -- e.g.,
//..
// void myHandler(const bsls::AssertViolation&);
//..
typedef void (*Handler)(const char *, const char *, int);
// 'Handler' is an alias for a pointer to a function returning 'void',
// and taking, as parameters, two null-terminated strings and an 'int',
// which is the structure of all assertion-failure handler functions
// supported by this class -- e.g.,
//..
// void myHandler(const char *text, const char *file, int line);
//..
private:
// FRIENDS
friend class AssertFailureHandlerGuard;
// PRIVATE CLASS METHODS
static void setViolationHandlerRaw(Assert::ViolationHandler function);
// Make the specified handler 'function' the current assertion-failure
// handler.
static void setFailureHandlerRaw(Assert::Handler function);
// Make the specified 'function' the current legacy handler and set the
// current assertion-failure handler to 'failOnViolation'.
static void failOnViolation(const AssertViolation& violation);
// Get the 'comment', 'fileName', and 'lineNumber' from the specified
// 'violation' and pass them to the registered 'Handler'. This
// function exists to provide support for the older signature for
// assertion-failure handlers specified by 'Handler'.
public:
// PUBLIC CONSTANTS
// 'assertLevel' Strings
static const char k_LEVEL_SAFE[];
static const char k_LEVEL_OPT[];
static const char k_LEVEL_ASSERT[];
static const char k_LEVEL_INVOKE[];
// PUBLIC CLASS DATA
static const char *k_permitOutOfPolicyReturningAssertionBuildKey;
// This constant has the value "No".
// See {Assertion Handler Policy}.
// CLASS METHODS
// Administrative Methods
static void setViolationHandler(Assert::ViolationHandler function);
// Make the specified violation handler 'function' the current
// assertion-failure handler. This method has no effect if the
// 'lockAssertAdministration' method has been called.
static void setFailureHandler(Assert::Handler function);
// Make the specified handler 'function' the current assertion-failure
// handler. This method has no effect if the
// 'lockAssertAdministration' method has been called.
static void lockAssertAdministration();
// Disable all subsequent calls to 'setFailureHandler'. Note that this
// method has no effect on the behavior of a
// 'AssertFailureHandlerGuard' object.
static Assert::Handler failureHandler();
// Return the address of the currently installed assertion-failure
// handler function if it is a 'Handler' (and not a
// 'ViolationHandler'); otherwise, return 'NULL'.
static Assert::ViolationHandler violationHandler();
// Return the address of the currently installed assertion-failure
// handler function.
// Dispatcher Method (called from within macros)
BSLS_ASSERT_NORETURN_INVOKE_HANDLER
static void invokeHandler(const AssertViolation& violation);
// Invoke the currently installed assertion-failure handler function
// with the specified 'violation'. The behavior is undefined if the
// macro 'BSLS_ASSERT_ENABLE_NORETURN_FOR_INVOKE_HANDLER' is defined,
// and the currently installed assertion-failure handler function
// returns to the caller (i.e., the assertion handler does *not*
// 'abort', 'exit', 'terminate', 'throw', or hang). Note that this
// function is intended for use by the (BSLS) "ASSERT" macros, but may
// also be called by clients directly as needed (preferably with
// 'BSLS_ASSERT_INVOKE'). Also note that the configuration macro
// 'BSLS_ASSERT_ENABLE_NORETURN_FOR_INVOKE_HANDLER' is intended to
// support static analysis tools, which require an annotation to see
// that a failed "ASSERT" prevents further execution of a function with
// "bad" values.
BSLS_ASSERT_NORETURN_INVOKE_HANDLER
static void invokeHandler(const char *text, const char *file, int line);
// !DEPRECATED!: Use 'invokeHandler(const AssertViolation&)' instead.
//
// Invoke the currently installed assertion-failure handler function
// with the specified expression 'text', 'file' name, and 'line' number
// as its arguments. The behavior is undefined if the macro
// 'BSLS_ASSERT_ENABLE_NORETURN_FOR_INVOKE_HANDLER' is defined, and the
// currently installed assertion-failure handler function returns to
// the caller (i.e., the assertion handler does *not* 'abort', 'exit',
// 'terminate', 'throw', or hang). Note that this function is
// deprecated, as the (BSLS) "ASSERT" macros all now use the
// 'bsls::AssertViolation' overload of 'invokeHandler' instead.
BSLS_ANNOTATION_NORETURN
static void invokeHandlerNoReturn(const AssertViolation &violation);
// Invoke the currently installed assertion-failure handler function
// with the specified 'violation'. If the handler returns normally,
// invoke 'bsls::Assert::failByAbort'.
#ifdef BSLS_ASSERT_USE_CONTRACTS
static void invokeLanguageContractHandler(
const std::contract_violation& violation);
// Call 'invokeHandler' with an 'AssertViolation' with properties from
// the specified 'violation'.
#endif
// Standard Assertion-Failure Handlers
BSLS_ANNOTATION_NORETURN
static void failByAbort(const AssertViolation& violation);
// (Default Handler) Emulate the invocation of the standard 'assert'
// macro with a 'false' argument, using the expression 'comment',
// 'file' name, and 'line' number from the specified 'violation' to
// generate a helpful output message and then, after logging,
// unconditionally aborting. Note that this handler function is the
// default installed assertion handler.
BSLS_ANNOTATION_NORETURN
static void failBySleep(const AssertViolation& violation);
// Use the expression 'comment', 'file' name, and 'line' number from
// the specified 'violation' to generate a helpful output message and
// then, after logging, spin in an infinite loop. Note that this
// handler function is useful for hanging a process so that a debugger
// may be attached to it.
BSLS_ANNOTATION_NORETURN
static void failByThrow(const AssertViolation& violation);
// Throw an 'AssertTestException' whose attributes are the 'comemnt',
// 'file', 'line', and 'level' from the specified 'violation' provided
// that 'BDE_BUILD_TARGET_EXC' is defined; otherwise, log an
// appropriate message and abort the program (similar to
// 'failByAbort').
BSLS_ANNOTATION_NORETURN
static void failAbort(const char *comment, const char *file, int line);
// !DEPRECATED!: Use 'failByAbort' instead.
//
// Emulate the invocation of the standard 'assert' macro with a 'false'
// argument, using the specified expression 'comment', 'file' name, and
// 'line' number to generate a helpful output message and then, after
// logging, unconditionally aborting.
BSLS_ANNOTATION_NORETURN
static void failSleep(const char *comment, const char *file, int line);
// !DEPRECATED!: Use 'failBySleep' instead.
//
// Use the specified expression 'comment', 'file' name, and 'line'
// number to generate a helpful output message and then, after logging,
// spin in an infinite loop. Note that this handler function is useful
// for hanging a process so that a debugger may be attached to it.
BSLS_ANNOTATION_NORETURN
static void failThrow(const char *comment, const char *file, int line);
// !DEPRECATED!: Use 'failByThrow' instead.
//
// Throw an 'AssertTestException' whose attributes are the specified
// 'comemnt', 'file', 'line', and 'level' provided that
// 'BDE_BUILD_TARGET_EXC' is defined; otherwise, log an appropriate
// message and abort the program (similar to 'failAbort').
// Assertion Handler Policy Enforcement
static bool abortUponReturningAssertionFailureHandler();
// Return 'true' if 'k_permitOutOfPolicyReturningAssertionBuildKey'
// does not have the value "bsls-PermitOutOfPolicyReturn" or
// 'permitOutOfPolicyReturningFailureHandler' has not previously been
// invoked, and 'false' otherwise. Note that returning 'true'
// indicates that 'bsls::Assert' should abort the task if the currently
// installed assertion-failure handler returns normally (after the
// detection of a failed assertion).
static void permitOutOfPolicyReturningFailureHandler();
// DO NOT USE! It is a violation of Bloomberg policy to invoke this
// function without having prior authorization from senior management.
//
// Allow an assertion handler to return control to the calling function
// (after a failed assertion). The behavior is undefined if
// 'BSLS_ASSERT_ENABLE_NORETURN_FOR_INVOKE_HANDLER' is defined (and
// thus 'invokeHandler' would not be able to return anyway). Note
// that, by default, an assertion handler that attempts to return
// normally will cause the program to be aborted.
//
// Internal Bloomberg users should contact the BDE team if they feel
// their application might need to violate Bloomberg policy by allowing
// the currently installed assertion handler to return normally (after
// a failed assertion).
};
// ===============================
// class AssertFailureHandlerGuard
// ===============================
class AssertFailureHandlerGuard {
// An object of this class saves the current assert handler and installs
// the one specified on construction. On destruction, the original assert
// handler is restored. Note that two objects of this class cannot be
// safely used concurrently from two separate threads (but may of course
// appear sequentially, including in nested blocks and function invocations
// within a single thread). Note that the behavior of objects of this
// class is unaffected by the ('static') 'Assert::lockAssertAdministration'
// method (i.e., the temporary replacement will occur, regardless of
// whether that method has been invoked.)
// DATA
Assert::ViolationHandler d_original; // original handler
Assert::Handler d_legacyOriginal; // original legacy handler
private:
// NOT IMPLEMENTED
AssertFailureHandlerGuard(const AssertFailureHandlerGuard&);
AssertFailureHandlerGuard& operator=(const AssertFailureHandlerGuard&);
public:
// CREATORS
explicit AssertFailureHandlerGuard(Assert::ViolationHandler temporary);
explicit AssertFailureHandlerGuard(Assert::Handler temporary);
// Create a guard object that installs the specified 'temporary'
// failure handler and automatically restores the original handler on
// destruction.
~AssertFailureHandlerGuard();
// Restore the failure handler that was in place when this object was
// created and destroy this guard.
};
} // close package namespace
#ifndef BDE_OPENSOURCE_PUBLICATION // BACKWARD_COMPATIBILITY
// ============================================================================
// BACKWARD COMPATIBILITY
// ============================================================================
// BDE_VERIFY pragma: push
// BDE_VERIFY pragma: -SLM01
// BDE_VERIFY pragma: -CP01
// BDE_VERIFY pragma: -TR04
// BDE_VERIFY pragma: -TR17
#ifndef BDE_OMIT_INTERNAL_DEPRECATED
// =========================
// BDE_ASSERT_H (deprecated)
// =========================
// Active in "Safe Mode"
#define BDE_ASSERT_H(X) BSLS_ASSERT_SAFE(X)
#define BSL_ASSERT_H(X) BSLS_ASSERT_SAFE(X) // introduced during migration
// ===========================
// BDE_ASSERT_CPP (deprecated)
// ===========================
// Active in "Safe Mode" and "Debug Mode"
#define BDE_ASSERT_CPP(X) BSLS_ASSERT(X)
#define BSL_ASSERT_CPP(X) BSLS_ASSERT(X) // introduced during migration
typedef bsls::Assert bdes_Assert;
// This alias is defined for backward compatibility.
typedef bsls::AssertFailureHandlerGuard bdes_AssertFailureHandlerGuard;
// This alias is defined for backward compatibility.
// ==========================
// BSLS_ASSERT_H (deprecated)
// ==========================
// Old 'BSLS_ASSERT' implementation macro that was incorrectly used externally.
#define BSLS_ASSERT_ASSERT(X) BSLS_ASSERT_ASSERT_IMP( \
X, \
BloombergLP::bsls::Assert::k_LEVEL_ASSERT)
#endif // BDE_OMIT_INTERNAL_DEPRECATED
typedef bsls::Assert bsls_Assert;
// This alias is defined for backward compatibility.
typedef bsls::AssertFailureHandlerGuard bsls_AssertFailureHandlerGuard;
// This alias is defined for backward compatibility.
#endif // BDE_OPENSOURCE_PUBLICATION -- BACKWARD_COMPATIBILITY
// BDE_VERIFY pragma: pop
// ============================================================================
// INLINE FUNCTION DEFINITIONS
// ============================================================================
namespace bsls {
// ---------------------
// class AssertViolation
// ---------------------
// CREATORS
BSLS_KEYWORD_CONSTEXPR
inline
AssertViolation::AssertViolation(const char *comment,
const char *fileName,
int lineNumber,
const char *assertLevel)
: d_comment_p((comment == 0) ? "" : comment)
, d_fileName_p((fileName == 0) ? "" : fileName)
, d_lineNumber(lineNumber)
, d_assertLevel_p((assertLevel == 0) ? "" : assertLevel)
{
}
// ACCESSORS
inline
const char *AssertViolation::assertLevel() const
{
return d_assertLevel_p;
}
inline
const char *AssertViolation::comment() const
{
return d_comment_p;
}
inline
const char *AssertViolation::fileName() const
{
return d_fileName_p;
}
inline
int AssertViolation::lineNumber() const
{
return d_lineNumber;
}
} // close package namespace
} // close enterprise namespace
#endif // deeper include guard
// ========================================================
// UNDEFINE THE LOCALLY-SCOPED IMPLEMENTATION DETAIL MACROS
// ========================================================
#undef BSLS_ASSERT_NORETURN_INVOKE_HANDLER
#undef BSLS_ASSERT_NO_ASSERTION_MACROS_DEFINED
#undef BSLS_ASSERT_ASSUME_ENABLED
// =========================================
// IMPLEMENTATION USING THE C++ PREPROCESSOR
// =========================================
//
// At most one of the following build options may be set during the compilation
// of any component that includes 'bsls_assert.h':
//..
// BSLS_ASSERT_LEVEL_ASSERT_SAFE
// BSLS_ASSERT_LEVEL_ASSERT
// BSLS_ASSERT_LEVEL_ASSERT_OPT
// BSLS_ASSERT_LEVEL_NONE
// BSLS_ASSERT_LEVEL_ASSUME_SAFE
// BSLS_ASSERT_LEVEL_ASSUME_ASSERT
// BSLS_ASSERT_LEVEL_ASSUME_OPT
//..
// ----------------------------------------------------------------------------
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) && \
defined(BSLS_ASSERT_LEVEL_ASSERT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_SAFE and ..._LEVEL_ASSERT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) && \
defined(BSLS_ASSERT_LEVEL_ASSERT_OPT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_SAFE and ..._LEVEL_ASSERT_OPT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) && \
defined(BSLS_ASSERT_LEVEL_NONE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_SAFE and ..._LEVEL_NONE
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_OPT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_SAFE and ..._LEVEL_ASSUME_OPT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_SAFE and ..._LEVEL_ASSUME_ASSERT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_SAFE) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_SAFE and ..._LEVEL_ASSUME_SAFE
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT) && \
defined(BSLS_ASSERT_LEVEL_ASSERT_OPT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT and ..._LEVEL_ASSERT_OPT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT) && \
defined(BSLS_ASSERT_LEVEL_NONE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT and ..._LEVEL_NONE
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_OPT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT and ..._LEVEL_ASSUME_OPT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT and ..._LEVEL_ASSUME_ASSERT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT and ..._LEVEL_ASSUME_SAFE
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_OPT) && \
defined(BSLS_ASSERT_LEVEL_NONE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_OPT and ..._LEVEL_NONE
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_OPT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_OPT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_OPT and ..._LEVEL_ASSUME_OPT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_OPT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_OPT and ..._LEVEL_ASSUME_ASSERT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSERT_OPT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSERT_OPT and ..._LEVEL_ASSUME_SAFE
#endif
#if defined(BSLS_ASSERT_LEVEL_NONE) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_OPT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_NONE and ..._LEVEL_ASSUME_OPT
#endif
#if defined(BSLS_ASSERT_LEVEL_NONE) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_NONE and ..._LEVEL_ASSUME_ASSERT
#endif
#if defined(BSLS_ASSERT_LEVEL_NONE) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_NONE and ..._LEVEL_ASSUME_SAFE
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSUME_OPT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSUME_OPT and ..._LEVEL_ASSUME_ASSERT
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSUME_OPT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSUME_OPT and ..._LEVEL_ASSUME_SAFE
#endif
#if defined(BSLS_ASSERT_LEVEL_ASSUME_ASSERT) && \
defined(BSLS_ASSERT_LEVEL_ASSUME_SAFE)
#error incompatible BSLS_ASSERT levels: \
..._LEVEL_ASSUME_ASSERT and ..._LEVEL_ASSUME_SAFE
#endif
#endif
// ----------------------------------------------------------------------------
// Copyright 2018 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------