From b1c34cafe1b958d9018029f6676c42ab3a12bbec Mon Sep 17 00:00:00 2001 From: Jade Abraham Date: Thu, 21 Sep 2023 12:12:30 -0700 Subject: [PATCH 1/4] add notes to docs about ref intents Signed-off-by: Jade Abraham --- test/release/examples/benchmarks/hpcc/ra-atomics.chpl | 2 +- test/release/examples/benchmarks/hpcc/ra.chpl | 2 +- .../examples/benchmarks/hpcc/variants/ra-cleanloop.chpl | 2 +- .../benchmarks/hpcc/variants/ra-unordered-atomics.chpl | 2 +- test/release/examples/primers/forallLoops.chpl | 8 +++++--- test/release/examples/primers/forallLoops.good | 2 +- test/studies/hpcc/FFT/fft.chpl | 2 +- test/studies/hpcc/HPL/hpl.chpl | 2 +- test/studies/hpcc/RA/diten/ra.chpl | 2 +- 9 files changed, 13 insertions(+), 11 deletions(-) diff --git a/test/release/examples/benchmarks/hpcc/ra-atomics.chpl b/test/release/examples/benchmarks/hpcc/ra-atomics.chpl index 0b8db4ccbfa8..d2cd5c49c403 100644 --- 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 index a6a8e3d1ba51..afe376cf2ab9 100644 --- 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 index 5a2a28fe453b..74b8563e4874 100644 --- 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 index 16586289deb6..9923d520471e 100644 --- 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 index 408eee1c9cdc..5762c190965a 100644 --- 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 `. -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 index 4d8cdce89bb6..8bc1a520c955 100644 --- 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 index f705aee954ae..8e6c885b108a 100644 --- 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 index 05c76012019b..e5a267de5c31 100644 --- 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 index 9ea2ba09b829..033f0bd9fa59 100644 --- 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 { From 1c7d0eca77c3075bfbf02e6de1424c9ef974f59b Mon Sep 17 00:00:00 2001 From: Jade Abraham Date: Thu, 21 Sep 2023 12:38:04 -0700 Subject: [PATCH 2/4] add note to arrays primer Signed-off-by: Jade Abraham --- test/release/examples/primers/arrays.chpl | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/test/release/examples/primers/arrays.chpl b/test/release/examples/primers/arrays.chpl index 06934199b3a0..7bc449a7d8d6 100644 --- a/test/release/examples/primers/arrays.chpl +++ b/test/release/examples/primers/arrays.chpl @@ -128,7 +128,11 @@ writeln("After incrementing B's elements, B is:\n", B, "\n"); // from the ranges specified within the array type's square brackets. // Array ``A2`` above will have the implicit domain ``{0..4}`` to // represent the five values in its initializing expression. - +// +// When an array is modified without being specified in the iterand inside +// of a parallel construct (like ``forall`` in the example below), it needs +// an explicit ``ref`` intent. +// // An array's domain can be queried using the ``.domain`` method, // which returns a ``const ref`` to the domain in question. For // example, here's a loop that iterates over B's indices in parallel @@ -158,7 +162,7 @@ proc negateAndPrintArr(ref X: [?D] real) { negateAndPrintArr(B); // -// Arrays are passed to routines by constant reference (``const ref``) by +// Arrays are passed to routines by constant (``const``) by // default, which does not allow them to be modified within the routine. // The above procedure ``negateAndPrintArr()`` must use a non-constant // reference intent (``ref``) explicitly, so that its modifications of ``X`` From b41c468b1dde2b5987763f1bd4bd090352520a4b Mon Sep 17 00:00:00 2001 From: Jade Abraham Date: Thu, 21 Sep 2023 14:28:23 -0700 Subject: [PATCH 3/4] revert .good file change Signed-off-by: Jade Abraham --- test/release/examples/primers/forallLoops.good | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/release/examples/primers/forallLoops.good b/test/release/examples/primers/forallLoops.good index 8bc1a520c955..4d8cdce89bb6 100644 --- 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 = 5) +(arrField = 2 4 6 8 10, intField = 0) From 302440fcd25770733739ad4f1da73064c98549c6 Mon Sep 17 00:00:00 2001 From: Jade Abraham Date: Thu, 21 Sep 2023 16:36:39 -0700 Subject: [PATCH 4/4] respond to feedback Signed-off-by: Jade Abraham --- test/release/examples/primers/arrays.chpl | 6 +++--- test/release/examples/primers/forallLoops.chpl | 9 +++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/test/release/examples/primers/arrays.chpl b/test/release/examples/primers/arrays.chpl index 7bc449a7d8d6..1ec544c7d732 100644 --- a/test/release/examples/primers/arrays.chpl +++ b/test/release/examples/primers/arrays.chpl @@ -129,9 +129,9 @@ writeln("After incrementing B's elements, B is:\n", B, "\n"); // Array ``A2`` above will have the implicit domain ``{0..4}`` to // represent the five values in its initializing expression. // -// When an array is modified without being specified in the iterand inside -// of a parallel construct (like ``forall`` in the example below), it needs -// an explicit ``ref`` intent. +// The explicit ``ref`` intent is required for ``B`` in the example below +// because ``B`` is not modifed directly through the loop's index variable (in +// this case ``i`` and ``j``). // // An array's domain can be queried using the ``.domain`` method, // which returns a ``const ref`` to the domain in question. For diff --git a/test/release/examples/primers/forallLoops.chpl b/test/release/examples/primers/forallLoops.chpl index 5762c190965a..dc1945097e27 100644 --- a/test/release/examples/primers/forallLoops.chpl +++ b/test/release/examples/primers/forallLoops.chpl @@ -32,8 +32,9 @@ an expression. Both kinds are shown in the following sections. "Must-parallel" forall statement -------------------------------- -In the following example, the forall loop iterates over the array indices -in parallel. Since the loop indirectly loops over ``A`` and the body modifies it, an explicit ``ref`` intent must be used. +In the following example, the forall loop iterates over the array indices in +parallel. Since the loop iterates over ``1..n`` and not ``A``, an explicit +``ref`` intent must be used to allow modification of ``A``. */ config const n = 5; @@ -81,8 +82,8 @@ provide a "leader" iterator and all iterables provide "follower" iterators. These are described in the :ref:`parallel iterators primer `. -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. +Here we illustrate zippering arrays and domains. In this example, we must +explicitly mark ``C`` as modified with a ``ref`` intent. */ var C: [1..n] real;