Summary

A Linker should support ways for clients to discover which layouts it supports.

Problem

As already noted in the Linker javadoc, the mapping between ABI types and memory layouts is platform-dependent and ad-hoc. For instance, the C type long might be modeled using a ValueLayout.OfLong on Linux/x64, but the same type might be modeled using a ValueLayout.OfInt on Windows/x64.

Moreover, beyond basic primitive types, different platforms might support different sets of ABI types. For instance, the SysV ABI defines the vector types __m128, __m256 and __m512, although their support might be dependent on the availability of processor-specific vector extensions (e.g. AVX2).

As there is currently no API which clients can use to ask a Linker the set of ABI types it supports, both situations listed above can be problematic.

Solution

We propose to add a new instance method, namely Linker::canonicalLayout which returns a Map<String, MemoryLayout>. In other words, this method returns a map from ABI type names to memory layouts. Clients can use this map to query which ABI types are supported, or to obtain the canonical layout for a given ABI type name.

Different solutions were considered, such as adding an enum with ABI types, or providing different set of platform-specific constants. Both solutions were found to add too much Java SE API surface for ABI types which might be less stable than the JDK itself. For this reason, a Charset-like approach was preferred.

All native linkers should provide canonical layouts for basic (signed) C types (e.g. int, long long etc.). Notably, the set of canonical layouts provided by a native linker does not include ValueLayout.JAVA_CHAR. We have discussed several solutions, such as exposing ValueLayout.JAVA_CHAR as unsigned short, but found them too brittle and ad-hoc, as they did not cover the entire range of C unsigned types. For these reasons, the set of canonical layouts is kept minimal, and the javadoc explicitly states that unsigned types are modeled using the canonical layout for the corresponding signed type.

Specification

Below is a summary of the changes proposed in this CSR:

javadoc: https://cr.openjdk.org/~mcimadamore/jdk/8308293/v3/javadoc/java.base/module-summary.html

specdiff: https://cr.openjdk.org/~mcimadamore/jdk/8308293/v3/specdiff_out/overview-summary.html