RFR: 8361300: Document exceptions for Unsafe offset methods [v4]

[John R Rose]

On Thu, 3 Jul 2025 18:41:27 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Unsafe throws IAE for misusing static vs instance fields, and it's revealed that AtomicXxxFieldUpdaters are using this mechanism to reject static fields. This is not a good practice, but we can at least document this so we don't accidentally introduce problems.
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Test to verify observed internal unsafe behaviors

src/java.base/share/classes/jdk/internal/misc/Unsafe.java line 3861:

> 3859:     private native void copySwapMemory0(Object srcBase, long srcOffset, Object destBase, long destOffset, long bytes, long elemSize);
> 3860:     private native long objectFieldOffset0(Field f); // throws IAE
> 3861:     private native long objectFieldOffset1(Class<?> c, String name); // throws InternalError

Ugh; this IE is part of the problem.  You could push an IAE into the C++ code for symmetry, or start pushing more IAE logic into the Java code (my preference, but a bigger change perhaps).

I can tell you that the original intention of choosing InternalError is to mark places where the caller has a responsibility to make InternalError impossible.  InternalError is not intended to trigger further processing; it denotes system failure.

test/jdk/jdk/internal/misc/Unsafe/AddressComputationContractTest.java line 69:

> 67:         assertThrows(NullPointerException.class, () -> getUnsafe().objectFieldOffset(null, "instanceField"));
> 68:         assertThrows(NullPointerException.class, () -> getUnsafe().objectFieldOffset(AddressComputationContractTest.class, null));
> 69:         assertThrows(InternalError.class, () -> getUnsafe().objectFieldOffset(AddressComputationContractTest.class, "doesNotExist"));

This is a malformed test on a malformed API.  VirtualMachineError exceptions signal system failure.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/25945#discussion_r2243472376
PR Review Comment: https://git.openjdk.org/jdk/pull/25945#discussion_r2243477795