[foreign-abi] RFR: 8248560: Specify the behaviour of the ForeignLinker returned by CSupport::getSystemLinker

[Jorn Vernee]

On Tue, 15 Sep 2020 15:21:59 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Hi,
>> 
>> This patch creates a new class called CLinker, which extends ForeignLinker. The new class documents how linking works
>> in the class's javadoc. This is done in a separate class since the specification is only relevant to linkers that
>> support the C ABI.  With the new class there was no more need to have CSupport, so the contents of CSupport has all
>> been move to CLinker.
>> After some offline discussion with Maurizio, we realized that it doesn't make much sense to expose platform specific
>> layout constants, since it is not possible to combine them with a platform specific linker any way, so for a particular
>> platform, there is only one set of layouts that can be used, namely the ones that are dynamically picked based on the
>> current platform. For that reason, all platform specific layouts have instead been moved to an internal PlatformLayouts
>> class. In order for downstream APIs (like jextract) to be able to filter out the ABI attributes from layouts, I've
>> added a String constant to CLinker that is used as a name prefix for all the ABI attribute names, so clients can for
>> instance filter attribute names using `.startsWith(ABI_ATTR_NAME)`.  The ForeignLinker::name method has been dropped in
>> favor of an internal enum.  The rest of the patch is just mechanical CSupport -> CLinker renames.  Thanks, Jorn
>
> src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/CLinker.java line 83:
> 
>> 81:  * variadic function by using a 'specialized' method type and function descriptor: for each argument that is to be
>> 82:  * passed as a variadic argument, an explicit carrier type and memory layout must be present in the method type and
>> 83:  * function descriptor when linking the function. Furthermore, the memory layouts of variadic arguments must
> 
> Furthermore, as memory layouts corresponding to variadic arguments in a function descriptor must contain additional
> classification information, it is required that the function {@link #asVarArg(MemoryLayout)} is called on each
> parameter layout that is used to compose a specialized variadic function descriptor.

This is not quite correct, as it must only be called on variadic arguments, not fixed ones. I went with:

Furthermore, as memory layouts corresponding to variadic arguments in a function descriptor must contain additional
classification information, it is required that {@link #asVarArg(MemoryLayout)} is used to create the memory layouts
for each parameter corresponding to a variadic arguments in a specialized function descriptor.

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

PR: https://git.openjdk.java.net/panama-foreign/pull/327