RFR: 8361300: Document exceptions for Unsafe offset methods

[Chen Liang]

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

>> src/java.base/share/classes/jdk/internal/misc/Unsafe.java line 1070:
>> 
>>> 1068:      *
>>> 1069:      * @throws NullPointerException if the field is {@code null}
>>> 1070:      * @throws IllegalArgumentException if the field is static
>> 
>> Maybe these checks could be done in **Java** like:
>> 
>> // implicit null check:
>> if ((f.getModifiers() & ACC_STATIC) != 0) {
>> 	throw new IllegalArgumentException("Field is static");
>> }
>> 
>> and for the `staticField(Offset/Base)` methods:
>> 
>> // implicit null check:
>> if ((f.getModifiers() & ACC_STATIC) == 0) {
>> 	throw new IllegalArgumentException("Field is not static");
>> }
>
> 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.

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

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