Summary
-------

This CSR refers to the latest iteration of the Foreign Memory Access and Foreign Linker API originally targeted for Java 14 and Java 16, respectively, with the goal of refining some of the API rough edges, as well as addressing the feedback received so far from developers.

Problem
-------

Real-world use of the Foreign Memory Access and Foreign Linker APIs revealed some remaining usability issues, listed below:

* Managing the life-cycle of memory segments is not intuitive, and can lead developers to write code that performs less efficiently than expected. For instance, the MemorySegment API heavily relies on dynamic ownership changes (see `MemorySegment::handoff`), where the ownership of a segment is updated in place, by killing the old segment and return a new one with new ownership characteristics. While for confined segment such an operation can be supported at a relatively low cost, the same cannot be said for shared segment (introduced in Java 16); since shared segment feature a relatively expensive `close` operation, it is generally not feasible to dynamically change ownership of a shared segment in critical code paths.

* Shared segments makes it hard to support asynchronous IO operations (e.g. `SocketChannel::read(ByteBuffer)`) on buffer views obtained by such segments; this is due to the fact that a shared segment can be closed by any thread - possibly in the middle of an async IO operation. The API did not provide any workaround for this use case; for this reason, asynchronous operations on byte buffer views obtained from shared segments are not supported (as stated in the javadoc for `MemorySegment::asByteBuffer`), and, as a result, clients are faced with a choice between shared segment and full byte buffer interoperability.

* When linking a foreign function, the address of said function has to be specified ahead of time (e.g. when the native method handle is obtained); while this is good in most cases when the user wants to call a foreign functions, some use cases require more flexibility. Certain libraries in fact, provide extension points by means of function pointers, with a well-defined signature. In such cases, it would be preferable to obtain a native method handle without having to specify an address, and late-bind the address when the foreign call is made.

* Allocating native memory can often be the source of performance bottlenecks in real world applications; while the API allows a more optimized allocation, using the `NativeScope` abstraction, not all the API points which perform allocation can be provided the desired allocation strategy. For instance, it is not possible to pass a `NativeScope` to a native function which returns a struct by value. In addition, `NativeScope` only represent a possible choice in the allocator design space: the allocation scheme it provides is, essentially, a thread-confined arena-based allocation. It is not possible to make `NativeScope` more general and/or to support different allocation schemes.

* Some of the static factory methods in the API are hostile to the use of static imports - for instance, consider `MemoryLayout.ofSequence`.

* Both the Foreign Memory Access API and the Foreign Linker API contained *unsafe* API points, called *restricted methods*; access to restricted methods is controlled by a read-only JDK property (namely, `foreign.restricted`), whose value must be explicitly set to `permit` for access to occur. While this solution is good enough to make restricted methods disabled by default, the use of a JDK property as a means to do so is rather ad-hoc and brittle.

Solution
-------

Here we describe the main ideas behind the API changes brought forward in this CSR:

* The new API models segment life-cycle with an explicit abstraction, named `ResourceScope`. A `ResourceScope` is a stateful abstraction which can be either alive, or closed. Resources managed by a resource scope can only be accessed if the owning resource scope is alive. Resource scopes can be confined (e.g. only thread which created the scope has access to the managed resources) or shared, and can be (optionally) associated with a `Cleaner` object, which is responsible for closing the scope in case the scope becomes unreachable. By making the `ResourceScope` abstraction a first-class citizen in the API, the semantics of other abstractions such as `MemorySegment`, `MemoryAddress`, `VaList` becomes clearer: these abstractions cannot, in fact, be closed in isolation - they can instead be closed, by closing the resource scope they belong to. This allowed us to greatly simplify the `MemorySegment` abstraction, and remove all API points related to dynamic ownership changes. Also, `MemorySegment` is no longer `AutoCloseable` (but `ResourceScope` is), which further clarifies the semantics of the API when multiple segments (e.g. slices) are owned by the same scope.

* As we have seen, there are cases where APIs might want to temporarily inhibit deterministic deallocation. The API now allows clients to *acquire* a `ResourceScope`; this returns a `ResourceScope.Handle` instance. This idiom can be used to perform operations on a segment (or any other resource managed by the scope) while the scope handle is being held by the client. Any attempt to close the resource scope when one or more handles have been acquired will result in an exception. When a client no longer need to work on a resource associated with the acquire scope, the acquire handle can be *released*. This allows to address interoperability issues between memory segments and byte buffer views in the context of asynchronous IO operations.

* The `CLinker` interface now offers an overload of `downcallHandle` which accept no `Addressable` parameter; the native method handle returned by this overload instead accepts an additional prefix argument (of type Addressable) which can be used to specify the foreign function entry point at call-time, rather than at link-time.

* A new abstraction, namely `SegmentAllocator`, replaces `NativeScope`. `SegmentAllocator`  is a functional interface which provides several default methods which help when allocating off-heap memory from Java objects (e.g. on heap arrays). The `SegmentAllocator` interface provides some ready-made allocators, such as an arena allocator, which provides the same optimized allocation scheme previously provided by `NativeScope`. Since now `SegmentAllocator` and `ResourceScope` are independent entities, clients can combine them at will, meaning that it is now possible. for instance, to create an arena allocator out of a shared resource scope. Several API points in `CLinker` have been enhanced to take an extra `SegmentAllocator` parameter, instead of the `NativeScope` parameter accepted previously. Most notably, all native method handles generated by `CLinker::downcallHandle` will now accept an additional `SegmentAllocator` parameter, in case the foreign function returns a `MemorySegment`. (An additional overload of `CLinker::downcallHandle` allows the user to select an allocator at link-time, if desired). To facilitate conversion from `ResourceScope` to `SegmentAllocator`, some API points in `CLinker` (e.g. `CLinker::toCString`) define overloads accepting a `ResourceScope` parameter; this scope is then internally converted into a so called *scoped* allocator (an allocator which allocates segment tied to the provided scope). This makes the API simpler to use in case clients do not require an alternate, more efficient allocation strategy.

* Some of the static factory methods in the API were renamed to be more friendly with respect to static imports. All factories in the layout API have been renamed - e.g. from `ofXYZ` to `XYZlayout`. In the newly added APIs (`ResourceScope` and `SegmentAllocator`) we used the `new` prefix whenever allocating a new instance was an important part of the API contract (this is especially true for resource scope creation). We also used the `of` prefix to denote a loose conversion - e.g. `SegmentAllocator.ofScope` is used to create an allocator from a resource scope.

* To allow access to restricted methods in the API, a new experimental command line option in the Java launcher is added, namely `--enable-native-access=<module list>`. This options accepts a list of modules (separated by commas), where a module name can also be `ALL-UNNAMED` (for the unnamed module). Adding this command line flag to the launcher has the effect of allowing access to restricted methods to a given set of modules (the list of modules specified in the command line option). Access to restricted methods from any other module not in the list is disallowed and will result in an `IllegalCallerException`.

Specification
-------------

A specdiff of the changes as of April 29th, 2021 has been attached to this CSR (v2).

A link of the latest javadoc (as of April 29th, 2021) is included below:

http://cr.openjdk.java.net/~mcimadamore/JEP-412/v2/javadoc/jdk/incubator/foreign/package-summary.html

A link of the latest specdiff (as of April 29th, 2021) is included below:

http://cr.openjdk.java.net/~mcimadamore/JEP-412/v2/specdiff/overview-summary.html