[foreign-memaccess+abi] RFR: Refresh FFM documents [v2]

[Jorn Vernee]

On Wed, 20 Dec 2023 10:04:22 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This PR brings the FFM documents in sync with the finalized API in JDK 22. The most obvious changes are:
>> 
>> * in the foreign memory document, the section on structured access has been rectified, to take into account the extra offset parameter that is added to memory access var handles;
>> * in both documents, several calls to `allocateArray` and `allocateUtf8String` have been replaced with `allocateFrom`
>> * the section introducing the `Linker` in the ffi document has been revamped; it now talks more at length about the mapping between layouts and C types. The table with Linux/x64 mappings has been moved to a section in the appendix, and I have also added a mention of `Linker::canonicalLayouts`
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review comments

Marked as reviewed by jvernee (Committer).

doc/panama_ffi.md line 98:

> 96: ```
> 97: 
> 98: For a more exhaustive examples of mapping between C types and layouts, please refer to the [appendix](#c-types-mapping-in-linuxx64). In the following sections, we will assume Linux/x64 as our target platform.

Misplaced 's'?

Suggestion:

For a more exhaustive example of mappings between C types and layouts, please refer to the [appendix](#c-types-mapping-in-linuxx64). In the following sections, we will assume Linux/x64 as our target platform.

doc/panama_memaccess.md line 172:

> 170: The above code creates a memory access var handle which reads/writes `int` values at a certain byte offset in a segment. To create this var handle we have to specify a carrier type — the type we want to use e.g. to extract values from memory, as well as whether any byte swapping should be applied when contents are read from or stored to memory. Additionally, the user might want to impose additional constraints on how memory dereferences should occur; for instance, a client might want to prevent access to misaligned 32 bit values. Of course, all this information can be succinctly derived from the provided value layout (`JAVA_INT` in the above example).
> 171: 
> 172: The attentive reader might have noted how rich the var handles obtained from the sequence layout in the previous section can be in fact derived from  the simple memory access var handle we have constructed here. That is, var handles can be adapted and turned into more complex var handles, using var handle *combinators*. Developers familiar with the method handle API know how simpler method handles can be combined into more complex ones using the various combinator methods in the `MethodHandles` class. These methods allow, for instance, to insert (or bind) arguments into a target method handle, filter return values, permute arguments and much more.

Typo?

Suggestion:

The attentive reader might have noted how the var handles obtained from the sequence layout in the previous section can be in fact derived from  the simple memory access var handle we have constructed here. That is, var handles can be adapted and turned into more complex var handles, using var handle *combinators*. Developers familiar with the method handle API know how simpler method handles can be combined into more complex ones using the various combinator methods in the `MethodHandles` class. These methods allow, for instance, to insert (or bind) arguments into a target method handle, filter return values, permute arguments and much more.

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

PR Review: https://git.openjdk.org/panama-foreign/pull/914#pullrequestreview-1813109630
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/914#discussion_r1447324255
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/914#discussion_r1447317159