[foreign-jextract] RFR: Update memory access and linker documents [v3]

[Jorn Vernee]

On Thu, 25 Mar 2021 15:37:48 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This patch updates the two documents describing usage of the foreign memory access and foreign linker API.
>
> Maurizio Cimadamore has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Another ffi fix
>  - Minor adjustments to the ffi document

Marked as reviewed by jvernee (Committer).

doc/panama_ffi.md line 216:

> 214:     long len = strlen_virtual.invokeExact(
> 215:         LibraryLookup.ofDefault().lookup("strlen").get() // address provided here!
> 216:         CLinker.toCString("Hello").address()

The scope is not being used for the string here.

doc/panama_ffi.md line 299:

> 297: The above code creates  a memory segment — `comparFunc` — containing a stub that can be used to invoke our Java comparator function. The memory segment is associated with the provided resource scope instance; this means that the stub will be uninstalled when the resource scope is closed. It is also possible (not shown here) to create upcall stubs associated with the *default scope*, in which case the stub will be uninstalled when the upcall segment becomes *unreachable*.
> 298: 
> 299: The snippet then creates an off-heap array from a Java array (using a `SegmemntAllocator`), which is then passed to the `qsort` handle, along with the comparator function we obtained from the foreign linker.  As a side-effect, after the call, the contents of the off-heap array will be sorted (as instructed by our comparator function, written in Java). We can than extract a new Java array from the segment, which contains the sorted elements. This is a more advanced example, but one that shows how powerful the native interop support provided by the foreign linker abstraction is, allowing full bidirectional interop support between Java and native.

s/SegmemntAllocator/SegmentAllocator

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

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