add notes to docs about ref intents

Signed-off-by: Jade Abraham <[email protected]>
arezaii · Sep 21, 2023 · b1c34ca · b1c34ca
1 parent 6d4cafa
commit b1c34ca
Show file tree

Hide file tree

Showing 9 changed files with 13 additions and 11 deletions.
diff --git a/test/release/examples/benchmarks/hpcc/ra-atomics.chpl b/test/release/examples/benchmarks/hpcc/ra-atomics.chpl
@@ -104,7 +104,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T(i).poke(i);
 

diff --git a/test/release/examples/benchmarks/hpcc/ra.chpl b/test/release/examples/benchmarks/hpcc/ra.chpl
@@ -128,7 +128,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T[i] = i;
 

diff --git a/test/release/examples/benchmarks/hpcc/variants/ra-cleanloop.chpl b/test/release/examples/benchmarks/hpcc/variants/ra-cleanloop.chpl
@@ -124,7 +124,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T[i] = i;
 

diff --git a/test/release/examples/benchmarks/hpcc/variants/ra-unordered-atomics.chpl b/test/release/examples/benchmarks/hpcc/variants/ra-unordered-atomics.chpl
@@ -91,7 +91,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T(i).poke(i);
 

diff --git a/test/release/examples/primers/forallLoops.chpl b/test/release/examples/primers/forallLoops.chpl
@@ -33,7 +33,7 @@ an expression. Both kinds are shown in the following sections.
 --------------------------------
 
 In the following example, the forall loop iterates over the array indices
-in parallel:
+in parallel. Since the loop indirectly loops over ``A`` and the body modifies it, an explicit ``ref`` intent must be used.
 */
 
 config const n = 5;
@@ -81,7 +81,8 @@ provide a "leader" iterator and all iterables provide "follower" iterators.
 These are described in the :ref:`parallel iterators primer
 <primers-parIters-leader-follower>`.
 
-Here we illustrate zippering arrays and domains:
+Here we illustrate zippering arrays and domains. Since ``C`` is not directly
+iterated over, we must explicitly mark it as modified with a ``ref`` intent.
 */
 
 var C: [1..n] real;
@@ -187,7 +188,8 @@ of shadow variables, one per outer variable.
 The default argument intent (:ref:`The_Default_Intent`) is used by default.
 For numeric types, this implies capturing the value of the outer
 variable by the time the task starts executing. Arrays are passed by
-reference, as are sync and atomic variables
+constant reference, so to modify them we must use an explicit intent.
+Sync and atomic variables are passed by reference
 (:ref:`primers-syncs`, :ref:`primers-atomics`).
 */
 

diff --git a/test/release/examples/primers/forallLoops.good b/test/release/examples/primers/forallLoops.good
@@ -40,5 +40,5 @@ After a loop with task-private variables:
 outerIntVariable is: 48
 
 After MyRecord.myMethod, myR is:
-(arrField = 2 4 6 8 10, intField = 0)
+(arrField = 2 4 6 8 10, intField = 5)
 
diff --git a/test/studies/hpcc/FFT/fft.chpl b/test/studies/hpcc/FFT/fft.chpl
@@ -205,7 +205,7 @@ proc dfft(ref A: [?ADom], W, cyclicPhase) {
 
 //
 // this is the radix-4 butterfly routine that takes multipliers wk1,
-// wk2, and wk3 and a 4-element array (slice) A.
+// wk2, and wk3 and a 4-element array (slice) X.
 //
 proc butterfly(wk1, wk2, wk3, ref X:[?D]) {
   const i0 = D.low,

diff --git a/test/studies/hpcc/HPL/hpl.chpl b/test/studies/hpcc/HPL/hpl.chpl
@@ -170,7 +170,7 @@ proc LUFactorize(n: int, ref Ab: [?AbD] elemType,
 //     |aaaaa|.....|.....|.....|  function but called AD here.  Similarly,
 //     +-----+-----+-----+-----+  'b' was 'tr' in the calling code, but BD
 //     |aaaaa|.....|.....|.....|  here.
-//     |aaaaa|.....|.....|.....|  
+//     |aaaaa|.....|.....|.....|
 //     |aaaaa|.....|.....|.....|
 //     +-----+-----+-----+-----+
 //

diff --git a/test/studies/hpcc/RA/diten/ra.chpl b/test/studies/hpcc/RA/diten/ra.chpl
@@ -100,7 +100,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T(i) = i;
   for loc in Locales {