From 5e2f929067de4071b9eccaa8046c9570dbe390cf Mon Sep 17 00:00:00 2001
From: Maurizio Cimadamore <mcimadamore@openjdk.org>
Date: Mon, 21 Aug 2023 13:30:55 +0000
Subject: [PATCH] Clarify javadoc w.r.t. exceptions thrown by a memory access
 var handle (part two)

Reviewed-by: pminborg
---
 .../java/lang/foreign/MemoryLayout.java       | 37 ++++++++++++-------
 1 file changed, 24 insertions(+), 13 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java b/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java
index 517b18232f1..3a06a690af3 100644
--- a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java
+++ b/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java
@@ -444,19 +444,22 @@ default MethodHandle byteOffsetHandle(PathElement... elements) {
      * {@snippet lang = "java":
      * offset = this.offsetHandle(P).invokeExact(B, I1, I2, ... In);
      * }
-     *
-     * The physical address of the accessed memory segment must be <a href="MemorySegment.html#segment-alignment">aligned</a>
+     * <p>
+     * Accessing a memory segment using the var handle returned by this method is subject to the following checks:
+     * <ul>
+     *     <li>The physical address of the accessed memory segment must be <a href="MemorySegment.html#segment-alignment">aligned</a>
      * according to the {@linkplain #byteAlignment() alignment constraint} of the root layout (this layout), or
      * an {@link IllegalArgumentException} will be issued. Note that the alignment constraint of the root layout
-     * can be more strict (but not less) than the alignment constraint of the selected value layout.
-     * <p>
-     * Moreover, if the access operation (computed as above) falls outside the spatial bounds of the
-     * accessed memory segment, an {@link IndexOutOfBoundsException} is thrown. This is the case when {@code O + A > S},
+     * can be more strict (but not less) than the alignment constraint of the selected value layout.</li>
+     *     <li>The offset of the access operation (computed as above) must fall fall inside the spatial bounds of the
+     * accessed memory segment, or an {@link IndexOutOfBoundsException} is thrown. This is the case when {@code O + A <= S},
      * where {@code O} is the accessed offset (computed as above), {@code A} is the size of the selected layout and {@code S}
-     * is the size of the accessed memory segment.
-     * <p>
-     * Finally, if the {@linkplain MemorySegment#scope() scope} associated with the accessed segment is not
-     * {@linkplain MemorySegment.Scope#isAlive() alive}, the access operation will result in an {@link IllegalStateException}.
+     * is the size of the accessed memory segment.</li>
+     *     <li>The accessed memory segment must be {@link MemorySegment#isAccessibleBy(Thread) accessible} from the
+     * thread performing the access operation, or a {@link WrongThreadException} is thrown.</li>
+     *     <li>The {@linkplain MemorySegment#scope() scope} associated with the accessed segment must be
+     * {@linkplain MemorySegment.Scope#isAlive() alive}, or an {@link IllegalStateException} is thrown.</li>
+     * </ul>
      * <p>
      * If the selected layout is an {@linkplain AddressLayout address layout}, calling {@link VarHandle#get(Object...)}
      * on the returned var handle will return a new memory segment. The segment is associated with a fresh scope that is
@@ -532,9 +535,17 @@ default VarHandle varHandle(PathElement... elements) {
      * The offset of the returned segment is computed as if by a call to a
      * {@linkplain #byteOffsetHandle(PathElement...) byte offset handle} constructed using the given path elements.
      * <p>
-     * The segment to be sliced must be <a href="MemorySegment.html#segment-alignment">aligned</a> according to the
-     * {@linkplain #byteAlignment() alignment constraint} of the root layout (this layout). Note that this can be more
-     * strict (but not less) than the alignment constraint of the selected value layout.
+     * Computing a slice of a memory segment using the method handle returned by this method is subject to the following checks:
+     * <ul>
+     *     <li>The physical address of the accessed memory segment must be <a href="MemorySegment.html#segment-alignment">aligned</a>
+     * according to the {@linkplain #byteAlignment() alignment constraint} of the root layout (this layout), or
+     * an {@link IllegalArgumentException} will be issued. Note that the alignment constraint of the root layout
+     * can be more strict (but not less) than the alignment constraint of the selected layout.</li>
+     *     <li>The start offset of the slicing operation (computed as above) must fall fall inside the spatial bounds of the
+     * accessed memory segment, or an {@link IndexOutOfBoundsException} is thrown. This is the case when {@code O + A <= S},
+     * where {@code O} is the start offset of the slicing operation (computed as above), {@code A} is the size of the
+     * selected layout and {@code S} is the size of the accessed memory segment.</li>
+     * </ul>
      *
      * @apiNote The returned method handle can be used to obtain a memory segment slice, similarly to {@link MemorySegment#asSlice(long, long)},
      * but more flexibly, as some indices can be specified when invoking the method handle.