RFR: 8312522: Implementation of Foreign Function & Memory API [v4]

[Uwe Schindler]

On Fri, 11 Aug 2023 12:37:59 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> This patch contains the implementation of the foreign linker & memory API JEP for Java 22. The initial patch is composed of commits brought over directly from the [panama-foreign repo](https://github.com/openjdk/panama-foreign). The main changes found in this patch come from the following PRs:
>> 
>> 1. https://github.com/openjdk/panama-foreign/pull/836 Where previous iterations supported converting Java strings to and from native strings in the UTF-8 encoding, we've extended the supported encoding to all the encodings found in the `java.nio.charset.StandardCharsets` class.
>> 2. https://github.com/openjdk/panama-foreign/pull/838 We dropped the `MemoryLayout::sequenceLayout` factory method which inferred the size of the sequence to be `Long.MAX_VALUE`, as this led to confusion among clients. A client is now required to explicitly specify the sequence size.
>> 3. https://github.com/openjdk/panama-foreign/pull/839 A new API was added: `Linker::canonicalLayouts`, which exposes a map containing the platform-specific mappings of common C type names to memory layouts.
>> 4. https://github.com/openjdk/panama-foreign/pull/840 Memory access varhandles, as well as byte offset and slice handles derived from memory layouts, now feature an additional 'base offset' coordinate that is added to the offset computed by the handle. This allows composing these handles with other offset computation strategies that may not be based on the same memory layout. This addresses use-cases where clients are working with 'dynamic' layouts, whose size might not be known statically, such as variable length arrays, or variable size matrices.
>> 5. https://github.com/openjdk/panama-foreign/pull/841 Remove this now redundant API. Clients can simply use the difference between the base address of two memory segments.
>> 6. https://github.com/openjdk/panama-foreign/pull/845 Disambiguate uses of `SegmentAllocator::allocateArray`, by renaming methods that both allocate + initialize memory segments to `allocateFrom`. (see the original PR for the problematic case)
>> 7. https://github.com/openjdk/panama-foreign/pull/846 Improve the documentation for variadic functions.
>> 8. https://github.com/openjdk/panama-foreign/pull/849 Several test fixes to make sure the `jdk_foreign` tests can pass on 32-bit machines, taking linux-x86 as a test bed.
>> 9. https://github.com/openjdk/panama-foreign/pull/850 Make the linker API required. The `Linker::nativeLinker` method is not longer allowed to throw an `UnsupportedO...
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   remove spurious imports

> > Just curious, what's the rationale for finalizing the API when there are significant changes from the last preview?
> 
> A preview API is finalized when it is ready. The preview process, as outlined by [JEP 12](https://bugs.openjdk.org/browse/JDK-8195734), does not place a mandate on the amount of changes that a JEP that finalizes a preview API should or should not contain. It only requires that the changes since the last preview iteration are noted (which we have done). Though, the amount of changes can be used to inform the decision to finalize. We feel that the FFM API is ready for finalization, and does not require another round of preview.
> 
> In this case in particular: previous iterations contained significant changes to the API, including re-shuffling of some of the core APIs. (See e.g. [#13079 (comment)](https://github.com/openjdk/jdk/pull/13079#issuecomment-1476648707)) In contrast this JEP contains mostly superficial changes to the API, that are not likely to impact how a client would write a program using the FFM API.

In addition if somebody wrote code against the preview API, heshe needs to update it anyways because the class files are marked by preview flag. So all is fine. We just make API ready to use for everybody and therefor all early adopters need to adapt. t won't affect anybox else.

To me it would be strange if code goes out of preview without changes, because if there are no changes why was it in preview then in the last JDK feature version?

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

PR Comment: https://git.openjdk.org/jdk/pull/15103#issuecomment-1675101701