Summary

Calling MemoryLayout.ofStructLayout might fail if one of the provided member layouts does not conform to its alignment constraint.

Problem

One of the changes in the memory layout API that were introduced as part of JEP 442 is eager layout validation. That is, layouts are now validated upon construction, in order to reject ill-formed combinations.

One such combination involves a struct layout where a layout elements occur at an offset within the struct that is not a multiple of the layout's alignment constraints:

MemoryLayout.ofStruct(JAVA_SHORT, JAVA_INT)

In the above struct layout creation, the member layout JAVA_INT occurs at bit offset 16 within the struct, which is incompatible with the bit alignment constraint associated with that member layout (32).

Solution

Ill-formed layout combinations should be detected (and rejected) as early as possible. As the implementation is already handling this case, only the documentation of the MemoryLayout::ofStructLayout needs to be updated to better reflect the behavior of the factory method.

Specification

We propose the following javadoc for MemoryLayout::ofStructLayout:

    /**
     * Creates a struct layout with the given member layouts.
     *
     * @param elements The member layouts of the struct layout.
     * @return a struct layout with the given member layouts.
     * @throws IllegalArgumentException if the sum of the {@linkplain #bitSize() bit sizes} of the member layouts
     * overflows.
     * @throws IllegalArgumentException if a member layouts in {@code elements} occurs at an offset (relative to the start
     * of the struct layout) which is not compatible with its alignment constraint.
     *
     * @apiNote This factory does not automatically align element layouts, by inserting additional {@linkplain PaddingLayout
     * padding layout} elements. As such, the following struct layout creation will fail with an exception:
     *
     * {@snippet lang = java:
     * structLayout(JAVA_SHORT, JAVA_INT)
     * }
     *
     * To avoid the exception, clients can either insert additional padding layout elements:
     *
     * {@snippet lang = java:
     * structLayout(JAVA_SHORT, MemoryLayout.ofPadding(16), JAVA_INT)
     * }
     *
     * Or, alternatively, they can use a member layout which features a smaller alignment constraint. This will result
     * in a <em>packed</em> struct layout:
     *
     * {@snippet lang = java:
     * structLayout(JAVA_SHORT, JAVA_INT.withBitAlignment(16))
     * }
     */