Summary

Following the integration of JEP-419, we would like to propose few minor API follow-up changes.

Problem

The changes in this CSR cover two areas:

• First, the name of some of the methods in FunctionDescriptor is unnecessarily verbose. See withAppendedLayoutArguments.
• Secondly, the alignment constraints of value layout constants (see ValueLayout.JAVA_INT) has changed subtly from 17 to 18 - as the constants in 18 do not feature any alignment constraint.

Solution

First, we renamed methods in FunctionDescriptor as follows:

• withAppendedArgumentLayout -> appendArgumentLayout
• withReturnLayout -> changeReturnLayout
• withVoidReturnLayout -> dropReturnLayout

And we added an extra method insertArgumentLayout, to add an argument layout at given index (similar to what's offered by j.l.i.MethodType).

We also reverted alignment constraints of Java layout constants to match VM alignment for Java primitive types. We originally opted for non-aligned constants to maximize flexibility when using these layouts when dereferencing memory segments; but unaligned access is not available on all platforms, and, following some external feedback, it seems like having these constants closely track the layout of primitive types in the JVM is a more stable choice.

Specification

Below is a link to revised javadoc and specdiff (as of Nov, 29th 2021):

Javadoc: http://cr.openjdk.java.net/~mcimadamore/8277924/v1/javadoc/jdk/incubator/foreign/package-summary.html

Specdiff: http://cr.openjdk.java.net/~mcimadamore/8277924/v1/spec_diff/overview-summary.html