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

(bf spec) ByteBuffer::alignmentOffset spec misleading when address is misaligned

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 14
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Specification change only.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Modify the specification of java.nio.ByteBuffer.alignmentOffset to be more clear about the meaning of the value it calculates.

      Problem

      java.nio.ByteBuffer.alignmentOffset is unclear that a returned value of zero means that the supplied index is aligned with the unit size and about the significance of a non-zero return value.

      Solution

      Revise the method specification to be clear about the meaning of the value it calculates.

      Specification

      See also the attached webrev.

      Old Specification

      Returns the memory address, pointing to the byte at the given index, modulus the given unit size.

      A return value greater than zero indicates the address of the byte at the index is misaligned for the unit size, and the value's quantity indicates how much the index should be rounded up or down to locate a byte at an aligned address. Otherwise, a value of 0 indicates that the address of the byte at the index is aligned for the unit size.

      New Specification

      Returns the memory address, pointing to the byte at the given index, modulo the given unit size.

      The return value is non-negative, with 0 indicating that the address of the byte at the index is aligned for the unit size, and a positive value that the address is misaligned for the unit size. If the address of the byte at the index is misaligned, the return value represents how much the index should be adjusted to locate a byte at an aligned address. Specifically, the index should either be decremented by the return value, or incremented by the unit size minus the return value. Therefore given

       int value = alignmentOffset(index, unitSize)

      then the identities

       alignmentOffset(index - value, unitSize) == 0

      and

       alignmentOffset(index + (unitSize - value), unitSize) == 0

      must hold.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bpb Brian Burkhalter
                Reporter:
                kganapureddy Krushnareddy Ganapureddy
                Reviewed By:
                Alan Bateman, Paul Sandoz
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: