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

[Volkan Yazici]

On Thu, 31 Jul 2025 19:04:34 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:
> 
>   Less specific reasons for IAE

I don't possess sufficient experience on `Unsafe` et al., though given there are no behavioral changes, I presume it should all be fine. I've verified the following:

* `Unsafe` doc improvements
* `U::objectFieldOffset(Class,String)` throws descriptive `IE`
* `U::objectFieldOffset1` is renamed to more descriptive `knownObjectFieldOffset0`
* `Atomic*FieldUpdater` checks and their TCK counterparts (This could have actually been a separate PR, but I see that the component owners gave consent.)
* `AddressComputationContractTest`

I guess you will have a follow-up JBS ticket (along with a PR? 😇) for @minborg's [suggestion on consolidating checks in `Atomic*FieldUpdater` classes](https://github.com/openjdk/jdk/pull/25945/files#r2189548142). For instance, I see `AIFU.AIFUImpl::isAncestor` is not even used.

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

> 62: 
> 63:     @Test
> 64:     void fastObjectFieldOffset() {

Nit: You may want to match the corresponding impl. method name, as you did in other test methods:

Suggestion:

    void knownObjectFieldOffset() {

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

Marked as reviewed by vyazici (Committer).

PR Review: https://git.openjdk.org/jdk/pull/25945#pullrequestreview-3078367564
PR Review Comment: https://git.openjdk.org/jdk/pull/25945#discussion_r2247407686