Aligned long views over byte arrays and heap ByteBuffers

[Paul Sandoz]

I propose the following methods on ByteBuffer:

/**
 * Returns the memory address, pointing to the byte at the given index,
 * modulus the given unit size.
 *
 * <p> A return value of zero indicates the byte at the index is aligned to
 * the unit size, otherwise the value indicates how much the index should be
 * rounded down or up to locate the nearest aligned byte.
 *
 * <p> If the unit size is a power of two then this method may be utilized
 * to determine if unit size bytes from the index can be accessed
 * atomically, if supported by the native platform.
 *
 * @param  index
 *         The index to query for alignment, must be non-negative, no upper
 *         bounds check is performed
 *
 * @param  unitSize
 *         The unit size, must be positive
 *
 * @return  The indexed byte's memory address modulus the unit size
 *
 * @throws IllegalArgumentException
 *         If the index is negative or the unit size is non-positive
 *
 * @see #alignedSlice(int)
 * @since 9
 */
public final int isAligned(int index, int unitSize)

/**
 * Creates a new byte buffer whose content is a shared and aligned
 * subsequence of this buffer's content.
 *
 * <p> The content of the new buffer will start at this buffer's current
 * position rounded up to the index of the nearest aligned byte for the
 * given unit size, and end at this buffer's limit rounded down to the index
 * of the nearest aligned byte for the given unit size.
 * The new buffer's current position and limit will equal this buffer's
 * position if rounding results in out-of-bound values.  If rounding is
 * within bounds the following expressions will be true for a new buffer
 * {@code nb} and unit size {@code unitSize}:
 * <pre>{@code
 * nb.isAligned(nb.position(), unitSize) == 0
 * nb.isAligned(nb.limit(), unitSize) == 0
 * (nb.limit() - nb.position()) % unitSize == 0
 * }</pre>
 *
 * <p> Changes to this buffer's content will be visible in the new
 * buffer, and vice versa; the two buffers' position, limit, and mark
 * values will be independent.
 *
 * <p> The new buffer's position will be zero, its mark will be undefined,
 * and its byte order will be {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 *
 * The new buffer will be direct if, and only if, this buffer is direct, and
 * it will be read-only if, and only if, this buffer is read-only.  </p>
 *
 * @param  unitSize
 *         The unit size, must be positive
 *
 * @return  The new byte buffer
 *
 * @throws IllegalArgumentException
 *         If the unit size is non-positive
 *
 * @see #isAligned(int, int)
 * @see #slice()
 * @since 9
 */
public final ByteBuffer alignedSlice(int unitSize)

Paul.

> On 18 Jan 2016, at 19:08, John Rose <john.r.rose at oracle.com> wrote:
> 
> 
>> On Jan 18, 2016, at 6:17 AM, Aleksey Shipilev <aleksey.shipilev at oracle.com> wrote:
>> 
>> That being said, there probably are VMs
> 
> 
> Such exotic VMs (for tiny platforms, perhaps) can throw appropriate UOEs.
> 
> Most widespread 32-bit system ABIs align long variables. We can expect nearly all JVMs to loosely follow ABI practices.
> 
> If you don't like the UOEs and want bullet proof GC-able buffers, simply use long arrays.
> 
> Later, we will get into odd territory if we introduce jumbo alignments for fast vector work. (E.g. AlignedLong4[] or Aligned<Long4>[] or even Aligned<256,Long4>[].) Such arrays will need special GC processing to enforce alignment, and byte arrays will probably never be conformable to such requirements. We may want to have a factory method for building maximally aligned buffers.
> 
> – John
>