RFR: 8340307: Add explanation around MemorySegment:reinterpret regarding arenas

[Jorn Vernee]

On Wed, 30 Oct 2024 10:58:22 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 766:
>> 
>>> 764:      * method returns a segment that behaves as if it had been allocated using the
>>> 765:      * provided arena except, the returned segment's deallocation is still managed by the
>>> 766:      * original arena.
>> 
>> I think the old sentence is just misleading here, IMO it should be completely removed. Maybe replaced with something like: "Note that if this segment was created by calling `Arena#allocate`, only closing the original arena will deallocate this segment's backing memory region".
>
> I disagree. IMHO the original sentence is still accurate - after reinterpret, the segment you get back looks like any other segments allocated with the arena. If you read that literally, not much is wrong with it? E.g. the segment will be alive when the arena is alive and will appear no longer alive after the arena is closed. The fact that there is _another_ segment somewhere which might still be alive somehow is irrelevant for the clients operating on a segment obtained via `reinterpret`.
> 
> There's two things here:
> * what can I do with the returned segment? Answer is: whatever you can do with any other segment returned/allocated by the arena (what this sentence says)
> * when is the region of memory associated with the returned segment deallocated? Not when the provided arena is closed, but when the original segment's arena is closed.
> 
> (To me, this calls for leaving the sentence in place and adding some new sentence after it like "However...")

I think it's technically correct, but I think it's starting off on the wrong foot. There's no transfer of ownership happening, `reinterpret` just returns a view of the old memory region with a new scope borrowed from the given arena. I think there is a conceptual difference between a segment allocated by a given arena, and one reinterpreted with a given arena, even if they act very similar. I think calling that concept by another name will help people's understanding.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21761#discussion_r1822542313