Fault injection macros and functionality (plus example)

CMakeLists.txt

@@ -51,6 +51,7 @@ set(rcutils_sources
   src/strerror.c
   src/string_array.c
   src/string_map.c
+  src/testing/fault_injection.c
   src/time.c
   ${time_impl_c}
   src/uint8_array.c

Doxyfile

@@ -24,6 +24,7 @@ EXPAND_ONLY_PREDEF     = YES
 PREDEFINED             += RCUTILS_PUBLIC=
 PREDEFINED             += RCUTILS_PUBLIC_TYPE=
 PREDEFINED             += RCUTILS_WARN_UNUSED=
+PREDEFINED             += RCUTILS_ENABLE_FAULT_INJECTION=
 
 # Tag files that do not exist will produce a warning and cross-project linking will not work.
 TAGFILES += "../../../doxygen_tag_files/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"

include/rcutils/error_handling.h

@@ -36,6 +36,7 @@ extern "C"
 #include "rcutils/allocator.h"
 #include "rcutils/macros.h"
 #include "rcutils/snprintf.h"
+#include "rcutils/testing/fault_injection.h"
 #include "rcutils/types/rcutils_ret.h"
 #include "rcutils/visibility_control.h"
 

include/rcutils/macros.h

@@ -131,6 +131,55 @@ extern "C"
 # define RCUTILS_UNLIKELY(x) (x)
 #endif  // _WIN32
 
+#if defined RCUTILS_ENABLE_FAULT_INJECTION
+#include "rcutils/testing/fault_injection.h"
+
+/**
+ * \def RCUTILS_CAN_RETURN_WITH_ERROR_OF
+ * 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_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 discrepency 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 checks your function does
+ * not modify output parameters when it actually returns a failing error 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.
+ *
+ * \param 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
+ */
+# define RCUTILS_CAN_RETURN_WITH_ERROR_OF(error_return_value) \
+  RCUTILS_MAYBE_RETURN_ERROR(error_return_value);
+
+#else
+# define RCUTILS_CAN_RETURN_WITH_ERROR_OF(error_return_value)
+#endif  // defined RCUTILS_ENABLE_FAULT_INJECTION
+
 #ifdef __cplusplus
 }
 #endif

include/rcutils/testing/fault_injection.h

@@ -0,0 +1,90 @@
+// Copyright 2020 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef RCUTILS__TESTING_MACROS_H_
+#define RCUTILS__TESTING_MACROS_H_
+#include <stdio.h>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+void _rcutils_set_fault_injection_count(int count);
+
+int _rcutils_maybe_fail();
+
+#if defined RCUTILS_ENABLE_FAULT_INJECTION
+
+/**
+ * \def RCUTILS_MAYBE_RETURN_ERROR
+ * \brief This macro checks and decrements a static global variable atomic counter and returns
+ * `return_value_on_error` if 0.
+ *
+ * This macro is not a function itself, so when this macro returns it will cause the calling
+ * function to return with the return value.
+ *
+ * Set the counter with `RCUTILS_SET_FAULT_INJECTION_COUNT`. If the count is less than 0, then
+ * `RCUTILS_MAYBE_RETURN_ERROR` will not cause an early return.
+ *
+ * This macro is thread-safe, and ensures that at most one invocation results in a failure for each
+ * time the fault injection counter is set with `RCUTILS_SET_FAULT_INJECTION_COUNT`
+ *
+ * \param return_value_on_error the value to return in the case of fault injected failure.
+ */
+#define RCUTILS_MAYBE_RETURN_ERROR(return_value_on_error) \
+  if (0 == _rcutils_maybe_fail()) { \
+    return return_value_on_error; \
+  }
+
+/**
+ * \def RCUTILS_SET_FAULT_INJECTION_COUNT
+ * \brief Atomically set the fault injection counter.
+ *
+ * There will be at most one fault injected failure per call to RCUTILS_SET_FAULT_INJECTION_COUNT.
+ * To test all reachable fault injection locations, call this macro inside a for loop with
+ * sufficient iterations setting count to the loop iteration variable. For example:
+ *
+ *  for (int i = 0; i < SUFFICIENTLY_LARGE_ITERATION_COUNT; ++i) {
+ *    RCUTILS_SET_FAULT_INJECTION_COUNT(i);
+ *    ... // Call function under test
+ *  }
+ *
+ * Where SUFFICIENTLY_LARGE_ITERATION_COUNT is a value larger than the maximum expected calls to
+ * `RCUTILS_MAYBE_RETURN_ERROR`. In your fault injection unit test, it is recommended to run one
+ * last iteration with the fault injection counter set to this maximum value and validate that the
+ * results of the call to the function under test would result in the same thing as if no fault
+ * injection was used. This will help ensure that this maximum value is suitable and will call
+ * attention to maintainers if it needs to be increased because more instances of
+ * RCUTILS_MAYBE_RETURN_ERROR were introduced.
+ *
+ * \param count The count to set the fault injection counter to. If count is negative, then fault
+ * injection errors will be disabled. The counter is globally initialized to -1.
+ */
+#define RCUTILS_SET_FAULT_INJECTION_COUNT(count) \
+  _rcutils_set_fault_injection_count(count);
+
+#else  // RCUTILS_ENABLE_FAULT_INJECTION
+
+#define RCUTILS_SET_FAULT_INJECTION_COUNT(count)
+
+#define RCUTILS_MAYBE_RETURN_ERROR(msg, error_statement)
+
+#endif  // defined RCUTILS_ENABLE_FAULT_INJECTION
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RCUTILS__TESTING_MACROS_H_

src/snprintf.c

@@ -39,6 +39,8 @@ rcutils_snprintf(char * buffer, size_t buffer_size, const char * format, ...)
 int
 rcutils_vsnprintf(char * buffer, size_t buffer_size, const char * format, va_list args)
 {
+  RCUTILS_CAN_RETURN_WITH_ERROR_OF(-1);
+
   if (NULL == format) {
     errno = EINVAL;
     return -1;

src/testing/fault_injection.c

@@ -0,0 +1,44 @@
+// Copyright 2020 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "rcutils/testing/fault_injection.h"
+
+#include "rcutils/stdatomic_helper.h"
+
+static atomic_int_least64_t g_rcutils_fault_injection_count = -1;
+
+int _rcutils_maybe_fail()
+{
+  bool set_atomic_success = false;
+  int_least64_t current_count = -1;
+  rcutils_atomic_load(&g_rcutils_fault_injection_count, current_count);
+  do {
+    // A fault_injection_count less than 0 means that maybe_fail doesn't fail, so just return.
+    if (current_count < 0) {
+      return current_count;
+    }
+
+    // Otherwise decrement by one, but do so in a thread-safe manner so that exactly one calling
+    // thread gets the 0 case.
+    int_least64_t desired_count = current_count - 1;
+    rcutils_atomic_compare_exchange_strong(
+      &g_rcutils_fault_injection_count, set_atomic_success, &current_count, desired_count);
+  } while (!set_atomic_success);
+  return current_count;
+}
+
+void _rcutils_set_fault_injection_count(int count)
+{
+  rcutils_atomic_store(&g_rcutils_fault_injection_count, count);
+}