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

This "utility" class maintains a pointer containing the address of the current review‐failure handler function (of type `Review::ViolationHandler`) and provides methods to administer this function pointer. The `invokeHandler` method calls the currently‐installed failure handler. The default installed handler is the `Review::failByLog` function.

== Synopsis

Declared in `<bsls_review.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Review;
----

== Description

This class also provides a suite of standard failure‐handler functions that are suitable to be installed as the current `Review::ViolationHandler` function. Note that clients are free to install any of these ("off‐the‐shelf") handlers, or to provide their own ("custom") review‐failure handler function when using this facility. Also note that review‐failure handlers CAN return, unlike assertion failure handlers, though not returning (thus escalating review behavior implicitly to the level of asserts) is acceptable.

Finally, this class defines the constant strings that are used as the `reviewLevel` in `ReviewViolation`s associated with failed `BSLS_REVIEW` invocations.

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/Review/Count.adoc[`Count`] 
| `Count` is an alias for an atomic integer. All `bsls_review` macros declare a static local `Count` variable that is used to track how many times that review has failed. This count gets updated through the `bsls::Review::updateCount` function.
| xref:BloombergLP/bsls/Review/ViolationHandler-06.adoc[`ViolationHandler`] 
| `ViolationHandler` is an alias for a pointer to a function returning `void`, and taking, as a parameter, a `const` reference to a `ReviewViolation` instance. For example: ` void myHandler(const ReviewViolation& violation); `
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/Review/failByAbort.adoc[`failByAbort`]  [.small]#[noreturn]#
| Emulate the invocation of the standard `assert` macro with a `false` argument, using the specified `violation` to generate an output message and then, after logging, unconditionally abort.
| xref:BloombergLP/bsls/Review/failByLog.adoc[`failByLog`] 
| Log a message to `stdout` that an assertion has failed with information on the failure from the specified `violation`. A suitably formatted "cheap stack" is included in the log message that identifies the call site where the failure occurred.
| xref:BloombergLP/bsls/Review/failBySleep.adoc[`failBySleep`]  [.small]#[noreturn]#
| Use the specified `violation` to generate an 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/Review/failByThrow.adoc[`failByThrow`]  [.small]#[noreturn]#
| Throw an `AssertTestException` (whose attributes are `comment`, `filename`, and `lineNumber` 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/Review/invokeHandler.adoc[`invokeHandler`] 
| Invoke the currently installed review‐failure handler function with the specified `violation` as its argument. Note that this function is intended for use by the (BSLS) "REVIEW" macros, but may also be called by clients directly as needed.
| xref:BloombergLP/bsls/Review/lockReviewAdministration.adoc[`lockReviewAdministration`] 
| Disable all subsequent calls to `setViolationHandler`. Note that this method has no effect on the behavior of a `ReviewFailureHandlerGuard` object.
| xref:BloombergLP/bsls/Review/setViolationHandler.adoc[`setViolationHandler`] 
| Make the specified handler `function` the current review‐failure handler. This method has no effect if the `lockReviewAdministration` method has been called.
| xref:BloombergLP/bsls/Review/updateCount.adoc[`updateCount`] 
| Increment the specified `count` and return the new value. Instead of overflowing, when the value is sufficiently large, decrement the value so that large values repeat periodically.
| xref:BloombergLP/bsls/Review/violationHandler-05.adoc[`violationHandler`] 
| Return the address of the currently installed review‐failure handler function. Note that the initial value of the review‐failure handler is the `Review::failByLog` method.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/Review/k_LEVEL_INVOKE.adoc[`k_LEVEL_INVOKE`] 
| String identifier ("R‐INV") for `BSLS_REVIEW_INVOKE` failures.
| xref:BloombergLP/bsls/Review/k_LEVEL_OPT.adoc[`k_LEVEL_OPT`] 
| Command‐line option name for the review level setting.
| xref:BloombergLP/bsls/Review/k_LEVEL_REVIEW.adoc[`k_LEVEL_REVIEW`] 
| String identifier ("R‐DBG") for `BSLS_REVIEW` failures.
| xref:BloombergLP/bsls/Review/k_LEVEL_SAFE.adoc[`k_LEVEL_SAFE`] 
| String identifier for the safe review level.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bsls/ReviewFailureHandlerGuard.adoc[BloombergLP::bsls::ReviewFailureHandlerGuard]`
| An object of this class saves the current review handler and installs the one specified on construction. On destruction, the original review 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`) `Review::lockReviewAdministration` method (i.e., the temporary replacement will occur, regardless of whether that method has been invoked).
|===


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