]> Savannah Git Hosting - gnulib.git/commitdiff
attribute: Clarify list of attributes.
authorBruno Haible <bruno@clisp.org>
Sun, 10 May 2020 17:18:44 +0000 (19:18 +0200)
committerBruno Haible <bruno@clisp.org>
Sun, 10 May 2020 17:18:44 +0000 (19:18 +0200)
* lib/attribute.h: Reorder the list of attributes, and group them by
purpose.

ChangeLog
lib/attribute.h

index 111cf89def97672a01a05c4ab740458bc25486ae..019e45bec4bbb13ad838aeab750b94bffede2d2b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2020-05-10  Bruno Haible  <bruno@clisp.org>
+
+       attribute: Clarify list of attributes.
+       * lib/attribute.h: Reorder the list of attributes, and group them by
+       purpose.
+
 2020-05-10  Bruno Haible  <bruno@clisp.org>
 
        string: Fix compilation error in C++ mode.
index 3bd23faae0e69cb1d990bee069a6a226a319bd7a..e9a81bba69cbbbcf46e48a457fa41068f3b40e06 100644 (file)
 #define _GL_ATTRIBUTE_H
 
 
-/* C2X standard attributes have macro names that do not begin with
-   'ATTRIBUTE_'.  */
+/* This file defines two types of attributes:
+   * C2X standard attributes.  These have macro names that do not begin with
+     'ATTRIBUTE_'.
+   * Selected GCC attributes; see:
+     https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
+     https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
+     https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
+     These names begin with 'ATTRIBUTE_' to avoid name clashes.  */
+
+
+/* =============== Attributes for specific kinds of functions =============== */
+
+/* Attributes for functions that should not be used.  */
 
 /* Warn if the entity is used.  */
 /* Applies to:
    in C++ also: namespace, class, template specialization.  */
 #define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
 
-/* Do not warn if control flow falls through to the immediately
-   following 'case' or 'default' label.  */
-/* Applies to: Empty statement (;), inside a 'switch' statement.  */
-#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
+/* If a function call is not optimized way, warn with MSG.  */
+/* Applies to: functions.  */
+#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
 
-/* Do not warn if the entity is not used.  */
-/* Applies to:
-     - function, variable,
-     - struct, union, struct/union member,
-     - enumeration, enumeration item,
-     - typedef,
-   in C++ also: class.  */
-#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
+/* If a function call is not optimized way, report an error with MSG.  */
+/* Applies to: functions.  */
+#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
 
-/* Warn if the caller does not use the return value,
-   unless the caller uses something like ignore_value.  */
-/* Applies to: function, enumeration, class.  */
-#define NODISCARD _GL_ATTRIBUTE_NODISCARD
 
+/* Attributes for memory-allocating functions.  */
 
-/* Selected GCC attributes; see:
-   https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
-   https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
-   https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
-   These names begin with 'ATTRIBUTE_' to avoid name clashes.  */
+/* The function returns a pointer to freshly allocated memory.  */
+/* Applies to: functions.  */
+#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
 
 /* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function
    is the size of the returned memory block.
 /* Applies to: function, pointer to function, function types.  */
 #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
 
-/* Always inline the function, and report an error if the compiler
-   cannot inline.  */
-/* Applies to: function.  */
-#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
 
-/* Omit the function from stack traces when debugging.  */
-/* Applies to: function.  */
-#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
+/* Attributes for variadic functions.  */
 
-/* The function is rarely executed.  */
+/* The variadic function expects a trailing NULL argument.
+   ATTRIBUTE_SENTINEL () - The last argument is NULL.
+   ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL.  */
 /* Applies to: functions.  */
-#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
+#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
 
-/* The function neither depends on nor affects observable state,
-   and always returns a value.  Compilers can omit duplicate calls with
-   the same arguments.  (This attribute is stricter than ATTRIBUTE_PURE.)  */
-/* Applies to: functions.  */
-#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
 
-/* If a function call is not optimized way, report an error with MSG.  */
-/* Applies to: functions.  */
-#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
+/* ================== Attributes for compiler diagnostics ================== */
 
-/* Make the entity visible to debuggers etc., even with '-fwhole-program'.  */
-/* Applies to: functions, variables.  */
-#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
+/* Attributes that help the compiler diagnose programmer mistakes.  */
 
 /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
    The STRING-INDEXth function argument is a format string of style
 /* Applies to: functions.  */
 #define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
 
-/* If called from some other compilation unit, the function executes
-   code from that unit only by return or by exception handling,
-   letting the compiler optimize that unit more aggressively.  */
+/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
+   ATTRIBUTE_NONNULL () - All pointer arguments must not be null.  */
 /* Applies to: functions.  */
-#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
-
-/* Pointers to the type may point to the same storage as pointers to
-   other types, thus disabling strict aliasing optimization.  */
-/* Applies to: types.  */
-#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
+#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
 
-/* The function returns a pointer to freshly allocated memory.  */
+/* The function's return value is a non-NULL pointer.  */
 /* Applies to: functions.  */
-#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
+#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
 
-/* Do not inline the function.  */
-/* Applies to: functions.  */
-#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
+/* Warn if the caller does not use the return value,
+   unless the caller uses something like ignore_value.  */
+/* Applies to: function, enumeration, class.  */
+#define NODISCARD _GL_ATTRIBUTE_NODISCARD
 
-/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL.
-   ATTRIBUTE_NONNULL () - All pointer arguments must not be null.  */
-/* Applies to: functions.  */
-#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
+
+/* Attributes that disable false alarms when the compiler diagnoses
+   programmer "mistakes".  */
+
+/* Do not warn if the entity is not used.  */
+/* Applies to:
+     - function, variable,
+     - struct, union, struct/union member,
+     - enumeration, enumeration item,
+     - typedef,
+   in C++ also: class.  */
+#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
 
 /* The contents of a character array is not meant to be NUL-terminated.  */
 /* Applies to: struct/union members and variables that are arrays of element
    type '[[un]signed] char'.  */
 #define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
 
+/* Do not warn if control flow falls through to the immediately
+   following 'case' or 'default' label.  */
+/* Applies to: Empty statement (;), inside a 'switch' statement.  */
+#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
+
+
+/* ================== Attributes for debugging information ================== */
+
+/* Attributes regarding debugging information emitted by the compiler.  */
+
+/* Omit the function from stack traces when debugging.  */
+/* Applies to: function.  */
+#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
+
+/* Make the entity visible to debuggers etc., even with '-fwhole-program'.  */
+/* Applies to: functions, variables.  */
+#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
+
+
+/* ========== Attributes that mainly direct compiler optimizations ========== */
+
 /* The function does not throw exceptions.  */
 /* Applies to: functions.  */
 #define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
 
-/* For struct members: The member has the smallest possible alignment.
-   For struct, union, class: All members have the smallest possible alignment,
-   minimizing the memory required.  */
-/* Applies to: struct members, struct, union,
-   in C++ also: class.  */
-#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
+/* Do not inline the function.  */
+/* Applies to: functions.  */
+#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
+
+/* Always inline the function, and report an error if the compiler
+   cannot inline.  */
+/* Applies to: function.  */
+#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
 
 /* The function does not affect observable state, and always returns a value.
    Compilers can omit duplicate calls with the same arguments if
 /* Applies to: functions.  */
 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
 
-/* The function's return value is a non-NULL pointer.  */
+/* The function neither depends on nor affects observable state,
+   and always returns a value.  Compilers can omit duplicate calls with
+   the same arguments.  (This attribute is stricter than ATTRIBUTE_PURE.)  */
 /* Applies to: functions.  */
-#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
+#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
 
-/* The variadic function expects a trailing NULL argument.
-   ATTRIBUTE_SENTINEL () - The last argument is NULL.
-   ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is NULL.  */
+/* The function is rarely executed.  */
 /* Applies to: functions.  */
-#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
+#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
 
-/* If a function call is not optimized way, warn with MSG.  */
+/* If called from some other compilation unit, the function executes
+   code from that unit only by return or by exception handling,
+   letting the compiler optimize that unit more aggressively.  */
 /* Applies to: functions.  */
-#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
+#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
+
+/* For struct members: The member has the smallest possible alignment.
+   For struct, union, class: All members have the smallest possible alignment,
+   minimizing the memory required.  */
+/* Applies to: struct members, struct, union,
+   in C++ also: class.  */
+#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
+
+
+/* ================ Attributes that make invalid code valid ================ */
+
+/* Attributes that prevent fatal compiler optimizations for code that is not
+   fully ISO C compliant.  */
+
+/* Pointers to the type may point to the same storage as pointers to
+   other types, thus disabling strict aliasing optimization.  */
+/* Applies to: types.  */
+#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
 
 
 #endif /* _GL_ATTRIBUTE_H */