RFR: 8304265: Implementation of Foreign Function and Memory API (Third Preview)

[Maurizio Cimadamore]

On Fri, 17 Mar 2023 15:42:56 GMT, Per Minborg <pminborg at openjdk.org> wrote:

> API changes for the FFM API (third preview)
> 
> Specdiff:
> https://cr.openjdk.org/~pminborg/panama/21/v1/specdiff/overview-summary.html
> 
> Javadoc:
> https://cr.openjdk.org/~pminborg/panama/21/v1/javadoc/java.base/module-summary.html

Here are the main API changes introduced in this round:

* `SegmentScope` has been simplified into a pure lifetime abstraction and moved into a nested class `MemorySegment.Scope`. All segments have a scope (e.g. the segment lifetime), which is usually the scope of some `Arena`. All the factory methods in `SegmentScope` to create non-closeable lifetimes have been moved to `Arena` (e.g. `Arena.ofAuto` and `Arena.global`). This leads to a simplified API, which still allows to build custom arenas via simple delegation, but, at the same time, allows clients to use arenas with minimal indirections (e.g. `arena.scope()` is no longer needed in many places). Some factory names in `Arena` were also updated (e.g. from `openConfined` to `ofConfined`).
* `ValueLayout::OfAddress` has been moved to a toplevel class `AddressLayout`. Also, the method to obtain an address layout of unbounded size (`OfAddress::asUnbounded`) has been changed, so that it now takes the layout of the target region of memory pointed to by the address (`AddressLayout::withTargetLayout`).
* A new *layout path* is provided to dereference an address layout. This allows memory segment var handle to deal with complex dereference expressions like `*(a[10].x).y`.
* A new linker implementation, namely the *fallback linker* has been added. This linker is based on `libffi` and provides a very easy way to add support for `Linker` API, even in platforms that have limited functionalities (such as [zero](https://openjdk.org/projects/zero/)).
* The `VaList` interface has been dropped. Unfortunately, the behavior of `va_list` is hopelessly platform specific, and we could also never make full use of it in the `jextract` tool, given that parsing support `va_list` is very limited in `libclang`.
* The API for unsafely attaching spatial/temporal bounds to an unsafe memory segment has been improved and streamlined. The `MemorySegment::ofAddress` method is now a single, unrestricted method which turns a long address into a native memory segment whose base address is the provided address. The returned segment has a scope that is always alive, and has zero-length. To resize, or add new temporal bounds to an existing segments, clients can use the new `MemorySegment::reinterpret` methods. The logic for attaching a cleanup action to a memory segment has also been updated: now the cleanup action will take as input a shallow copy of the memory segment, in a scope that is always alive, so that clients can pass that copy to other functions in order to perform custom cleanup.
* We have made some changes and simplfications to the way in which runtime values such as `errno` are preserved, The `CapturedCallState` interface has been removed. Instead, there is a way to obtain a group layout of all the values that can be saved, given the platform in which the linker runs. Clients can query the layout, e.g. obtaining names for the values to be saved, and then create a linker option which lists all the name of the values to be saved.
* We have added support for *trivial* (or *leaf*) calls - that is native calls whose execution completes very quickly. This option might be useful when calling functions whose total execution time is comparable to that of the overhead of the change of the thread state from Java to native (in JNI, such calls are handled using *critical JNI*).

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

PR Comment: https://git.openjdk.org/jdk/pull/13079#issuecomment-1476648707