[PATCH] D48239: [LangRef] Clarify meaning of "dereferencable" attribute/metadata.

[Eli Friedman via Phabricator via llvm-commits]

efriedma created this revision.
efriedma added reviewers: rsmith, chandlerc, hfinkel, nlopes, sanjoy, apilipenko.

This is consistent with what is currently implemented in LLVM, as far as I know.

There's an alternative model where "dereferenceable" only applies at the point of the call/load.  That might be more generally useful?  But it doesn't match the implementation of Value::getPointerDereferenceableBytes.


Repository:
  rL LLVM

https://reviews.llvm.org/D48239

Files:
  docs/LangRef.rst


Index: docs/LangRef.rst
===================================================================
--- docs/LangRef.rst
+++ docs/LangRef.rst
@@ -1127,7 +1127,10 @@
     is non-null.
 
 ``dereferenceable(<n>)``
-    This indicates that the parameter or return pointer is dereferenceable. This
+    On a parameter, this indicates the parameter is dereferenceable for
+    the duration of the function. On a return value, this indicates the
+    returned value is dereferenceable for the duration of the program.
+    If the pointer cannot be dereferenced, the behavior is undefined. 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
@@ -7954,7 +7957,9 @@
 The optional ``!dereferenceable`` metadata must reference a single metadata
 name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64``
 entry. The existence of the ``!dereferenceable`` metadata on the instruction
-tells the optimizer that the value loaded is known to be dereferenceable.
+tells the optimizer that the value loaded is known to be dereferenceable
+at any later point in the program.  If the pointer cannot be dereferenced,
+the behavior is undefined.
 The number of bytes known to be dereferenceable is specified by the integer
 value in the metadata node. This is analogous to the ''dereferenceable''
 attribute on parameters and return values. This metadata can only be applied
@@ -7964,7 +7969,8 @@
 metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one
 ``i64`` entry. The existence of the ``!dereferenceable_or_null`` metadata on the
 instruction tells the optimizer that the value loaded is known to be either
-dereferenceable or null.
+dereferenceable or null at any later point in the program.  If the pointer
+cannot be dereferenced and is not null, the behavior is undefined.
 The number of bytes known to be dereferenceable is specified by the integer
 value in the metadata node. This is analogous to the ''dereferenceable_or_null''
 attribute on parameters and return values. This metadata can only be applied


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D48239.151561.patch
Type: text/x-patch
Size: 2219 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180615/02f8b97f/attachment-0001.bin>