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).

Synopsis

Declared in <bsls_assert.h>

class Assert;

Description

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}).

Type Aliases

Name

Description

Handler

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); `

ViolationHandler

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&); `

Static Member Functions

Name

Description

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).

failAbort [noreturn]

DEPRECATED: Use failByAbort instead.

failByAbort [noreturn]

(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.

failBySleep [noreturn]

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.

failByThrow [noreturn]

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).

failSleep [noreturn]

DEPRECATED: Use failBySleep instead.

failThrow [noreturn]

DEPRECATED: Use failByThrow instead.

failureHandler

Return the address of the currently installed assertion‐failure handler function if it is a Handler (and not a ViolationHandler); otherwise, return NULL.

invokeHandler

invokeHandler overloads

invokeHandlerNoReturn [noreturn]

Invoke the currently installed assertion‐failure handler function with the specified violation. If the handler returns normally, invoke bsls::Assert::failByAbort.

lockAssertAdministration

Disable all subsequent calls to setFailureHandler. Note that this method has no effect on the behavior of a AssertFailureHandlerGuard object.

permitOutOfPolicyReturningFailureHandler

DO NOT USE! It is a violation of Bloomberg policy to invoke this function without having prior authorization from senior management.

setFailureHandler

Make the specified handler function the current assertion‐failure handler. This method has no effect if the lockAssertAdministration method has been called.

setViolationHandler

Make the specified violation handler function the current assertion‐failure handler. This method has no effect if the lockAssertAdministration method has been called.

violationHandler

Return the address of the currently installed assertion‐failure handler function.

Static Data Members

Name

Description

k_LEVEL_ASSERT

String identifier ("DBG") for BSLS_ASSERT failures.

k_LEVEL_INVOKE

String identifier ("INV") for BSLS_ASSERT_INVOKE failures.

k_LEVEL_OPT

String identifier ("OPT") for BSLS_ASSERT_OPT failures.

k_LEVEL_SAFE

String identifier ("SAF") for BSLS_ASSERT_SAFE failures.

k_permitOutOfPolicyReturningAssertionBuildKey

Build key used to enforce assertion handler return policy; has value "No". See {Assertion Handler Policy}.

Friends

Name

Description

BloombergLP::bsls::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.)

Created with MrDocs