[foreign-memaccess+abi] RFR: 8294970: Add linker option for saving thread-locals that the VM can overwrite [v5]

[Maurizio Cimadamore]

On Wed, 26 Oct 2022 20:40:26 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> This patch adds a new linker option, called `preserveValue`, that can be used to save thread-local values such as `errno` and `GetLastError` that the VM might overwrite. It takes a list of names of the values to save. Values are saved into a MemorySegment passed by the user, that is allocated according to the layout associated with the returned `PreserveValue` instance.
>> 
>> The API for this is somewhat convoluted, as we have to account for:
>>  1. a different JVM implementation might not overwrite the same thread-locals, or non at all. Such JVM implementations should be free to support a different set of names to save, or none at all.
>>  2. it should be possible to save multiple values during a single call.
>> 
>> But, this API is also flexible enough for an implementation to choose any layout it wants for the MemorySegment into which the values are saved. In the current implementation it's just a set of ints, but this could be changed as well.
>> 
>> ---------
>> ### Progress
>> - [x] Change must not contain extraneous whitespace
>> - [ ] Change must be properly reviewed (1 review required, with at least 1 [Committer](https://openjdk.org/bylaws#committer))
>> 
>> 
>> 
>> ### Reviewing
>> <details><summary>Using <code>git</code></summary>
>> 
>> Checkout this PR locally: \
>> `$ git fetch https://git.openjdk.org/panama-foreign pull/742/head:pull/742` \
>> `$ git checkout pull/742`
>> 
>> Update a local copy of the PR: \
>> `$ git checkout pull/742` \
>> `$ git pull https://git.openjdk.org/panama-foreign pull/742/head`
>> 
>> </details>
>> <details><summary>Using Skara CLI tools</summary>
>> 
>> Checkout this PR locally: \
>> `$ git pr checkout 742`
>> 
>> View PR using the GUI difftool: \
>> `$ git pr show -t 742`
>> 
>> </details>
>> <details><summary>Using diff file</summary>
>> 
>> Download this PR as a diff file: \
>> <a href="https://git.openjdk.org/panama-foreign/pull/742.diff">https://git.openjdk.org/panama-foreign/pull/742.diff</a>
>> 
>> </details>
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   rename to CaptureCallState

Looks good - some javadoc nits

src/java.base/share/classes/java/lang/foreign/Linker.java line 314:

> 312: 
> 313:         /**
> 314:          * {@return A linker option used to portions of the execution state immediately after

Suggestion:

         * {@return A linker option used to save portions of the execution state immediately after

src/java.base/share/classes/java/lang/foreign/Linker.java line 333:

> 331: 
> 332:         /**
> 333:          * A linker option for portions of the execution state immediately

Suggestion:

         * A linker option for saving portions of the execution state immediately

src/java.base/share/classes/java/lang/foreign/Linker.java line 334:

> 332:         /**
> 333:          * A linker option for portions of the execution state immediately
> 334:          * calling a foreign function associated with a downcall method handle,

Suggestion:

         * after calling a foreign function associated with a downcall method handle,

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

Marked as reviewed by mcimadamore (Committer).

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