libc/docs/dev/code_style.rst

   1 .. _code_style:
   2
   3 ===================
   4 The libc code style
   5 ===================
   6
   7 Naming style
   8 ============
   9
  10 For the large part, the libc project follows the general `coding standards of
  11 the LLVM project <https://llvm.org/docs/CodingStandards.html>`_. The libc
  12 project differs from that standard with respect to the naming style. The
  13 differences are as follows:
  14
  15 #. **Non-const variables** - This includes function arguments, struct and
  16    class data members, non-const globals and local variables. They all use the
  17    ``snake_case`` style.
  18 #. **const and constexpr variables** - They use the capitalized
  19    ``SNAKE_CASE`` irrespective of whether they are local or global.
  20 #. **Function and methods** - They use the ``snake_case`` style like the
  21    non-const variables.
  22 #. **Internal type names** - These are types which are internal to the libc
  23    implementation. They use the ``CaptilizedCamelCase`` style.
  24 #. **Public names** - These are the names as prescribed by the standards and
  25    will follow the style as prescribed by the standards.
  26
  27 Macro style
  28 ===========
  29
  30 We define two kinds of macros:
  31
  32 #. **Build defined** macros are generated by `CMake` or `Bazel` and are passed
  33    down to the compiler with the ``-D`` command line flag. They start with the
  34    ``LIBC_COPT_`` prefix. They are used to tune the behavior of the libc.
  35    They either denote an action or define a constant.
  36
  37 #. **Code defined** macros are defined within the ``src/__support/macros``
  38    folder. They all start with the ``LIBC_`` prefix.
  39
  40    * ``src/__support/macros/properties/`` - Build related properties like
  41      target architecture or enabled CPU features defined by introspecting
  42      compiler defined preprocessor definitions.
  43
  44      * ``architectures.h`` - Target architecture properties.
  45        e.g., ``LIBC_TARGET_ARCH_IS_ARM``.
  46      * ``compiler.h`` - Host compiler properties.
  47        e.g., ``LIBC_COMPILER_IS_CLANG``.
  48      * ``cpu_features.h`` - Target cpu apu feature availability.
  49        e.g., ``LIBC_TARGET_CPU_HAS_AVX2``.
  50
  51    * ``src/__support/macros/config.h`` - Important compiler and platform
  52      features. Such macros can be used to produce portable code by
  53      parameterizing compilation based on the presence or lack of a given
  54      feature. e.g., ``LIBC_HAS_BUILTIN``
  55    * ``src/__support/macros/attributes.h`` - Attributes for functions, types,
  56      and variables. e.g., ``LIBC_UNUSED``
  57    * ``src/__support/macros/optimization.h`` - Portable macros for performance
  58      optimization. e.g., ``LIBC_LIKELY``, ``LIBC_LOOP_NOUNROLL``
  59
  60 Inline functions and variables defined in header files
  61 ======================================================
  62
  63 When defining functions and variables inline in header files, we follow certain
  64 rules:
  65
  66 #. The functions should not be given file-static linkage. There can be class
  67    static methods defined inline however.
  68 #. Instead of using the ``inline`` keyword, functions should be tagged with the
  69    ``LIBC_INLINE`` macro and variables should be tagged with the
  70    ``LIBC_INLINE_VAR`` macro defined in ``src/__support/macros/attributes.h``.
  71    For example:
  72
  73    .. code-block:: c++
  74
  75      LIBC_INLINE_VAR constexpr bool foo = true;
  76
  77      LIBC_INLINE ReturnType function_defined_inline(ArgType arg) {
  78        ...
  79      }
  80
  81 #. The ``LIBC_INLINE`` tag should also be added to functions which have
  82    definitions that are implicitly inline. Examples of such functions are
  83    class methods (static and non-static) defined inline and ``constexpr``
  84    functions.
  85
  86 Setting ``errno`` from runtime code
  87 ===================================
  88
  89 Many libc functions set ``errno`` to indicate an error condition. If LLVM's libc
  90 is being used as the only libc, then the ``errno`` from LLVM's libc is affected.
  91 If LLVM's libc is being used in the :ref:`overlay_mode`, then the ``errno`` from
  92 the system libc is affected. When a libc function, which can potentially affect
  93 the ``errno``, is called from a unit test, we do not want the global ``errno``
  94 (as in, the ``errno`` of the process thread running the unit test) to be
  95 affected. If the global ``errno`` is affected, then the operation of the unit
  96 test infrastructure itself can be affected. To avoid perturbing the unit test
  97 infrastructure around the setting of ``errno``, the following rules are to be
  98 followed:
  99
 100 #. A special macro named ``libc_errno`` defined in ``src/errno/libc_errno.h``
 101    should be used when setting ``errno`` from libc runtime code. For example,
 102    code to set ``errno`` to ``EINVAL`` should be:
 103
 104    .. code-block:: c++
 105
 106     libc_errno = EINVAL;
 107
 108 #. ``errno`` should be set just before returning from the implementation of the
 109    public function. It should not be set from within helper functions. Helper
 110    functions should use idiomatic C++ constructs like
 111    `cpp::optional <https://github.com/llvm/llvm-project/blob/main/libc/src/__support/CPP/optional.h>`_
 112    and
 113    `ErrorOr <https://github.com/llvm/llvm-project/blob/main/libc/src/__support/error_or.h>`_
 114    to return error values.
 115
 116 #. The header file ``src/errno/libc_errno.h`` is shipped as part of the target
 117    corresponding to the ``errno`` entrypoint ``libc.src.errno.errno``. We do
 118    not in general allow dependencies between entrypoints. However, the ``errno``
 119    entrypoint is the only exceptional entrypoint on which other entrypoints
 120    should explicitly depend on if they set ``errno`` to indicate error
 121    conditions.
 122
 123 Assertions in libc runtime code
 124 ===============================
 125
 126 The libc developers should, and are encouraged to, use assertions freely in
 127 the libc runtime code. However, the assertion should be listed via the macro
 128 ``LIBC_ASSERT`` defined in ``src/__support/libc_assert.h``. This macro can be
 129 used from anywhere in the libc runtime code. Internally, all it does is to
 130 print the assertion expression and exit. It does not implement the semantics
 131 of the standard ``assert`` macro. Hence, it can be used from any where in the
 132 libc runtime code without causing any recursive calls or chicken-and-egg
 133 situations.
 134
 135 Allocations in the libc runtime code
 136 ====================================
 137
 138 Some libc functions allocate memory. For example, the ``strdup`` function
 139 allocates new memory into which the input string is duplicated. Allocations
 140 are typically done by calling a function from the ``malloc`` family of
 141 functions. Such functions can fail and return an error value to indicate
 142 allocation failure. To conform to standards, the libc should handle
 143 allocation failures gracefully and surface the error conditions to the user
 144 code as appropriate. Since LLVM's libc is implemented in C++, we want
 145 allocations and deallocations to employ C++ operators ``new`` and ``delete``
 146 as they implicitly invoke constructors and destructors respectively. However,
 147 if we use the default ``new`` and ``delete`` operators, the libc will end up
 148 depending on the C++ runtime. To avoid such a dependence, and to handle
 149 allocation failures gracefully, we use special ``new`` and ``delete`` operators
 150 defined in
 151 `src/__support/CPP/new.h <https://github.com/llvm/llvm-project/blob/main/libc/src/__support/CPP/new.h>`_.
 152 Allocations and deallocations using these operators employ a pattern like
 153 this:
 154
 155 .. code-block:: c++
 156
 157    #include "src/__support/CPP/new.h"
 158
 159    ...
 160
 161      LIBC_NAMESPACE::AllocChecker ac;
 162      auto *obj = new (ac) Type(...);
 163      if (!ac) {
 164        // handle allocator failure.
 165      }
 166      ...
 167      delete obj;
 168
 169 The only exception to using the above pattern is if allocating using the
 170 ``realloc`` function is of value. In such cases, prefer to use only the
 171 ``malloc`` family of functions for allocations and deallocations. Allocation
 172 failures will still need to be handled gracefully. Further, keep in mind that
 173 these functions do not call the constructors and destructors of the
 174 allocated/deallocated objects. So, use these functions carefully and only
 175 when it is absolutely clear that constructor and destructor invocation is
 176 not required.