bsla_error

Macros
#define	BSLA_ERROR(QUOTED_MESSAGE)

Detailed Description

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: defined if BSLA_ERROR is active

See also

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 if BSLA_ERROR expands to something with the desired effect; otherwise BSLA_ERROR_IS_ACTIVE is not defined and BSLA_ERROR expands to nothing.

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

Macro Definition Documentation

BSLA_ERROR

#define BSLA_ERROR

(

QUOTED_MESSAGE

)