[foreign-memaccess] RFR: JDK-8241154: Clarify the role of MemorySegments

[Jorn Vernee]

On Wed, 18 Mar 2020 15:11:24 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch proposes a restacking of the memory access API. Currently, memory segments are playing a dual role: they are
> both view of a resource, and they impersonate the resource itself. This creates confusion when thinking about
> operationssuch as close() and acquire().  The idea put forward by this patch is to put all segments on equal footing;
> e.g. remove the distinction between normal segments and *acquired* segments. Now *all* segments are, in a sense,
> acquired from some memory *source*. A memory source, in other words, model the actual memory that the segment is a view
> of.  Memory sources are unconfined, which makes them ideal to support operation such as registration with cleaners (to
> allow for automatic cleanup, where needed). Moreover, since we can support many kinds of memory sources, this patch
> also adds a MappedMemorySource which is specific to mapped segments; such memory source contains methods for syncing
> contents of memory against the mapped file (e.g. force()).   This split between memory segment and memory source allows
> us to keep the memory segment API sane, while at the same time providing us room to expand the API in the future to add
> more memory sources. And it makes the API cleaner too, as we can put methods where they belong (e.g. see difference
> between MemorySegment::isAlive vs. MemorySource::isReleased).  A javadoc for this refactoring is available here:
> http://cr.openjdk.java.net/~mcimadamore/panama/8241154_javadoc/javadoc/jdk/incubator/foreign/package-summary.html  Many
> thanks to Brian, John, Jorn, Paul and Stuart for the feedback which led to this iteration.

Looks good. Left some minor inline comments

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 281:

> 280:      * @param arr the primitive array backing the array memory segment.
> 281:      * @return a new memory segment backed by an heap memory source.
> 282:      */

Typo
Suggestion:

     * @return a new memory segment backed by a heap memory source.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 294:

> 293:      * @param arr the primitive array backing the array memory segment.
> 294:      * @return a new memory segment backed by an heap memory source.
> 295:      */

Suggestion:

     * @return a new memory segment backed by a heap memory source.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 307:

> 306:      * @param arr the primitive array backing the array memory segment.
> 307:      * @return a new memory segment backed by an heap memory source.
> 308:      */

Suggestion:

     * @return a new memory segment backed by a heap memory source.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 320:

> 319:      * @param arr the primitive array backing the array memory segment.
> 320:      * @return a new memory segment backed by an heap memory source.
> 321:      */

Suggestion:

     * @return a new memory segment backed by a heap memory source.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 333:

> 332:      * @param arr the primitive array backing the array memory segment.
> 333:      * @return a new memory segment backed by an heap memory source.
> 334:      */

Suggestion:

     * @return a new memory segment backed by a heap memory source.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 346:

> 345:      * @param arr the primitive array backing the array memory segment.
> 346:      * @return a new memory segment backed by an heap memory source.
> 347:      */

Suggestion:

     * @return a new memory segment backed by a heap memory source.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 359:

> 358:      * @param arr the primitive array backing the array memory segment.
> 359:      * @return a new memory segment backed by an heap memory source.
> 360:      */

Suggestion:

     * @return a new memory segment backed by a heap memory source.

test/jdk/java/foreign/TestCleaner.java line 8:

> 7:  * published by the Free Software Foundation.  Oracle designates this
> 8:  * particular file as subject to the "Classpath" exception as provided
> 9:  * by Oracle in the LICENSE file that accompanied this code.

Wrong copyright header.

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

Marked as reviewed by jvernee (Committer).

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