On Thu, 25 May 2023 15:31:43 GMT, Maurizio Cimadamore <mcimadam...@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 incrementally with one > additional commit since the last revision: > > Tweak javadoc of MemorySegment::get/setUtf8String to deal with overflow I brought over some javadoc improvements from https://github.com/openjdk/jdk/pull/14037 (which has been withdrawn). These improvements should allow us to enable support for Linker in x86 platforms, as they define the notion of "what is a linker supported layout" much more precisely, and in a way that is not dependent on natural alignment (for value layouts). ------------- PR Comment: https://git.openjdk.org/jdk/pull/14098#issuecomment-1564747719
