bsls::Assert Class Reference

#include <bsls_assert.h>

Detailed Description

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

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

See bsls_assert

Public Types
typedef void(*	ViolationHandler) (const AssertViolation &)
typedef void(*	Handler) (const char *, const char *, int)

Static Public Member Functions
static void	setViolationHandler (Assert::ViolationHandler function)
static void	setFailureHandler (Assert::Handler function)
static void	lockAssertAdministration ()
static Assert::Handler	failureHandler ()
static Assert::ViolationHandler	violationHandler ()
static BSLS_ASSERT_NORETURN_INVOKE_HANDLER void	invokeHandler (const AssertViolation &violation)
static BSLS_ASSERT_NORETURN_INVOKE_HANDLER void	invokeHandler (const char *text, const char *file, int line)
static BSLS_ANNOTATION_NORETURN void	invokeHandlerNoReturn (const AssertViolation &violation)
static BSLS_ANNOTATION_NORETURN void	failByAbort (const AssertViolation &violation)
static BSLS_ANNOTATION_NORETURN void	failBySleep (const AssertViolation &violation)
static BSLS_ANNOTATION_NORETURN void	failByThrow (const AssertViolation &violation)
static BSLS_ANNOTATION_NORETURN void	failAbort (const char *comment, const char *file, int line)
static BSLS_ANNOTATION_NORETURN void	failSleep (const char *comment, const char *file, int line)
static BSLS_ANNOTATION_NORETURN void	failThrow (const char *comment, const char *file, int line)
static bool	abortUponReturningAssertionFailureHandler ()
static void	permitOutOfPolicyReturningFailureHandler ()

Static Public Attributes
static const char	k_LEVEL_SAFE []
static const char	k_LEVEL_OPT []
static const char	k_LEVEL_ASSERT []
static const char	k_LEVEL_INVOKE []
static const char *	k_permitOutOfPolicyReturningAssertionBuildKey

Friends
class	AssertFailureHandlerGuard

Member Typedef Documentation

Handler

typedef void(* bsls::Assert::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);

ViolationHandler

typedef void(* bsls::Assert::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&);

Member Function Documentation

abortUponReturningAssertionFailureHandler()

static bool bsls::Assert::abortUponReturningAssertionFailureHandler ( )

static

Return true if k_permitOutOfPolicyReturningAssertionBuildKey does not have the value "bsls-PermitOutOfPolicyReturn" or permitOutOfPolicyReturningFailureHandler has not previously been invoked, and false otherwise.

Note

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

static BSLS_ANNOTATION_NORETURN void bsls::Assert::failAbort ( const char *  comment, const char *  file, int  line  )

static

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.

failByAbort()

static BSLS_ANNOTATION_NORETURN void bsls::Assert::failByAbort ( const AssertViolation &  violation )

static

(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

Note that this handler function is the default installed assertion handler.

failBySleep()

static BSLS_ANNOTATION_NORETURN void bsls::Assert::failBySleep ( const AssertViolation &  violation )

static

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

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::Assert::failByThrow ( const AssertViolation &  violation )

static

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

static BSLS_ANNOTATION_NORETURN void bsls::Assert::failSleep ( const char *  comment, const char *  file, int  line  )

static

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

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

failThrow()

static BSLS_ANNOTATION_NORETURN void bsls::Assert::failThrow ( const char *  comment, const char *  file, int  line  )

static

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

failureHandler()

static Assert::Handler bsls::Assert::failureHandler ( )

static

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

invokeHandler() [1/2]

static BSLS_ASSERT_NORETURN_INVOKE_HANDLER void bsls::Assert::invokeHandler ( const AssertViolation &  violation )

static

Invoke the currently installed assertion-failure handler function with the specified violation.

Precondition

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

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.

invokeHandler() [2/2]

static BSLS_ASSERT_NORETURN_INVOKE_HANDLER void bsls::Assert::invokeHandler ( const char *  text, const char *  file, int  line  )

static

Invoke the currently installed assertion-failure handler function with the specified expression text, file name, and line number as its arguments.

Precondition

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

Note that this function is deprecated, as the (BSLS) "ASSERT" macros all now use the bsls::AssertViolation overload of invokeHandler instead.

Deprecated:

Use invokeHandler(const AssertViolation&) instead.

invokeHandlerNoReturn()

static BSLS_ANNOTATION_NORETURN void bsls::Assert::invokeHandlerNoReturn ( const AssertViolation &  violation )

static

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

lockAssertAdministration()

static void bsls::Assert::lockAssertAdministration ( )

static

Disable all subsequent calls to setFailureHandler.

Note

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

permitOutOfPolicyReturningFailureHandler()

static void bsls::Assert::permitOutOfPolicyReturningFailureHandler ( )

static

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

Precondition

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

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

setFailureHandler()

static void bsls::Assert::setFailureHandler ( Assert::Handler  function )

static

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

setViolationHandler()

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

static

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

violationHandler()

static Assert::ViolationHandler bsls::Assert::violationHandler ( )

static

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

Friends And Related Symbol Documentation

AssertFailureHandlerGuard

friend class AssertFailureHandlerGuard

friend

Member Data Documentation

k_LEVEL_ASSERT

const char bsls::Assert::k_LEVEL_ASSERT[]

static

k_LEVEL_INVOKE

const char bsls::Assert::k_LEVEL_INVOKE[]

static

k_LEVEL_OPT

const char bsls::Assert::k_LEVEL_OPT[]

static

k_LEVEL_SAFE

const char bsls::Assert::k_LEVEL_SAFE[]

static

k_permitOutOfPolicyReturningAssertionBuildKey

const char* bsls::Assert::k_permitOutOfPolicyReturningAssertionBuildKey

static

---

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

• bsls_assert.h