bsla_annotations

Outline

• Purpose
• Macros
• Description
  • Macro Reference
  • Usage

Purpose

Provide support for compiler annotations for compile-time safety.

Macros

• BSLA_DEPRECATED: warn if annotated (deprecated) entity is used
• BSLA_ERROR(QUOTED_MESSAGE): emit error message and fail compilation
• BSLA_FALLTHROUGH: do not warn if switch case falls through
• BSLA_FORMAT(FMT_IDX): validate printf-style format spec in nth argument
• BSLA_MAYBE_UNUSED: suppress compiler warnings on unused entities
• BSLA_NODISCARD: warn if annotated function result is not used
• BSLA_NONNULLARG(...): warn if indexed arguments are NULL
• BSLA_NONNULLARGS: warn if any arguments are NULL
• BSLA_NORETURN: issue a compiler warning if function returns normally
• BSLA_NULLTERMINATED: warn if last argument is non-NULL
• BSLA_NULLTERMINATEDAT(ARG_IDX): warn if argument at ARG_IDX is non-NULL
• BSLA_PRINTF(FMTIDX, STARTIDX): validate printf format and arguments
• BSLA_SCANF(FMTIDX, STARTIDX): validate scanf format and arguments
• BSLA_UNUSED: do not warn if annotated entity is unused
• BSLA_USED: emit annotated entity even if not referenced
• BSLA_WARNING(QUOTED_MESSAGE): emit warning message during compilation
• BSLA_DEPRECATED_IS_ACTIVE: defined if BSLA_DEPRECATED is active
• BSLA_ERROR_IS_ACTIVE: defined if BSLA_ERROR is active
• BSLA_FALLTHROUGH_IS_ACTIVE: defined if BSLA_FALLTHROUGH is active
• BSLA_FORMAT_IS_ACTIVE: defined if BSLA_FORMAT is active
• BSLA_MAYBE_UNUSED_IS_ACTIVE: defined if BSLA_MAYBE_UNUSED is active
• BSLA_NODISCARD_IS_ACTIVE: defined if BSLA_NODISCARD is active
• BSLA_NONNULLARG_IS_ACTIVE: defined if BSLA_NONNULLARG is active
• BSLA_NONNULLARGS_IS_ACTIVE: defined if BSLA_NONNULLARGS is active
• BSLA_NORETURN_IS_ACTIVE: defined if BSLA_NORETURN is active
• BSLA_NULLTERMINATED_IS_ACTIVE: defined if BSLA_NULLTERMINATED is active
• BSLA_NULLTERMINATEDAT_IS_ACTIVE: defined if BSLA_NULLTERMINATEDAT active
• BSLA_PRINTF_IS_ACTIVE: defined if BSLA_PRINTF is active
• BSLA_SCANF_IS_ACTIVE: defined if BSLA_SCANF is active
• BSLA_UNUSED_IS_ACTIVE: defined if BSLA_UNUSED is active
• BSLA_USED_IS_ACTIVE: defined if BSLA_USED is active
• BSLA_WARNING_IS_ACTIVE: defined if BSLA_WARNING is active

Description

This component exists to provide a single component whose header can be included to transitively include all of the annotation macros defined in the bsla package. The macros that are transitively included by this component correspond to various compiler features, and 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 macros are 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.

Macro Reference

BSLA_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.

BSLA_ERROR(QUOTED_MESSAGE): This annotation, when used, will cause a compile-time error 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_FALLTHROUGH: This annotation should be placed in a case clause as the last statement within a flow of control that is expected to allow control to fall through instead of ending with a break, continue, or return. This will prevent compilers from warning about fall-through. The BSLA_FALLTHROUGH must be followed by a semicolon and may be nested within blocks, ifs, or elses.

BSLA_FORMAT(FMT_IDX): This annotation specifies that the so-annotated function takes an argument 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, or fail to generate warnings about mismatched arguments.

BSLA_MAYBE_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.

BSLA_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.

BSLA_NONNULLARGS: This annotation indicates that a compiler warning is to be issued if any of the pointer arguments to this function are passed null.

BSLA_NONNULLARG(...): This annotation, passed a variable-length list of positive integers, indicates that a compiler warning is to be issued if null is passed to a pointer argument at any of the specified indices, where the first argument of the annotated function has an index of 1.

BSLA_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.

BSLA_NULLTERMINATED: This annotation on a variadic macro indicates that a warning should be issued unless the last argument to the function is explicitly NULL.

BSLA_NULLTERMINATEDAT(ARG_IDX): This annotation on a variadic function indicates that a warning should be issued unless the argument at ARG_IDX is NULL, where ARG_IDX is the number of arguments from the last, the last argument having ARG_IDX == 0. Thus, BSLA_NULLTERMINATED is equivalent to BSLA_NULLTERMINATEDAT(0).

BSLA_PRINTF(FMTIDX, STARTIDX): This annotation instructs the compiler to perform additional compile-time checks on so-annotated functions that take printf-style arguments, which should be type-checked against a format string. The FMTIDX parameter is the one-based index to the const char * format string. The STARTIDX 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, ...) BSLA_PRINTF(2, 3);

BSLA_SCANF(FMTIDX, STARTIDX): This annotation instructs the compiler to perform additional checks on so-annotated functions that take scanf-style arguments, which should be type-checked against a format string.

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

extern int my_scanf(void *obj, const char *format, ...) BSLA_SCANF(2, 3);

BSLA_UNREACHABLE: This annotation will, when used, indicate that a given statement in a code path is intended to be unreachable, causing compilers, where supported, to issue warnings if there is actually a way that the code can be reached. Note that the behavior is undefined if control actually reaches a BSLA_UNREACHABLE statement.

BSLA_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.

BSLA_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.

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_DEPRECATED_IS_ACTIVE BSLA_ERROR_IS_ACTIVE BSLA_FALLTHROUGH_IS_ACTIVE BSLA_FORMAT_IS_ACTIVE BSLA_MAYBE_UNUSED_IS_ACTIVE BSLA_NODISCARD_IS_ACTIVE BSLA_NONNULLARG_IS_ACTIVE BSLS_NONNULLARGS_IS_ACTIVE BSLA_NORETURN_IS_ACTIVE BSLA_NULLTERMINATED_IS_ACTIVE BSLA_NULLTERMINATEDAT_IS_ACTIVE BSLA_PRINTF_IS_ACTIVE BSLA_SCANF_IS_ACTIVE BSLA_UNREACHABLE_IS_ACTIVE BSLA_UNUSED_IS_ACTIVE BSLA_USED_IS_ACTIVE BSLA_WARNING_IS_ACTIVE: For each BSLA_{X} macro, there is a BSLA_{X}_IS_ACTIVE macro that is defined only if BSLA_{X} expands to something and has its documented effects.

Usage

See the other bsla components for usage examples for the macros offered (transitively) by this component.