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: that is, the first index must be < 5, while
the second must be < 10. If this is not true, an `IndexOutOfBoundException` is
thrown.
However, the javadoc for `MemoryLayout::byteOffsetHandle` doesn't claim
anything in this direction. There are only some vague claims in the javadoc for
`PathElement::sequenceElement()` and `PathElement::sequenceElement(long, long,
long)` which make some claims on which indices are actually allowed, but the
text seems more in the tone of a discussion, rather than actual normative text.
I've tweaked the javadoc for `MemoryLayout::byteOffsetHandle` to actually state
that the indices will be checked against the "size" of the corresponding open
path element (this is a new concept that I also have defined in the javadoc).
I also added a test for `byteOffsetHandle` as I don't think we had a test for
that specifically (although this method is tested indirectly, via
`MemoryLayout::varHandle`).
-------------
Commit messages:
- Initial push
Changes: https://git.openjdk.org/jdk/pull/19158/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=19158&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8332003
Stats: 30 lines in 2 files changed: 26 ins; 0 del; 4 mod
Patch: https://git.openjdk.org/jdk/pull/19158.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/19158/head:pull/19158
PR: https://git.openjdk.org/jdk/pull/19158
