[foreign-memaccess] RFR 8236267: Cleanup support for layouts with undefined size

[Maurizio Cimadamore]

Thanks for the comments Paul and Jorn - will address and resubmit.

Maurizio

On 06/01/2020 18:28, Paul Sandoz wrote:
> Suggested JavaDoc tweaks.  I had to look a little more deeply as to what MemoryLayout.map was doing.
>
>
>   313      * Obtains the layout selected by a given layout path, where the path is considered rooted in this layout.
>
> -> "Selects the layout from a path rooted in this layout."
>
>
> 335     /**
>   336      * Transform the layout selected by a given layout path, where the path is considered rooted in this layout,
>   337      * according to the specified unary operation.
>
> IIUC this copies the layout with the exception that the selected layout is mapped.
>
> -> "Creates a transformed copy of this layout where a selected layout, from a path rooted in this layout, is replaced with the result of applying the given operation."
>    
>
>
> TestLayoutPaths.java
> —
>
>   144         for (PathElement e : new PathElement[] { PathElement.sequenceElement(), PathElement.sequenceElement(0, 2) }) {
>
> FWIW using List.of(…) may be marginally more readable.
>
>
> Paul.
>
>
>> On Dec 19, 2019, at 6:52 AM, Maurizio Cimadamore <maurizio.cimadamore at oracle.com> wrote:
>>
>> Hi,
>> I decided to go ahead and create a separate issue for dealing with unbounded sequence layouts, since it seems like the API has some aspects which makes it difficult to deal with them:
>>
>> * it is not possible to establish whether a layout has a size, and hence whether e.g. passing it to MemorySegment::allocateNative will blow up
>> * there's no way, given a layout which contains one or more unbound sequences to replace them with bounded ones - w/o recreating everything from scratch
>>
>> This patch fixes these problems by:
>>
>> * adding an hasSize() predicate to all layouts
>> * adding a way to 'map' a layout given a path - that is, create a new layout where one nested element has been replaced using a given unary operator
>>
>> Separately, I've also added a way to 'select' a nested layout given a path (which is not strictly necessary, but seems a nice to have).
>>
>> Webrev:
>>
>> http://cr.openjdk.java.net/~mcimadamore/panama/8236267/
>>
>> I've also updated javadoc here:
>>
>> http://cr.openjdk.java.net/~mcimadamore/panama/memaccess_javadoc/jdk/incubator/foreign/package-summary.html
>>
>> I've done a significant cleanup of the javadoc associated with the methods accepting layout paths (as well as their implementations), as there were a number of issues:
>>
>> * the javadoc were not documenting that some path element selection could fail (e.g. if traversing a layout with no size)
>> * related, the newly created methods should be robust to the lack of size in a traversed layout (as they are more about selection than about precise offset computation)
>> * we were not clear (both in spec and impl) re. which PahElement are allowed on each of the path-accepting methods. For instance, passing PathElement.sequenceElement() to MemoryLayout::offset() makes no sense, as it does not select a single layout element with given offset. Similarly, the newly added methods have other restrictions which are documented (and tested)
>> * I've added more examples in the MemoryLayout toplevel javadoc, to show how layout paths can be used
>>
>> Cheers
>> Maurizio
>>
>>
>>