Интерфейс MemoryLayout

В иерархии макета есть два листа, макеты значений^{ПРЕДПРОСМОТР}, которые используются для представления значений заданного размера и типа (см. и макеты заполнения^{ПРЕДПРОСМОТР}, которые, как следует из названия, используются для представления части сегмента памяти, содержимое которой должно быть пропущено, и которые в основном присутствуют для выравнивания. Некоторые общие константы макета значений, такие как ValueLayout.JAVA_INT^{ПРЕДПРОСМОТР} и ValueLayout.JAVA_FLOAT_UNALIGNED^{ПРЕДПРОСМОТР} определены в классе ValueLayout^{ПРЕДПРОСМОТР}. Специальный вид макета значений, а именно макет адреса^{ПРЕДПРОСМОТР} используется для моделирования значений, обозначающих адрес области памяти.

Более сложные макеты могут быть получены из более простых: макет последовательности^{ПРЕДПРОСМОТР} обозначает однородное повторение нуля или более вхождений макета элемента; групповой макет^{ПРЕДПРОСМОТР} обозначает разнородное объединение нуля или более макетов членов. Групповые макеты бывают двух видов: макет структуры^{ПРЕДПРОСМОТР}, где макеты членов выкладываются друг за другом, и макет объединения^{ПРЕДПРОСМОТР}, где макеты членов выкладываются в одном начальном смещении.

Макеты могут быть необязательно связаны с именем. Имя макета может быть использовано при построении путей макета.

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

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

SequenceLayout taggedValues = MemoryLayout.sequenceLayout(5,
    MemoryLayout.structLayout(
        ValueLayout.JAVA_BYTE.withName("kind"),
        MemoryLayout.paddingLayout(3),
        ValueLayout.JAVA_INT.withName("value")
    )
).withName("TaggedValues");

Характеристики макетов памяти

• Размер макета значения определяется ValueLayout.carrier()^{ПРЕДПРОСМОТР}, связанным с макетом значения. То есть, константа ValueLayout.JAVA_INT^{ПРЕДПРОСМОТР} имеет носитель int, и размер 4 байта;
• Размер макета адреса зависит от платформы. То есть, константа ValueLayout.ADDRESS^{ПРЕДПРОСМОТР} имеет размер 8 байт на 64-битной платформе;
• Размер макета заполнения всегда задается явно при создании;
• Размер макета последовательности, макет элемента которого — E, а количество элементов — L, равен размеру E, умноженному на L;
• Размер макета структуры с макетами членов M1, M2, ..., Mn, размерами соответственно S1, S2, ..., Sn, равен S1 + S2 + ... + Sn;
• Размер макета объединения U с макетами членов M1, M2, ..., Mn, размерами соответственно S1, S2, ..., Sn, равен max(S1, S2, ... Sn).

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

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

Пути макета

Пути макета можно использовать для:

• получения смещений произвольно вложенных макетов;
• получения обработчика var, который можно использовать для доступа к значению, соответствующему выбранному макету;
• выбора произвольно вложенного макета.

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

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

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

Открытые элементы пути

VarHandle valueHandle = taggedValues.varHandle(PathElement.sequenceElement(),
                                               PathElement.groupElement("value"));
MemorySegment valuesSegment = ...
int val = (int) valueHandle.get(valuesSegment, 2); // reads the "value" field of the third struct in the array

Открытые элементы пути также влияют на создание обработчиков методам вычисления смещения. Каждый открытый элемент пути становится дополнительным long параметром в полученном обработчике метода. Этот параметр можно использовать для указания индекса элемента последовательности, смещение которого нужно вычислить:

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

Элементы пути разыменования

StructLayout RECTANGLE = MemoryLayout.structLayout(
        ValueLayout.ADDRESS.withTargetLayout(
                MemoryLayout.sequenceLayout(4,
                        MemoryLayout.structLayout(
                                ValueLayout.JAVA_INT.withName("x"),
                                ValueLayout.JAVA_INT.withName("y")
                        ).withName("point")
                 )
         ).withName("points")
);

С помощью элементов пути разыменования мы можем получить обработчик var, который обращается к координате y одной из точек в прямоугольнике, следующим образом:

VarHandle rectPointYs = RECTANGLE.varHandle(
        PathElement.groupElement("points"),
        PathElement.dereferenceElement(),
        PathElement.sequenceElement(),
        PathElement.groupElement("y")
);

MemorySegment rect = ...
int rect_y_4 = (int) rectPointYs.get(rect, 2); // rect.points[2]->y

Корректность пути макета

Путь макета P считается корректным для исходного макета C_0 в случае, если все его элементы пути E1, E2, ... En корректны для соответствующих входных макетов C_0, C_1, ... C_n-1. Элемент пути E считается корректным для макета L в случае, если выполняется любое из следующих условий:

• L — это макет последовательности, а E — это элемент пути последовательности (один из MemoryLayout.PathElement.sequenceElement(long)^ПРЕВИЮ, MemoryLayout.PathElement.sequenceElement(long, long)^ПРЕВИЮ или MemoryLayout.PathElement.sequenceElement()^ПРЕВИЮ). Кроме того, если E содержит один или несколько индексов последовательности, такие индексы должны быть совместимы со счетчиком элементов макета последовательности;
• L — это макет группы, а E — это элемент пути группы (один из MemoryLayout.PathElement.groupElement(String)^ПРЕВИЮ или MemoryLayout.PathElement.groupElement(long)^ПРЕВИЮ). Кроме того, элемент пути группы должен ссылаться на допустимый макет члена в L, по имени или индексу;
• L — это макет адреса, а E — это элемент пути разыменования^ПРЕВИЮ. Кроме того, L должен определять какой-либо целевой макет^ПРЕВИЮ.