third_party/pigweed/repo/docs/embedded_cpp_guide.rst

   1 .. _docs-embedded-cpp:
   2
   3 ==================
   4 Embedded C++ Guide
   5 ==================
   6
   7 This page contains recommendations for using C++ for embedded software. For
   8 Pigweed code, these should be considered as requirements. For external
   9 projects, these recommendations can serve as a resource for efficiently using
  10 C++ in embedded projects.
  11
  12 These recommendations are subject to change as the C++ standard and compilers
  13 evolve, and as the authors continue to gain more knowledge and experience in
  14 this area. If you disagree with recommendations, please discuss them with the
  15 Pigweed team, as we're always looking to improve the guide or correct any
  16 inaccuracies.
  17
  18 Constexpr functions
  19 ===================
  20 Constexpr functions are functions that may be called from a constant
  21 expression, such as a template parameter, constexpr variable initialization, or
  22 ``static_assert`` statement. Labeling a function ``constexpr`` does not
  23 guarantee that it is executed at compile time; if called from regular code, it
  24 will be compiled as a regular function and executed at run time.
  25
  26 Constexpr functions are implicitly inline, which means they are suitable to be
  27 defined in header files. Like any function in a header, the compiler is more
  28 likely to inline it than other functions. Marking non-trivial functions as
  29 ``constexpr`` could increase code size, so check the compilation results if this
  30 is a concern.
  31
  32 Simple constructors should be marked ``constexpr`` whenever possible. GCC
  33 produces smaller code in some situations when the ``constexpr`` specifier is
  34 present. Do not avoid important initialization in order to make the class
  35 constexpr-constructible unless it actually needs to be used in a constant
  36 expression.
  37
  38 Constexpr variables
  39 ===================
  40 Constants should be marked ``constexpr`` whenever possible. Constexpr variables
  41 can be used in any constant expression, such as a non-type template argument,
  42 ``static_assert`` statement, or another constexpr variable initialization.
  43 Constexpr variables can be initialized at compile time with values calculated by
  44 constexpr functions.
  45
  46 ``constexpr`` implies ``const`` for variables, so there is no need to include
  47 the ``const`` qualifier when declaring a constexpr variable.
  48
  49 Unlike constexpr functions, constexpr variables are **not** implicitly inline.
  50 Constexpr variables in headers must be declared with the ``inline`` specifier.
  51
  52 .. code-block:: cpp
  53
  54   namespace pw {
  55
  56   inline constexpr const char* kStringConstant = "O_o";
  57
  58   inline constexpr float kFloatConstant1 = CalculateFloatConstant(1);
  59   inline constexpr float kFloatConstant2 = CalculateFloatConstant(2);
  60
  61   }  // namespace pw
  62
  63 Function templates
  64 ==================
  65 Function templates facilitate writing code that works with different types. For
  66 example, the following clamps a value within a minimum and maximum:
  67
  68 .. code-block:: cpp
  69
  70   template <typename T>
  71   T Clamp(T min, T max, T value) {
  72     if (value < min) {
  73       return min;
  74     }
  75     if (value > max) {
  76       return min;
  77     }
  78     return value;
  79   }
  80
  81 The above code works seamlessly with values of any type -- float, int, or even a
  82 custom type that supports the < and > operators.
  83
  84 The compiler implements templates by generating a separate version of the
  85 function for each set of types it is instantiated with. This can increase code
  86 size significantly.
  87
  88 .. tip::
  89
  90   Be careful when instantiating non-trivial template functions with multiple
  91   types.
  92
  93 Virtual functions
  94 =================
  95 Virtual functions provide for runtime polymorphism. Unless runtime polymorphism
  96 is required, virtual functions should be avoided. Virtual functions require a
  97 virtual table, which increases RAM usage and requires extra instructions at each
  98 call site. Virtual functions can also inhibit compiler optimizations, since the
  99 compiler may not be able to tell which functions will actually be invoked. This
 100 can prevent linker garbage collection, resulting in unused functions being
 101 linked into a binary.
 102
 103 When runtime polymorphism is required, virtual functions should be considered.
 104 C alternatives, such as a struct of function pointers, could be used instead,
 105 but these approaches may offer no performance advantage while sacrificing
 106 flexibility and ease of use.
 107
 108 .. tip::
 109
 110   Only use virtual functions when runtime polymorphism is needed.