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

[Paul Sandoz]

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
> 
> 
>