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

Change layout API to work with bytes, not bits

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 21
    • core-libs
    • None
    • source, behavioral
    • medium
    • Hide
      Some methods in the memory layout are removed; as a result some existing code might fail to compile. A more subtle issue is that calls to `MemoryLayout::paddingLayout(size)` will still work, but will have different meaning. For these reasons we believe it's better to make this change as soon as possible, while the API is still in preview.
      Show
      Some methods in the memory layout are removed; as a result some existing code might fail to compile. A more subtle issue is that calls to `MemoryLayout::paddingLayout(size)` will still work, but will have different meaning. For these reasons we believe it's better to make this change as soon as possible, while the API is still in preview.
    • Java API
    • SE

    Description

      Summary

      Update the MemoryLayout API so that sizes are expressed in bytes, not bits.

      Problem

      Memory segments are expressed as "bag of bytes". All their sizes and offsets are expressed in number of bytes, which obviously makes sense given that (a) memory addressing is byte-oriented and (b) ByteBuffer API also works that way (which means it's relatively easy to update code using ByteBuffer to use MemorySegment instead).

      On the other hand, memory layouts are expressed in bits. The historical reasons for this can be found in John's great LDL document. Essentially, the layout language proposed in the LDL document was originally intended to model both memory and registers.

      While this asymmetry can rarely be observed in practice, it is bothersome for a number of reasons:

      • Factories accepting layouts (e.g. SegmentAllocator::allocate(MemoryLayout)) cannot be expressed as simple sugar for factories expressed in byte size/alignment (e.g. SegmentAllocator::allocate(long, long)). That is, there is always some segments that can be allocated in one factory which can't be allocated in the other.

      • Var handles generated using the memory layout API have different constraints from those generated directly from MethodHandles. The latter just accepts a byte offset (in sync with what memory segments do), while the former perform all internal computation, as well as range checking, in bits - which again leads to asymmetries.

      More details on this problem can be found here.

      Solution

      While in principle we could tweak memory segments to express their sizes and offsets in bits, such a solution would hurt adoption of the MemorySegment API (as noted above). The only realistic solution is to change the memory layout API to express sizes in bytes rather than in bits. This comes with few consequences:

      • Some duplicate methods in the layout API are removed. For instance, instead of having both MemoryLayout::bitSize and MemoryLayout::byteSize, only the latter should be retained;
      • The MemoryLayout::withBitAlignment method should be renamed to MemoryLayout::withByteAlignment and its semantics expressed in bytes;
      • The padding layout factory (MemorySegment::paddingLayout(long)) should now take a byte size.

      Specification

      A summary of the required changes is attached to this CSR (see 8308276_v1.zip). Links are also included below:

      javadoc: https://cr.openjdk.org/~mcimadamore/jdk/8308276/8308276/v1/javadoc/java.base/java/lang/foreign/package-summary.html

      specdiff: https://cr.openjdk.org/~mcimadamore/jdk/8308276/8308276/v1/specdiff_out/overview-summary.html

      Attachments

        Issue Links

          Activity

            People

              mcimadamore Maurizio Cimadamore
              mcimadamore Maurizio Cimadamore
              Paul Sandoz
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: