Module java.base
Package java.lang.foreign

Interface ValueLayout

所有超接口:
MemoryLayout预览
所有已知子接口:
AddressLayout预览, ValueLayout.OfBoolean预览, ValueLayout.OfByte预览, ValueLayout.OfChar预览, ValueLayout.OfDouble预览, ValueLayout.OfFloat预览, ValueLayout.OfInt预览, ValueLayout.OfLong预览, ValueLayout.OfShort预览
public sealed interface ValueLayout extends MemoryLayoutPREVIEW permits ValueLayout.OfBooleanPREVIEW, ValueLayout.OfBytePREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfShortPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfDoublePREVIEW, AddressLayoutPREVIEW
ValueLayout是Java平台的预览API。
仅当启用预览功能时，程序才能使用ValueLayout。
预览功能可能会在将来的版本中被移除，或升级为Java平台的永久功能。
一个模拟基本数据类型值的布局。值布局模拟的值的示例包括整数值（有符号或无符号）、浮点值和地址值。

每个值布局都有一个大小、一个对齐方式（都以字节表示）、一个字节顺序，以及一个载体，即在使用值布局访问预览内存区域时应使用的Java类型。

此类为Java原始类型和地址定义了有用的值布局常量。

API注释:
Java布局常量的一些特征是依赖于平台的。例如，这些常量的字节顺序设置为本机字节顺序，因此可以轻松地与其他API（如数组和ByteBuffer）一起使用。此外，JAVA_LONG和JAVA_DOUBLE的对齐约束在64位平台上设置为8字节，但在32位平台上仅设置为4字节。
实现要求:
实现类和子类是不可变的、线程安全的，并且是基于值的。
密封类层次结构图:
ValueLayout的密封类层次结构图ValueLayout的密封类层次结构图
自Java版本:
19

  • Field Details

    • ADDRESS

      static final AddressLayoutPREVIEW ADDRESS
      一个地址布局常量，其大小与机器地址（size_t）相同，字节对齐设置为sizeof(size_t)，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_BYTE

      static final ValueLayout.OfBytePREVIEW JAVA_BYTE
      一个大小与Java byte相同的值布局常量，字节对齐设置为1，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_BOOLEAN

      static final ValueLayout.OfBooleanPREVIEW JAVA_BOOLEAN
      一个大小与Java boolean相同的值布局常量，字节对齐设置为1，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_CHAR

      static final ValueLayout.OfCharPREVIEW JAVA_CHAR
      一个值布局常量，其大小与Java char相同，字节对齐设置为2，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_SHORT

      static final ValueLayout.OfShortPREVIEW JAVA_SHORT
      一个值布局常量，其大小与Java short相同，字节对齐设置为2，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_INT

      static final ValueLayout.OfIntPREVIEW JAVA_INT
      一个值布局常量，其大小与Java int相同，字节对齐设置为4，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_LONG

      static final ValueLayout.OfLongPREVIEW JAVA_LONG
      一个值布局常量，其大小与Java long相同，（依赖于平台）字节对齐设置为ADDRESS.byteSize()，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_FLOAT

      static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT
      一个值布局常量，其大小与Java float相同，字节对齐设置为4，字节顺序设置为ByteOrder.nativeOrder()。

    • JAVA_DOUBLE

      static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE
      一个值布局常量，其大小与Java double相同，（依赖于平台）字节对齐设置为ADDRESS.byteSize()，字节顺序设置为ByteOrder.nativeOrder()。

    • ADDRESS_UNALIGNED

      static final AddressLayoutPREVIEW ADDRESS_UNALIGNED
      一个不对齐的地址布局常量，其大小与机器地址相同（size_t），字节顺序设置为ByteOrder.nativeOrder()。等同于以下代码： 
      ADDRESS.withByteAlignment(1);
      API 注意：
      在使用不对齐的值布局时应谨慎，因为可能会引起性能和可移植性问题。

    • JAVA_CHAR_UNALIGNED

      static final ValueLayout.OfCharPREVIEW JAVA_CHAR_UNALIGNED
      一个不对齐的值布局常量，其大小与Java char相同，字节顺序设置为ByteOrder.nativeOrder()。等同于以下代码： 
      JAVA_CHAR.withByteAlignment(1);
      API 注意：
      在使用不对齐的值布局时应谨慎，因为可能会引起性能和可移植性问题。

    • JAVA_SHORT_UNALIGNED

      static final ValueLayout.OfShortPREVIEW JAVA_SHORT_UNALIGNED
      一个不对齐的值布局常量，其大小与Java short相同，字节顺序设置为ByteOrder.nativeOrder()。等同于以下代码： 
      JAVA_SHORT.withByteAlignment(1);
      API 注意：
      在使用不对齐的值布局时应谨慎，因为可能会引起性能和可移植性问题。

    • JAVA_INT_UNALIGNED

      static final ValueLayout.OfIntPREVIEW JAVA_INT_UNALIGNED
      一个不对齐的值布局常量，其大小与Java int相同，字节顺序设置为ByteOrder.nativeOrder()。等同于以下代码： 
      JAVA_INT.withByteAlignment(1);
      API 注意：
      在使用不对齐的值布局时应谨慎，因为可能会引起性能和可移植性问题。

    • JAVA_LONG_UNALIGNED

      static final ValueLayout.OfLongPREVIEW JAVA_LONG_UNALIGNED
      一个不对齐的值布局常量，其大小与Java long相同，字节顺序设置为ByteOrder.nativeOrder()。等同于以下代码： 
      JAVA_LONG.withByteAlignment(1);
      API 注意：
      在使用不对齐的值布局时应谨慎，因为可能会引起性能和可移植性问题。

    • JAVA_FLOAT_UNALIGNED

      static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT_UNALIGNED
      一个不对齐的值布局常量，其大小与Java float相同，字节顺序设置为ByteOrder.nativeOrder()。等同于以下代码： 
      JAVA_FLOAT.withByteAlignment(1);
      API 注意：
      在使用不对齐的值布局时应谨慎，因为可能会引起性能和可移植性问题。

    • JAVA_DOUBLE_UNALIGNED

      static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE_UNALIGNED
      一个不对齐的值布局常量，其大小与Java double相同，字节顺序设置为ByteOrder.nativeOrder()。等同于以下代码： 
      JAVA_DOUBLE.withByteAlignment(1);
      API 注意：
      在使用不对齐的值布局时应谨慎，因为可能会引起性能和可移植性问题。

  • Method Details

    • order

      ByteOrder order()
      返回值的字节顺序。
      返回：
      值的字节顺序

    • withOrder

      ValueLayoutPREVIEW withOrder(ByteOrder order)
      返回一个具有与此布局相同特性的值布局，但具有给定的字节顺序。
      参数：
      order - 所需的字节顺序。
      返回：
      一个具有与此布局相同特性的值布局，但具有给定的字节顺序

    • withoutName

      ValueLayoutPREVIEW withoutName()
      返回一个具有与此布局相同特性的内存布局，但没有名称。
      指定者：
      withoutName 在接口 MemoryLayoutPREVIEW
      返回：
      一个具有与此布局相同特性的内存布局，但没有名称
      参见：

    • arrayElementVarHandle

      VarHandle arrayElementVarHandle(int... shape)
      创建一个分步变量句柄，可用于将内存段作为多维数组访问。该数组具有一个概念上的序列布局，包含shape.length个嵌套的序列布局。在概念上的序列布局中，内部序列布局的元素布局即为此值布局。生成的变量句柄就好像在概念布局上调用MemoryLayout.varHandle(PathElement...)预览方法一样，其中布局路径包含恰好shape.length + 1个开放序列布局路径元素预览。

      例如，以下方法调用：

      VarHandle arrayHandle = ValueLayout.JAVA_INT.arrayElementVarHandle(10, 20);
      等同于以下代码： 
       SequenceLayout notionalLayout = MemoryLayout.sequenceLayout(
                                         MemoryLayout.sequenceLayout(10, MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));
 VarHandle arrayHandle = notionalLayout.varHandle(PathElement.sequenceElement(),
                                                  PathElement.sequenceElement(),
                                                  PathElement.sequenceElement());
      生成的变量句柄arrayHandle将具有3个long类型的坐标；每个坐标被解释为对应序列布局的索引。如果我们将变量句柄的坐标从左到右分别表示为x、y和z，则变量句柄访问的最终偏移量可以使用以下公式计算： 
      
 偏移量 = (10 * 20 * 4 * x) + (20 * 4 * y) + (4 * z)
      另外，x、y和z的值受以下约束：
      • 0 <= x < notionalLayout.elementCount()
      • 0 <= y < 10
      • 0 <= z < 20

      考虑以下访问表达式：

      int value1 = (int) arrayHandle.get(10, 2, 4); // 正常，访问偏移量 = 8176
int value2 = (int) arrayHandle.get(0, 0, 30); // z的值超出范围
      在第一个情况下，访问是正确的，因为x、y和z的值符合上述指定的边界。在第二个情况下，访问失败并抛出IndexOutOfBoundsException，因为z的值超出了指定的边界。
      参数：
      shape - 每个嵌套数组维度的大小。
      返回：
      一个变量句柄，可用于将内存段作为多维数组访问，具有shape.length + 1个long坐标。
      抛出：
      IllegalArgumentException - 如果对于至少一个索引i，shape[i] < 0。
      UnsupportedOperationException - 如果byteAlignment() > byteSize()。
      参见：

    • carrier

      Class<?> carrier()
      返回与此值布局关联的载体。
      返回：
      与此值布局关联的载体

    • withName

      ValueLayoutPREVIEW withName(String name)
      返回具有与此布局相同特征但具有给定名称的内存布局。
      在接口中指定：
      withName in interface MemoryLayout预览
      参数：
      name - 布局名称。
      返回：
      具有与此布局相同特征但具有给定名称的内存布局
      参见：

    • withByteAlignment

      ValueLayoutPREVIEW withByteAlignment(long byteAlignment)
      返回具有与此布局相同特征但具有给定对齐约束（以字节为单位）的内存布局。
      在接口中指定：
      withByteAlignment in interface MemoryLayout预览
      参数：
      byteAlignment - 以字节为单位表示的布局对齐约束。
      返回：
      具有与此布局相同特征但具有给定对齐约束（以字节为单位）的内存布局
      抛出：
      IllegalArgumentException - 如果byteAlignment不是2的幂。