RFR: 8282191: Implementation of Foreign Function & Memory API (Preview)

[Maurizio Cimadamore]

On Mon, 21 Mar 2022 10:45:27 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

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

Here is a list of the main changes in this iteration.

#### java.lang.foreign

The API is now a **preview** API in `java.lang.foreign`. As such to be able to use the API, users must pass the `--enable-preview` flag accordingly, to `javac` and `java`.

Since the API now lives in `java.base`, we dropped the `MemoryHandles` class and moved all its var handle combinator methods under `MethodHandles`. We have also dropped the `MemorySegment::map` factory and replaced it with a new overload in `FileChannel`, which plays much better with custom file systems.

#### ResourceScope

The `ResourceScope` abstraction has been renamed to `MemorySession`. Aside from the naming difference (which also is reflected in some of the factories associated with `MemorySession`, another difference are that `MemorySession` now implements `SegmentAllocator` and can be used straight away to allocate segments. Finally, the fact that some sessions are not closeable is now reflected in the API (see `MemorySession::isCloseable`), and a method has been added to create a non-closeable *view* of the memory session.

#### Restricted methods

Addressing the feedback we have received during incubation, the mechanism to control access to restricted methods is now more permissive. Users can still use the `--enable-native-access` flag, to get a strict, opt-in behavior, in case they want to control which modules can access restricted methods in the foreign API. But if no flag is specified, access is allowed, with a runtime warning. Supporting this required some changes in `ModuleBootstrap` so that we could record the fact that we have seen an `--enable-native-access` flag (so that all checks in `Reflection.java` becomes constant).

#### Deterministic library loading/unloading

We have enhanced the `SymbolLookup` abstraction to provide a new symbol lookup, called *library lookup*. A library lookup is a symbol lookup built around a specific native library which is loaded/unloaded using dlopen/LoadLibrary. Library lookups are associated with memory sessions, so the library can be unloaded deterministically when the session is closed.

#### Memory layouts

All memory layout constants feature the expected alignment constraints. For instance, `JAVA_CHAR` is 2 byte aligned, `JAVA_INT` is 4 byte aligned, and so on.

#### Removed functionalities

As we moved the API in `java.base` we have dropped a number of API points which did not seem to add much value, based on the feedback received:

* `SequenceLayout`s now always have a bounded size. As a result, `MemoryLayout::byteSize` no longer returns an optional. A zero-length sequence can be used instead;
*  `NativeSymbol` has been dropped. At the end of the day, its role is undistinguishable from that of a memory segment with zero-length, so API (and users) should use zero-length segments instead;
* `MemorySession::keepAlive` - has been removed; in its place we have a simple, high-order method which executes an action (a  `Runnable`) while keeping the session alive (`MemorySession::whileAlive`);
* `MemoryLayout::map` only provides limited capabilities when rewriting layouts (e.g. it can only replace one layout at a time); as such we removed this API, and we might add something better at a later point.

#### Hotspot changes

While the Panama foreign repo contains several Hotspot changes which simplify and regularize the foreign function support, these changes are not included here, as we have discovered some intermittent instability in macosx-aarch64. We might attempt to integrate the hotspot changes at a later date.

Javadoc: http://cr.openjdk.java.net/~mcimadamore/8282191/v1/javadoc/java.base/module-summary.html
Specdiff: http://cr.openjdk.java.net/~mcimadamore/8282191/v1/specdiff_out/overview-summary.html

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

PR: https://git.openjdk.java.net/jdk/pull/7888