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

[John R Rose]

On Tue, 24 Jun 2025 18:40:45 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Don't think anyone is willing to change code here...
>
> That said, the only places that depend on this IAE behavior is the AtomicXxxFieldUpdater classes. All other sites pass trusted fields into these methods, of course besides the sun.misc.Unsafe users which definitely need this IAE. Still I personally prefer adding these checks to atomic field updaters instead of here to reduce risky dependencies.

As I commented on the C++ change, I think it's better to put the check in Java rather than C++.

The behavioral results are equivalent, right?  It is fine to upgrade the InternalError to IAE; InternalError is by definition a poorly-defined state, and IAE is a less poorly defined way to report it.  Changing that path to throw IAE is better, since it aligns with other field-query APIs.  Because we control use of Unsafe (in this package) we can make small changes like this and just adjust our own code if something breaks.

Error checks and validations in Java code will be 10x clearer (more maintainable, scrutable to JITs) than logic in the C++ code.

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

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