[libc-commits] [PATCH] D146115: [libc][docs] Add a section about allocations and deallocations to the style doc.

[Siva Chandra via Phabricator via libc-commits]

sivachandra created this revision.
sivachandra added a reviewer: jeffbailey.
Herald added subscribers: libc-commits, ecnelises, tschuett.
Herald added projects: libc-project, All.
sivachandra requested review of this revision.

Fixes #59277 - The main part of that bug has already been addressed. This commit
just adds documentation.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D146115

Files:
  libc/docs/dev/code_style.rst


Index: libc/docs/dev/code_style.rst
===================================================================
--- libc/docs/dev/code_style.rst
+++ libc/docs/dev/code_style.rst
@@ -114,3 +114,46 @@
 of the standard ``assert`` macro. Hence, it can be used from any where in the
 libc runtime code without causing any recursive calls or chicken-and-egg
 situations.
+
+Allocations in the libc runtime code
+====================================
+
+Some libc functions allocate memory. For example, the ``strdup`` function
+allocates new memory into which the input string is duplicated. Allocations
+are typically done by calling a function from the ``malloc`` family of
+functions. Such functions can fail and return an error value to indicate
+allocation failure. To conform to standards, the libc should handle
+allocation failures gracefully and surface the error conditions to the user
+code as appropriate. Since LLVM's libc is implemented in C++, we want
+allocations and deallocations to employ C++ operators ``new`` and ``delete``
+as they implicitly invoke constructors and destructors respectively. However,
+if we use the default ``new`` and ``delete`` operators, the libc will end up
+depending on the C++ runtime. To avoid such a dependence, and to handle
+allocation failures gracefully, we use special ``new`` and ``delete`` operators
+defined in
+`src/__support/CPP/new.h <https://github.com/llvm/llvm-project/blob/main/libc/src/__support/CPP/new.h>`_.
+Allocations and deallocations using these operators employ a pattern like
+this:
+
+.. code-block:: c++
+
+   #include "src/__support/CPP/new.h"
+
+   ...
+
+     __llvm_libc::AllocChecker ac;
+     auto *obj = new (ac) Type(...);
+     if (!ac) {
+       // handle allocator failure.
+     }
+     ...
+     delete obj;
+
+The only exception to using the above pattern is if allocating using the
+``realloc`` function is of value. In such cases, prefer to use only the
+``malloc`` family of functions for allocations and deallocations. Allocation
+failures will still need to be handled gracefully. Further, keep in mind that
+these functions do not call the constructors and destructors of the
+allocated/deallocated objects. So, use these functions carefully and only
+when it is absolutely clear that constructor and desctructor invocation is
+not required.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D146115.505385.patch
Type: text/x-patch
Size: 2323 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libc-commits/attachments/20230315/13de3f65/attachment-0001.bin>