Component bsla_warning [Package bsla]

Provide a macro to emit a warning when a function is called. More...

Outline

• Purpose
• Macros
• Description
  • Macro Reference
  • Usage
    • Example 1: Function Annotated with BSLA_WARNING

Purpose:

Provide a macro to emit a warning when a function is called.

Macros:

BSLA_WARNING(QUOTED_MESSAGE)	emit warning message during compilation
BSLA_WARNING_IS_ACTIVE	0 if BSLA_WARNING expands to nothing, else 1

See also:

Component bsla_annotations

Description:

This component provides a macro that indicates that a compiler warning should be emitted when a given function is called.

Macro Reference:

BSLA_WARNING(QUOTED_MESSAGE) This annotation, when used, will cause a compile-time warning containing the specified QUOTED_MESSAGE, which must be a string contained in double quotes, 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.

BSLA_WARNING_IS_ACTIVE The macro BSLA_WARNING_IS_ACTIVE is defined to 0 if BSLA_WARNING expands to nothing and 1 otherwise.

Usage:

This section illustrates intended use of this component.

Example 1: Function Annotated with BSLA_WARNING:

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

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

  void usageFunc()
  {
  }

Now, in main, we call usageFunc:

      usageFunc();

Finally, observe the following warning issued by the compiler:

  .../bsla_warning.t.cpp: In function 'int main(int, char**)':
  .../bsla_warning.t.cpp:246:16: warning: call to 'usageFunc' declared with
  attribute warning: Don't call 'usageFunc'
       usageFunc();
                  ^