[PATCH] D61652: [LangRef][Attr] Clarify dereferenceable(_in_scope)

[Johannes Doerfert via Phabricator via llvm-commits]

jdoerfert updated this revision to Diff 199829.
jdoerfert marked an inline comment as done.
jdoerfert added a comment.

Grammar + reintroduce existing "pointer only" restriction


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D61652

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -1132,15 +1132,23 @@
     the behavior is undefined.
 
 ``dereferenceable(<n>)``
-    This indicates that the parameter or return pointer is dereferenceable. This
-    attribute may only be applied to pointer typed parameters. A pointer that
-    is dereferenceable can be loaded from speculatively without a risk of
-    trapping. The number of bytes known to be dereferenceable must be provided
-    in parentheses. It is legal for the number of bytes to be less than the
-    size of the pointee type. The ``nonnull`` attribute does not imply
-    dereferenceability (consider a pointer to one element past the end of an
-    array), however ``dereferenceable(<n>)`` does imply ``nonnull`` in
-    ``addrspace(0)`` (which is the default address space).
+    This indicates that the annotated value, e.g., a parameter or return
+    value, is dereferenceable *at its definition*, which would be the beginning
+    of the function entry or the call site for annotated parameters and return
+    values respectively. This attribute may only be applied to values with
+    pointer type. A pointer that is known to be dereferenceable (and properly
+    aligned) can be loaded from speculatively without a risk of trapping. The
+    number of bytes known to be dereferenceable must be provided in
+    parentheses. It is legal for the number of bytes to be less than the
+    size of the pointee type. If, at runtime, the annotated pointer is not
+    dereferenceable, the behavior is undefined. The ``nonnull`` attribute does
+    not imply dereferenceability (consider a pointer to one element past the
+    end of an array), however ``dereferenceable(<n>)`` does imply ``nonnull``
+    in ``addrspace(0)`` (which is the default address space). The
+    dereferenceability property provided through this argument is tied to the
+    definition because it can be lost, e.g., via a call to ``free``. Use
+    ``dereferenceable_globally(<n>)`` for pointer values that cannot be
+    deallocated.
 
 ``dereferenceable_or_null(<n>)``
     This indicates that the parameter or return value isn't both
@@ -1151,9 +1159,24 @@
     a pointer is exactly one of ``dereferenceable(<n>)`` or ``null``,
     and in other address spaces ``dereferenceable_or_null(<n>)``
     implies that a pointer is at least one of ``dereferenceable(<n>)``
-    or ``null`` (i.e. it may be both ``null`` and
-    ``dereferenceable(<n>)``). This attribute may only be applied to
-    pointer typed parameters.
+    or ``null`` (i.e. it may be both ``null`` and ``dereferenceable(<n>)``).
+    This attribute may only be applied to pointer typed parameters.
+
+``dereferenceable_globally(<n>)``
+    This indicates that the annotated pointer value has the
+    ``dereferenceable(<n>)`` property *at any program point*, starting from the
+    definition of the value to the termination of the program. Thus, unlike
+    pointer values annotated with ``dereferenceable(<n>)``,
+    ``dereferenceable_globally(<n>)`` pointer values can never lose the
+    ``dereferenceable(<n>)`` property.
+
+``dereferenceable_or_null_globally(<n>)``
+    This indicates that the annotated pointer value has the
+    ``dereferenceable_or_null(<n>)`` property *at any program point*, starting
+    from the definition of the value to the termination of the program. Thus,
+    unlike pointer values annotated with ``dereferenceable_or_null(<n>)``,
+    ``dereferenceable_or_null_globally(<n>)`` pointer values can never lose the
+    ``dereferenceable_or_null(<n>)`` property.
 
 ``swiftself``
     This indicates that the parameter is the self/context parameter. This is not


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D61652.199829.patch
Type: text/x-patch
Size: 3776 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20190516/c331df2d/attachment.bin>