Aligned long views over byte arrays and heap ByteBuffers

[Vitaly Davidovich]

Hi Paul,

isAligned(int,int) could probably use a better name since it's not
returning a boolean.  How about alignIndex(int,int)?

By the way, what's the rationale behind adding new APIs vs the runtime
detection option we discussed earlier?

Thanks

On Wed, Jan 20, 2016 at 8:12 AM, Paul Sandoz <paul.sandoz at oracle.com> wrote:

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