Value Layout

ValueLayout is the most primitive layout type, representing the layout of, well, primitives. They are:

  1. ValueLayout.ADDRESS
  2. ValueLayout.JAVA_BOOLEAN
  3. ValueLayout.JAVA_BYTE
  4. ValueLayout.JAVA_CHAR
  5. ValueLayout.JAVA_DOUBLE
  6. ValueLayout.JAVA_FLOAT
  7. ValueLayout.JAVA_INT
  8. ValueLayout.JAVA_LONG
  9. ValueLayout.JAVA_SHORT
  10. ValueLayout.ADDRESS_UNALIGNED
  11. ValueLayout.JAVA_CHAR_UNALIGNED
  12. ValueLayout.JAVA_DOUBLE_UNALIGNED
  13. ValueLayout.JAVA_FLOAT_UNALIGNED
  14. ValueLayout.JAVA_INT_UNALIGNED
  15. ValueLayout.JAVA_LONG_UNALIGNED
  16. ValueLayout.JAVA_SHORT_UNALIGNED

These all correspond to the Java primitives (ADDRESS is a bit special), aligned and unaligned, which have direct mappings to C primitive types.

Java TypeC TypeRust Type
ValueLayout.ADDRESSpointerpointer or Option<reference>
ValueLayout.ADDRESS_UNALIGNEDpointer with alignment 1ditto with alignment 1
ValueLayout.JAVA_BOOLEANchar but must be 0 or 1bool
ValueLayout.JAVA_BYTEchari8
ValueLayout.JAVA_CHARshort storing a UTF-16 codepointu16 storing a UTF-16 codepoint
ValueLayout.JAVA_CHAR_UNALIGNEDditto with alignment 1ditto with alignment 1
ValueLayout.JAVA_DOUBLEdoublef64
ValueLayout.JAVA_DOUBLE_UNALIGNEDf64 with alignment 1
ValueLayout.JAVA_FLOATfloatf32
ValueLayout.JAVA_FLOAT_UNALIGNEDfloat with alignment 1f32 with alignment 1
ValueLayout.JAVA_INTinti32
ValueLayout.JAVA_INT_UNALIGNEDint with alignment 1i32 with alignment 1
ValueLayout.JAVA_LONGlongi64
ValueLayout.JAVA_LONG_UNALIGNEDlong with alignment 1i64 with alignment 1
ValueLayout.JAVA_SHORTshorti16
ValueLayout.JAVA_SHORT_UNALIGNEDshort with alignment 1i16 with alignment 1

So the _UNALIGNED versions are exactly the same as their counterparts except that they have an alignment of 1. This allows storing them unaligned, but it will also force the JVM to issue special instruction sequences to load values, since most CPU architectures do not natively support unaligned loads and stores from or to memory. It is also worth noting that ValueLayout.JAVA_DOUBLE and ValueLayout.JAVA_LONG have platform-dependent alignment because some CPU architectures require natural alignment (size = alignment, so 8 in this case) whereas some like x86 only require an alignment of 4. All other primitives are defined to have natural alignment.

Beyond representing primitive types, ValueLayouts also provide access to different byte ordering (also known as endianness) through the .withOrder(ByteOrder) method. The choices for ByteOrder are BIG_ENDIAN, and LITTLE_ENDIAN, although the static method ByteOrder.nativeOrder() will return whichever of those your CPU natively uses (usually LITTLE_ENDIAN). This is required by many serialization formats, such as most network formats, because many of them require BIG_ENDIAN byte order while most CPU architectures only natively support LITTLE_ENDIAN. Rust doesn’t have int, long, etc., so we must use a different translation to

For additional information on ValueLayout, visit Oracle's official documentation, and official Rust resource The Rustonomicon.