RFR: 8304265: Implementation of Foreign Function and Memory API (Third Preview) [v5]

[Maurizio Cimadamore]

On Tue, 21 Mar 2023 00:54:10 GMT, Paul Sandoz <psandoz at openjdk.org> wrote:

>> Per Minborg has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Add example for Option::captureStateLayout
>
> src/java.base/share/classes/java/lang/foreign/Linker.java line 621:
> 
>> 619:          *          to a downcall handle linked with {@link #captureCallState(String...)}}
>> 620:          *
>> 621:          * @see #captureCallState(String...)
> 
> How does a caller know what the structure may contain? Should we document the platform specific structures?

Back to @PaulSandoz  question - "how does the caller know what the structure contains?". The caller typically doesn't care too much about what the returned struct is. But it might care about which "values" can be captured. That said, the set of such interesting values, is not too surprising. As demonstrated in the example in the `Linker.capturedCallState` method, once the client knows the name (and "errno" is likely to be 90% case), everything else follows from there - as the layout can be used to obtain var handles for the required values.

But, perhaps, now that I write this, I realize that what @PaulSandoz might _really_ be asking is: how do I know that e.g. the returned struct will not contain e.g. nested structs, sequences, or other non-sense. So we might specify (in a normative way) that the returned layout is a struct layout, whose member layouts are one or more value layouts (possibly with some added padding layouts). The names of the value layouts reflect the names of the values that can be captured.

And _then_ we show an example of the layout we return for Windows/x64 (as that's more interesting).

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/13079#discussion_r1143281164