[flang-commits] [flang] [flang][docs] Add note about Cray pointers and the TARGET attribute (PR #137993)

[Asher Mancinelli via flang-commits]

https://github.com/ashermancinelli updated https://github.com/llvm/llvm-project/pull/137993

>From e103201bafd1dbc532984b8639c3cc141e57b4c4 Mon Sep 17 00:00:00 2001
From: Asher Mancinelli <ashermancinelli at gmail.com>
Date: Wed, 30 Apr 2025 09:56:02 -0700
Subject: [PATCH 1/2] [flang][docs] Add note about Cray pointers and the TARGET
 attribute

We found some tests checking for loops assigning between Cray pointer
handles and their pointees which produced "incorrect" results with
optimizations enabled; this is because the compiler expects Cray
pointers not to alias with any other entity.

The HPE documentation for Cray Fortran extensions specifies:

> the compiler assumes that the storage of a pointee is
> never overlaid on the storage of another variable

Jean pointed out that if a user's code uses entities that alias
via Cray pointers, they may add the TARGET attribute to inform Flang
of this aliasing, but that Flang's behavior is inline with Cray's own
documentation and we should not make any changes to our alias analysis
to try and detect this case.

Updating documentation so that users that encounter this situation
have a way to allow their code to compile as they intend.
---
 flang/docs/Aliasing.md | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/flang/docs/Aliasing.md b/flang/docs/Aliasing.md
index 652b766541fd4..1bdf9f4a1838e 100644
--- a/flang/docs/Aliasing.md
+++ b/flang/docs/Aliasing.md
@@ -264,11 +264,30 @@ Fortran also has no rule against associating read-only data with a pointer.
 Cray pointers are, or were, an extension that attempted to provide
 some of the capabilities of modern pointers and allocatables before those
 features were standardized.
-They had some aliasing restrictions; in particular, Cray pointers were
-not allowed to alias each other.
 
-They are now more or less obsolete and we have no plan in place to
-support them.
+They had some aliasing restrictions; in particular, Cray pointers were not
+allowed to alias each other.
+
+In this example, `handle` aliases with `target`.
+
+```
+integer(kind=8) :: target(10)
+integer(kind=8) :: ptr
+integer(kind=8) :: handle(10)
+pointer(ptr, handle)
+target = 1
+ptr = loc(target)
+print *, target
+end
+```
+
+Optimizations assume that Cray pointers do not alias any other variables.
+In the above example, it is assumed that `handle` and `target` do not alias,
+and optimizations will treat them as seperate entities.
+
+You may add the TARGET attribute to variables aliasing with a Cray pointer (the
+`target` variable in this example), and this will disable some optimizations
+that would otherwise assume there is no aliasing.
 
 ## Type considerations
 

>From 09a1ed2ed182b2d36706530cc5a4fc631d5052a5 Mon Sep 17 00:00:00 2001
From: Asher Mancinelli <ashermancinelli at gmail.com>
Date: Wed, 30 Apr 2025 12:18:06 -0700
Subject: [PATCH 2/2] Update wording after review comments

---
 flang/docs/Aliasing.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/flang/docs/Aliasing.md b/flang/docs/Aliasing.md
index 1bdf9f4a1838e..d5edf59f37c6e 100644
--- a/flang/docs/Aliasing.md
+++ b/flang/docs/Aliasing.md
@@ -283,11 +283,11 @@ end
 
 Optimizations assume that Cray pointers do not alias any other variables.
 In the above example, it is assumed that `handle` and `target` do not alias,
-and optimizations will treat them as seperate entities.
+and optimizations will treat them as separate entities.
 
-You may add the TARGET attribute to variables aliasing with a Cray pointer (the
-`target` variable in this example), and this will disable some optimizations
-that would otherwise assume there is no aliasing.
+In order to disable optimizations that assume that there is no aliasing between
+Cray pointer targets and entities they alias with, add the TARGET attribute to
+variables aliasing with a Cray pointer (the `target` variable in this example).
 
 ## Type considerations