Integrated: 8332003: Clarify javadoc for MemoryLayout::offsetHandle
Maurizio Cimadamore
mcimadamore at openjdk.org
Wed May 15 14:43:07 UTC 2024
On Thu, 9 May 2024 15:00:35 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:
> 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`).
This pull request has now been integrated.
Changeset: 30bb066b
Author: Maurizio Cimadamore <mcimadamore at openjdk.org>
URL: https://git.openjdk.org/jdk/commit/30bb066b1982c5318d54bfe74115306c602e2974
Stats: 67 lines in 2 files changed: 61 ins; 0 del; 6 mod
8332003: Clarify javadoc for MemoryLayout::offsetHandle
Reviewed-by: psandoz
-------------
PR: https://git.openjdk.org/jdk/pull/19158
More information about the core-libs-dev
mailing list