[foreign-memaccess] RFR: JDK-8242051: Clarify difference between checked and unchecked addresses

[Jorn Vernee]

On Thu, 2 Apr 2020 17:49:50 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> While most memory addresses are associated with a segment, addresses coming from native code, or those created from
> scratch (e.g. MemoryAddress::ofLong) do not have an associated segment.
> This patch addresses this problem by having unchecked memory addresses returning`null` on MemoryAddress::segment().
> Similarly, the MemoryAddress::offset method has been renamed to `segmentOffset` and now throws UOE if called on an
> unchecked address.  This makes the API cleaner: it is only possible to dereference those addresses which have an
> associated segment. I've tweaked the javadoc to convey that message more clearly.

Looks good.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java line 40:

> 39:  * If an address does not have any associated segment, it is said to be <em>unchecked</em>. Unchecked memory
> 40:  * address do not feature known spatial or temporal bounds; as such, attempting a memory dereference operation
> 41:  * using an unchecked memory address will result in a runtime exception. Unchecked addresses can be obtained

Typo
Suggestion:

 * addresses do not feature known spatial or temporal bounds; as such, attempting a memory dereference operation

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

Marked as reviewed by jvernee (Committer).

PR: https://git.openjdk.java.net/panama-foreign/pull/90