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

8318966: Some methods make promises about Java array element alignment that are too strong

Browse source 
Reviewed-by: psandoz, mcimadamore
This commit is contained in:
Jorn Vernee 2024-02-14 14:30:54 +00:00
parent 737b4c515e
commit 9c852df6aa
19 changed files with 1850 additions and 4678 deletions
Download patch file Download diff file Expand all files Collapse all files

62
src/java.base/share/classes/java/lang/invoke/MethodHandles.java
View file

@ -4513,48 +4513,18 @@ return mh1;
* or greater than the {@code byte[]} array length minus the size (in bytes)
* of {@code T}.
* <p>
* Access of bytes at an index may be aligned or misaligned for {@code T},
* with respect to the underlying memory address, {@code A} say, associated
* with the array and index.
* If access is misaligned then access for anything other than the
* {@code get} and {@code set} access modes will result in an
* {@code IllegalStateException}. In such cases atomic access is only
* guaranteed with respect to the largest power of two that divides the GCD
* of {@code A} and the size (in bytes) of {@code T}.
* If access is aligned then following access modes are supported and are
* guaranteed to support atomic access:
* <ul>
* <li>read write access modes for all {@code T}, with the exception of
* access modes {@code get} and {@code set} for {@code long} and
* {@code double} on 32-bit platforms.
* <li>atomic update access modes for {@code int}, {@code long},
* {@code float} or {@code double}.
* (Future major platform releases of the JDK may support additional
* types for certain currently unsupported access modes.)
* <li>numeric atomic update access modes for {@code int} and {@code long}.
* (Future major platform releases of the JDK may support additional
* numeric types for certain currently unsupported access modes.)
* <li>bitwise atomic update access modes for {@code int} and {@code long}.
* (Future major platform releases of the JDK may support additional
* numeric types for certain currently unsupported access modes.)
* </ul>
* <p>
* Misaligned access, and therefore atomicity guarantees, may be determined
* for {@code byte[]} arrays without operating on a specific array. Given
* an {@code index}, {@code T} and its corresponding boxed type,
* {@code T_BOX}, misalignment may be determined as follows:
* <pre>{@code
* int sizeOfT = T_BOX.BYTES; // size in bytes of T
* int misalignedAtZeroIndex = ByteBuffer.wrap(new byte[0]).
* alignmentOffset(0, sizeOfT);
* int misalignedAtIndex = (misalignedAtZeroIndex + index) % sizeOfT;
* boolean isMisaligned = misalignedAtIndex != 0;
* }</pre>
* <p>
* If the variable type is {@code float} or {@code double} then atomic
* update access modes compare values using their bitwise representation
* (see {@link Float#floatToRawIntBits} and
* {@link Double#doubleToRawLongBits}, respectively).
* Only plain {@linkplain VarHandle.AccessMode#GET get} and {@linkplain VarHandle.AccessMode#SET set}
* access modes are supported by the returned var handle. For all other access modes, an
* {@link UnsupportedOperationException} will be thrown.
*
* @apiNote if access modes other than plain access are required, clients should
* consider using off-heap memory through
* {@linkplain java.nio.ByteBuffer#allocateDirect(int) direct byte buffers} or
* off-heap {@linkplain java.lang.foreign.MemorySegment memory segments},
* or memory segments backed by a
* {@linkplain java.lang.foreign.MemorySegment#ofArray(long[]) {@code long[]}},
* for which stronger alignment guarantees can be made.
*
* @param viewArrayClass the view array class, with a component type of
* type {@code T}
* @param byteOrder the endianness of the view array elements, as
@ -4600,7 +4570,13 @@ return mh1;
* or greater than the {@code ByteBuffer} limit minus the size (in bytes) of
* {@code T}.
* <p>
* Access of bytes at an index may be aligned or misaligned for {@code T},
* For heap byte buffers, access is always unaligned. As a result, only the plain
* {@linkplain VarHandle.AccessMode#GET get}
* and {@linkplain VarHandle.AccessMode#SET set} access modes are supported by the
* returned var handle. For all other access modes, an {@link IllegalStateException}
* will be thrown.
* <p>
* For direct buffers only, access of bytes at an index may be aligned or misaligned for {@code T},
* with respect to the underlying memory address, {@code A} say, associated
* with the {@code ByteBuffer} and index.
* If access is misaligned then access for anything other than the