Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8246096

Tweaks to memory access API

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P2
    • Resolution: Approved
    • Fix Version/s: 15
    • Component/s: core-libs
    • Labels:
      None
    • Compatibility Risk:
      low
    • Compatibility Risk Description:
      The risk associated with this change is low - the only changed signature is that of `MemoryLayout::offset`, which has been split into `bitOffset` and `byteOffset`, for clarity. All other signatures stay the same - some new API points are provided.
    • Interface Kind:
      Java API

      Description

      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.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              mcimadamore Maurizio Cimadamore
              Reporter:
              mcimadamore Maurizio Cimadamore
              Reviewed By:
              Chris Hegarty, Paul Sandoz
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: