RFR: 8295044: Implementation of Foreign Function and Memory API (Second Preview)

[Maurizio Cimadamore]

On Wed, 26 Oct 2022 13:11:50 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This PR contains the API and implementation changes for JEP-434 [1]. A more detailed description of such changes, to avoid repetitions during the review process, is included as a separate comment.
> 
> [1] - https://openjdk.org/jeps/434

Here are the main API changes introduced in this round (there are also some JVM changes which will be integrated separately):

* The main change is the removal of `MemoryAddress` and `Addressable`. Instead, *zero-length memory segments* are used whenever the API needs to model "raw" addresses coming from native code. This simplifies the API, removing an ambiguous abstraction as well as some duplication in the API (see accessor methods in `MemoryAddress`);

* To allow for "unsafe" access of zero-length memory segments, a new method has been added to `ValueLayout.OfAddress`, namely `asUnbounded`. This new restricted method takes an address layout and creates a new unbounded address layout. When using an unbounded layout to dereference memory, or construct downcall method handles, the API will create memory segments with maximal length (i.e. `Long.MAX_VALUE`, rather than zero-length memory segments, which can therefore be accessed;

* The `MemoryLayout` hierarchy has been improved in several ways. First, the hierarchy is now defined in terms of sealed interfaces (intermediate abstract classes have been moved into the implementation package). The hierarchy is also exhaustive now, and works much better to pattern matching. More specifically, three new types have been added: `PaddingLayout`, `StructLayout` and `UnionLayout`, the latter two are a subtype of `GroupLayout`. Thanks to this move, several predicate methods (`isPadding`, `isStruct`, `isUnion`) have been dropped from the API;

* The `SymbolLookup::lookup` method has been renamed to `SymbolLookup::find` - to avoid using the same word `lookup` in both noun and verb form, which leads to confusion;

* A new method, on `ModuleLayer.Controller` has been added to enable native access on a module in a custom layer;

* The new interface `Linker.Option` has been introduced. This is a tag interface accepted in `Linker::downcallHandle`. At the moment, only a single option is provided, to specify variadic function calls (because of this, the `FunctionDescriptor` interface has been simplified, and is now a simple carrier of arguments/return layouts). More linker options will follow.

Javadoc: http://cr.openjdk.java.net/~mcimadamore/jdk/8295044/v1/javadoc/java.base/java/lang/foreign/package-summary.html

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

PR: https://git.openjdk.org/jdk/pull/10872