bsls::Review Class Reference

#include <bsls_review.h>

Detailed Description

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.

This class also provides a suite of standard failure-handler functions that are suitable to be installed as the current Review::ViolationHandler function.

Note

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 ReviewViolations associated with failed BSLS_REVIEW invocations.

See bsls_review

Public Types
typedef bsls::AtomicOperations::AtomicTypes::Int	Count
typedef void(*	ViolationHandler) (const ReviewViolation &)

Static Public Member Functions
static void	setViolationHandler (Review::ViolationHandler function)
static Review::ViolationHandler	violationHandler ()
static void	lockReviewAdministration ()
static int	updateCount (Count *count)
static void	invokeHandler (const ReviewViolation &violation)
static void	failByLog (const ReviewViolation &violation)
static BSLS_ANNOTATION_NORETURN void	failByAbort (const ReviewViolation &violation)
static BSLS_ANNOTATION_NORETURN void	failBySleep (const ReviewViolation &violation)
static BSLS_ANNOTATION_NORETURN void	failByThrow (const ReviewViolation &violation)

Static Public Attributes
static const char	k_LEVEL_SAFE []
static const char	k_LEVEL_OPT []
static const char	k_LEVEL_REVIEW []
static const char	k_LEVEL_INVOKE []

Friends
class	ReviewFailureHandlerGuard

Member Typedef Documentation

Count

typedef bsls::AtomicOperations::AtomicTypes::Int bsls::Review::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.

ViolationHandler

typedef void(* bsls::Review::ViolationHandler) (const ReviewViolation &)

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

Member Function Documentation

failByAbort()

static BSLS_ANNOTATION_NORETURN void bsls::Review::failByAbort ( const ReviewViolation &  violation )

static

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.

failByLog()

static void bsls::Review::failByLog ( const ReviewViolation &  violation )

static

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.

failBySleep()

static BSLS_ANNOTATION_NORETURN void bsls::Review::failBySleep ( const ReviewViolation &  violation )

static

Use the specified violation to generate an output message and then, after logging, spin in an infinite loop.

Note

Note that this handler function is useful for hanging a process so that a debugger may be attached to it.

failByThrow()

static BSLS_ANNOTATION_NORETURN void bsls::Review::failByThrow ( const ReviewViolation &  violation )

static

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

invokeHandler()

static void bsls::Review::invokeHandler ( const ReviewViolation &  violation )

static

Invoke the currently installed review-failure handler function with the specified violation as its argument.

Note

Note that this function is intended for use by the (BSLS) "REVIEW" macros, but may also be called by clients directly as needed.

lockReviewAdministration()

static void bsls::Review::lockReviewAdministration ( )

static

Disable all subsequent calls to setViolationHandler.

Note

Note that this method has no effect on the behavior of a ReviewFailureHandlerGuard object.

setViolationHandler()

static void bsls::Review::setViolationHandler ( Review::ViolationHandler  function )

static

Make the specified handler function the current review-failure handler. This method has no effect if the lockReviewAdministration method has been called.

updateCount()

static int bsls::Review::updateCount ( Count *  count )

static

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.

violationHandler()

static Review::ViolationHandler bsls::Review::violationHandler ( )

static

Return the address of the currently installed review-failure handler function.

Note

Note that the initial value of the review-failure handler is the Review::failByLog method.

Friends And Related Symbol Documentation

ReviewFailureHandlerGuard

friend class ReviewFailureHandlerGuard

friend

Member Data Documentation

k_LEVEL_INVOKE

const char bsls::Review::k_LEVEL_INVOKE[]

static

k_LEVEL_OPT

const char bsls::Review::k_LEVEL_OPT[]

static

k_LEVEL_REVIEW

const char bsls::Review::k_LEVEL_REVIEW[]

static

k_LEVEL_SAFE

const char bsls::Review::k_LEVEL_SAFE[]

static

---

The documentation for this class was generated from the following file:

• bsls_review.h