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

[Maurizio Cimadamore]

On Thu, 19 Mar 2020 17:17:10 GMT, Paul Sandoz <psandoz 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.
>
> 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?

Obtaining map modes is hard, although I agree it would be desirable. Unfortunately the MappedByteBuffer class throws
them away soon after creation, and only keeps an 'isSync' flag around (which is just for NV memory).

In other words, the javadoc of this method mimics that of MappedByteBuffer - similarly, MappedByteBuffer has no way to
tell which map mode was used at creation, and the javadoc vaguely refers to the map modes being used at
FileChannel::map time. I'm trying to do the same here.

> 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?

right

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

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