On Thu, 9 May 2024 18:26:17 GMT, Maurizio Cimadamore <mcimadam...@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`).
>
> Maurizio Cimadamore has updated the pull request incrementally with two
> additional commits since the last revision:
>
> - Update copyright
> - Add javadoc to other MemoryLayout methods returning VarHandle/MethodHandle
> to describe which exception can be thrown by returned handle
src/java.base/share/classes/java/lang/foreign/MemoryLayout.java line 574:
> 572: * {@code c_1}, {@code c_2}, ... {@code c_m} are other
> <em>static</em> offset
> 573: * constants (such as field offsets) which are derived from the
> layout path.
> 574: * <p>
Can we connected back to the prior paragraph? e.g., for any given dynamic
argument `x_n`, the index into the sequence associated with the n'th open path
element whose size is `size_n`,`x_n` must be `>= 0` or `< size_n`
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/19158#discussion_r1595836040
