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

[Johannes Doerfert via Phabricator via llvm-commits]

jdoerfert updated this revision to Diff 204372.
jdoerfert added a comment.

Add argument definitions


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
  llvm/include/llvm/IR/Attributes.td


Index: llvm/include/llvm/IR/Attributes.td
===================================================================
--- llvm/include/llvm/IR/Attributes.td
+++ llvm/include/llvm/IR/Attributes.td
@@ -45,6 +45,12 @@
 /// Pointer is either null or dereferenceable.
 def DereferenceableOrNull : EnumAttr<"dereferenceable_or_null">;
 
+/// Pointer is known to be dereferenceable_globally.
+def DereferenceableGlobally : EnumAttr<"dereferenceable_globally">;
+
+/// Pointer is either null or dereferenceable_globally.
+def DereferenceableOrNullGlobally : EnumAttr<"dereferenceable_or_null_globally">;
+
 /// Function may only access memory that is inaccessible from IR.
 def InaccessibleMemOnly : EnumAttr<"inaccessiblememonly">;
 
Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -1135,15 +1135,22 @@
     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 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
@@ -1154,9 +1161,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.204372.patch
Type: text/x-patch
Size: 4467 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20190612/c29051e2/attachment.bin>