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

Generalize MemorySegment::ofBuffer

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 19
    • Component/s: core-libs
    • Labels:
      None
    • Compatibility Kind:
      source, binary
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Hide
      The changes in CSR amount at making the signature of a static factory more general, e.g. accept a `Buffer` instance instead of `ByteBuffer` one. To make things consistent, the name of the factory is also generalized, from `ofByteBuffer` to `ofBuffer`, which can affect clients of the renamed factory.
      Show
      The changes in CSR amount at making the signature of a static factory more general, e.g. accept a `Buffer` instance instead of `ByteBuffer` one. To make things consistent, the name of the factory is also generalized, from `ofByteBuffer` to `ofBuffer`, which can affect clients of the renamed factory.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      The changes described here allow the Foreign Function & Memory API to create a memory segment from an arbitrary Buffer instance, regardless of its concrete type.

      Problem

      The MemorySegment class has a static factory, namely MemorySegment::ofByteBuffer. This factory can be used to create a memory segment view out of a ByteBuffer instance (whether on- or off-heap).

      It is not possible to create a memory segment view out of other Buffer subclasses, such as IntBuffer, LongBuffer, etc. This creates an asymmetry with respect to the Java Native Interface (JNI), since JNI clients can access the base address of any Buffer instance, regardless of its concrete type (see the JNI function GetDirectBufferAddress).

      Solution

      We propose to generalize the ofByteBuffer factory as follows:

      • change the parameter type to take any Buffer
      • change the name of the factory to ofBuffer

      These changes allow clients to create memory segments views out of Buffer instance of any kind - meaning that clients can now wrap an IntBuffer into a MemorySegment in case they want to pass that segment to a foreign function.

      We are not proposing to make changes to the dual method of the API considered here, namely the instance method MemorySegment::asByteBuffer. This simply doesn't seem worth, due to asymmetries in the Buffer API. For instance, off-heap buffers can only created form ByteBuffer::allocateDirect. So, to create an off-heap IntBuffer, clients have to first create a direct ByteBuffer then to view that buffer as an IntBuffer (usingByteBuffer::asIntBuffer).

      In other words, CharBuffer, ShortBuffer, IntBuffer, LongBuffer, FloatBuffer and DoubleBuffer are not first-class citizens of the Buffer API. As such it would not be possible to map many memory segments into an IntBuffer; in fact, the only segment we could safely map into an IntBuffer would be an heap segment backed by an int array (e.g. created from MemorySegment::ofArray(int[]). As such it doesn't seem worth adding a lot of API surface (in terms of additional overloads) for such a corner case.

      Specification

      A link to the specdiff for the proposed changes can be found here:

      http://cr.openjdk.java.net/~mcimadamore/8286715/v1/specdiff_out/overview-summary.html

      A link to the javadoc for the proposed changes can be found here:

      http://cr.openjdk.java.net/~mcimadamore/8286715/v1/javadoc/java.base/module-summary.html

      A zip file containing both has been attached to this CSR.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              mcimadamore Maurizio Cimadamore
              Reporter:
              mcimadamore Maurizio Cimadamore
              Reviewed By:
              Jorn Vernee, Sundararajan Athijegannathan
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: