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