[PATCH] D97924: [LangRef] clarify the semantics of nocapture

[Juneyoung Lee via Phabricator via llvm-commits]

aqjune updated this revision to Diff 328156.
aqjune added a comment.

Minor updates


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D97924/new/

https://reviews.llvm.org/D97924

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -1195,12 +1195,12 @@
     function, returning a pointer to allocated storage disjoint from the
     storage for any other object accessible to the caller.
 
+.. _nocapture:
+
 ``nocapture``
-    This indicates that the callee does not make any copies of the
-    pointer that outlive the callee itself in any form such as a pointer stored
-    in the memory or as a return value. This is not a valid
-    attribute for return values.  Addresses used in volatile operations
-    are considered to be captured.
+    This indicates that the callee does not :ref:`capture <pointerescape>` the
+    pointer. This is not a valid attribute for return values.  Addresses used
+    in volatile operations are considered to be captured.
 
 ``nofree``
     This indicates that callee does not free the pointer argument. This is not
@@ -2627,6 +2627,39 @@
 which specialized optimization passes may use to implement type-based
 alias analysis.
 
+.. _pointerescape:
+
+Pointer Escape
+--------------
+
+Given a function call and a pointer that is passed as an argument or stored in
+the memory before the call, a pointer is *escaped* or *captured* by the call if
+the call stores the pointer into a place that is readable by the caller or
+subsequent function calls, such as in a global variable and caller's register.
+If the pointer isn't a :ref:`non-integral pointer <nointptrtype>`, it is escaped
+if assigning different integral addresses to the pointer causes changes in the
+results of operations such as :ref:`ptrtoint <i_ptrtoint>` and thus alters the
+final state.
+
+A stack/heap allocation whose pointer is never stored to the memory or passed
+as an argument to a function call is never escaped.
+A pointer that is passed as a :ref:`nocapture <nocapture>` argument isn't
+escaped by the function call.
+
+If a pointer is tagged as 'nocapture', the pointer is escaped if the memory and
+register after the call contains the pointer value with the 'nocapture' tag.
+This means that a caller can pass two same pointers with one nocapture tagged
+and another not tagged as arguments, and callee can escape the untagged
+pointer.
+
+.. code-block:: llvm
+    define void @f(i8* %a, i8* %b) {
+      ; (escape %b)
+    }
+
+    call void @f(i8* nocapture @glb, i8* @glb) ; well-defined
+
+
 .. _volatile:
 
 Volatile Memory Accesses


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D97924.328156.patch
Type: text/x-patch
Size: 2480 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20210304/7a501d2e/attachment.bin>