A DESCRIPTION OF THE PROBLEM :
The documentation for the `jdk.internal.misc.Unsafe` methods `putAddress(Object, long, long)` and `getAddress(Object, long)` is misleading. It currently says:
> Stores a native pointer into a given memory address. If the address is
> zero, or does not point into a block obtained from {@link
> #allocateMemory}, the results are undefined.
The confusion comes from the fact that "address" here can refer to the value being written or read, or the location where the value is being written to or read from.
It might not be clear what "address" (especially the second occurrence) refers to:
- none of the parameters are named "address"
- the method is named "getAddress" / "putAddress", so it could refer to the value being written or read
- the first sentence of the documentation calls the value "native pointer", so "address" could refer to the memory address where the value is stored
Part of this problem originates from https://github.com/openjdk/jdk/commit/2b1fdef17a5fffe8ce0076a5e2d1b0e70aafd3ae where previously only the "single-register addressing mode" existed for these methods and the parameter was called "address", but the documentation was copied to the new method overloads mostly as-is.
Suggested changes:
- reword the first two sentences of `putAddress` and `getAddress` for example to:
> Stores a native pointer. The first two parameters are interpreted as described by {@link #putInt(Object, long, int)} (the implementation might however not delegate to {@code putInt}).
- maybe: rename the parameter "x" to "pointer"?
- maybe: rename the parameter "x" of `putAddress(long, long)` to "pointer"?
The documentation for the `jdk.internal.misc.Unsafe` methods `putAddress(Object, long, long)` and `getAddress(Object, long)` is misleading. It currently says:
> Stores a native pointer into a given memory address. If the address is
> zero, or does not point into a block obtained from {@link
> #allocateMemory}, the results are undefined.
The confusion comes from the fact that "address" here can refer to the value being written or read, or the location where the value is being written to or read from.
It might not be clear what "address" (especially the second occurrence) refers to:
- none of the parameters are named "address"
- the method is named "getAddress" / "putAddress", so it could refer to the value being written or read
- the first sentence of the documentation calls the value "native pointer", so "address" could refer to the memory address where the value is stored
Part of this problem originates from https://github.com/openjdk/jdk/commit/2b1fdef17a5fffe8ce0076a5e2d1b0e70aafd3ae where previously only the "single-register addressing mode" existed for these methods and the parameter was called "address", but the documentation was copied to the new method overloads mostly as-is.
Suggested changes:
- reword the first two sentences of `putAddress` and `getAddress` for example to:
> Stores a native pointer. The first two parameters are interpreted as described by {@link #putInt(Object, long, int)} (the implementation might however not delegate to {@code putInt}).
- maybe: rename the parameter "x" to "pointer"?
- maybe: rename the parameter "x" of `putAddress(long, long)` to "pointer"?
- caused by
-
JDK-8150921 Update Unsafe getters/setters to use double-register variants
-
- Resolved
-