bsls_assertimputil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • BSLS_ASSERTIMPUTIL_AVOID_STRING_CONSTANTS
  • Usage
    • Example 1: Aborting the Current Process
    • Example 2: Sleeping Forever

Purpose

Provide utilities to implement bsls_assert and bsls_review .

Classes

• bsls::AssertImpUtil: namespace for shared assert and review functions

Description

This component defines a struct, bsls::AssertImpUtil, that serves as a namespace for shared functions used by the various handlers provided by bsls_assert and bsls_review .

BSLS_ASSERTIMPUTIL_AVOID_STRING_CONSTANTS

On some platforms the string constants used to pass filenames to the assert macro invocations are not coalesced, so each inline function use containing such a macro puts an extra copy of the filename string into the resulting executable. For these platforms, it is possible to locally alter the filename that assert macros will use by altering the definition of BSLS_ASSERTIMPUTIL_FILE.

At the start of your component header, after all other include directives, place the following block of code to detect if this is a platform where the workaround is needed and apply it:

// my_component.h
// ...
// 'BSLS_ASSERT' filename fix -- See {bsls_assertimputil}
#ifdef BSLS_ASSERTIMPUTIL_AVOID_STRING_CONSTANTS
extern const char s_my_component_h[];
#undef BSLS_ASSERTIMPUTIL_FILE
#define BSLS_ASSERTIMPUTIL_FILE BloombergLP::s_my_component_h
#endif

Then, at the end of your header revert the definition of the filename macro to its default:

// Undo 'BSLS_ASSERT' filename fix -- See {bsls_assertimputil}
#ifdef BSLS_ASSERTIMPUTIL_AVOID_STRING_CONSTANTS
#undef BSLS_ASSERTIMPUTIL_FILE
#define BSLS_ASSERTIMPUTIL_FILE BSLS_ASSERTIMPUTIL_DEFAULTFILE
#endif

Finally, in the .cpp file add the following:

// 'BSLS_ASSERT' filename fix -- See {bsls_assertimputil}
#ifdef BSLS_ASSERTIMPUTIL_AVOID_STRING_CONSTANTS
extern const char s_my_component_h[] = "my_component.h";
#endif

Note that these constants should all be in an appropriate namespace and should have names and contents that match your actual component name.

Usage

This section illustrates the intended use of this component.

Example 1: Aborting the Current Process

Suppose you are implementing an assertion handler that should cause a process to terminate when invoked. In order to stop the process immediately, you would call failByAbort like this:

void myAbort()
{
    bsls::AssertImpUtil::failByAbort();
    // This code should never be reached.
}

This function would then abort the current process.

Example 2: Sleeping Forever

Suppose you want a process to no longer continue doing anything, but you want to leave it running in order to attach a debugger to it and diagnose the full state of your system. In order to have your process sleep forever, you might call failBySleep like this:

void mySleep()
{
    bsls::AssertImpUtil::failBySleep();
    // This code should never be reached.
}

This function would then sleep forever and never return.