Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8358462

Unsafe putAddress and getAddress documentation is misleading

XMLWordPrintable

    • generic
    • generic

      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"?



            Unassigned Unassigned
            webbuggrp Webbug Group
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated: