Summary

This change addresses a number of usability issues with the memory access API which have been brought to the attention of the Panama team during the integration of JEP 383.

Problem

There are some issues with the usability of the memory access API, which require the addition of new API methods, and few tweaks to the existing methods:

• computing offset on layouts can only be done in bits, not bytes - which leads to usability issues when byte computation is required.
• there is no way to specify a mapping offset in the MemorySegment::mapFromPath factory - which leads to potentially inefficient memory usage
• The MemorySegment API seems to miss some useful bulk operations, similar to Arrays::mismatch and Arrays:fill; at the same time, the current bulk copy API MemoryAddress::copy is not very discoverable.
• There is no facility to turn a signed VarHandle into an unsigned one; while this can be done by the user, this operation is common enough that should be standardized.
• While the carrier of a VarHandle can be adapted using the MemoryHandles::filterValue combinator, the current API does not support cases where the adaptation require contextual information (e.g. where going from a type A to B might need some state S1, S2 ... Sn).
• MemorySegment does not define a constant for an access mode mask corresponding to full access modes.

Solution

The following changes are proposed:

• replace the existing MemoryLayout::offset method with two new methods, MemoryLayout::bitOffset and MemoryLayout::byteOffset, respectively
• add an additional parameter to the MemorySegment::mapFromPath factory, to specify the starting offset of the mapped region
• Add three instance methods to MemorySegment - namely:
  • MemorySegment::copyFrom(MemorySegment). This method also replaces the old MemoryAddress::copy method.
  • MemorySegment::fill(byte)
  • MemorySegment::mismatch(MemorySegment)
• Add a new combinator method: MemoryHandles:asUnsigned(VarHandle, Class); this combinator takes an existing VarHandle which deals with a signed primitive type T, and returns a new VarHandle which deals with a bigger primitive type S - where unsigned conversion is applied so that the full value set can be represented in the bigger carrier type.
  • Change the contract of the existing MemoryHandles::filterValue combinator to allow mapper handles which accept more than one argument. More specifically, an arbitrary amount of additional coordinate types can be accepted by the two adapters - the resulting var handle will include such additional coordinate types in its set of accepted coordinates.
  • An extra long, namely MemorySegment::ALL_ACCESS has been added to model a mask which supports all access modes.

Specification

Here are some useful links which should help in navigating through the changes in the API.

Webrev:

http://cr.openjdk.java.net/~mcimadamore/8246095_v1/webrev/

Javadoc:

http://cr.openjdk.java.net/~mcimadamore/8246095_v1/javadoc/jdk/incubator/foreign/package-summary.html

Specdiff:

http://cr.openjdk.java.net/~mcimadamore/8246095_v1/specdiff/overview-summary.html

In addition, a specdiff of the changes as of May 28st 2020 has been attached to this CSR.