Interface MemoryLayout

public sealed interface MemoryLayout extends Constable permits SequenceLayout, GroupLayout, ValueLayout (not exhaustive)

A memory layout can be used to describe the contents of a memory segment in a language neutral fashion. There are two leaves in the layout hierarchy, value layouts, which are used to represent values of given size and kind (see ValueLayout) and padding layouts which are used, as the name suggests, to represent a portion of a memory segment whose contents should be ignored, and which are primarily present for alignment reasons (see paddingLayout(long)). Some common value layout constants are defined in the MemoryLayouts class.

More complex layouts can be derived from simpler ones: a sequence layout denotes a repetition of one or more element layout (see SequenceLayout); a group layout denotes an aggregation of (typically) heterogeneous member layouts (see GroupLayout).

For instance, consider the following struct declaration in C:

 typedef struct {
     char kind;
     int value;
 } TaggedValues[5];
 

The above declaration can be modelled using a layout object, as follows:

SequenceLayout taggedValues = MemoryLayout.sequenceLayout(5,
    MemoryLayout.structLayout(
        MemoryLayout.valueLayout(8, ByteOrder.nativeOrder()).withName("kind"),
        MemoryLayout.paddingLayout(24),
        MemoryLayout.valueLayout(32, ByteOrder.nativeOrder()).withName("value")
    )
).withName("TaggedValues");
 

All implementations of this interface must be value-based; programmers should treat instances that are equal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail. The equals method should be used for comparisons.

Non-platform classes should not implement MemoryLayout directly.

Unless otherwise specified, passing a null argument, or an array argument containing one or more null elements to a method in this class causes a NullPointerException to be thrown.

Size, alignment and byte order

All layouts have a size; layout size for value and padding layouts is always explicitly denoted; this means that a layout description always has the same size in bits, regardless of the platform in which it is used. For derived layouts, the size is computed as follows:

• for a finite sequence layout S whose element layout is E and size is L, the size of S is that of E, multiplied by L
• the size of an unbounded sequence layout is unknown
• for a group layout G with member layouts M1, M2, ... Mn whose sizes are S1, S2, ... Sn, respectively, the size of G is either S1 + S2 + ... + Sn or max(S1, S2, ... Sn) depending on whether the group is a struct or an union, respectively

Furthermore, all layouts feature a natural alignment which can be inferred as follows:

• for a padding layout L, the natural alignment is 1, regardless of its size; that is, in the absence of an explicit alignment constraint, a padding layout should not affect the alignment constraint of the group layout it is nested into
• for a value layout L whose size is N, the natural alignment of L is N
• for a sequence layout S whose element layout is E, the natural alignment of S is that of E
• for a group layout G with member layouts M1, M2, ... Mn whose alignments are A1, A2, ... An, respectively, the natural alignment of G is max(A1, A2 ... An)

A layout's natural alignment can be overridden if needed (see withBitAlignment(long)), which can be useful to describe hyper-aligned layouts.

All value layouts have an explicit byte order (see ByteOrder) which is set when the layout is created.

Layout paths

A layout path originates from a root layout (typically a group or a sequence layout) and terminates at a layout nested within the root layout - this is the layout selected by the layout path. Layout paths are typically expressed as a sequence of one or more MemoryLayout.PathElement instances.

Layout paths are for example useful in order to obtain offsets of arbitrarily nested layouts inside another layout (see bitOffset(PathElement...)), to quickly obtain a memory access handle corresponding to the selected layout (see varHandle(Class, PathElement...)), to select an arbitrarily nested layout inside another layout (see select(PathElement...), or to transform a nested layout element inside another layout (see map(UnaryOperator, PathElement...)).

Such layout paths can be constructed programmatically using the methods in this class. For instance, given the taggedValues layout instance constructed as above, we can obtain the offset, in bits, of the member layout named value in the first sequence element, as follows:

long valueOffset = taggedValues.bitOffset(PathElement.sequenceElement(0),
                                          PathElement.groupElement("value")); // yields 32
 

Similarly, we can select the member layout named value, as follows:

MemoryLayout value = taggedValues.select(PathElement.sequenceElement(),
                                         PathElement.groupElement("value"));
 

And, we can also replace the layout named value with another layout, as follows:

MemoryLayout taggedValuesWithHole = taggedValues.map(l -> MemoryLayout.paddingLayout(32),
                                            PathElement.sequenceElement(), PathElement.groupElement("value"));
 

That is, the above declaration is identical to the following, more verbose one:

MemoryLayout taggedValuesWithHole = MemoryLayout.sequenceLayout(5,
    MemoryLayout.structLayout(
        MemoryLayout.valueLayout(8, ByteOrder.nativeOrder()).withName("kind"),
        MemoryLayout.paddingLayout(32),
        MemoryLayout.paddingLayout(32)
));
 

Layout paths can feature one or more free dimensions. For instance, a layout path traversing an unspecified sequence element (that is, where one of the path component was obtained with the MemoryLayout.PathElement.sequenceElement() method) features an additional free dimension, which will have to be bound at runtime. This is important when obtaining memory access var handle from layouts, as in the following code:

VarHandle valueHandle = taggedValues.varHandle(int.class,
                                               PathElement.sequenceElement(),
                                               PathElement.groupElement("value"));
 

Since the layout path constructed in the above example features exactly one free dimension (as it doesn't specify which member layout named value should be selected from the enclosing sequence layout), it follows that the memory access var handle valueHandle will feature an additional long access coordinate.

A layout path with free dimensions can also be used to create an offset-computing method handle, using the bitOffset(PathElement...) or byteOffsetHandle(PathElement...) method. Again, free dimensions are translated into long parameters of the created method handle. The method handle can be used to compute the offsets of elements of a sequence at different indices, by supplying these indices when invoking the method handle. For instance:

MethodHandle offsetHandle = taggedValues.byteOffsetHandle(PathElement.sequenceElement(),
                                                          PathElement.groupElement("kind"));
long offset1 = (long) offsetHandle.invokeExact(1L); // 8
long offset2 = (long) offsetHandle.invokeExact(2L); // 16
 

Layout attributes

Layouts can be optionally associated with one or more attributes. A layout attribute forms a name/value pair, where the name is a String and the value is a Constable. The most common form of layout attribute is the layout name (see LAYOUT_NAME), a custom name that can be associated with memory layouts and that can be referred to when constructing layout paths.