RFR: 8308645: Javadoc of FFM API needs to be refreshed [v6]

[Maurizio Cimadamore]

On Tue, 6 Jun 2023 10:35:09 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> 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 29 commits:
> 
>  - 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
>  - Merge branch 'master' into javadoc_fixes
>  - Add overflow tests
>  - ... and 19 more: https://git.openjdk.org/jdk/compare/01455a07...b59edd93

Closing, as the review is complete and I have to rebase against the forked 21 repo. A similar PR will pop up soon :-)

-------------

PR Comment: https://git.openjdk.org/jdk/pull/14098#issuecomment-1587049739