> 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 throw because of an overflow during ...
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
-------------
Changes: https://git.openjdk.org/jdk/pull/14098/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=14098&range=06
Stats: 964 lines in 28 files changed: 357 ins; 138 del; 469 mod
Patch: https://git.openjdk.org/jdk/pull/14098.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/14098/head:pull/14098
PR: https://git.openjdk.org/jdk/pull/14098
