src/java.base/share/classes/java/nio/X-Buffer.java.template

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -1867,17 +1867,29 @@
         return this;
     }
 
     /**
      * Returns the memory address, pointing to the byte at the given index,
-     * modulus the given unit size.
+     * modulo the given unit size.
      *
-     * <p> 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 {@code 0} indicates
-     * that the address of the byte at the index is aligned for the unit size.
+     * <p> The return value is non-negative, with {@code 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
+     * <blockquote><pre>
+     * int value = alignmentOffset(index, unitSize)</pre></blockquote>
+     * then the identities
+     * <blockquote><pre>
+     * alignmentOffset(index - value, unitSize) == 0</pre></blockquote>
+     * and
+     * <blockquote><pre>
+     * alignmentOffset(index + (unitSize - value), unitSize) == 0</pre></blockquote>
+     * must hold.
      *
      * @apiNote
      * This method may be utilized to determine if unit size bytes from an
      * index can be accessed atomically, if supported by the native platform.
      *

@@ -1890,11 +1902,11 @@
      *         upper bounds check is performed
      *
      * @param  unitSize
      *         The unit size in bytes, must be a power of {@code 2}
      *
-     * @return  The indexed byte's memory address modulus the unit size
+     * @return  The indexed byte's memory address modulo the unit size
      *
      * @throws IllegalArgumentException
      *         If the index is negative or the unit size is not a power of
      *         {@code 2}
      *

@@ -1916,11 +1928,11 @@
         if (unitSize < 1 || (unitSize & (unitSize - 1)) != 0)
             throw new IllegalArgumentException("Unit size not a power of two: " + unitSize);
         if (unitSize > 8 && !isDirect())
             throw new UnsupportedOperationException("Unit size unsupported for non-direct buffers: " + unitSize);
 
-        return (int) ((address + index) % unitSize);
+        return (int) ((address + index) & (unitSize - 1));
     }
 
     /**
      * Creates a new byte buffer whose content is a shared and aligned
      * subsequence of this buffer's content.