[#BloombergLP-bsls-Assert]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bsls.adoc[bsls]::Assert
:relfileprefix: ../../
:mrdocs:

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
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

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/Assert/Handler.adoc[`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); `
| xref:BloombergLP/bsls/Assert/ViolationHandler-03.adoc[`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

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/Assert/abortUponReturningAssertionFailureHandler.adoc[`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).
| xref:BloombergLP/bsls/Assert/failAbort.adoc[`failAbort`]  [.small]#[noreturn]#
| *DEPRECATED*: Use `failByAbort` instead.
| xref:BloombergLP/bsls/Assert/failByAbort.adoc[`failByAbort`]  [.small]#[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.
| xref:BloombergLP/bsls/Assert/failBySleep.adoc[`failBySleep`]  [.small]#[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.
| xref:BloombergLP/bsls/Assert/failByThrow.adoc[`failByThrow`]  [.small]#[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`).
| xref:BloombergLP/bsls/Assert/failSleep.adoc[`failSleep`]  [.small]#[noreturn]#
| *DEPRECATED*: Use `failBySleep` instead.
| xref:BloombergLP/bsls/Assert/failThrow.adoc[`failThrow`]  [.small]#[noreturn]#
| *DEPRECATED*: Use `failByThrow` instead.
| xref:BloombergLP/bsls/Assert/failureHandler.adoc[`failureHandler`] 
| Return the address of the currently installed assertion‐failure handler function if it is a `Handler` (and not a `ViolationHandler`); otherwise, return `NULL`.
| xref:BloombergLP/bsls/Assert/invokeHandler-082.adoc[`invokeHandler`] 
| `invokeHandler` overloads
| xref:BloombergLP/bsls/Assert/invokeHandlerNoReturn.adoc[`invokeHandlerNoReturn`]  [.small]#[noreturn]#
| Invoke the currently installed assertion‐failure handler function with the specified `violation`. If the handler returns normally, invoke `bsls::Assert::failByAbort`.
| xref:BloombergLP/bsls/Assert/lockAssertAdministration.adoc[`lockAssertAdministration`] 
| Disable all subsequent calls to `setFailureHandler`. Note that this method has no effect on the behavior of a `AssertFailureHandlerGuard` object.
| xref:BloombergLP/bsls/Assert/permitOutOfPolicyReturningFailureHandler.adoc[`permitOutOfPolicyReturningFailureHandler`] 
| DO NOT USE! It is a violation of Bloomberg policy to invoke this function without having prior authorization from senior management.
| xref:BloombergLP/bsls/Assert/setFailureHandler.adoc[`setFailureHandler`] 
| Make the specified handler `function` the current assertion‐failure handler. This method has no effect if the `lockAssertAdministration` method has been called.
| xref:BloombergLP/bsls/Assert/setViolationHandler.adoc[`setViolationHandler`] 
| Make the specified violation handler `function` the current assertion‐failure handler. This method has no effect if the `lockAssertAdministration` method has been called.
| xref:BloombergLP/bsls/Assert/violationHandler-00.adoc[`violationHandler`] 
| Return the address of the currently installed assertion‐failure handler function.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/Assert/k_LEVEL_ASSERT.adoc[`k_LEVEL_ASSERT`] 
| String identifier ("DBG") for `BSLS_ASSERT` failures.
| xref:BloombergLP/bsls/Assert/k_LEVEL_INVOKE.adoc[`k_LEVEL_INVOKE`] 
| String identifier ("INV") for `BSLS_ASSERT_INVOKE` failures.
| xref:BloombergLP/bsls/Assert/k_LEVEL_OPT.adoc[`k_LEVEL_OPT`] 
| String identifier ("OPT") for `BSLS_ASSERT_OPT` failures.
| xref:BloombergLP/bsls/Assert/k_LEVEL_SAFE.adoc[`k_LEVEL_SAFE`] 
| String identifier ("SAF") for `BSLS_ASSERT_SAFE` failures.
| xref:BloombergLP/bsls/Assert/k_permitOutOfPolicyReturningAssertionBuildKey.adoc[`k_permitOutOfPolicyReturningAssertionBuildKey`] 
| Build key used to enforce assertion handler return policy; has value "No". See {Assertion Handler Policy}.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bsls/AssertFailureHandlerGuard.adoc[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.)
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#