[1/3] eal: add macro to warn for unused function return values
Checks
Commit Message
This patch adds a wrapper macro __rte_warn_unused_result for the
warn_unused_result function attribute.
Marking a function __rte_warn_unused_result will make the compiler
emit a warning in case the caller does not use the function's return
value.
Changes since RFC:
* Include usage recommendation and GCC peculiarities in the macro
documentation.
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: Mattias Rönnblom <mattias.ronnblom@ericsson.com>
---
lib/eal/include/rte_common.h | 25 +++++++++++++++++++++++++
1 file changed, 25 insertions(+)
Comments
> From: Mattias Rönnblom [mailto:mattias.ronnblom@ericsson.com]
> Sent: Monday, 11 April 2022 17.16
>
> This patch adds a wrapper macro __rte_warn_unused_result for the
> warn_unused_result function attribute.
>
> Marking a function __rte_warn_unused_result will make the compiler
> emit a warning in case the caller does not use the function's return
> value.
>
> Changes since RFC:
> * Include usage recommendation and GCC peculiarities in the macro
> documentation.
>
> Acked-by: Bruce Richardson <bruce.richardson@intel.com>
>
> Signed-off-by: Mattias Rönnblom <mattias.ronnblom@ericsson.com>
> ---
> lib/eal/include/rte_common.h | 25 +++++++++++++++++++++++++
> 1 file changed, 25 insertions(+)
>
> diff --git a/lib/eal/include/rte_common.h
> b/lib/eal/include/rte_common.h
> index 4a399cc7c8..67587025ab 100644
> --- a/lib/eal/include/rte_common.h
> +++ b/lib/eal/include/rte_common.h
> @@ -222,6 +222,31 @@ static void
> __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)
> */
> #define __rte_noreturn __attribute__((noreturn))
>
> +/**
> + * Issue a warning in case the function's return value is ignored.
> + *
> + * The use of this attribute should be restricted to cases where
> + * ignoring the marked function's return value is almost always a
> + * bug. With GCC, some effort is required to make clear that ignoring
> + * the return value is intentional. The usual void-casting method to
> + * mark something unused as used does not suppress the warning with
> + * this compiler.
> + *
> + * @code{.c}
> + * __rte_warn_unused_result int foo();
> + *
> + * void ignore_foo_result(void) {
> + * foo(); // generates a warning with all compilers
> + *
> + * (void)foo(); // still generates the warning with GCC (but
> not clang)
> + *
> + * int unused __rte_unused;
> + * unused = foo(); // does the trick with all compilers
> + * }
> + * @endcode
> + */
> +#define __rte_warn_unused_result __attribute__((warn_unused_result))
> +
> /**
> * Force a function to be inlined
> */
> --
> 2.25.1
>
Nice! If only all functions were that well documented. :-)
Reviewed-by: Morten Brørup <mb@smartsharesystems.com>
@@ -222,6 +222,31 @@ static void __attribute__((destructor(RTE_PRIO(prio)), used)) func(void)
*/
#define __rte_noreturn __attribute__((noreturn))
+/**
+ * Issue a warning in case the function's return value is ignored.
+ *
+ * The use of this attribute should be restricted to cases where
+ * ignoring the marked function's return value is almost always a
+ * bug. With GCC, some effort is required to make clear that ignoring
+ * the return value is intentional. The usual void-casting method to
+ * mark something unused as used does not suppress the warning with
+ * this compiler.
+ *
+ * @code{.c}
+ * __rte_warn_unused_result int foo();
+ *
+ * void ignore_foo_result(void) {
+ * foo(); // generates a warning with all compilers
+ *
+ * (void)foo(); // still generates the warning with GCC (but not clang)
+ *
+ * int unused __rte_unused;
+ * unused = foo(); // does the trick with all compilers
+ * }
+ * @endcode
+ */
+#define __rte_warn_unused_result __attribute__((warn_unused_result))
+
/**
* Force a function to be inlined
*/