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

[Paul Sandoz]

Looks good, esp. the common implementation routine.

Paul.

> On Jan 7, 2020, at 6:25 AM, Maurizio Cimadamore <maurizio.cimadamore at oracle.com> wrote:
> 
> Another update:
> 
> http://cr.openjdk.java.net/~mcimadamore/panama/8236267_v3
> 
> I've rewritten all the layout path-accepting methods to use a common implementation routine. This also helped shaking out an issue in a test (TestLayoutPaths::testBadSequencePathInOffset) which was expecting a failure on a correct path element (MemoryLayout::offset() should only choke on unspecified sequence element selections).
> 
> Maurizio
> 
> On 07/01/2020 12:47, Maurizio Cimadamore wrote:
>> Updated webrev here:
>> 
>> http://cr.openjdk.java.net/~mcimadamore/panama/8236267_v2/
>> 
>> Cheers
>> Maurizio
>> 
>> On 19/12/2019 14:52, Maurizio Cimadamore 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
>>> 
>>> 
>>>