On Mon, 12 Jun 2023 10:33:41 GMT, Maurizio Cimadamore <[email protected]>
wrote:
>> As the FFM API evolved over time, some parts of the javadoc went out of
>> sync. Now that most of the API is stable, it is a good time to look again at
>> the javadoc as a whole, and bring some more consistency.
>>
>> While most of the changes in this PR are stylistic, I'd like to call out few
>> things which resulted in API changes:
>>
>> * `MemorySegment::asSlice(long, long, long)` did not (incorrectly) specified
>> requirement that its alignment parameter must be a power of two.
>>
>> * `MemoryLayout::sliceHandle` did not require the absence of dereference
>> paths in the provided layout path. While that is technically possible to
>> allow, currently the method is specified as returning a "slice"
>> corresponding to some "nested layout", so following pointers seems
>> incompatible with the spec. I have decided to disallow for now - we can
>> always compatibly enable it later, if required.
>>
>> * `MemorySegment::copy` - most of the overloads did not specify that
>> `UnsupportedOperationException` is thrown if the destination segment is
>> read-only.
>>
>> * In several places, an extra `@throws IllegalArgumentException` or `@throws
>> IllegalArgumentException` has been added to capture cases where element size
>> * index computation can overflow. This is true for all the element-wise
>> segment copy methods, for the indexed accessors in memory segment (e.g.
>> `MemorySegment.getAtIndex(ValueLayout.OfInt, long)`), as well as for
>> `SegmentAllocator::allocateArray(MemoryLayout, long)`.
>>
>> In all these cases (except for overflows), new tests have been added to
>> cover the additional API changes (a CSR will also be filed to cover these).
>>
>> The class with most changes is `MemoryLayout`. I realized that the javadoc
>> there was a bit sloppy around the definition of "layout paths". Now there
>> are several subsection in the class javadoc, which explain how different
>> kinds of paths can be used. I have introduced the notion of "open path
>> elements" to denote those path elements that are not fully specified, and
>> result in additional var handle coordinates to be added. There is also now a
>> definition of what it means for a layout path to be "well-formed", so that
>> all methods accepting a layout path can simply refer to it (this definition
>> is tricky to give inline in the javadoc of the various path-accepting
>> methods, as it depends on many factors).
>>
>> Another biggie change was in `MemorySegment` as now all dereference methods
>> state precisely their spatial checks requirements, as well also specifying
>> when the API can th...
>
> Maurizio Cimadamore has updated the pull request with a new target base due
> to a merge or a rebase. The pull request now contains 31 commits:
>
> - Merge branch 'master' into javadoc_fixes
> - Fix implementation for byteOffsetHandle to accept ranged open paths.
> - Merge branch 'master' into javadoc_fixes
> - Fix issue with ArithmeticException not being wrapped in IAE for
> SequenceLayout::withElementCount
> Fix issue with IAE thrown instead of UOE for
> ValueLayout::arrayElementVarHandle
> Add apiNote to MemorySegment::address re. reachability
> - Missed a review comment
> - Use more `{@return}` tags
> - Address review comments
> - Fix wrong link in layout well-formedness doc
> - Improve javadoc on supported linker layouts
> - Tweak javadoc of MemorySegment::get/setUtf8String to deal with overflow
> - ... and 21 more: https://git.openjdk.org/jdk/compare/268ec61d...78f7bd24
Re-opening - as per new policies, changes will NOT be automatically forward
ported (see [1]), so we need a separate PR for 22.
[1] - https://mail.openjdk.org/pipermail/jdk-dev/2023-June/007894.html
-------------
PR Comment: https://git.openjdk.org/jdk/pull/14098#issuecomment-1587608037
