[foreign-memaccess+abi] RFR: Update foreign linker doc

[Jorn Vernee]

On Fri, 9 Dec 2022 18:24:17 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch refreshes the document describing the Foreign Linker API.
> 
> The biggest change is at the beginning, as we have to deal with the concept of zero-length memory segments (we had a section on memory addresses here).
> 
> Other than that, it's mostly cosmetic changes to rename `MemorySession` to `Arena`.

Marked as reviewed by jvernee (Committer).

doc/panama_ffi.md line 68:

> 66: In the above code, the arena acts as a *native* allocator (that is, an allocator built on top of `MemorySegment::allocateNative`). The arena is then used to create a native array, initialized to the values `0, 1, 2, 3, 4`.  The array initialization is more efficient, compared to the previous snippet, as the Java array is copied *in bulk* into the memory region associated with the newly allocated memory segment. The returned segment is associated with the scope of the arena which performed the allocation, meaning that the segment will no longer be accessible after the try-with-resource construct.
> 67: 
> 68: Custom segment allocators are also critical to achieve optimal allocation performance; for this reason, a number of predefined allocators are available via factories in the `SegmentAllocator` interface. or example, the following code creates a *slicing* allocator and uses it to allocate a segment whose content is initialized from a Java `int` array:

Suggestion:

Custom segment allocators are also critical to achieve optimal allocation performance; for this reason, a number of predefined allocators are available via factories in the `SegmentAllocator` interface. For example, the following code creates a *slicing* allocator and uses it to allocate a segment whose content is initialized from a Java `int` array:

doc/panama_ffi.md line 137:

> 135: Both C structs/unions and pointers are modelled using the `MemorySegment` carrier type. However, C structs/unions are modelled in function descriptors with memory layouts of type `GroupLayout`, whereas pointers are modelled using the `ADDRESS` value layout constant (whose size is platform-specific). Moreover, the behavior of a downcall method handle returning a struct/union type is radically different from that of a downcall method handle returning a C pointer:
> 136: 
> 137: * donwcall method handles returning C pointers will wrap the pointer address into a fresh zero-length memory segment (unless an unbounded address layout is specified);

Suggestion:

* downcall method handles returning C pointers will wrap the pointer address into a fresh zero-length memory segment (unless an unbounded address layout is specified);

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

PR: https://git.openjdk.org/panama-foreign/pull/759