Интерфейс MemoryLayout

public sealed interface MemoryLayout extends Constable permits SequenceLayout, GroupLayout, ValueLayout (not exhaustive)

Макет памяти может использоваться для описания содержимого сегмента памяти в нейтральном к языку формате. В иерархии макета есть два типа листов: макеты значений, которые используются для представления значений заданного размера и типа (см. ValueLayout) и макеты заполнения, которые, как следует из названия, используются для представления части сегмента памяти, содержимое которой должно быть проигнорировано, главным образом для выравнивания (см. paddingLayout(long)). Некоторые общие константы макета значений определены в классе MemoryLayouts.

Более сложные макеты могут быть получены из более простых: последовательный макет обозначает повторение одного или нескольких макетов элементов (см. SequenceLayout); групповой макет обозначает агрегацию (как правило, разнородных) макетов членов (см. GroupLayout).

Например, рассмотрим следующее объявление структуры в C:

 typedef struct {
     char kind;
     int value;
 } TaggedValues[5];
 

Вышеприведенное объявление можно смоделировать с помощью объекта макета следующим образом:

SequenceLayout taggedValues = MemoryLayout.sequenceLayout(5,
    MemoryLayout.structLayout(
        MemoryLayout.valueLayout(8, ByteOrder.nativeOrder()).withName("kind"),
        MemoryLayout.paddingLayout(24),
        MemoryLayout.valueLayout(32, ByteOrder.nativeOrder()).withName("value")
    )
).withName("TaggedValues");
 

Все реализации этого интерфейса должны быть базируемыми на значениях; программисты должны рассматривать экземпляры, которые равны, как взаимозаменяемые и не должны использовать их для синхронизации, иначе может произойти непредсказуемое поведение. Например, в будущей версии синхронизация может завершиться неудачей. Метод equals должен использоваться для сравнения.

Классы, не относящиеся к платформе, не должны реализовывать MemoryLayout напрямую.

Если не указано иное, передача null аргумента или аргумента массива, содержащего один или несколько null элементов методу в этом классе, приводит к тому, что выбрасывается исключение NullPointerException.

Размер, выравнивание и порядок байтов

Все макеты имеют размер; размер макета для макетов значений и заполнения всегда явно указывается; это означает, что описание макета всегда имеет одинаковый размер в битах независимо от платформы, на которой он используется. Для производных макетов размер вычисляется следующим образом:

• для конечного макета последовательности S, у которого макет элемента — E и размер — L, размер S равен размеру E, умноженному на L
• размер бесконечного макета последовательности — неизвестен
• для группового макета G с макетами членов M1, M2, ..., Mn, соответственно, размерами S1, S2, ..., Sn, размер G равен либо S1 + S2 + ... + Sn, либо max(S1, S2, ... Sn) в зависимости от того, является ли группа структурой или объединением, соответственно

Кроме того, все макеты имеют естественное выравнивание, которое можно определить следующим образом:

• для макета заполнения L естественное выравнивание равно 1 независимо от его размера; то есть в отсутствие явного ограничения на выравнивание макет заполнения не должен влиять на ограничение на выравнивание группового макета, в который он вложен
• для макета значения L, размер которого равен N, естественное выравнивание L равно N
• для макета последовательности S, у которого макет элемента — E, естественное выравнивание S равно естественному выравниванию E
• для группового макета G с макетами членов M1, M2, ..., Mn, соответственно, выравниваниями A1, A2, ..., An, естественное выравнивание G равно max(A1, A2 ... An)

Естественное выравнивание макета может быть переопределено при необходимости (см. withBitAlignment(long)), что может быть полезно для описания гипервыровненных макетов.

Все макеты значений имеют явный порядок байтов (см. ByteOrder), который задается при создании макета.

Пути макета

Путь макета начинается с корневого макета (обычно группового или последовательного макета) и заканчивается вложенным в корневой макет макетом — это выбранный макет пути. Пути макетов обычно представляются как последовательность одного или нескольких экземпляров MemoryLayout.PathElement.

Пути макетов, например, полезны для получения смещений произвольно вложенных макетов внутри другого макета (см. bitOffset(PathElement...)), для быстрого получения дескриптора доступа к памяти, соответствующего выбранному макету (см. varHandle(Class, PathElement...)), для выбора произвольно вложенного макета внутри другого макета (см. select(PathElement...)) или для преобразования вложенного элемента макета внутри другого макета (см. map(UnaryOperator, PathElement...)).

Такие пути макетов могут быть построены программно с помощью методов этого класса. Например, для данного экземпляра макета taggedValues, созданного как описано выше, мы можем получить смещение в битах макета члена, названного value, в первом элементе последовательности следующим образом:

long valueOffset = taggedValues.bitOffset(PathElement.sequenceElement(0),
                                          PathElement.groupElement("value")); // yields 32
 

Аналогично, мы можем выбрать макет члена, названный value, следующим образом:

MemoryLayout value = taggedValues.select(PathElement.sequenceElement(),
                                         PathElement.groupElement("value"));
 

И мы также можем заменить макет, названный value, другим макетом, следующим образом:

MemoryLayout taggedValuesWithHole = taggedValues.map(l -> MemoryLayout.paddingLayout(32),
                                            PathElement.sequenceElement(), PathElement.groupElement("value"));
 

То есть, вышеприведенное объявление идентично следующему, более подробному:

MemoryLayout taggedValuesWithHole = MemoryLayout.sequenceLayout(5,
    MemoryLayout.structLayout(
        MemoryLayout.valueLayout(8, ByteOrder.nativeOrder()).withName("kind"),
        MemoryLayout.paddingLayout(32),
        MemoryLayout.paddingLayout(32)
));
 

Пути макета могут содержать один или несколько свободных измерений. Например, путь макета, проходящий через неопределенный элемент последовательности (то есть, где один из компонентов пути был получен с помощью метода MemoryLayout.PathElement.sequenceElement()) имеет дополнительное свободное измерение, которое необходимо связать во время выполнения. Это важно при получении дескриптора доступа к памяти varHandle из макетов, как показано в следующем коде:

VarHandle valueHandle = taggedValues.varHandle(int.class,
                                               PathElement.sequenceElement(),
                                               PathElement.groupElement("value"));
 

Поскольку путь макета, построенный в приведенном выше примере, содержит ровно одно свободное измерение (поскольку он не указывает, какой макет члена, названный value, должен быть выбран из содержащего последовательности макета), следует, что дескриптор доступа к памяти varHandle valueHandle будет иметь дополнительную long координату доступа.

Путь макета со свободными измерениями также может использоваться для создания дескриптора метода вычисления смещения с помощью метода bitOffset(PathElement...) или byteOffsetHandle(PathElement...). Опять же, свободные измерения переводятся в long параметры созданного дескриптора метода. Дескриптор метода может использоваться для вычисления смещений элементов последовательности в разных индексах, путем предоставления этих индексов при вызове дескриптора метода. Например:

MethodHandle offsetHandle = taggedValues.byteOffsetHandle(PathElement.sequenceElement(),
                                                          PathElement.groupElement("kind"));
long offset1 = (long) offsetHandle.invokeExact(1L); // 8
long offset2 = (long) offsetHandle.invokeExact(2L); // 16
 

Атрибуты макета

Макеты могут быть необязательно связаны с одним или несколькими атрибутами. Атрибут макета образует пару имя/значение, где имя — это String, а значение — это Constable. Наиболее распространенным типом атрибута макета является имя макета (см. LAYOUT_NAME), пользовательское имя, которое может быть связано с макетами памяти и к которому можно обратиться при построении путей макетов.