RFR: 8308293: A linker should expose the layouts it supports

[Maurizio Cimadamore]

On Wed, 17 May 2023 17:15:06 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch adds an instance method on `Linker`, namely `Linker::canonicalLayouts` which returns all the layouts known by the linker as implementing some ABI type. For instance, if I call this on my machine (Linux/x64) I get this:
> 
> 
> jshell> import java.lang.foreign.*;
> 
> jshell> Linker.nativeLinker().canonicalLayouts()
> $2 ==> {char16_t=c16, int8_t=b8, long=j64, size_t=j64, bool=z8, int=i32, long long=j64, int64_t=j64, void*=a64, float=f32, char=b8, int16_t=s16, int32_t=i32, short=s16, double=d64}
> 
> 
> This can be useful to discover the ABI types supported by a linker implementation, as well as for, in the future, add support for more exotic (and platform-dependent) linker types, such as `long double` or `complex long`.

javadoc: https://cr.openjdk.org/~mcimadamore/jdk/8308293/v1/javadoc/java.base/module-summary.html
specdiff: https://cr.openjdk.org/~mcimadamore/jdk/8308293/v1/specdiff_out/overview-summary.html

src/java.base/share/classes/java/lang/foreign/Linker.java line 205:

> 203:  * </table></blockquote>
> 204:  * <p>
> 205:  * All the native linker implementations can only operate on a subset of memory layouts, called <em>supported layouts</em>.

I revamped this section as I realized that what we had did not cover things in the recursive case - e.g. a struct layout is only supported if it contains other supported layouts. This new text should hopefully capture everything in a more mathematical form.

src/java.base/share/classes/java/lang/foreign/Linker.java line 595:

> 593: 
> 594:     /**
> 595:      * {@return a mapping between the names of data types used by the ABI implemented by this linker and their

Much of the verbiage here is carried over from `defaultLookup` as we need to do the usual dance of saying that the set of returned types is not specified, but should be (a) sensible and (b) stable.

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

PR Comment: https://git.openjdk.org/jdk/pull/14037#issuecomment-1551817970
PR Review Comment: https://git.openjdk.org/jdk/pull/14037#discussion_r1196842518
PR Review Comment: https://git.openjdk.org/jdk/pull/14037#discussion_r1196841486