Clarify javadoc for MemoryLayout::offsetHandle

Summary

The specification for MemoryLayout::offsetHandle doesn't specify under which circumstances the returned MethodHandle can throw IndexOutOfBoundException.

Problem

Consider this layout:

MemoryLayout SEQ = MemoryLayout.sequenceLayout(5,
             MemoryLayout.sequenceLayout(10, JAVA_INT));

And the corresponding offset handle:

MethodHandle offsetHandle = SEQ.offsetHandle(PathElement.sequenceLayout(), PathElement.sequenceLayout());

The resulting method handle takes two additional long indices. The implementation checks that the dynamically provided indices conform to the bound available at construction:

• the first index must be < 5
• the second must be < 10

If any of the above checks fail, then IndexOutOfBoundException is thrown.

However, the javadoc for MemoryLayout::byteOffsetHandle doesn't specify this behavior. This is made worse by the fact that the implementation of other methods in the MemoryLayout API is specified in terms of MemoryLayout::byteOffsetHandle:

• sliceHandle
• varHandle
• arrayElementVarHandle

Solution

MemoryLayout::byteOffsetHandle, and all the methods derived from it should clearly specify what index checks are applied to the method handles/var handles they return.

Specification

• javadoc: https://cr.openjdk.org/~mcimadamore/jdk/8332003/v1/javadoc/api/index.html
• specdiff: https://cr.openjdk.org/~mcimadamore/jdk/8332003/v1/specdiff_out/overview-summary.html