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

Tweaks to memory access API



    • Type: CSR
    • Status: Closed
    • Priority: P2
    • Resolution: Approved
    • Fix Version/s: 15
    • Component/s: core-libs
    • Labels:
    • Compatibility Risk:
    • 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



      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.


      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.


      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.


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







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


          Issue Links



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