- 所有超接口:
-
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。
预览功能可能会在将来的版本中被移除,或升级为Java平台的永久功能。
一个模拟基本数据类型值的布局。值布局模拟的值的示例包括整数值(有符号或无符号)、浮点值和地址值。
每个值布局都有一个大小、一个对齐方式(都以字节表示)、一个字节顺序,以及一个载体,即在使用值布局访问预览内存区域时应使用的Java类型。
此类为Java原始类型和地址定义了有用的值布局常量。
- API注释:
-
Java布局常量的一些特征是依赖于平台的。例如,这些常量的字节顺序设置为本机字节顺序,因此可以轻松地与其他API(如数组和
ByteBuffer
)一起使用。此外,JAVA_LONG
和JAVA_DOUBLE
的对齐约束在64位平台上设置为8字节,但在32位平台上仅设置为4字节。 - 实现要求:
- 实现类和子类是不可变的、线程安全的,并且是基于值的。
- 密封类层次结构图:
-
- 自Java版本:
- 19
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
预览。一个载体为boolean.class
的值布局。static interface
预览。一个载体为byte.class
的值布局。static interface
预览。一个载体为char.class
的值布局。static interface
预览。一个载体为double.class
的值布局。static interface
预览。一个载体为float.class
的值布局。static interface
预览。一个载体为int.class
的值布局。static interface
预览。一个载体为long.class
的值布局。static interface
预览。一个载体为short.class
的值布局。Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayoutPREVIEW
MemoryLayout.PathElementPREVIEW
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final AddressLayoutPREVIEW
static final AddressLayoutPREVIEW
一个未对齐的地址布局常量,其大小与机器地址(size_t
)相同,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfBooleanPREVIEW
一个大小与Javaboolean
相同的值布局常量,字节对齐设置为1,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfBytePREVIEW
一个大小与Javabyte
相同的值布局常量,字节对齐设置为1,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfCharPREVIEW
一个大小与Javachar
相同的值布局常量,字节对齐设置为2,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfCharPREVIEW
一个未对齐的值布局常量,其大小与Javachar
相同,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfDoublePREVIEW
static final ValueLayout.OfDoublePREVIEW
一个未对齐的值布局常量,其大小与Javadouble
相同,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfFloatPREVIEW
一个大小与Javafloat
相同的值布局常量,字节对齐设置为4,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfFloatPREVIEW
一个未对齐的值布局常量,其大小与Javafloat
相同,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfIntPREVIEW
一个大小与Javaint
相同的值布局常量,字节对齐设置为4,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfIntPREVIEW
一个未对齐的值布局常量,其大小与Javaint
相同,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfLongPREVIEW
static final ValueLayout.OfLongPREVIEW
一个未对齐的值布局常量,其大小与Javalong
相同,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfShortPREVIEW
一个大小与Javashort
相同的值布局常量,字节对齐设置为2,字节顺序设置为ByteOrder.nativeOrder()
。static final ValueLayout.OfShortPREVIEW
一个未对齐的值布局常量,其大小与Javashort
相同,字节顺序设置为ByteOrder.nativeOrder()
。 -
Method Summary
Modifier and TypeMethodDescriptionarrayElementVarHandle
(int... shape) 创建一个跨度变量句柄,可用于将内存段作为多维数组访问。Class
<?> carrier()
返回与此值布局关联的载体。order()
返回值的字节顺序。withByteAlignment
(long byteAlignment) 返回具有与此布局相同特征的内存布局,但具有给定的对齐约束(以字节为单位)。返回具有与此布局相同特征的内存布局,但具有给定的名称。返回具有与此布局相同特征的值布局,但具有给定的字节顺序。返回具有与此布局相同特征的内存布局,但没有名称。Methods declared in interface java.lang.foreign.MemoryLayoutPREVIEW
byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle
-
Field Details
-
ADDRESS
-
JAVA_BYTE
一个大小与Javabyte
相同的值布局常量,字节对齐设置为1,字节顺序设置为ByteOrder.nativeOrder()
。 -
JAVA_BOOLEAN
一个大小与Javaboolean
相同的值布局常量,字节对齐设置为1,字节顺序设置为ByteOrder.nativeOrder()
。 -
JAVA_CHAR
一个值布局常量,其大小与Javachar
相同,字节对齐设置为2,字节顺序设置为ByteOrder.nativeOrder()
。 -
JAVA_SHORT
一个值布局常量,其大小与Javashort
相同,字节对齐设置为2,字节顺序设置为ByteOrder.nativeOrder()
。 -
JAVA_INT
一个值布局常量,其大小与Javaint
相同,字节对齐设置为4,字节顺序设置为ByteOrder.nativeOrder()
。 -
JAVA_LONG
-
JAVA_FLOAT
一个值布局常量,其大小与Javafloat
相同,字节对齐设置为4,字节顺序设置为ByteOrder.nativeOrder()
。 -
JAVA_DOUBLE
-
ADDRESS_UNALIGNED
一个不对齐的地址布局常量,其大小与机器地址相同(size_t
),字节顺序设置为ByteOrder.nativeOrder()
。等同于以下代码:ADDRESS.withByteAlignment(1);
- API 注意:
- 在使用不对齐的值布局时应谨慎,因为可能会引起性能和可移植性问题。
-
JAVA_CHAR_UNALIGNED
- API 注意:
- 在使用不对齐的值布局时应谨慎,因为可能会引起性能和可移植性问题。
-
JAVA_SHORT_UNALIGNED
一个不对齐的值布局常量,其大小与Javashort
相同,字节顺序设置为ByteOrder.nativeOrder()
。等同于以下代码:JAVA_SHORT.withByteAlignment(1);
- API 注意:
- 在使用不对齐的值布局时应谨慎,因为可能会引起性能和可移植性问题。
-
JAVA_INT_UNALIGNED
- API 注意:
- 在使用不对齐的值布局时应谨慎,因为可能会引起性能和可移植性问题。
-
JAVA_LONG_UNALIGNED
- API 注意:
- 在使用不对齐的值布局时应谨慎,因为可能会引起性能和可移植性问题。
-
JAVA_FLOAT_UNALIGNED
一个不对齐的值布局常量,其大小与Javafloat
相同,字节顺序设置为ByteOrder.nativeOrder()
。等同于以下代码:JAVA_FLOAT.withByteAlignment(1);
- API 注意:
- 在使用不对齐的值布局时应谨慎,因为可能会引起性能和可移植性问题。
-
JAVA_DOUBLE_UNALIGNED
一个不对齐的值布局常量,其大小与Javadouble
相同,字节顺序设置为ByteOrder.nativeOrder()
。等同于以下代码:JAVA_DOUBLE.withByteAlignment(1);
- API 注意:
- 在使用不对齐的值布局时应谨慎,因为可能会引起性能和可移植性问题。
-
-
Method Details
-
order
ByteOrder order()返回值的字节顺序。- 返回:
- 值的字节顺序
-
withOrder
返回一个具有与此布局相同特性的值布局,但具有给定的字节顺序。- 参数:
-
order
- 所需的字节顺序。 - 返回:
- 一个具有与此布局相同特性的值布局,但具有给定的字节顺序
-
withoutName
ValueLayoutPREVIEW withoutName()返回一个具有与此布局相同特性的内存布局,但没有名称。- 指定者:
-
withoutName
在接口MemoryLayoutPREVIEW
- 返回:
- 一个具有与此布局相同特性的内存布局,但没有名称
- 参见:
-
arrayElementVarHandle
创建一个分步变量句柄,可用于将内存段作为多维数组访问。该数组具有一个概念上的序列布局,包含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
返回具有与此布局相同特征但具有给定名称的内存布局。- 在接口中指定:
-
withName
in interfaceMemoryLayout预览
- 参数:
-
name
- 布局名称。 - 返回:
- 具有与此布局相同特征但具有给定名称的内存布局
- 参见:
-
withByteAlignment
返回具有与此布局相同特征但具有给定对齐约束(以字节为单位)的内存布局。- 在接口中指定:
-
withByteAlignment
in interfaceMemoryLayout预览
- 参数:
-
byteAlignment
- 以字节为单位表示的布局对齐约束。 - 返回:
- 具有与此布局相同特征但具有给定对齐约束(以字节为单位)的内存布局
- 抛出:
-
IllegalArgumentException
- 如果byteAlignment
不是2的幂。
-
ValueLayout
。