macros.h File Reference

#include "rcutils/testing/fault_injection.h"

Include dependency graph for macros.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	RCUTILS_WARN_UNUSED   __attribute__((warn_unused_result))
	A macro to make the compiler warn when the return value of a function is not used. More...
#define	RCUTILS_ATTRIBUTE_PRINTF_FORMAT(format_string_index, first_to_check_index)   __attribute__ ((format(printf, format_string_index, first_to_check_index)))
#define	RCUTILS_DEPRECATED   __attribute__((deprecated))
	Macro to declare deprecation in the platform appropriate manner. More...
#define	RCUTILS_DEPRECATED_WITH_MSG(msg)   __attribute__((deprecated(msg)))
	Macro to declare deprecation in the platform appropriate manner with a message. More...
#define	RCUTILS_LIKELY(x)   __builtin_expect((x), 1)
#define	RCUTILS_UNLIKELY(x)   __builtin_expect((x), 0)
#define	RCUTILS_CAN_RETURN_WITH_ERROR_OF(error_return_value)   RCUTILS_FAULT_INJECTION_MAYBE_RETURN_ERROR(error_return_value);
#define	RCUTILS_CAN_FAIL_WITH(failure_code)   RCUTILS_FAULT_INJECTION_MAYBE_FAIL(failure_code);

Macro Definition Documentation

RCUTILS_WARN_UNUSED

#define RCUTILS_WARN_UNUSED   __attribute__((warn_unused_result))

A macro to make the compiler warn when the return value of a function is not used.

RCUTILS_ATTRIBUTE_PRINTF_FORMAT

#define RCUTILS_ATTRIBUTE_PRINTF_FORMAT	(		format_string_index,
			first_to_check_index
	)		__attribute__ ((format(printf, format_string_index, first_to_check_index)))

Macro to annotate printf-like functions which are relying on a format string and a variable number of arguments. This enables GCC to emit warnings if dangerous patterns are detected. See GCC documentation for details: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html

For the following function:

int snprintf(char *str, size_t size, const char *format, ...);
             ^^^^^^^^^  ^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^  ^^^
             ARG 1      ARG 2        ARG 3               ARG 4
                                     format string       first optional argument

format_string_index value would be 3, first_to_check_index value would be 4.

IMPORTANT: the first argument has an index of ONE (not zero!).

Parameters

[in]	format_string_index	index of the format string passed to the function
[in]	first_to_check_index	index of the first "optional argument"

RCUTILS_DEPRECATED

#define RCUTILS_DEPRECATED   __attribute__((deprecated))

Macro to declare deprecation in the platform appropriate manner.

RCUTILS_DEPRECATED_WITH_MSG

#define RCUTILS_DEPRECATED_WITH_MSG

(

msg

)

__attribute__((deprecated(msg)))

Macro to declare deprecation in the platform appropriate manner with a message.

RCUTILS_LIKELY

#define RCUTILS_LIKELY

(

x

)

__builtin_expect((x), 1)

Instruct the compiler to optimize for the case where the argument equals 1.

RCUTILS_UNLIKELY

#define RCUTILS_UNLIKELY

(

x

)

__builtin_expect((x), 0)

Instruct the compiler to optimize for the case where the argument equals 0.

RCUTILS_CAN_RETURN_WITH_ERROR_OF

#define RCUTILS_CAN_RETURN_WITH_ERROR_OF

(

error_return_value

)

RCUTILS_FAULT_INJECTION_MAYBE_RETURN_ERROR(error_return_value);

Indicating macro that the function intends to return possible error value.

Put this macro as the first line in the function. For example:

int rcutils_function_that_can_fail() { RCUTILS_CAN_RETURN_WITH_ERROR_OF(RCUTILS_RET_INVALID_ARGUMENT); ... // rest of function }

For now, this macro just simply calls RCUTILS_FAULT_INJECTION_MAYBE_RETURN_ERROR if fault injection is enabled. However, for source code, the macro annotation RCUTILS_CAN_RETURN_WITH_ERROR_OF helps clarify that a function may return a value signifying an error and what those are.

In general, you should only include a return value that originates in the function you're annotating instead of one that is merely passed on from a called function already annotated with RCUTILS_CAN_RETURN_WITH_ERROR_OF. If you are passing on return values from a called function, but that function is not annotated with RCUTILS_CAN_RETURN_WITH_ERROR_OF, then you might consider annotating that function first. If for some reason that is not desired or possible, then annotate your function as if the return values you are passing on originated from your function.

If the function can return multiple return values indicating separate failure types, each one should go on a separate line.

If in your function, there are expected effects on output parameters that occur during the failure case, then it will introduce a discrepancy between fault injection testing and production operation. This is because the fault injection will cause the function to return where this macro is used, not at the location the error values are typically returned. To help protect against this scenario you may consider adding unit tests that check your function does not modify output parameters when it actually returns a failing error code if it's possible for your code.

If your function is void, this macro can be used without parameters. However, for the above reasoning, there should be no side effects on output parameters for all possible early returns.

Parameters

error_return_value

the value returned as a result of an error. It does not need to be a rcutils_ret_t type. It could also be NULL, -1, a string error message, etc

RCUTILS_CAN_FAIL_WITH

#define RCUTILS_CAN_FAIL_WITH

(

failure_code

)

RCUTILS_FAULT_INJECTION_MAYBE_FAIL(failure_code);

Indicating macro similar to RCUTILS_CAN_RETURN_WITH_ERROR_OF but for use with more complicated statements.

The failure_code will be executed inside a scoped if block, so any variables declared within will not be available outside of the macro.

One example where you might need this version, is if a side-effect may occur within a function. For example, in snprintf, rcutils_snprintf needs to set both errno and return -1 on failure. This macro is used to capture both effects.

Parameters

failure_code

Code that is representative of the failure case in this function.