Merge latest openjdk

src/java.base/share/classes/java/lang/foreign/AddressLayout.java

@@ -35,23 +35,27 @@
 import java.util.Optional;
 
 /**
- * A value layout used to model the address of some region of memory. The carrier associated with an address layout is
- * {@code MemorySegment.class}. The size and alignment of an address layout are platform-dependent
- * (e.g. on a 64-bit platform, the size and alignment of an address layout are set to 8 bytes).
+ * A value layout used to model the address of some region of memory. The carrier
+ * associated with an address layout is {@code MemorySegment.class}. The size and
+ * alignment of an address layout are platform-dependent (e.g. on a 64-bit platform,
+ * the size and alignment of an address layout are set to 8 bytes).
  * <p>
- * An address layout may optionally feature a {@linkplain #targetLayout() target layout}. An address layout with
- * target layout {@code T} can be used to model the address of a region of memory whose layout is {@code T}.
- * For instance, an address layout with target layout {@link ValueLayout#JAVA_INT} can be used to model the address
- * of a region of memory that is 4 bytes long. Specifying a target layout can be useful in the following situations:
+ * An address layout may optionally feature a {@linkplain #targetLayout() target layout}.
+ * An address layout with target layout {@code T} can be used to model the address of a
+ * region of memory whose layout is {@code T}. For instance, an address layout with
+ * target layout {@link ValueLayout#JAVA_INT} can be used to model the address of a
+ * region of memory that is 4 bytes long. Specifying a target layout can be useful in
+ * the following situations:
  * <ul>
- *     <li>When accessing a memory segment that has been obtained by reading an address from another
- *     memory segment, e.g. using {@link MemorySegment#getAtIndex(AddressLayout, long)};</li>
+ *     <li>When accessing a memory segment that has been obtained by reading an address from
+ *     another memory segment, e.g. using {@link MemorySegment#getAtIndex(AddressLayout, long)};</li>
  *     <li>When creating a downcall method handle, using {@link Linker#downcallHandle(FunctionDescriptor, Option...)};
  *     <li>When creating an upcall stub, using {@link Linker#upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...)}.
  * </ul>
  *
  * @implSpec
- * Implementations of this interface are immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
+ * Implementations of this interface are immutable, thread-safe and
+ * <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
  *
  * @see #ADDRESS
  * @see #ADDRESS_UNALIGNED
@@ -84,43 +88,49 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O
     AddressLayout withOrder(ByteOrder order);
 
     /**
-     * Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
-     * but associated with the specified target layout. The returned address layout allows raw addresses to be accessed
-     * as {@linkplain MemorySegment memory segments} whose size is set to the size of the specified layout. Moreover,
-     * if the accessed raw address is not compatible with the alignment constraint in the provided layout,
-     * {@linkplain IllegalArgumentException} will be thrown.
+     * Returns an address layout with the same carrier, alignment constraint, name and
+     * order as this address layout, but associated with the specified target layout.
+     * The returned address layout allows raw addresses to be accessed as
+     * {@linkplain MemorySegment memory segments} whose size is set to the size of the
+     * specified layout. Moreover, if the accessed raw address is not compatible with
+     * the alignment constraint in the provided layout, {@linkplain IllegalArgumentException}
+     * will be thrown.
      * @apiNote
-     * This method can also be used to create an address layout which, when used, creates native memory
-     * segments with maximal size (e.g. {@linkplain Long#MAX_VALUE}). This can be done by using a target sequence
-     * layout with unspecified size, as follows:
+     * This method can also be used to create an address layout which, when used, creates
+     * native memory segments with maximal size (e.g. {@linkplain Long#MAX_VALUE}). This
+     * can be done by using a target sequence layout with unspecified size, as follows:
      * {@snippet lang = java:
      * AddressLayout addressLayout   = ...
      * AddressLayout unboundedLayout = addressLayout.withTargetLayout(
      *         MemoryLayout.sequenceLayout(Long.MAX_VALUE, ValueLayout.JAVA_BYTE));
      *}
      *
-     * @param layout the target layout.
-     * @return an address layout with the same characteristics as this layout, but with the provided target layout.
-     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled
+     * @param layout the target layout
+     * @return an address layout with same characteristics as this layout, but with the
+     *          provided target layout
+     * @throws IllegalCallerException If the caller is in a module that does not have
+     *         native access enabled
      * @see #targetLayout()
      */
     @CallerSensitive
     @Restricted
     AddressLayout withTargetLayout(MemoryLayout layout);
 
     /**
-     * Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
-     * but with no target layout.
+     * Returns an address layout with the same carrier, alignment constraint, name and
+     * order as this address layout, but with no target layout.
      *
-     * @apiNote This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
+     * @apiNote This can be useful to compare two address layouts that have different
+     *          target layouts, but are otherwise equal.
      *
-     * @return an address layout with the same characteristics as this layout, but with no target layout.
+     * @return an address layout with same characteristics as this layout, but with no
+     *         target layout
      * @see #targetLayout()
      */
     AddressLayout withoutTargetLayout();
 
     /**
-     * {@return the target layout associated with this address layout (if any)}.
+     * {@return the target layout associated with this address layout (if any)}
      */
     Optional<MemoryLayout> targetLayout();