bsls_annotation

Macros
#define	BSLS_ANNOTATION_USED
#define	BSLS_ANNOTATION_UNUSED
#define	BSLS_ANNOTATION_ERROR(x)
#define	BSLS_ANNOTATION_WARNING(x)
#define	BSLS_ANNOTATION_ALLOC_SIZE(x)
#define	BSLS_ANNOTATION_ALLOC_SIZE_MUL(x, y)
#define	BSLS_ANNOTATION_ARG_NON_NULL(...)
#define	BSLS_ANNOTATION_ARGS_NON_NULL
#define	BSLS_ANNOTATION_DEPRECATED
#define	BSLS_ANNOTATION_FORMAT(arg)
#define	BSLS_ANNOTATION_NULL_TERMINATED
#define	BSLS_ANNOTATION_NULL_TERMINATED_AT(x)
#define	BSLS_ANNOTATION_PRINTF(fmt, arg)
#define	BSLS_ANNOTATION_SCANF(fmt, arg)
#define	BSLS_ANNOTATION_WARN_UNUSED_RESULT
#define	BSLS_ANNOTATION_NODISCARD
#define	BSLS_ANNOTATION_NORETURN
#define	BSLS_ANNOTATION_ANALYZER_NORETURN
#define	BSLS_ANNOTATION_FALLTHROUGH

Detailed Description

Outline

• Purpose
• Classes
• Macros
• Description
  • Function Annotations
  • Function, Variable, and Type Annotations
  • Usage

Purpose

Provide support for compiler annotations for compile-time safety.

Classes

Macros

• BSLS_ANNOTATION_ALLOC_SIZE(x): optimize when returning memory
• BSLS_ANNOTATION_ALLOC_SIZE_MUL(x, y): optimize when returning memory
• BSLS_ANNOTATION_ANALYZER_NORETURN: analyzers treat function as noreturn
• BSLS_ANNOTATION_ERROR("msg"): emit error message and fail compilation
• BSLS_ANNOTATION_WARNING("msg"): emit warning message during compilation
• BSLS_ANNOTATION_PRINTF(s, n): validate printf format and arguments
• BSLS_ANNOTATION_SCANF(s, n): validate scanf format and arguments
• BSLS_ANNOTATION_FORMAT(n): validate printf format in nth argument
• BSLS_ANNOTATION_ARG_NON_NULL(...): warn if listed arguments are NULL
• BSLS_ANNOTATION_ARGS_NON_NULL: warn if any arguments are NULL
• BSLS_ANNOTATION_NULL_TERMINATED: warn if last argument is non-NULL
• BSLS_ANNOTATION_NULL_TERMINATED_AT(x): warn if argument at x is non-NULL
• BSLS_ANNOTATION_WARN_UNUSED_RESULT: warn if annotated function result used
• BSLS_ANNOTATION_NODISCARD: warn if annotated function result is not used
• BSLS_ANNOTATION_DEPRECATED: warn if annotated entity is used
• BSLS_ANNOTATION_USED: emit annotated entity even if not referenced
• BSLS_ANNOTATION_UNUSED: do not warn if annotated entity is unused
• BSLS_ANNOTATION_NORETURN: error if function returns normally

• BSLS_ANNOTATION_FALLTHROUGH: do not warn if case fall through

  Deprecated:

  See package bsla.

Description

This component provides a suite of preprocessor macros that define compiler-specific compile-time annotations. These macros, which correspond to various compiler features, can be used to annotate code for specific compile-time safety checks.

For the most part, these compile-time annotations are supported only when the BSLS_PLATFORM_CMP_GNU or BSLS_PLATFORM_CMP_CLANG preprocessor macro is defined. Other compilers may implement a few annotations, but the macros should be expected to work only with compilers for which BSLS_PLATFORM_CMP_GNU or BSLS_PLATFORM_CMP_CLANG is defined.

Function Annotations

The following macros pertain to function declarations (only):

BSLS_ANNOTATION_ALLOC_SIZE(x)
BSLS_ANNOTATION_ALLOC_SIZE_MUL(x, y)

This annotation is used to inform the compiler that the return value of the so-annotated function is the address of an allocated block of memory whose size (in bytes) is given by one or two of the function parameters. Certain compilers use this information to improve the correctness of built-in object-size functions (e.g., __builtin_object_size with BSLS_PLATFORM_CMP_GNU or BSLS_PLATFORM_CMP_CLANG).

The function parameter(s) denoting the size of the block are specified by one or two integer arguments supplied to the macro. The allocated size (in bytes) is either the value of the single function argument or the product of the two arguments. Argument numbering starts at one. For example:

void *my_calloc(size_t, size_t) BSLS_ANNOTATION_ALLOC_SIZE_MUL(1, 2);
void my_realloc(void *, size_t) BSLS_ANNOTATION_ALLOC_SIZE(2);

BSLS_ANNOTATION_ERROR("message")
BSLS_ANNOTATION_WARNING("message")

This annotation, when used, will cause a compile-time error (or warning) 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 exact location of the function call.

BSLS_ANNOTATION_PRINTF(stringIndex, firstToCheck)
BSLS_ANNOTATION_SCANF(stringIndex, firstToCheck)

These annotations perform additional compile-time checks on so-annotated functions that take printf-style arguments, which should be type-checked against a format string.

The stringIndex parameter is the one-based index to the const format string. The firstToCheck parameter is the one-based index to the first variable argument to type-check against that format string. For example:

extern int my_printf(void *obj, const char *format, ...)
                                              BSLS_ANNOTATION_PRINTF(2, 3);

BSLS_ANNOTATION_FORMAT(stringIndex)

This annotation specifies that the so-annotated function takes an argument parameter that is a valid format string for a printf-style function and returns a format string that is consistent with that format. This allows format strings manipulated by translation functions to be checked against arguments. Without this annotation, attempting to manipulate the format string via this kind of function might generate warnings about non-literal formats. For example:

const char *translateFormat(const char *locale, const char *format)
                                                 BSLS_ANNOTATION_FORMAT(2);

On a conforming compiler, this will validate the "Mike" argument against the format specification passed to translateFormat.

 printf(translateFormat("FR", "Name: %s"), "Mike");

BSLS_ANNOTATION_ARG_NON_NULL(...)
BSLS_ANNOTATION_ARGS_NON_NULL

These annotations are used to tell the compiler that a function argument must not be null. If the compiler determines that a null pointer is passed to an argument slot marked by this annotation, a warning is issued. If the BSLS_ANNOTATION_ARG_NON_NULL annotation is used, it expects a variable list of argument slots to be specified. An argument slot is a one-based index of the argument in the function parameters. The BSLS_ANNOTATION_ARGS_NON_NULL annotation specifies that all pointer arguments must not be null.

BSLS_ANNOTATION_NULL_TERMINATED
BSLS_ANNOTATION_NULL_TERMINATED_AT(x)

This annotation ensures that a parameter in a function call is an explicit NULL. The annotation is valid only on variadic functions. By default, the sentinel is located at position 0, the last parameter of the function call. If an optional position is specified, the sentinel must be located at that index, counting backwards from the end of the argument list.

BSLS_ANNOTATION_NODISCARD

This annotation causes a warning to be emitted if the caller of a so-annotated function does not use its return value. This is useful for functions where not checking the result is either a security problem or always a bug, such as with the realloc function.

BSLS_ANNOTATION_WARN_UNUSED_RESULT

This deprecated macro is an older name for BSLS_ANNOTATION_NODISCARD.

BSLS_ANNOTATION_NORETURN

This annotation is used to tell the compiler that a specified function will not return in a normal fashion. The function can still exit via other means such as throwing an exception or aborting the process.

BSLS_ANNOTATION_ANALYZER_NORETURN

This annotation is used to tell static analyzers (particularly clang-tidy) that they should not consider situations where the specified function returns normally. This annotation does not have any impact on actual generated code (where BSLS_ANNOTATION_NORETURN might) and should be used in cases where a function cannot be marked [[noreturn]] but should be treated as such anyway.

BSLS_ANNOTATION_FALLTHROUGH

This annotation should be placed as a the statement before a case in a switch statement that is expceted to allow control to fall through instead of ending with a break, continue, or return. This will prevent compilers from warning about fallthrough.

Function, Variable, and Type Annotations

The following macros pertain to function, variable, and type declarations:

BSLS_ANNOTATION_DEPRECATED

This annotation will, when used, cause a compile-time warning if the so-annotated function, variable, or type is used anywhere within the source file. This is useful, for example, when identifying functions that are expected to be removed in a future version of a library. The warning includes the location of the declaration of the deprecated entity to enable users to find further information about the deprecation, or what they should use instead. For example:

int oldFnc() BSLS_ANNOTATION_DEPRECATED;
int oldFnc();
int (*fncPtr)() = oldFnc;

In the above code, the third line results in a compiler warning.

BSLS_ANNOTATION_USED

This annotation indicates that the so-annotated function, variable, or type must be emitted even if it appears that the variable is not referenced.

BSLS_ANNOTATION_UNUSED

This annotation indicates that the so-annotated function, variable, or type is possibly unused and the compiler should not generate a warning for the unused identifier.

Usage

Function annotations must be specified after the function declaration, prior to the terminating semi-colon:

void function() BSLS_ANNOTATION_ABC BSLS_ANNOTATION_XYZ;

Annotations cannot be specified on function definitions, only on declarations.

Variable annotations must be specified after the variable declaration, prior to the terminating semi-colon:

int foo BSLS_ANNOTATION_ABC BSLS_ANNOTATION_XYZ;

Macro Definition Documentation

BSLS_ANNOTATION_ALLOC_SIZE

#define BSLS_ANNOTATION_ALLOC_SIZE

(

x

)

BSLS_ANNOTATION_ALLOC_SIZE_MUL

#define BSLS_ANNOTATION_ALLOC_SIZE_MUL	(		x,
			y
	)

BSLS_ANNOTATION_ANALYZER_NORETURN

#define BSLS_ANNOTATION_ANALYZER_NORETURN

BSLS_ANNOTATION_ARG_NON_NULL

#define BSLS_ANNOTATION_ARG_NON_NULL

(

...

)

BSLS_ANNOTATION_ARGS_NON_NULL

#define BSLS_ANNOTATION_ARGS_NON_NULL

BSLS_ANNOTATION_DEPRECATED

#define BSLS_ANNOTATION_DEPRECATED

BSLS_ANNOTATION_ERROR

#define BSLS_ANNOTATION_ERROR

(

x

)

BSLS_ANNOTATION_FALLTHROUGH

#define BSLS_ANNOTATION_FALLTHROUGH

BSLS_ANNOTATION_FORMAT

#define BSLS_ANNOTATION_FORMAT

(

arg

)

BSLS_ANNOTATION_NODISCARD

#define BSLS_ANNOTATION_NODISCARD

BSLS_ANNOTATION_NORETURN

#define BSLS_ANNOTATION_NORETURN

BSLS_ANNOTATION_NULL_TERMINATED

#define BSLS_ANNOTATION_NULL_TERMINATED

BSLS_ANNOTATION_NULL_TERMINATED_AT

#define BSLS_ANNOTATION_NULL_TERMINATED_AT

(

x

)

BSLS_ANNOTATION_PRINTF

#define BSLS_ANNOTATION_PRINTF	(		fmt,
			arg
	)

BSLS_ANNOTATION_SCANF

#define BSLS_ANNOTATION_SCANF	(		fmt,
			arg
	)

BSLS_ANNOTATION_UNUSED

#define BSLS_ANNOTATION_UNUSED

BSLS_ANNOTATION_USED

#define BSLS_ANNOTATION_USED

BSLS_ANNOTATION_WARN_UNUSED_RESULT

#define BSLS_ANNOTATION_WARN_UNUSED_RESULT

BSLS_ANNOTATION_WARNING

#define BSLS_ANNOTATION_WARNING

(

x

)