Clarify the description of the noalias attribute

The previous description of the noalias attribute did not accurately specify
the implemented semantics, and the terminology used differed unnecessarily
from that used by the C specification to define the semantics of restrict. For
the argument attribute, the semantics can be precisely specified in terms of
objects accessed through pointers based on the arguments, and this is now what
is done.

Saying that the semantics are 'slightly weaker' than that provided by C99
restrict is not really useful without further elaboration, so that has been
removed from the sentence.

noalias on a return value is really used to mean that the function is
malloc-like (and, in fact, we use this attribute to represent
__attribute__((malloc)) in Clang), and this is a stronger guarantee than that
provided by restrict (because it is a property of the pointed-to memory region,
not just a guarantee on object access). Clarifying this is relevant to fixing
(and was motivated by the discussion on) PR21556.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@222497 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index 3b7d80ba376ee7100de47be4404d732f27aad5f0..56221c5154a4270df603811d214d32374a2cc88d 100644 (file)
--- a/docs/LangRef.rst
+++ b/docs/LangRef.rst
@@ -941,23 +941,26 @@ Currently, only the following parameter attributes are defined:
 .. _noalias:
 
 ``noalias``
 .. _noalias:
 
 ``noalias``

-    This indicates that pointer values :ref:`based <pointeraliasing>` on
-    the argument or return value do not alias pointer values that are
-    not *based* on it, ignoring certain "irrelevant" dependencies. For a
-    call to the parent function, dependencies between memory references
-    from before or after the call and from those during the call are
-    "irrelevant" to the ``noalias`` keyword for the arguments and return
-    value used in that call. The caller shares the responsibility with
-    the callee for ensuring that these requirements are met. For further
-    details, please see the discussion of the NoAlias response in :ref:`alias
-    analysis <Must, May, or No>`.
+    This indicates that objects accessed via pointer values
+    :ref:`based <pointeraliasing>` on the argument or return value are not also
+    accessed, during the execution of the function, via pointer values not
+    *based* on the argument or return value. The attribute on a return value
+    also has additional semantics described below. The caller shares the
+    responsibility with the callee for ensuring that these requirements are met.
+    For further details, please see the discussion of the NoAlias response in
+    :ref:`alias analysis <Must, May, or No>`.

 
     Note that this definition of ``noalias`` is intentionally similar
 
     Note that this definition of ``noalias`` is intentionally similar

-    to the definition of ``restrict`` in C99 for function arguments,
-    though it is slightly weaker.
+    to the definition of ``restrict`` in C99 for function arguments.

 
     For function return values, C99's ``restrict`` is not meaningful,
 
     For function return values, C99's ``restrict`` is not meaningful,

-    while LLVM's ``noalias`` is.
+    while LLVM's ``noalias`` is. Furthermore, the semantics of the ``noalias``
+    attribute on return values are stronger than the semantics of the attribute
+    when used on function arguments. On function return values, the ``noalias``
+    attribute indicates that the function acts like a system memory allocation
+    function, returning a pointer to allocated storage disjoint from the
+    storage for any other object accessible to the caller.
+

 ``nocapture``
     This indicates that the callee does not make any copies of the
     pointer that outlive the callee itself. This is not a valid
 ``nocapture``
     This indicates that the callee does not make any copies of the
     pointer that outlive the callee itself. This is not a valid