RFR: 8340307: Add explanation around MemorySegment:reinterpret regarding arenas [v2]

[Jorn Vernee]

On Thu, 31 Oct 2024 14:03:51 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Per Minborg has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
>> 
>>  - Improve docs from comments made in the PR
>>  - Merge branch 'master' into reinterpret-doc
>>  - Add doc on original arena is responsible for freeing a segment
>
> src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 773:
> 
>> 771:      *         of memory has been deallocated via the original arena (use after free).</li>
>> 772:      *     <li>The reinterpreted segments' region of memory will not be deallocated
>> 773:      *         when the <em>provided scope becomes invalid.</em>
> 
> Putting the emphasis like this seems a bit more natural to me:
> Suggestion:
> 
>      *     <li>The reinterpreted segments' region of memory will <em>not</em> be deallocated
>      *         when the provided scope becomes invalid.

Also, since the method actually takes an `Arena`, maybe it's better here to say '... when the provided arena is closed'

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

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