[llvm] 5d8c6c1 - [LangRef] Mention allocation elision (#177592)

[via llvm-commits]

Author: Nikita Popov
Date: 2026-03-03T10:51:38+01:00
New Revision: 5d8c6c198ddefc6b63449fd66b99b83e929da15c

URL: https://github.com/llvm/llvm-project/commit/5d8c6c198ddefc6b63449fd66b99b83e929da15c
DIFF: https://github.com/llvm/llvm-project/commit/5d8c6c198ddefc6b63449fd66b99b83e929da15c.diff

LOG: [LangRef] Mention allocation elision (#177592)

allockind / alloc-family enable allocation elision, but this was not
previously mentioned by LangRef.

Related discussion:
https://discourse.llvm.org/t/rfc-clarifying-semantic-assumptions-for-custom-allocators/89469

The semantics here are specified in terms of allowed transforms.
Making the semantics operational is tracked in #184102.

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index a1835436ae359..068c67363b3b6 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -2088,6 +2088,19 @@ For example:
     The first three options are mutually exclusive, and the remaining options
     describe more details of how the function behaves. The remaining options
     are invalid for "free"-type functions.
+
+    Calls to functions annotated with ``allockind`` are subject to allocation
+    elision: Calls to allocator functions can be removed, and the allocation
+    served from a "virtual" allocator instead. Notably, this is allowed even if
+    the allocator calls have side-effects. In other words, for each allocation
+    there is a non-deterministic choice between calling the allocator as usual,
+    or using a virtual, side-effect-free allocator instead.
+
+    If multiple allocation functions operate on the same allocation,
+    allocation elision is only allowed for pairs of "alloc" and "free" with the
+    same ``"alloc-family"`` attribute. For this purpose, a "realloc" call may
+    be decomposed into "alloc" and "free" operations, as long as at least one
+    of them will be elided.
 ``"alloc-variant-zeroed"="FUNCTION"``
     This attribute indicates that another function is equivalent to an allocator function,
     but returns zeroed memory. The function must have "zeroed" allocation behavior,