Spec-Zone.ru › OpenJDK 21

Интерфейс ValueLayout

Все суперинтерфейсы:
MemoryLayoutPREVIEW
Все известные подинтерфейсы:
AddressLayoutPREVIEW, ValueLayout.OfBooleanPREVIEW, ValueLayout.OfBytePREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfDoublePREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfShortPREVIEW
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 — это предварительный API платформы Java.
Программы могут использовать ValueLayout только при включенных функциях предварительного просмотра.
Функции предварительного просмотра могут быть удалены в будущих выпусках или модернизированы до постоянных функций платформы Java.
Макет, моделирующий значения основных типов данных. Примеры значений, моделируемых макетом значения, — это целочисленные значения (как со знаком, так и без знака), значения с плавающей точкой и значения адресов.

Каждый макет значения имеет размер, выравнивание (оба выражаются в байтах), порядок байтов и носитель, то есть тип Java, который следует использовать при доступеПРЕДПРОСМОТР к области памяти с использованием макета значения.

Этот класс определяет полезные константы макета значений для примитивных типов Java и адресов.

Примечание API:
Некоторые характеристики констант макета Java зависят от платформы. Например, порядок байтов этих констант задан в соответствии с родным порядком байтов, что упрощает работу с другими API, такими как массивы и ByteBuffer. Кроме того, ограничение выравнивания JAVA_LONG и JAVA_DOUBLE установлено в 8 байтов на 64-битных платформах, но только в 4 байта на 32-битных платформах.
Требования к реализации:
Реализующие классы и подклассы являются неизменяемыми, потокобезопасными и базированными на значениях.
Диаграмма иерархии классов-герметиков:
Sealed class hierarchy graph for ValueLayoutSealed class hierarchy graph for ValueLayout
С:
19

Краткое описание вложенных классов

Модификатор и тип Интерфейс Описание
static interface  ValueLayout.OfBooleanPREVIEW
Предварительный просмотр.
Макет значения, носитель которого — boolean.class.
static interface  ValueLayout.OfBytePREVIEW
Предварительный просмотр.
Макет значения, носитель которого — byte.class.
static interface  ValueLayout.OfCharPREVIEW
Предварительный просмотр.
Макет значения, носитель которого — char.class.
static interface  ValueLayout.OfDoublePREVIEW
Предварительный просмотр.
Макет значения, носитель которого — double.class.
static interface  ValueLayout.OfFloatPREVIEW
Предварительный просмотр.
Макет значения, носитель которого — float.class.
static interface  ValueLayout.OfIntPREVIEW
Предварительный просмотр.
Макет значения, носитель которого — int.class.
static interface  ValueLayout.OfLongPREVIEW
Предварительный просмотр.
Макет значения, носитель которого — long.class.
static interface  ValueLayout.OfShortPREVIEW
Предварительный просмотр.
Макет значения, носитель которого — short.class.

Вложенные классы/интерфейсы, объявленные в интерфейсе java.lang.foreign.MemoryLayoutПРЕДПРОСМОТР

MemoryLayout.PathElementPREVIEW

Краткое описание полей

Модификатор и тип Поле Описание
static final AddressLayoutPREVIEW ADDRESS
Постоянная макета адреса, размер которой такой же, как у машинного адреса (size_t), выравнивание по байтам установлено в sizeof(size_t), порядок байтов установлен в ByteOrder.nativeOrder().
static final AddressLayoutPREVIEW ADDRESS_UNALIGNED
Постоянная макета невыровненного адреса, размер которой такой же, как у машинного адреса (size_t), порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfBooleanPREVIEW JAVA_BOOLEAN
Постоянная макета значения, размер которой такой же, как у Java boolean, выравнивание по байтам установлено в 1, порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfBytePREVIEW JAVA_BYTE
Постоянная макета значения, размер которой такой же, как у Java byte, выравнивание по байтам установлено в 1, порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfCharPREVIEW JAVA_CHAR
Постоянная макета значения, размер которой такой же, как у Java char, выравнивание по байтам установлено в 2, порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfCharPREVIEW JAVA_CHAR_UNALIGNED
Постоянная макета невыровненного значения, размер которой такой же, как у Java char и порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE
Постоянная макета значения, размер которой такой же, как у Java double, (зависит от платформы) выравнивание по байтам установлено в ADDRESS.byteSize(), порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE_UNALIGNED
Постоянная макета невыровненного значения, размер которой такой же, как у Java double и порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT
Постоянная макета значения, размер которой такой же, как у Java float, выравнивание по байтам установлено в 4, порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT_UNALIGNED
Постоянная макета невыровненного значения, размер которой такой же, как у Java float и порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfIntPREVIEW JAVA_INT
Постоянная макета значения, размер которой такой же, как у Java int, выравнивание по байтам установлено в 4, порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfIntPREVIEW JAVA_INT_UNALIGNED
Постоянная макета невыровненного значения, размер которой такой же, как у Java int и порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfLongPREVIEW JAVA_LONG
Постоянная макета значения, размер которой такой же, как у Java long, (зависит от платформы) выравнивание по байтам установлено в ADDRESS.byteSize(), порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfLongPREVIEW JAVA_LONG_UNALIGNED
Постоянная макета невыровненного значения, размер которой такой же, как у Java long и порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfShortPREVIEW JAVA_SHORT
Постоянная макета значения, размер которой такой же, как у Java short, выравнивание по байтам установлено в 2, порядок байтов установлен в ByteOrder.nativeOrder().
static final ValueLayout.OfShortPREVIEW JAVA_SHORT_UNALIGNED
Постоянная макета невыровненного значения, размер которой такой же, как у Java short и порядок байтов установлен в ByteOrder.nativeOrder().

Краткое описание методов

Модификатор и тип Метод Описание
VarHandle arrayElementVarHandle(int... shape)
Создаёт шагированную обработку переменной, которую можно использовать для доступа к сегменту памяти как многомерному массиву.
Class<?> carrier()
Возвращает носитель, связанный с этим макетом значения.
ByteOrder order()
Возвращает порядок байтов значения.
ValueLayoutPREVIEW withByteAlignment(long byteAlignment)
Возвращает макет памяти с такими же характеристиками, как у этого макета, но с заданным ограничением выравнивания (в байтах).
ValueLayoutPREVIEW withName(String name)
Возвращает макет памяти с такими же характеристиками, как у этого макета, но с заданным именем.
ValueLayoutPREVIEW withOrder(ByteOrder order)
Возвращает макет значения с такими же характеристиками, как у этого макета, но с заданным порядком байтов.
ValueLayoutPREVIEW withoutName()
Возвращает макет памяти с такими же характеристиками, как у этого макета, но без имени.

Методы, объявленные в интерфейсе java.lang.foreign.MemoryLayoutПРЕДПРОСМОТР

byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle

Подробное описание полей

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);
Прим.:
Следует проявлять осторожность при использовании макетов невыровненных значений, так как они могут вызвать проблемы с производительностью и переносимостью.

JAVA_CHAR_UNALIGNED

static final ValueLayout.OfCharPREVIEW JAVA_CHAR_UNALIGNED
Константа макета невыровненного значения, размер которой равен размеру Java char и порядок байтов установлен в ByteOrder.nativeOrder(). Эквивалентно следующему коду:
JAVA_CHAR.withByteAlignment(1);
Прим.:
Следует проявлять осторожность при использовании макетов невыровненных значений, так как они могут вызвать проблемы с производительностью и переносимостью.

JAVA_SHORT_UNALIGNED

static final ValueLayout.OfShortPREVIEW JAVA_SHORT_UNALIGNED
Константа макета невыровненного значения, размер которой равен размеру Java short и порядок байтов установлен в ByteOrder.nativeOrder(). Эквивалентно следующему коду:
JAVA_SHORT.withByteAlignment(1);
Прим.:
Следует проявлять осторожность при использовании макетов невыровненных значений, так как они могут вызвать проблемы с производительностью и переносимостью.

JAVA_INT_UNALIGNED

static final ValueLayout.OfIntPREVIEW JAVA_INT_UNALIGNED
Константа макета невыровненного значения, размер которой равен размеру Java int и порядок байтов установлен в ByteOrder.nativeOrder(). Эквивалентно следующему коду:
JAVA_INT.withByteAlignment(1);
Прим.:
Следует проявлять осторожность при использовании макетов невыровненных значений, так как они могут вызвать проблемы с производительностью и переносимостью.

JAVA_LONG_UNALIGNED

static final ValueLayout.OfLongPREVIEW JAVA_LONG_UNALIGNED
Константа макета невыровненного значения, размер которой равен размеру Java long и порядок байтов установлен в ByteOrder.nativeOrder(). Эквивалентно следующему коду:
JAVA_LONG.withByteAlignment(1);
Прим.:
Следует проявлять осторожность при использовании макетов невыровненных значений, так как они могут вызвать проблемы с производительностью и переносимостью.

JAVA_FLOAT_UNALIGNED

static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT_UNALIGNED
Константа макета невыровненного значения, размер которой равен размеру Java float и порядок байтов установлен в ByteOrder.nativeOrder(). Эквивалентно следующему коду:
JAVA_FLOAT.withByteAlignment(1);
Прим.:
Следует проявлять осторожность при использовании макетов невыровненных значений, так как они могут вызвать проблемы с производительностью и переносимостью.

JAVA_DOUBLE_UNALIGNED

static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE_UNALIGNED
Константа макета невыровненного значения, размер которой равен размеру Java double и порядок байтов установлен в ByteOrder.nativeOrder(). Эквивалентно следующему коду:
JAVA_DOUBLE.withByteAlignment(1);
Прим.:
Следует проявлять осторожность при использовании макетов невыровненных значений, так как они могут вызвать проблемы с производительностью и переносимостью.

Подробное описание методов

order

ByteOrder order()
Возвращает порядок байтов значения.
Возвращает:
порядок байтов значения

withOrder

ValueLayoutPREVIEW withOrder(ByteOrder order)
Возвращает макет значения с теми же характеристиками, что и этот макет, но с заданным порядком байтов.
Параметры:
order - желаемый порядок байтов.
Возвращает:
макет значения с теми же характеристиками, что и этот макет, но с заданным порядком байтов

withoutName

ValueLayoutPREVIEW withoutName()
Возвращает макет памяти с теми же характеристиками, что и этот макет, но без имени.
Задано в:
withoutName в интерфейсе MemoryLayoutPREVIEW
Возвращает:
макет памяти с теми же характеристиками, что и этот макет, но без имени
См. также:
  • MemoryLayout.name()ПЕРЕДПРОСМОТР

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 соответственно, окончательный смещение, доступный через обработчик переменных, может быть вычислено по следующей формуле:

 offset = (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); // ok, accessed offset = 8176
int value2 = (int) arrayHandle.get(0, 0, 30); // out of bounds value for z
В первом случае доступ корректен, так как значения x, y и z соответствуют указанным границам. Во втором случае доступ завершается с ошибкой IndexOutOfBoundsException, так как значение z выходит за пределы указанных границ.
Параметры:
shape - размер каждой вложенной размерности массива.
Возвращает:
обработчик переменных, который может использоваться для доступа к сегменту памяти в виде многомерного массива, содержащего shape.length + 1 long координат.
Исключения:
IllegalArgumentException - если shape[i] < 0, для хотя бы одного индекса i.
UnsupportedOperationException - если byteAlignment() > byteSize().
См. также:
  • MethodHandles.memorySegmentViewVarHandle(java.lang.foreign.ValueLayout)ПРОСМОТР
  • MemoryLayout.varHandle(PathElement...)ПРОСМОТР
  • SequenceLayoutПРОСМОТР

carrier

Class<?> carrier()
Возвращает носитель, связанный с этой структурой данных.
Возвращает:
носитель, связанный с этой структурой данных

withName

ValueLayoutPREVIEW withName(String name)
Возвращает структуру памяти с теми же характеристиками, что и эта структура, но с заданным именем.
Определено в:
withName в интерфейсе MemoryLayoutPREVIEW
Параметры:
name - имя структуры.
Возвращает:
структура памяти с теми же характеристиками, что и эта структура, но с заданным именем
См. также:
  • MemoryLayout.name()ПРОСМОТР

withByteAlignment

ValueLayoutPREVIEW withByteAlignment(long byteAlignment)
Возвращает структуру памяти с теми же характеристиками, что и эта структура, но с заданным ограничением выравнивания (в байтах).
Определено в:
withByteAlignment в интерфейсе MemoryLayoutPREVIEW
Параметры:
byteAlignment - ограничение выравнивания структуры, выраженное в байтах.
Возвращает:
структура памяти с теми же характеристиками, что и эта структура, но с заданным ограничением выравнивания (в байтах)
Исключения:
IllegalArgumentException - если byteAlignment не является степенью двойки.

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/ValueLayout.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API