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.

Type Mappings: Java, C, and Rust

Java TypeC TypeRust TypeDescription
ValueLayout.ADDRESSPointer*mut, *constPointer to a memory location.
ValueLayout.JAVA_INTinti3232-bit signed integer.
ValueLayout.JAVA_LONGlongi6464-bit signed integer.
ValueLayout.JAVA_SHORTshorti1616-bit signed integer.
ValueLayout.JAVA_BYTEchari88-bit signed integer.
ValueLayout.JAVA_BOOLEANchar (0 or 1)boolBoolean value (true or false).
ValueLayout.JAVA_FLOATfloatf3232-bit floating-point number.
ValueLayout.JAVA_DOUBLEdoublef6464-bit floating-point number.
ValueLayout.JAVA_CHARshort (UTF-16)u1616-bit unsigned integer for UTF-16.

Unsigned Types

Java TypeC TypeRust TypeDescription
ValueLayout.JAVA_INTunsigned intu88-bit unsigned integer.
ValueLayout.JAVA_INTunsigned intu1616-bit unsigned integer.
ValueLayout.JAVA_LONGunsigned longu3232-bit unsigned integer.
ValueLayout.JAVA_LONGunsigned longu6464-bit unsigned integer.

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.