[foreign-memaccess+abi] RFR: Update docs

[Jorn Vernee]

On Wed, 25 May 2022 15:34:57 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch updates the README of the foreign-memaccess+abi branch (which will soon become the new default branch for this repo).
> It also updates the various docs to reflect the latest API changes

The section about `keepAlive` was removed, but we now have `whileAlive`. Should something about that be added instead?

doc/panama_ffi.md line 48:

> 46: try (MemorySession session = MemorySession openConfined()) {
> 47:     MemorySegment arr = MemorySegment.allocateNative(MemoryLayout.sequenceLayout(5, JAVA_INT), session);
> 48:     for Memory(int i = 0 ; i < 5 ; i++) {

Typo?
Suggestion:

    for (int i = 0 ; i < 5 ; i++) {

doc/panama_ffi.md line 107:

> 105: ### Linker
> 106: 
> 107: At the core of Panama foreign function support we find the `Linker` abstraction. This abstraction plays a dual role: first, for downcalls, it allows modelling foreign function calls as plain `MethodHandle` calls (see `Linker::downcallHandle`); second, for upcalls, it allows to convert an existing `MethodHandle` (which might point to some Java method) into a `NativeSymbol` which could then be passed to foreign functions as a function pointer (see `Linker::upcallStub`):

Suggestion:

At the core of Panama foreign function support we find the `Linker` abstraction. This abstraction plays a dual role: first, for downcalls, it allows modelling foreign function calls as plain `MethodHandle` calls (see `Linker::downcallHandle`); second, for upcalls, it allows to convert an existing `MethodHandle` (which might point to some Java method) into a `MemorySegment` which could then be passed to foreign functions as a function pointer (see `Linker::upcallStub`):

doc/panama_ffi.md line 112:

> 110: interface Linker {
> 111:     MethodHandle downcallHandle(NativeSymbol func, FunctionDescriptor function);
> 112:     NativeSymbol upcallStub(MethodHandle target, FunctionDescriptor function, MemorySession session);    

Suggestion:

    MethodHandle downcallHandle(Addressable symbol, FunctionDescriptor function);
    MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function, MemorySession session);

doc/panama_ffi.md line 244:

> 242: ```java
> 243: try (MemorySession session = MemorySession openConfined()) {
> 244:     NativeSymbol comparFunc = linker.upcallStub(comparHandle, comparDesc, session);

Suggestion:

    MemorySegment comparFunc = linker.upcallStub(comparHandle, comparDesc, session);

doc/panama_ffi.md line 251:

> 249: ```
> 250: 
> 251: The above code creates an upcall stub — `comparFunc` — a function pointer that can be used to invoke our Java comparator function, of type `NativeSymbol`. The upcall stub is associated with the provided memory session instance; this means that the stub will be uninstalled when the session is closed.

Suggestion:

The above code creates an upcall stub — `comparFunc` — a function pointer that can be used to invoke our Java comparator function, of type `MemorySegment`. The upcall stub is associated with the provided memory session instance; this means that the stub will be uninstalled when the session is closed.

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

PR: https://git.openjdk.java.net/panama-foreign/pull/688