#include <bsls_assert.h>

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 void	invokeHandler (const AssertViolation &violation)
static 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

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 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 Component bsls_assert

Member Typedef Documentation

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

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

Member Function Documentation

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.

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.

static void bsls::Assert::lockAssertAdministration ( ) [static]

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

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.

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

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

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

Invoke the currently installed assertion-failure handler function with the specified violation. 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 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.

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

DEPRECATED: Use invokeHandler(const AssertViolation&) instead.

Invoke the currently installed assertion-failure handler function with the specified expression text, file name, and line number as its arguments. 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 that this function is deprecated, as the (BSLS) "ASSERT" macros all now use the bsls::AssertViolation overload of invokeHandler instead.

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.

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 that this handler function is the default installed assertion handler.

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 that this handler function is useful for hanging a process so that a debugger may be attached to it.

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

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.

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 that this handler function is useful for hanging a process so that a debugger may be attached to it.

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

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

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