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

[Maurizio Cimadamore]

On Tue, 29 Oct 2024 12:42:47 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> This PR proposes to add a small text segment on the `MemorySegment::reinterpret` overloads that takes an Arena stating the responsibility of actually freeing reinterpreted segments lies with the *original* arena.
>
> 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...")

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

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