[llvm] [LangRef] Mention allocation elision (PR #177592)

[Ralf Jung via llvm-commits]

================
@@ -2077,6 +2077,22 @@ 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.
+
+    If multiple allocation functions operate on the same allocation (for
+    example, an "alloc" followed by "free"), allocation elision is only allowed
+    if all involved functions have the same ``"alloc-family"``. The following
+    transforms can be performed, or combinations thereof:
+
+    * An "alloc" that is leaked (no "free"/"realloc") can be elided.
+    * An "alloc" and "free" pair can be elided.
+    * A "realloc" and "free" pair can be converted into a "free" of the original
+      allocation.
+    * An "alloc" and "realloc" pair can be converted into an "alloc".
----------------
RalfJung wrote:

It's not always clear here where the conversion happens. For instance, when alloc+realloc are turned into alloc, is that put in the place of the original alloc, or the original realloc (with some stack memory being used for the time between the original alloc and realloc)?

https://github.com/llvm/llvm-project/pull/177592