JDK-8308279 : Change layout API to work with bytes, not bits
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang.foreign
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 21
  • Submitted: 2023-05-17
  • Updated: 2023-05-19
  • Resolved: 2023-05-19
Related Reports
CSR :  
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](https://cr.openjdk.org/~jrose/panama/minimal-ldl.html). 
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](https://mail.openjdk.org/pipermail/panama-dev/2023-May/019059.html).

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

Comments
Moving to Approved.
19-05-2023

Moving to Provisional, not Approved. [~mcimadamore], please attach some representation of the exact change to the CSR to serve as the official record (in addition to the helpful links to the specdiff, etc.).
18-05-2023

Compatibility risks are reduced if depending on the output of jextract (after regenerating the bindings)
17-05-2023