Component bsls_assertimputil [Package bsls]

Provide utilities to implement bsls_assert and bsls_review. More...

Namespaces
namespace	bsls

---

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.