RFR: 8254693: Add Panama feature to pass heap segments to native code [v2]

[Maurizio Cimadamore]

On Wed, 18 Oct 2023 09:25:49 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/foreign/Linker.java line 795:
>> 
>>> 793:          * memory segments as addresses, where normally only off-heap memory segments would be allowed. The memory region
>>> 794:          * inside the Java heap is exposed through a temporary native address that is valid for the duration of the
>>> 795:          * function call. As such, these temporary addresses, or any addresses derived from them, should not be used
>> 
>> The API does not expose temporary addresses - so it is not 100% clear when reading what this para refers to. I suppose you mean a native function that "captures" an object's address and then returns it, so that the client wraps it in a zero-length memory segment? I can't decide on top of my head if this is too cornery or not, even for this javadoc.
>
> I'm not sure what to write to make this clearer. The address that is exposed to the native target function is indeed a temporary address that is constructed from the oop and offset. It is temporary because after the native call, the GC might move the object around, which invalidates the address.
> 
> This part is meant to document that native code should not be holding on to the address until after the call completes. This also includes returning the address back to Java. The address would be invalid the moment the function returns.
> 
> Would it help if this said: `The memory region inside the Java heap is exposed to the native target function through a temporary native address`?

I'm considering to leave `As such, these temporary addresses...` out. You already said that the address "is valid for the duration of the call". I'm not sure the subsequent sentence adds much. If you want to make a concrete example of something that should not be done, that would be better. But it seems to me that the client is as in charge as this text suggests - (e.g. if a native lib decides to hold onto an address, the client can't do much about it).

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16201#discussion_r1363593890