Component bsla_error [Package bsla]

Provide a macro to emit an error message when a function is called. More...

Outline

• Purpose
• Macros
• Description
  • Macro Reference
  • Usage
    • Example 1: Flagging a Function for a Compile Failure and Message if Used

Purpose:

Provide a macro to emit an error message when a function is called.

Macros:

BSLA_ERROR(QUOTED_MESSAGE)	emit error message and fail compilation
BSLA_ERROR_IS_ACTIVE	1 if BSLA_ERROR is active and 0 otherwise

See also:

Component bsla_annotations

Description:

This component provides a preprocessor macro that flags a function such that the compile will fail with an error message when the function is called. On platforms where the appropriate attribute is not supported, the macro expands to nothing.

Macro Reference:

BSLA_ERROR(QUOTED_MESSAGE) This annotation, when used, will cause compilation to fail with an error message when a call to the so-annotated function is not removed through dead-code elimination or other optimizations. While it is possible to leave the function undefined, thus incurring a link-time failure, with the use of this macro the invalid call will be diagnosed earlier (i.e., at compile time), and the diagnostic will include the location of the function call. The message QUOTED_MESSAGE, which should be a double-quoted string, will appear in the error message.

BSLA_ERROR_IS_ACTIVE The macro BSLA_ERROR_IS_ACTIVE is defined to 0 if BSLA_ERROR expands to nothing and 1 otherwise.

Usage:

This section illustrates intended use of this component.

Example 1: Flagging a Function for a Compile Failure and Message if Used:

First, we declare and define a function annotated with BSLA_ERROR. Note that the argument to BSLA_ERROR must be a quoted string:

  void usageFunc() BSLA_ERROR("Don't call 'usageFunc'");
      // Do nothing.

  void usageFunc()
  {
  }

Now, we call usageFunc:

  usageFunc();

Finally, observe that the compile fails with the following error message:

  .../bsla_error.t.cpp:226:16: error: call to 'usageFunc' declared with
  attribute error: Don't call 'usageFunc'
       usageFunc();
                  ^