Summary

The javadoc of some parts of the FFM API is inconsistent with how the implementation has evolved, and needs to be clarified.

Problem

As the FFM API evolved over time, some parts of the javadoc went out of sync. Some examples:

• MemorySegment::asSlice(long, long, long) does not (incorrectly) specified requirement that its alignment parameter must be a power of two.
• MemoryLayout::sliceHandle does not (incorrectly) 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.
• MemorySegment::copy - most of the overloads do not specify that UnsupportedOperationException is thrown if the destination segment is read-only.
• Several places are missing an extra @throws IllegalArgumentException or @throws IndexOutOfBoundsException 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).

Solution

The aforementioned API issues should be resolved as follows:

• Require that MemorySegment::asSlice(long, long, long) must accept an alignment parameter that is a power of two;
• Require that MemoryLayout::sliceHandle cannot accept any dereference layout path elements;
• Document that MemorySegment::copy can fail with UnsupportedOperationException if the destination segment is read-only;
• Add extra @throws IllegalArgumentException or @throws IndexOutOfBoundsException to document spatial bound checks, where required.

From a stylistic perspective, the javadoc with most changes in MemoryLayout. The reason for this is that this interface had only little changes across different iterations of the FFM API. We decided to add new toplevel section to better showcase the abilities of the memory layout API.

Specification

A specdiff for this changes (v1) is attached to this CSR, and also available below:

https://cr.openjdk.org/~mcimadamore/jdk/8308645/v1/javadoc/java.base/module-summary.html

https://cr.openjdk.org/~mcimadamore/jdk/8308645/v1/specdiff_out/overview-summary.html