archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 06:45:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8326172: Dubious claim on long[]/double[] alignment in MemorySegment javadoc

Browse source 
Reviewed-by: mcimadamore
This commit is contained in:
Jorn Vernee 2024-03-05 13:32:24 +00:00
parent c653e67c0f
commit 2372aba6a2
10 changed files with 44 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

35
src/java.base/share/classes/java/lang/foreign/MemorySegment.java
View file

@ -305,8 +305,7 @@ import jdk.internal.vm.annotation.ForceInline;
* and/or garbage collection behavior).
* <p>
* In practice, the Java runtime lays out arrays in memory so that each n-byte element
* occurs at an n-byte aligned physical address (except for {@code long[]} and
* {@code double[]}, where alignment is platform-dependent, as explained below). The
* occurs at an n-byte aligned physical address. The
* runtime preserves this invariant even if the array is relocated during garbage
* collection. Access operations rely on this invariant to determine if the specified
* offset in a heap segment refers to an aligned address in physical memory.
@ -325,26 +324,17 @@ import jdk.internal.vm.annotation.ForceInline;
* would correspond to physical address 1008 but offset 4 would correspond to
* physical address 1010.</li>
* <li>The starting physical address of a {@code long[]} array will be 8-byte aligned
* (e.g. 1000) on 64-bit platforms, so that successive long elements occur at
* 8-byte aligned addresses (e.g., 1000, 1008, 1016, 1024, etc.) On 64-bit platforms,
* a heap segment backed by a {@code long[]} array can be accessed at offsets
* 0, 8, 16, 24, etc under an 8-byte alignment constraint. In addition, the segment
* can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint,
* because the target addresses (1000, 1004, 1008, 1012) are 4-byte aligned. And,
* the segment can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment
* constraint, because the target addresses (e.g. 1000, 1002, 1004, 1006) are
* 2-byte aligned.</li>
* <li>The starting physical address of a {@code long[]} array will be 4-byte aligned
* (e.g. 1004) on 32-bit platforms, so that successive long elements occur at 4-byte
* aligned addresses (e.g., 1004, 1008, 1012, 1016, etc.) On 32-bit platforms, a heap
* segment backed by a {@code long[]} array can be accessed at offsets
* 0, 4, 8, 12, etc under a 4-byte alignment constraint, because the target addresses
* (1004, 1008, 1012, 1016) are 4-byte aligned. And, the segment can be accessed at
* offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint, because the target
* addresses (e.g. 1000, 1002, 1004, 1006) are 2-byte aligned.</li>
* (e.g. 1000), so that successive long elements occur at 8-byte aligned addresses
* (e.g., 1000, 1008, 1016, 1024, etc.) A heap segment backed by a {@code long[]}
* array can be accessed at offsets 0, 8, 16, 24, etc under an 8-byte alignment
* constraint. In addition, the segment can be accessed at offsets 0, 4, 8, 12,
* etc under a 4-byte alignment constraint, because the target addresses (1000, 1004,
* 1008, 1012) are 4-byte aligned. And, the segment can be accessed at offsets 0, 2,
* 4, 6, etc under a 2-byte alignment constraint, because the target addresses (e.g.
* 1000, 1002, 1004, 1006) are 2-byte aligned.</li>
* </ul>
* <p>
* In other words, heap segments feature a (platform-dependent) <em>maximum</em>
* In other words, heap segments feature a <em>maximum</em>
* alignment which is derived from the size of the elements of the Java array backing the
* segment, as shown in the following table:
*
@ -389,10 +379,7 @@ import jdk.internal.vm.annotation.ForceInline;
* In such circumstances, clients have two options. They can use a heap segment backed
* by a different array type (e.g. {@code long[]}), capable of supporting greater maximum
* alignment. More specifically, the maximum alignment associated with {@code long[]} is
* set to {@code ValueLayout.JAVA_LONG.byteAlignment()} which is a platform-dependent
* value (set to {@code ValueLayout.ADDRESS.byteSize()}). That is, {@code long[]}) is
* guaranteed to provide at least 8-byte alignment in 64-bit platforms, but only 4-byte
* alignment in 32-bit platforms:
* set to {@code ValueLayout.JAVA_LONG.byteAlignment()}, which is 8 bytes:
*
* {@snippet lang=java :
* MemorySegment longSegment = MemorySegment.ofArray(new long[10]);

3
src/java.base/share/classes/java/lang/foreign/ValueLayout.java
View file

@ -47,9 +47,6 @@ import jdk.internal.foreign.layout.ValueLayouts;
* For instance, the byte order of these constants is set to the
* {@linkplain ByteOrder#nativeOrder() native byte order}, thus making it easy
* to work with other APIs, such as arrays and {@link java.nio.ByteBuffer}.
* Moreover, the alignment constraint of {@link ValueLayout#JAVA_LONG} and
* {@link ValueLayout#JAVA_DOUBLE} is set to 8 bytes on 64-bit platforms,
* but only to 4 bytes on 32-bit platforms.
*
* @implSpec implementing classes and subclasses are immutable, thread-safe and
* <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.