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

[Paul Sandoz]

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.

Marked as reviewed by psandoz (Committer).

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySource.java line 31:

> 30:  * As such, it provides additional operations to allow for syncing the contents of the mapped memory source with
> 31:  * the ones of the underlying file backing the memory mapping (see {@link #force()} and {@link
> #force(MemorySegment)}). 32:  *

s/with the ones of/with that of

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySource.java line 45:

> 44:      * made to this memory source since it was created, or since this method was last
> 45:      * invoked, will have been written to that device.
> 46:      *

Something to consider later: we might need to document a happens-before relation.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySource.java line 50:

> 49:      *
> 50:      * <p> If this the map mode associated with this memory source is not ({@link
> 51:      * java.nio.channels.FileChannel.MapMode#READ_WRITE}) then invoking this method may have no effect.

s/if this the/if the ?

How does one obtain the map mode?

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySource.java line 71:

> 70:      *
> 71:      * <p> If this the map modes associated with this memory source is not ({@link
> 72:      * java.nio.channels.FileChannel.MapMode#READ_WRITE}) then invoking this method may have no effect.

s/if this the/if the ?

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySource.java line 77:

> 76:      *
> 77:      * @throws IllegalStateException if the memory region backing this memory source has already been released (see
> 78:      * {@link #isReleased()}).

And also if the segment is not derived from this memory source?

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySource.java line 61:

> 60:     /**
> 61:      * Register this memory source against a {@link java.lang.ref.Cleaner}; this means that when all memory segments
> 62:      * backed by this memory sources become unreacheable, this memory source will be automatically released.

s/Register/Registers

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

> 66:  * using the factory method {@link MemorySegment#ofByteBuffer(ByteBuffer)}. Memory segments obtained in this can be
> 67:  * backed by a native memory source, an heap memory source, or a mapped memory source, depending on the
> characteristics 68:  * of the byte buffer instance the segment is associated with. For instance, a memory segment
> obtained from a byte buffer

s/an heap/a heap

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

> 144:     /**
> 145:      * Obtains a new memory segment backed by the same memory source as this segment which can be used to access
> memory associated 146:      * with this segment from the current thread.

Consider later perhaps: now we have `MemorySource` we could name this method `share` since we have the ability to talk
about what is shared.

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

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