[foreign-memaccess+abi] RFR: 8292034: Improve javadoc after memory segment/memory address unification [v2]

[Maurizio Cimadamore]

On Fri, 23 Sep 2022 11:40:35 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Replace "alignment constraints" with "alignment constraint", in accordance to what done in `MemorySegment` javadoc
>
> src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 71:
> 
>> 69:  * Native segments can be obtained by calling one of the {@link MemorySegment#allocateNative(long, long)}
>> 70:  * factory methods, which return a memory segment backed by a newly allocated off-heap region with the given size
>> 71:  * and alignment constraint. Alternatively, native segments can be obtained by
> 
> I think it would be more correct here to say: "with the given size, and aligned to the given alignment constraint". i.e. it is not the memory region that _has_ an alignment constraint.
> Suggestion:
> 
>  * factory methods, which return a memory segment backed by a newly allocated off-heap region with the given size
>  * and aligned to the given alignment constraint. Alternatively, native segments can be obtained by

Yeah, I agree  that works better.

> src/java.base/share/classes/java/lang/foreign/MemorySession.java line 228:
> 
>> 226:      *
>> 227:      * @param byteSize the size (in bytes) of the off-heap memory block backing the native memory segment.
>> 228:      * @param byteAlignment the alignment constraint (in bytes) of the off-heap region of memory backing the native memory segment.
> 
> I notice that in this section there are 2 ways of referring to a memory segment's underlying memory region:
> - "The off-heap region of memory associated with the"
> - "the off-heap region of memory backing the"
> 
> I wonder if it's worth it to align these to one or the other. i.e. either "associated with", or "backing"

well spotted - "backing" is the way to go. Memory sessions are "associated" to segments. Regions of memory "back" segments. Note that we deliberately use "region of memory" instead of "memory region" to avoid confusion between the concept and API construct (e.g. memory segment - there are many memory XYZ in the API).

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

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