Интерфейс MemorySegment

public sealed interface MemorySegment

Сегмент памяти предоставляет доступ к непрерывной области памяти.

Существует два вида сегментов памяти:

Сегмент кучи находится в области памяти внутри кучи Java и предоставляет к ней доступ (в области «в куче»).
Нативный сегмент находится в области памяти за пределами кучи Java и предоставляет к ней доступ (в области «вне кучи»).

Сегменты кучи можно получить, вызвав один из фабричных методов ofArray(int[]). Эти методы возвращают сегмент памяти, находящийся в области кучи, в которой хранится указанный массив Java.

Нативные сегменты можно получить, вызвав один из фабричных методов Arena.allocate(long, long). Они возвращают сегмент памяти, находящийся в недавно выделенной области вне кучи заданного размера и с заданным ограничением на выравнивание. Кроме того, нативные сегменты можно получить, mapping файл в новую область вне кучи (в некоторых системах эта операция иногда называется mmap). Полученные таким способом сегменты называются отображенными, а их содержимое можно сохранить и загрузить из базового файла, отображенного в память, и обратно.

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

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

У каждого сегмента памяти есть адрес, выраженный значением long. Характер адреса сегмента зависит от его вида:

Адрес сегмента кучи не является физическим адресом, а представляет собой смещение внутри области памяти, на которой основан сегмент. Эта область находится в куче Java, поэтому сборка мусора со временем может привести к перемещению области в физической памяти, однако это не видно клиентам API MemorySegment, которые видят стабильный виртуализированный адрес сегмента кучи, основанного на этой области. Адрес сегмента кучи, полученного одним из фабричных методов ofArray(int[]), равен нулю.
Адрес нативного сегмента (включая отображенные сегменты) обозначает физический адрес области памяти, на которой основан сегмент.

У каждого сегмента памяти есть максимальное выравнивание в байтах, выраженное значением long. Максимальное выравнивание всегда является степенью двойки и определяется адресом сегмента и типом сегмента, как подробнее объясняется ниже.

У каждого сегмента памяти есть размер. Размер сегмента кучи определяется массивом Java, из которого он получен. Этот размер предсказуем в разных средах выполнения Java. Размер нативного сегмента либо задается явно (как в Arena.allocate(long, long)), либо определяется из MemoryLayout (как в SegmentAllocator.allocate(MemoryLayout)). Обычно размер сегмента памяти является положительным числом, но может быть нулевым, но никогда не бывает отрицательным.

Адрес и размер сегмента памяти вместе гарантируют, что операции доступа к сегменту не выйдут за пределы области памяти, на которой он основан. Иными словами, у сегмента памяти есть пространственные границы.

Каждый сегмент памяти связан с областью действия. Это гарантирует, что операции доступа к сегменту памяти не будут выполняться, когда область памяти, на которой основан сегмент, больше недоступна (например, если связанная с используемым сегментом памяти область действия больше не является активной). Иными словами, у сегмента памяти есть временные границы.

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

Доступ к сегментам памяти

Сегмент памяти можно читать и записывать с помощью различных операций доступа, предоставляемых этим классом (например, get(ValueLayout.OfInt, long)). Каждая операция доступа принимает компоновку значения, задающую размер и форму значения, а также смещение, выраженное в байтах. Например, чтобы прочитать int из сегмента, используя порядок байтов по умолчанию, можно использовать следующий код:

MemorySegment segment = ...
int value = segment.get(ValueLayout.JAVA_INT, 0);

Если считываемое значение хранится в памяти в кодировке с прямым порядком байтов, операцию доступа можно записать следующим образом:

int value = segment.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);

Операции доступа к сегментам памяти реализованы с помощью VarHandle. Метод ValueLayout.varHandle() можно использовать для получения VarHandle, который позволяет считывать и записывать на сегмент памяти по заданному смещению значения, представленные указанной компоновкой значения:

VarHandle intAtOffsetHandle = ValueLayout.JAVA_INT.varHandle(); // (MemorySegment, long)
int value = (int) intAtOffsetHandle.get(segment, 10L);          // segment.get(ValueLayout.JAVA_INT, 10L)

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

VarHandle intAtOffsetAndIndexHandle =
        ValueLayout.JAVA_INT.arrayElementVarHandle();             // (MemorySegment, long, long)
int value = (int) intAtOffsetAndIndexHandle.get(segment, 2L, 3L); // segment.get(ValueLayout.JAVA_INT, 2L + (3L * 4L))

Клиенты также могут опустить параметр базового смещения, чтобы упростить выражение доступа. Это можно использовать для реализации таких операций доступа, как getAtIndex(OfInt, long):

VarHandle intAtIndexHandle =
        MethodHandles.insertCoordinates(intAtOffsetAndIndexHandle, 1, 0L); // (MemorySegment, long)
int value = (int) intAtIndexHandle.get(segment, 3L);                       // segment.getAtIndex(ValueLayout.JAVA_INT, 3L);

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

Срезы сегментов памяти

Сегменты памяти поддерживают создание срезов. Создание среза сегмента памяти возвращает новый сегмент памяти, основанный на той же области памяти, что и исходный. Адрес сегмента-среза определяется на основе адреса исходного сегмента путем прибавления смещения (выраженного в байтах). Размер сегмента-среза определяется либо неявно (путем вычитания заданного смещения из размера исходного сегмента), либо задается явно. Иными словами, пространственные границы сегмента-среза строже, чем у исходного сегмента:

 Arena arena = ...
 MemorySegment segment = arena.allocate(100);
 MemorySegment slice = segment.asSlice(50, 10);
 slice.get(ValueLayout.JAVA_INT, 20); // Out of bounds!
 arena.close();
 slice.get(ValueLayout.JAVA_INT, 0); // Already closed!

В приведенном выше коде создается нативный сегмент длиной 100 байт, а затем срез, начинающийся со смещения 50 в segment и имеющий длину 10 байт. То есть адрес slice равен segment.address() + 50, а его размер составляет 10. В результате попытка прочитать значение int по смещению 20 в сегменте slice приведет к исключению. Временные границы исходного сегмента наследуются его срезами; то есть, когда связанная с segment область действия перестанет быть активной, slice также станет недоступным.

Клиент может получить Stream из сегмента, а затем использовать его для создания срезов сегмента (в соответствии с заданной компоновкой элемента) и даже разрешить нескольким потокам параллельно работать с непересекающимися срезами сегмента (для этого сегмент должен быть доступен из нескольких потоков). Следующий код позволяет параллельно просуммировать все значения int в сегменте памяти:

 try (Arena arena = Arena.ofShared()) {
     SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, ValueLayout.JAVA_INT);
     MemorySegment segment = arena.allocate(SEQUENCE_LAYOUT);
     int sum = segment.elements(ValueLayout.JAVA_INT).parallel()
                      .mapToInt(s -> s.get(ValueLayout.JAVA_INT, 0))
                      .sum();
 }

Выравнивание

Операции доступа к сегменту памяти ограничены не только пространственными и временными границами сегмента, но и ограничением на выравнивание компоновки значения, заданной для операции. Операция доступа может обращаться только к тем смещениям в сегменте, которые обозначают адреса в физической памяти, выровненные согласно компоновке. Адрес в физической памяти выровнен согласно компоновке, если он кратен ограничению на выравнивание этой компоновки. Например, адрес 1000 выровнен согласно ограничению на выравнивание в 8 байт (поскольку 1000 кратно 8), а также согласно ограничениям на выравнивание в 4 и 2 байта; напротив, адрес 1004 выровнен согласно ограничениям на выравнивание в 4 и 2 байта, но не в 8 байт. Операции доступа должны соблюдать выравнивание, поскольку оно может влиять на производительность операций доступа, а также определять, какие операции доступа доступны по заданному физическому адресу. Например, атомарные операции доступа с использованием VarHandle разрешены только по выровненным адресам. Кроме того, выравнивание учитывается при операции доступа независимо от того, к нативному сегменту или сегменту кучи производится обращение.

Если используемый сегмент является нативным, его адрес в физической памяти можно сложить со смещением, чтобы получить целевой адрес в физической памяти. Это демонстрирует приведенная ниже псевдофункция:

boolean isAligned(MemorySegment segment, long offset, MemoryLayout layout) {
  return ((segment.address() + offset) % layout.byteAlignment()) == 0;
}

Например:

К нативному сегменту с адресом 1000 можно обращаться по смещениям 0, 8, 16, 24 и т. д. при ограничении на выравнивание в 8 байт, поскольку целевые адреса (1000, 1008, 1016, 1024) выровнены по 8 байт. Доступ по смещениям 1–7, 9–15 или 17–23 запрещен, поскольку целевые адреса не будут выровнены по 8 байт.
К нативному сегменту с адресом 1000 можно обращаться по смещениям 0, 4, 8, 12 и т. д. при ограничении на выравнивание в 4 байта, поскольку целевые адреса (1000, 1004, 1008, 1012) выровнены по 4 байта. Доступ по смещениям 1–3, 5–7 или 9–11 запрещен, поскольку целевые адреса не будут выровнены по 4 байта.
К нативному сегменту с адресом 1000 можно обращаться по смещениям 0, 2, 4, 6 и т. д. при ограничении на выравнивание в 2 байта, поскольку целевые адреса (1000, 1002, 1004, 1006) выровнены по 2 байта. Доступ по смещениям 1, 3 или 5 запрещен, поскольку целевые адреса не будут выровнены по 2 байта.
К нативному сегменту с адресом 1004 можно обращаться по смещениям 0, 4, 8, 12 и т. д. при ограничении на выравнивание в 4 байта, а также по смещениям 0, 2, 4, 6 и т. д. при ограничении на выравнивание в 2 байта. При ограничении на выравнивание в 8 байт к нему можно обращаться по смещениям 4, 12, 20, 28 и т. д.
К нативному сегменту с адресом 1006 можно обращаться по смещениям 0, 2, 4, 6 и т. д. при ограничении на выравнивание в 2 байта. При ограничении на выравнивание в 4 байта к нему можно обращаться по смещениям 2, 6, 10, 14 и т. д. При ограничении на выравнивание в 8 байт к нему можно обращаться по смещениям 2, 10, 18, 26 и т. д.
К нативному сегменту с адресом 1007 можно обращаться по смещениям 0, 1, 2, 3 и т. д. при ограничении на выравнивание в 1 байт. При ограничении на выравнивание в 2 байта к нему можно обращаться по смещениям 1, 3, 5, 7 и т. д. При ограничении на выравнивание в 4 байта к нему можно обращаться по смещениям 1, 5, 9, 13 и т. д. При ограничении на выравнивание в 8 байт к нему можно обращаться по смещениям 1, 9, 17, 25 и т. д.

Ограничение на выравнивание, используемое при доступе к сегменту, обычно определяется формой структуры данных, хранящейся в сегменте. Например, если программист хочет хранить последовательность 8-байтовых значений в нативном сегменте, сегмент следует выделить, указав ограничение на выравнивание в 8 байт — с помощью Arena.allocate(long, long) или SegmentAllocator.allocate(MemoryLayout). Эти фабричные методы обеспечивают, что начальный адрес области вне кучи, на которой основан возвращаемый сегмент, выровнен по 8 байт. После этого программист может обращаться к сегменту по нужным смещениям — 0, 8, 16, 24 и т. д. — зная, что каждое такое обращение выровнено.

Если используемый сегмент является сегментом кучи, определить, выровнен ли доступ, сложнее. Адрес сегмента в физической памяти неизвестен и даже не является постоянным (он может измениться, если сегмент переместится во время сборки мусора). Это означает, что невозможно сложить адрес со заданным смещением, чтобы определить целевой адрес в физической памяти. Поскольку ограничение на выравнивание всегда относится к выравниванию адресов в физической памяти, в принципе невозможно определить, выровнено ли какое-либо смещение в сегменте кучи. Например, предположим, что программист выбирает ограничение на выравнивание в 8 байт и пытается обратиться к смещению 16 в сегменте кучи. Если адресу 0 сегмента кучи соответствует физический адрес 1000, целевой адрес (1016) будет выровнен, но если адресу 0 соответствует физический адрес 1004, целевой адрес (1020) не будет выровнен. Нежелательно разрешать доступ к целевым адресам, которые выровнены согласно выбранному программистом ограничению, но могут быть не гарантированно выровнены в физической памяти (например, из-за особенностей платформы и/или поведения сборщика мусора).

На практике среда выполнения Java располагает массивы в памяти так, чтобы каждый элемент размером n байт находился по физическому адресу, выровненному по n байт. Среда выполнения сохраняет этот инвариант, даже если массив перемещается во время сборки мусора. Операции доступа используют этот инвариант, чтобы определить, соответствует ли заданное смещение в сегменте кучи выровненному адресу в физической памяти. Например:

Начальный физический адрес массива short[] будет выровнен по 2 байта (например, 1006), чтобы последовательные элементы short находились по адресам, выровненным по 2 байта (например, 1006, 1008, 1010, 1012 и т. д.). К сегменту кучи, основанному на массиве short[], можно обращаться по смещениям 0, 2, 4, 6 и т. д. при ограничении на выравнивание в 2 байта. Обращаться к сегменту при ограничении на выравнивание в 4 байта нельзя ни по одному смещению, поскольку нет гарантии, что целевой адрес будет выровнен по 4 байта: например, смещению 0 будет соответствовать физический адрес 1006, а смещению 1 — физический адрес 1007. Аналогично, обращаться к сегменту при ограничении на выравнивание в 8 байт нельзя ни по одному смещению, поскольку нет гарантии, что целевой адрес будет выровнен по 8 байт: например, смещению 2 будет соответствовать физический адрес 1008, а смещению 4 — физический адрес 1010.
Начальный физический адрес массива long[] будет выровнен по 8 байт (например, 1000), чтобы последовательные элементы long находились по адресам, выровненным по 8 байт (например, 1000, 1008, 1016, 1024 и т. д.). К сегменту кучи, основанному на массиве long[], можно обращаться по смещениям 0, 8, 16, 24 и т. д. при ограничении на выравнивание в 8 байт. Кроме того, к сегменту можно обращаться по смещениям 0, 4, 8, 12 и т. д. при ограничении на выравнивание в 4 байта, поскольку целевые адреса (1000, 1004, 1008, 1012) выровнены по 4 байта. Также к сегменту можно обращаться по смещениям 0, 2, 4, 6 и т. д. при ограничении на выравнивание в 2 байта, поскольку целевые адреса (например, 1000, 1002, 1004, 1006) выровнены по 2 байта.

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

Максимальное выравнивание сегментов кучи

Тип массива (базовой области) Максимальное поддерживаемое выравнивание (в байтах)

boolean[] ValueLayout.JAVA_BOOLEAN.byteAlignment()

byte[] ValueLayout.JAVA_BYTE.byteAlignment()

char[] ValueLayout.JAVA_CHAR.byteAlignment()

short[] ValueLayout.JAVA_SHORT.byteAlignment()

int[] ValueLayout.JAVA_INT.byteAlignment()

float[] ValueLayout.JAVA_FLOAT.byteAlignment()

long[] ValueLayout.JAVA_LONG.byteAlignment()

double[] ValueLayout.JAVA_DOUBLE.byteAlignment()

Максимальное выравнивание сегментов кучи
Тип массива (базовой области)	Максимальное поддерживаемое выравнивание (в байтах)
`boolean[]`	`ValueLayout.JAVA_BOOLEAN.byteAlignment()`
`byte[]`	`ValueLayout.JAVA_BYTE.byteAlignment()`
`char[]`	`ValueLayout.JAVA_CHAR.byteAlignment()`
`short[]`	`ValueLayout.JAVA_SHORT.byteAlignment()`
`int[]`	`ValueLayout.JAVA_INT.byteAlignment()`
`float[]`	`ValueLayout.JAVA_FLOAT.byteAlignment()`
`long[]`	`ValueLayout.JAVA_LONG.byteAlignment()`
`double[]`	`ValueLayout.JAVA_DOUBLE.byteAlignment()`

Доступ к сегментам кучи возможен только с помощью компоновки, выравнивание которой меньше или равно максимальному выравниванию, связанному с сегментом кучи. Попытка обратиться к сегменту кучи с помощью компоновки, выравнивание которой превышает максимальное выравнивание, связанное с сегментом кучи, завершится ошибкой, как показано в следующем примере:

MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
byteSegment.get(ValueLayout.JAVA_INT, 0); // fails: ValueLayout.JAVA_INT.byteAlignment() > ValueLayout.JAVA_BYTE.byteAlignment()

В такой ситуации у клиентов есть два варианта. Они могут использовать сегмент кучи, основанный на массиве другого типа (например, long[]), который поддерживает большее максимальное выравнивание. В частности, максимальное выравнивание, связанное с long[], равно ValueLayout.JAVA_LONG.byteAlignment(), то есть 8 байтам:

MemorySegment longSegment = MemorySegment.ofArray(new long[10]);
longSegment.get(ValueLayout.JAVA_INT, 0); // ok: ValueLayout.JAVA_INT.byteAlignment() <= ValueLayout.JAVA_LONG.byteAlignment()

Кроме того, они могут вызвать операцию доступа с невыровненной компоновкой. Для всех констант невыровненных компоновок (например, ValueLayout.JAVA_INT_UNALIGNED) ограничение на выравнивание установлено в 1:

MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
byteSegment.get(ValueLayout.JAVA_INT_UNALIGNED, 0); // ok: ValueLayout.JAVA_INT_UNALIGNED.byteAlignment() == ValueLayout.JAVA_BYTE.byteAlignment()

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

MemoryLayout layout = ...
MemorySegment segment = ...
boolean isAligned = segment.maxByteAlignment() >= layout.byteAlignment();

Сегменты памяти нулевой длины

При взаимодействии с внешними функциями часто такие функции выделяют область памяти и возвращают указатель на нее. Представление этой области памяти в виде сегмента памяти затруднительно, поскольку среда выполнения Java не располагает сведениями о ее размере. Доступен только адрес начала области, хранящийся в указателе. Например, функция C с возвращаемым типом char* может возвращать указатель на область, содержащую одно значение char, либо на область с массивом значений char, размер которого может передаваться в отдельном параметре. Код, вызывающий внешнюю функцию и желающий использовать ее результат, не может легко определить размер массива. Кроме того, он не знает, каков срок жизни области памяти, на которую указывает указатель, возвращенный внешней функцией, выделившей эту область.

API MemorySegment использует сегменты памяти нулевой длины для представления:

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

Адрес сегмента нулевой длины — это адрес, хранящийся в указателе. Пространственные и временные границы сегмента нулевой длины таковы:

Размер сегмента равен нулю. Любая попытка обратиться к таким сегментам завершится исключением IndexOutOfBoundsException. Это важная функция безопасности: поскольку такие сегменты связаны с областью памяти неизвестного размера, любые операции доступа с их участием невозможно проверить. По сути, сегмент памяти нулевой длины оборачивает адрес и не может использоваться без явного намерения (см. ниже);
Сегмент связан с глобальной областью действия. Поэтому, хотя к сегментам памяти нулевой длины нельзя обращаться напрямую, их можно передавать в непрозрачном виде другим внешним функциям, принимающим указатели.

Чтобы показать, как клиенты могут работать с сегментами памяти нулевой длины, рассмотрим случай, когда клиент хочет считать указатель из некоторого сегмента памяти. Это можно сделать с помощью метода доступа get(AddressLayout, long). Этот метод принимает компоновку адреса (например, ValueLayout.ADDRESS) — компоновку считываемого указателя. Например, на 64-разрядной платформе размер компоновки адреса составляет 8 байт. Операция доступа также принимает смещение, выраженное в байтах, которое указывает позицию (относительно начала сегмента памяти), в которой хранится указатель. Операция доступа возвращает нативный сегмент памяти нулевой длины, основанный на области памяти, начальный адрес которой является 64-разрядным значением, считанным по заданному смещению.

Клиент не может обращаться к возвращенному сегменту памяти нулевой длины напрямую: поскольку размер сегмента равен нулю, любая операция доступа приведет к выходу за границы. Вместо этого клиент должен небезопасно назначить сегменту памяти нулевой длины новые пространственные границы. Это можно сделать с помощью метода reinterpret(long)^RESTRICTED следующим образом:

 MemorySegment z = segment.get(ValueLayout.ADDRESS, ...);   // size = 0
 MemorySegment ptr = z.reinterpret(16);                     // size = 16
 int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);           // ok

В некоторых случаях клиенту может также потребоваться назначить сегменту памяти нулевой длины новые временные границы. Это можно сделать с помощью метода reinterpret(long, Arena, Consumer)^RESTRICTED, который возвращает новый нативный сегмент с требуемым размером и теми же временными границами, что и у заданной арены:

 MemorySegment ptr = null;
 try (Arena arena = Arena.ofConfined()) {
       MemorySegment z = segment.get(ValueLayout.ADDRESS, ...);    // size = 0, scope = always alive
       ptr = z.reinterpret(16, arena, null);                       // size = 16, scope = arena.scope()
       int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);            // ok
 }
 int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);                  // throws IllegalStateException

Если размер области памяти, на которой основан сегмент памяти нулевой длины, известен заранее, клиент может наложить целевую компоновку^RESTRICTED на компоновку адреса, используемую при считывании указателя. Затем целевая компоновка используется для динамического расширения размера нативного сегмента памяти, возвращаемого операцией доступа, до размера целевой компоновки. Иными словами, возвращаемый сегмент уже не является сегментом памяти нулевой длины, и указатель, который он представляет, можно разыменовать напрямую:

 AddressLayout intArrPtrLayout = ValueLayout.ADDRESS.withTargetLayout(
         MemoryLayout.sequenceLayout(4, ValueLayout.JAVA_INT)); // layout for int (*ptr)[4]
 MemorySegment ptr = segment.get(intArrPtrLayout, ...);         // size = 16
 int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);               // ok

Все методы для работы с сегментами памяти нулевой длины (reinterpret(long)^RESTRICTED, reinterpret(Arena, Consumer)^RESTRICTED, reinterpret(long, Arena, Consumer)^RESTRICTED и AddressLayout.withTargetLayout(MemoryLayout)^RESTRICTED) являются ограниченными методами, и использовать их следует с осторожностью: назначение сегменту неверных пространственных и/или временных границ может привести к аварийному завершению виртуальной машины при попытке обратиться к сегменту памяти.

Требования к реализации:: Реализации этого интерфейса неизменяемы, потокобезопасны и основаны на значениях.
Начиная с:: 22

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

Модификатор и тип	Интерфейс	Описание
`static interface`	`MemorySegment.Scope`	Область действия моделирует время жизни всех связанных с ней сегментов памяти.

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

Модификатор и тип	Поле	Описание
`static final MemorySegment`	`NULL`	Нативный сегмент нулевой длины, моделирующий адрес `NULL`.

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

Модификатор и тип	Метод	Описание
`long`	`address()`	Возвращает адрес этого сегмента памяти.
`ByteBuffer`	`asByteBuffer()`	Оборачивает этот сегмент в `ByteBuffer`.
`Optional<MemorySegment>`	`asOverlappingSlice(MemorySegment other)`	Возвращает срез этого сегмента, представляющий область пересечения этого сегмента с указанным сегментом.
`MemorySegment`	`asReadOnly()`	Возвращает доступное только для чтения представление этого сегмента.
`MemorySegment`	`asSlice(long offset)`	Возвращает срез этого сегмента памяти, начинающийся с указанного смещения.
`MemorySegment`	`asSlice(long offset, long newSize)`	Возвращает срез этого сегмента памяти, начинающийся с указанного смещения.
`MemorySegment`	`asSlice(long offset, long newSize, long byteAlignment)`	Возвращает срез этого сегмента памяти, начинающийся с указанного смещения и удовлетворяющий заданному ограничению на выравнивание.
`MemorySegment`	`asSlice(long offset, MemoryLayout layout)`	Возвращает срез этого сегмента памяти с заданной раскладкой, начинающийся с указанного смещения.
`long`	`byteSize()`	Возвращает размер этого сегмента памяти в байтах.
`static void`	`copy(MemorySegment srcSegment, long srcOffset, MemorySegment dstSegment, long dstOffset, long bytes)`	Выполняет массовое копирование из исходного сегмента в целевой сегмент.
`static void`	`copy(MemorySegment srcSegment, ValueLayout srcElementLayout, long srcOffset, MemorySegment dstSegment, ValueLayout dstElementLayout, long dstOffset, long elementCount)`	Выполняет массовое копирование из исходного сегмента в целевой сегмент.
`static void`	`copy(MemorySegment srcSegment, ValueLayout srcLayout, long srcOffset, Object dstArray, int dstIndex, int elementCount)`	Копирует заданное количество элементов из исходного сегмента памяти в целевой массив.
`static void`	`copy(Object srcArray, int srcIndex, MemorySegment dstSegment, ValueLayout dstLayout, long dstOffset, int elementCount)`	Копирует заданное количество элементов из исходного массива в целевой сегмент памяти.
`MemorySegment`	`copyFrom(MemorySegment src)`	Выполняет массовое копирование из указанного исходного сегмента в этот сегмент.
`Stream<MemorySegment>`	`elements(MemoryLayout elementLayout)`	Возвращает последовательный `Stream` по непересекающимся срезам этого сегмента, размер которых соответствует размеру указанной раскладки.
`boolean`	`equals(Object that)`	Сравнивает указанный объект с этим сегментом памяти на равенство.
`MemorySegment`	`fill(byte value)`	Заполняет содержимое этого сегмента памяти указанным значением.
`void`	`force()`	Принудительно записывает все изменения содержимого этого отображённого сегмента на устройство хранения, указанное дескриптором файла сегмента.
`MemorySegment`	`get(AddressLayout layout, long offset)`	Читает адрес из этого сегмента по указанному смещению с использованием заданной раскладки.
`boolean`	`get(ValueLayout.OfBoolean layout, long offset)`	Читает логическое значение из этого сегмента по указанному смещению с использованием заданной раскладки.
`byte`	`get(ValueLayout.OfByte layout, long offset)`	Читает байт из этого сегмента по указанному смещению с использованием заданной раскладки.
`char`	`get(ValueLayout.OfChar layout, long offset)`	Читает символ из этого сегмента по указанному смещению с использованием заданной раскладки.
`double`	`get(ValueLayout.OfDouble layout, long offset)`	Читает значение типа double из этого сегмента по указанному смещению с использованием заданной раскладки.
`float`	`get(ValueLayout.OfFloat layout, long offset)`	Читает значение типа float из этого сегмента по указанному смещению с использованием заданной раскладки.
`int`	`get(ValueLayout.OfInt layout, long offset)`	Читает значение типа int из этого сегмента по указанному смещению с использованием заданной раскладки.
`long`	`get(ValueLayout.OfLong layout, long offset)`	Читает значение типа long из этого сегмента по указанному смещению с использованием заданной раскладки.
`short`	`get(ValueLayout.OfShort layout, long offset)`	Читает значение типа short из этого сегмента по указанному смещению с использованием заданной раскладки.
`MemorySegment`	`getAtIndex(AddressLayout layout, long index)`	Читает адрес из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`boolean`	`getAtIndex(ValueLayout.OfBoolean layout, long index)`	Читает логическое значение из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`byte`	`getAtIndex(ValueLayout.OfByte layout, long index)`	Читает байт из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`char`	`getAtIndex(ValueLayout.OfChar layout, long index)`	Читает символ из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`double`	`getAtIndex(ValueLayout.OfDouble layout, long index)`	Читает значение типа double из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`float`	`getAtIndex(ValueLayout.OfFloat layout, long index)`	Читает значение типа float из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`int`	`getAtIndex(ValueLayout.OfInt layout, long index)`	Читает значение типа int из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`long`	`getAtIndex(ValueLayout.OfLong layout, long index)`	Читает значение типа long из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`short`	`getAtIndex(ValueLayout.OfShort layout, long index)`	Читает значение типа short из этого сегмента по указанному индексу, масштабированному на размер заданной раскладки.
`String`	`getString(long offset)`	Читает из этого сегмента строку с нулевым символом-терминатором по указанному смещению, используя кодировку UTF-8.
`String`	`getString(long offset, Charset charset)`	Читает из этого сегмента строку с нулевым символом-терминатором по указанному смещению, используя заданную кодировку.
`int`	`hashCode()`	Возвращает хеш-код этого сегмента памяти.
`Optional<Object>`	`heapBase()`	Возвращает объект Java, хранящийся в области памяти в куче, на которой основан этот сегмент памяти, если такой объект есть.
`boolean`	`isAccessibleBy(Thread thread)`	Возвращает `true`, если указанный поток может обращаться к этому сегменту.
`boolean`	`isLoaded()`	Определяет, находится ли всё содержимое этого отображённого сегмента в физической памяти.
`boolean`	`isMapped()`	Возвращает `true`, если этот сегмент является отображённым сегментом.
`boolean`	`isNative()`	Возвращает `true`, если этот сегмент является нативным сегментом.
`boolean`	`isReadOnly()`	Возвращает `true`, если этот сегмент доступен только для чтения.
`void`	`load()`	Загружает содержимое этого отображённого сегмента в физическую память.
`long`	`maxByteAlignment()`	Возвращает максимальное выравнивание в байтах, связанное с этим сегментом памяти.
`long`	`mismatch(MemorySegment other)`	Находит и возвращает смещение в байтах первого несовпадения между этим сегментом и указанным другим сегментом.
`static long`	`mismatch(MemorySegment srcSegment, long srcFromOffset, long srcToOffset, MemorySegment dstSegment, long dstFromOffset, long dstToOffset)`	Находит и возвращает относительное смещение в байтах первого несовпадения между исходным и целевым сегментами.
`static MemorySegment`	`ofAddress(long address)`	Создаёт нативный сегмент нулевой длины из указанного значения адреса.
`static MemorySegment`	`ofArray(byte[] byteArray)`	Создаёт сегмент в куче, основанный на области памяти в куче, в которой хранится указанный массив байтов.
`static MemorySegment`	`ofArray(char[] charArray)`	Создаёт сегмент в куче, основанный на области памяти в куче, в которой хранится указанный массив символов.
`static MemorySegment`	`ofArray(double[] doubleArray)`	Создаёт сегмент в куче, основанный на области памяти в куче, в которой хранится указанный массив значений double.
`static MemorySegment`	`ofArray(float[] floatArray)`	Создаёт сегмент в куче, основанный на области памяти в куче, в которой хранится указанный массив значений float.
`static MemorySegment`	`ofArray(int[] intArray)`	Создаёт сегмент в куче, основанный на области памяти в куче, в которой хранится указанный массив значений int.
`static MemorySegment`	`ofArray(long[] longArray)`	Создаёт сегмент в куче, основанный на области памяти в куче, в которой хранится указанный массив значений long.
`static MemorySegment`	`ofArray(short[] shortArray)`	Создаёт сегмент в куче, основанный на области памяти в куче, в которой хранится указанный массив значений short.
`static MemorySegment`	`ofBuffer(Buffer buffer)`	Создаёт сегмент памяти, основанный на той же области памяти, что и указанный экземпляр `Buffer`.
`MemorySegment`	`reinterpret(long newSize)`	Ограниченный. Возвращает новый сегмент памяти с теми же адресом и областью действия, что и у этого сегмента, но с указанным размером.
`MemorySegment`	`reinterpret(long newSize, Arena arena, Consumer<MemorySegment> cleanup)`	Ограниченный. Возвращает новый сегмент с тем же адресом, что и у этого сегмента, но с указанным размером и областью действия указанной арены.
`MemorySegment`	`reinterpret(Arena arena, Consumer<MemorySegment> cleanup)`	Ограниченный. Возвращает новый сегмент памяти с теми же адресом и размером, что и у этого сегмента, но с областью действия указанной арены.
`MemorySegment.Scope`	`scope()`	Возвращает область действия, связанную с этим сегментом памяти.
`void`	`set(AddressLayout layout, long offset, MemorySegment value)`	Записывает адрес в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfBoolean layout, long offset, boolean value)`	Записывает логическое значение в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfByte layout, long offset, byte value)`	Записывает байт в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfChar layout, long offset, char value)`	Записывает символ в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfDouble layout, long offset, double value)`	Записывает значение типа double в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfFloat layout, long offset, float value)`	Записывает значение типа float в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfInt layout, long offset, int value)`	Записывает значение типа int в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfLong layout, long offset, long value)`	Записывает значение типа long в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`set(ValueLayout.OfShort layout, long offset, short value)`	Записывает значение типа short в этот сегмент по указанному смещению с использованием заданной раскладки.
`void`	`setAtIndex(AddressLayout layout, long index, MemorySegment value)`	Записывает адрес в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfBoolean layout, long index, boolean value)`	Записывает логическое значение в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfByte layout, long index, byte value)`	Записывает байт в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfChar layout, long index, char value)`	Записывает символ в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfDouble layout, long index, double value)`	Записывает значение типа double в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfFloat layout, long index, float value)`	Записывает значение типа float в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfInt layout, long index, int value)`	Записывает значение типа int в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfLong layout, long index, long value)`	Записывает значение типа long в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setAtIndex(ValueLayout.OfShort layout, long index, short value)`	Записывает значение типа short в этот сегмент по указанному индексу, масштабированному на размер заданной раскладки.
`void`	`setString(long offset, String str)`	Записывает указанную строку в этот сегмент по заданному смещению, преобразуя её в последовательность байтов с нулевым символом-терминатором с использованием кодировки UTF-8.
`void`	`setString(long offset, String str, Charset charset)`	Записывает указанную строку в этот сегмент по заданному смещению, преобразуя её в последовательность байтов с нулевым символом-терминатором с использованием заданной кодировки.
`Spliterator<MemorySegment>`	`spliterator(MemoryLayout elementLayout)`	Возвращает сплитератор для этого сегмента памяти.
`byte[]`	`toArray(ValueLayout.OfByte elementLayout)`	Копирует содержимое этого сегмента памяти в новый массив байтов.
`char[]`	`toArray(ValueLayout.OfChar elementLayout)`	Копирует содержимое этого сегмента памяти в новый массив символов.
`double[]`	`toArray(ValueLayout.OfDouble elementLayout)`	Копирует содержимое этого сегмента памяти в новый массив значений double.
`float[]`	`toArray(ValueLayout.OfFloat elementLayout)`	Копирует содержимое этого сегмента памяти в новый массив значений float.
`int[]`	`toArray(ValueLayout.OfInt elementLayout)`	Копирует содержимое этого сегмента памяти в новый массив значений int.
`long[]`	`toArray(ValueLayout.OfLong elementLayout)`	Копирует содержимое этого сегмента памяти в новый массив значений long.
`short[]`	`toArray(ValueLayout.OfShort elementLayout)`	Копирует содержимое этого сегмента памяти в новый массив значений short.
`void`	`unload()`	Выгружает содержимое этого отображённого сегмента из физической памяти.

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

NULL

static final MemorySegment NULL

Нативный сегмент нулевой длины, моделирующий адрес NULL. Эквивалентен MemorySegment.ofAddress(0L).

Максимальное выравнивание по байтам для сегмента NULL составляет 2⁶².

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

address

long address()

Возвращает адрес этого сегмента памяти.

Примечание к API:: При использовании этого метода для передачи адреса сегмента во внешнюю операцию (например, функцию JNI) клиенты должны убедиться, что сегмент остается достижимым в течение всего времени выполнения операции. Если этого не сделать, область памяти, на которой основан сегмент памяти, может быть освобождена преждевременно, если сегмент был выделен с помощью автоматической арены.
Возвращает:: адрес этого сегмента памяти

heapBase

Optional<Object> heapBase()

Возвращает объект Java, хранящийся в области памяти в куче, на которой основан этот сегмент памяти, если такой объект есть. Например, если этот сегмент памяти является сегментом кучи, созданным фабричным методом ofArray(byte[]), этот метод вернет объект byte[], который использовался для получения сегмента. Этот метод возвращает пустое значение Optional, если этот сегмент является нативным или доступен только для чтения.

Возвращает:: объект Java, связанный с этим сегментом памяти, если таковой имеется

spliterator

Spliterator<MemorySegment> spliterator(MemoryLayout elementLayout)

Возвращает сплитератор для этого сегмента памяти. Возвращаемый сплитератор имеет характеристики Spliterator.SIZED, Spliterator.SUBSIZED, Spliterator.IMMUTABLE, Spliterator.NONNULL и Spliterator.ORDERED.

Возвращаемый сплитератор разделяет этот сегмент в соответствии с заданной раскладкой элементов; то есть, если размер предоставленной раскладки равен N, вызов Spliterator.trySplit() приведет к созданию сплитератора, обрабатывающего приблизительно S/N элементов (в зависимости от того, является ли N четным), где S — размер этого сегмента. Таким образом, разделение возможно, пока выполняется условие S/N >= 2. Сплитератор возвращает сегменты с таким же временем жизни, как у этого сегмента.

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

Параметры:: elementLayout — раскладка, используемая для разделения
Возвращает:: сплитератор элементов для этого сегмента
Вызывает исключение:: IllegalArgumentException — если elementLayout.byteSize() == 0; IllegalArgumentException — если byteSize() % elementLayout.byteSize() != 0; IllegalArgumentException — если elementLayout.byteSize() % elementLayout.byteAlignment() != 0; IllegalArgumentException — если этот сегмент несовместим с ограничением выравнивания, заданным в предоставленной раскладке.

elements

Stream<MemorySegment> elements(MemoryLayout elementLayout)

Возвращает последовательный Stream по непересекающимся срезам (размер которых совпадает с размером заданной раскладки) этого сегмента. Вызов этого метода эквивалентен следующему коду:

StreamSupport.stream(segment.spliterator(elementLayout), false);

Параметры:: elementLayout — раскладка, используемая для разделения
Возвращает:: последовательный Stream по непересекающимся срезам этого сегмента
Вызывает исключение:: IllegalArgumentException — если elementLayout.byteSize() == 0; IllegalArgumentException — если byteSize() % elementLayout.byteSize() != 0; IllegalArgumentException — если elementLayout.byteSize() % elementLayout.byteAlignment() != 0; IllegalArgumentException — если этот сегмент несовместим с ограничением выравнивания, заданным в предоставленной раскладке

scope

MemorySegment.Scope scope()

Возвращает область действия, связанную с этим сегментом памяти.

Возвращает:: область действия, связанную с этим сегментом памяти

isAccessibleBy

boolean isAccessibleBy(Thread thread)

Возвращает true, если к этому сегменту можно получить доступ из указанного потока.

Параметры:: thread — проверяемый поток
Возвращает:: true, если к этому сегменту можно получить доступ из указанного потока

byteSize

long byteSize()

Возвращает размер этого сегмента памяти (в байтах).

Возвращает:: размер этого сегмента памяти (в байтах)

maxByteAlignment

long maxByteAlignment()

Возвращает максимальное выравнивание по байтам, связанное с этим сегментом памяти.

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

Этот метод можно использовать, чтобы убедиться, что сегмент достаточно выровнен относительно раскладки:

MemoryLayout layout = ...
MemorySegment segment = ...
if (segment.maxByteAlignment() < layout.byteAlignment()) {
    // Take action (e.g. throw an Exception)
}

Возвращает:: максимальное выравнивание по байтам, связанное с этим сегментом памяти
Начиная с версии:: 23

asSlice

MemorySegment asSlice(long offset, long newSize)

Возвращает срез этого сегмента памяти со смещением, заданным аргументом. Адрес возвращаемого сегмента равен адресу этого сегмента плюс заданное смещение; его размер задается аргументом.

Эквивалентно следующему коду:

asSlice(offset, newSize, 1);

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

Возвращаемый сегмент памяти использует ту же область базовой памяти, что и этот сегмент. Следовательно, этот метод не выделяет и не освобождает память.

Параметры:

offset — смещение начала нового сегмента относительно адреса этого сегмента, в байтах

newSize — размер нового сегмента, в байтах

Возвращает:

срез этого сегмента памяти

Вызывает исключение:

IndexOutOfBoundsException — если offset < 0, offset > byteSize(), newSize < 0 или newSize > byteSize() - offset

См. также:

asSlice

MemorySegment asSlice(long offset, long newSize, long byteAlignment)

Возвращает срез этого сегмента памяти со смещением, заданным аргументом, и указанным ограничением выравнивания. Адрес возвращаемого сегмента равен адресу этого сегмента плюс заданное смещение; его размер задается аргументом.

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

Параметры:: offset — смещение начала нового сегмента относительно адреса этого сегмента, в байтах; newSize — размер нового сегмента, в байтах; byteAlignment — ограничение выравнивания возвращаемого среза (в байтах)
Возвращает:: срез этого сегмента памяти
Вызывает исключение:: IndexOutOfBoundsException — если offset < 0, offset > byteSize(), newSize < 0 или newSize > byteSize() - offset; IllegalArgumentException — если к этому сегменту нельзя получить доступ по адресу offset с указанным ограничением выравнивания; IllegalArgumentException — если byteAlignment <= 0 или если byteAlignment не является степенью двойки

asSlice

MemorySegment asSlice(long offset, MemoryLayout layout)

Возвращает срез этого сегмента памяти с заданной раскладкой и смещением. Адрес возвращаемого сегмента равен адресу этого сегмента плюс заданное смещение; его размер совпадает с размером предоставленной раскладки.

Эквивалентно следующему коду:

asSlice(offset, layout.byteSize(), layout.byteAlignment());

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

Параметры:

offset — смещение начала нового сегмента относительно адреса этого сегмента, в байтах

layout — раскладка среза сегмента

Возвращает:

срез этого сегмента памяти

Вызывает исключение:

IndexOutOfBoundsException — если offset < 0, offset > byteSize() или layout.byteSize() > byteSize() - offset

IllegalArgumentException — если к этому сегменту нельзя получить доступ по адресу offset с ограничением выравнивания, заданным layout

См. также:

asSlice

MemorySegment asSlice(long offset)

Возвращает срез этого сегмента памяти со смещением, заданным аргументом. Адрес возвращаемого сегмента равен адресу этого сегмента плюс заданное смещение; его размер вычисляется вычитанием указанного смещения из размера этого сегмента.

Эквивалентно следующему коду:

asSlice(offset, byteSize() - offset);

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

Параметры:

offset — смещение начала нового сегмента относительно адреса этого сегмента, в байтах

Возвращает:

срез этого сегмента памяти

Вызывает исключение:

IndexOutOfBoundsException — если offset < 0 или offset > byteSize()

См. также:

reinterpret

MemorySegment reinterpret(long newSize)

reinterpret — это ограниченный метод платформы Java.

Программы могут использовать reinterpret только при включенном доступе к ограниченным методам.

Ограниченные методы небезопасны и при неправильном использовании могут привести к сбою JVM или повреждению памяти.

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

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

Параметры:: newSize — размер возвращаемого сегмента
Возвращает:: новый сегмент памяти с тем же адресом и областью действия, что и у этого сегмента, но с указанным новым размером
Вызывает исключение:: IllegalArgumentException — если newSize < 0; UnsupportedOperationException — если этот сегмент не является нативным; IllegalCallerException — если вызывающий код находится в модуле, для которого не включен доступ к нативному коду

reinterpret

MemorySegment reinterpret(Arena arena, Consumer<MemorySegment> cleanup)

reinterpret — это ограниченный метод платформы Java.

Программы могут использовать reinterpret только при включенном доступе к ограниченным методам.

Возвращает новый сегмент памяти с теми же адресом и размером, что и у этого сегмента, но с областью действия предоставленной арены. Поэтому к возвращаемому сегменту нельзя получить доступ после закрытия предоставленной арены. Кроме того, к возвращаемому сегменту можно обращаться с учетом ограничений доступа, связанных с предоставленной ареной: то есть, если предоставленная арена является ареной с ограниченным доступом, к возвращаемому сегменту может обращаться только поток-владелец арены, независимо от ограничений доступа, связанных с этим сегментом. Иными словами, этот метод возвращает сегмент, который можно использовать как любой другой сегмент, выделенный с помощью предоставленной арены. Однако возвращаемый сегмент использует ту же область памяти, что и исходный сегмент. Поэтому область памяти, на которой основан возвращаемый сегмент, освобождается только при закрытии арены этого сегмента. Это может привести к проблемам типа use-after-free, поскольку к возвращаемому сегменту можно обращаться после освобождения области памяти через арену этого сегмента.

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

MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
                                            .reinterpret(byteSize());

Иными словами, действие очистки получает сегмент, связанный с областью действия глобальной арены и доступный из любого потока. Размер сегмента, принимаемого действием очистки, равен byteSize().

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

Примечание к API:: Действие очистки (если оно задано) не должно передавать полученный сегмент внешним клиентам, которые могут обратиться к нему после того, как его базовая область памяти станет недоступной. Кроме того, если предоставленная арена является автоматической ареной, действие очистки не должно препятствовать тому, чтобы арена стала недостижимой. В противном случае области памяти, выделенные автоматической ареной, никогда не будут освобождены.
Параметры:: arena — арена, с которой будет связан возвращаемый сегмент; cleanup — действие очистки, выполняемое при закрытии предоставленной арены (может быть null)
Возвращает:: новый сегмент памяти с неограниченным размером
Вызывает исключение:: IllegalStateException — если arena.scope().isAlive() == false; UnsupportedOperationException — если этот сегмент не является нативным; IllegalCallerException — если вызывающий код находится в модуле, для которого не включен доступ к нативному коду

reinterpret

MemorySegment reinterpret(long newSize, Arena arena, Consumer<MemorySegment> cleanup)

reinterpret — это ограниченный метод платформы Java.

Программы могут использовать reinterpret только при включенном доступе к ограниченным методам.

Возвращает новый сегмент с тем же адресом, что и у этого сегмента, но с заданными размером и областью действия предоставленной арены. Поэтому к возвращаемому сегменту нельзя получить доступ после закрытия предоставленной арены. Кроме того, к возвращаемому сегменту можно обращаться с учетом ограничений доступа, связанных с предоставленной ареной: то есть, если предоставленная арена является ареной с ограниченным доступом, к возвращаемому сегменту может обращаться только поток-владелец арены, независимо от ограничений доступа, связанных с этим сегментом. Иными словами, этот метод возвращает сегмент, который можно использовать как любой другой сегмент, выделенный с помощью предоставленной арены. Однако возвращаемый сегмент использует ту же область памяти, что и исходный сегмент. Поэтому область памяти, на которой основан возвращаемый сегмент, освобождается только при закрытии арены этого сегмента. Это может привести к проблемам типа use-after-free, поскольку к возвращаемому сегменту можно обращаться после освобождения области памяти через арену этого сегмента.

MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
                                            .reinterpret(newSize);

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

Примечание к API:: Действие очистки (если оно задано) не должно передавать полученный сегмент внешним клиентам, которые могут обратиться к нему после того, как его базовая область памяти станет недоступной. Кроме того, если предоставленная арена является автоматической ареной, действие очистки не должно препятствовать тому, чтобы арена стала недостижимой. В противном случае области памяти, выделенные автоматической ареной, никогда не будут освобождены.
Параметры:: newSize — размер возвращаемого сегмента; arena — арена, с которой будет связан возвращаемый сегмент; cleanup — действие очистки, выполняемое при закрытии предоставленной арены (может быть null).
Возвращает:: новый сегмент с тем же адресом, что и у этого сегмента, но с новым размером и областью действия предоставленной арены.
Вызывает исключение:: UnsupportedOperationException — если этот сегмент не является нативным; IllegalArgumentException — если newSize < 0; IllegalStateException — если arena.scope().isAlive() == false; IllegalCallerException — если вызывающий код находится в модуле, для которого не включен доступ к нативному коду

isReadOnly

boolean isReadOnly()

Возвращает true, если этот сегмент доступен только для чтения.

Возвращает:

true, если этот сегмент доступен только для чтения

См. также:

asReadOnly

MemorySegment asReadOnly()

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

Возвращает:

представление этого сегмента только для чтения

См. также:

isNative

boolean isNative()

Возвращает true, если этот сегмент является нативным.

Нативный сегмент можно создать, например, с помощью фабричного метода Arena.allocate(long, long) (и связанных методов) или обернув прямой буфер.

Возвращает:: true, если этот сегмент является нативным

isMapped

boolean isMapped()

Возвращает true, если этот сегмент является отображенным сегментом. Отображенный сегмент памяти можно создать, например, с помощью фабричного метода FileChannel.map(FileChannel.MapMode, long, long, Arena) или обернув отображенный байтовый буфер.

Возвращает:: true, если этот сегмент является отображенным сегментом

asOverlappingSlice

Optional<MemorySegment> asOverlappingSlice(MemorySegment other)

Возвращает срез этого сегмента, представляющий собой область пересечения этого сегмента с предоставленным сегментом.

Сегменты S1 и S2 считаются пересекающимися, если можно найти по крайней мере два среза L1 (из S1) и L2 (из S2), использующие одну и ту же область памяти. Поэтому нативный сегмент не может пересекаться с сегментом кучи; в этом случае, а также при отсутствии пересечения, возвращается пустое значение Optional.

Параметры:: other — сегмент, с которым проверяется пересечение этого сегмента
Возвращает:: срез этого сегмента (в области пересечения)

fill

MemorySegment fill(byte value)

Заполняет содержимое этого сегмента памяти заданным значением.

В частности, заданное значение записывается по каждому адресу этого сегмента. Эквивалентно (но, вероятно, менее эффективно) следующему коду:

for (long offset = 0; offset < segment.byteSize(); offset++) {
    segment.set(ValueLayout.JAVA_BYTE, offset, value);
}

При этом порядок установки отдельных элементов памяти не учитывается и не гарантируется.

Этот метод может пригодиться для инициализации или сброса содержимого сегмента памяти.

Параметры:: value — значение, записываемое в этот сегмент
Возвращает:: этот сегмент памяти
Вызывает исключение:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если этот сегмент доступен только для чтения

copyFrom

MemorySegment copyFrom(MemorySegment src)

Выполняет массовое копирование из заданного исходного сегмента в этот сегмент. В частности, байты с позиции 0 по src.byteSize() - 1 в исходном сегменте копируются в этот сегмент с позиции 0 по src.byteSize() - 1.

Вызов этого метода эквивалентен следующему коду:

MemorySegment.copy(src, 0, this, 0, src.byteSize());

Параметры:: src — исходный сегмент
Возвращает:: этот сегмент
Вызывает исключение:: IndexOutOfBoundsException — если src.byteSize() > this.byteSize(); IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если связанная с src область действия не активна; WrongThreadException — если этот метод вызван из потока T, так что src.isAccessibleBy(T) == false; IllegalArgumentException — если этот сегмент доступен только для чтения

mismatch

long mismatch(MemorySegment other)

Находит и возвращает смещение (в байтах) первого несовпадения между этим сегментом и заданным другим сегментом. Смещение отсчитывается относительно адреса каждого сегмента и находится в диапазоне от 0 (включительно) до размера (в байтах) меньшего сегмента памяти (не включая его).

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

Параметры:: other — сегмент, в котором ищется несовпадение с этим сегментом
Возвращает:: относительное смещение (в байтах) первого несовпадения между этим и заданным сегментом; если несовпадений нет, возвращает -1
Вызывает исключение:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если связанная с other область действия не активна; WrongThreadException — если этот метод вызван из потока T, так что other.isAccessibleBy(T) == false

isLoaded

boolean isLoaded()

Определяет, находятся ли все содержимое этого отображенного сегмента в физической памяти.

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

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

Возвращает:: true, если содержимое этого сегмента, вероятно, находится в физической памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; UnsupportedOperationException — если этот сегмент не является отображенным сегментом памяти, например если isMapped() == false

load

void load()

Загружает содержимое этого отображенного сегмента в физическую память.

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

Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; UnsupportedOperationException — если этот сегмент не является отображенным сегментом памяти, например если isMapped() == false

unload

void unload()

Выгружает содержимое этого отображенного сегмента из физической памяти.

Этот метод прилагает все усилия, чтобы содержимое этого сегмента больше не находилось в физической памяти. Доступ к содержимому этого сегмента после вызова метода может привести к возникновению некоторого количества ошибок страниц и операций ввода-вывода (поскольку содержимое сегмента, возможно, потребуется снова загрузить в память).

Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; UnsupportedOperationException — если этот сегмент не является отображенным сегментом памяти, например если isMapped() == false

force

void force()

Принудительно записывает все изменения, внесенные в содержимое этого отображенного сегмента, на устройство хранения, описываемое дескриптором файла сегмента.

Если дескриптор файла, связанный с этим отображенным сегментом, находится на локальном устройстве хранения, то к моменту возврата этого метода гарантируется, что все изменения, внесенные в этот сегмент с момента его создания или последнего вызова этого метода, будут записаны на это устройство.

Если дескриптор файла, связанный с этим отображенным сегментом, находится не на локальном устройстве, такая гарантия не предоставляется.

Если этот сегмент был отображен не в режиме чтения/записи (FileChannel.MapMode.READ_WRITE), вызов этого метода может не дать никакого эффекта. В частности, метод не влияет на сегменты, отображенные в режимах только для чтения или приватного отображения. Для режимов отображения, зависящих от реализации, этот метод может иметь или не иметь эффект.

Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; UnsupportedOperationException — если этот сегмент не является отображенным сегментом памяти, например если isMapped() == false; UncheckedIOException — если при записи содержимого этого сегмента на связанное устройство хранения произошла ошибка ввода-вывода

asByteBuffer

ByteBuffer asByteBuffer()

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

Он является буфером только для чтения, если этот сегмент является сегментом только для чтения;
Его позиция установлена в ноль;
Его емкость и предел установлены в значение размера этого сегмента. По этой причине нельзя вернуть байтовый буфер, если размер этого сегмента превышает Integer.MAX_VALUE;
Он является прямым буфером, если этот сегмент является нативным.

Жизненный цикл возвращенного буфера связан с жизненным циклом этого сегмента. То есть при обращении к возвращенному буферу после того, как связанная с этим сегментом область действия перестает быть активной, будет выброшено исключение IllegalStateException. Аналогично, обращение к возвращенному буферу из потока T, так что isAccessible(T) == false, приведет к выбросу исключения WrongThreadException.

Если этот сегмент доступен только из одного потока, вызов операций ввода-вывода чтения/записи для полученного буфера может привести к выбросу исключений, не специфицированных явно. Примерами таких проблемных операций являются AsynchronousSocketChannel.read(ByteBuffer) и AsynchronousSocketChannel.write(ByteBuffer).

Наконец, порядок байтов полученного буфера — ByteOrder.BIG_ENDIAN; его можно изменить с помощью ByteBuffer.order(java.nio.ByteOrder).

Возвращает:: представление этого сегмента памяти в виде ByteBuffer
Вызывает исключения:: UnsupportedOperationException — если этот сегмент нельзя отобразить на экземпляр ByteBuffer, например если это сегмент кучи, поддерживаемый массивом, отличным от byte[]), или если его размер превышает Integer.MAX_VALUE

toArray

byte[] toArray(ValueLayout.OfByte elementLayout)

Копирует содержимое этого сегмента памяти в новый массив byte.

Параметры:: elementLayout — схема расположения исходного элемента. Если порядок байтов, связанный со схемой расположения, отличается от нативного порядка, для каждого элемента массива будет выполнена перестановка байтов
Возвращает:: новый массив byte, содержимое которого скопировано из этого сегмента памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если содержимое этого сегмента нельзя скопировать в экземпляр byte[], например если его размер превышает Integer.MAX_VALUE

toArray

short[] toArray(ValueLayout.OfShort elementLayout)

Копирует содержимое этого сегмента памяти в новый массив short.

Параметры:: elementLayout — схема расположения исходного элемента. Если порядок байтов, связанный со схемой расположения, отличается от нативного порядка, для каждого элемента массива будет выполнена перестановка байтов
Возвращает:: новый массив short, содержимое которого скопировано из этого сегмента памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если содержимое этого сегмента нельзя скопировать в экземпляр short[], например потому что byteSize() % 2 != 0 или byteSize() / 2 > Integer.MAX_VALUE

toArray

char[] toArray(ValueLayout.OfChar elementLayout)

Копирует содержимое этого сегмента памяти в новый массив char.

Параметры:: elementLayout — схема расположения исходного элемента. Если порядок байтов, связанный со схемой расположения, отличается от нативного порядка, для каждого элемента массива будет выполнена перестановка байтов
Возвращает:: новый массив char, содержимое которого скопировано из этого сегмента памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если содержимое этого сегмента нельзя скопировать в экземпляр char[], например потому что byteSize() % 2 != 0 или byteSize() / 2 > Integer.MAX_VALUE

toArray

int[] toArray(ValueLayout.OfInt elementLayout)

Копирует содержимое этого сегмента памяти в новый массив int.

Параметры:: elementLayout — схема расположения исходного элемента. Если порядок байтов, связанный со схемой расположения, отличается от нативного порядка, для каждого элемента массива будет выполнена перестановка байтов.
Возвращает:: новый массив int, содержимое которого скопировано из этого сегмента памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если содержимое этого сегмента нельзя скопировать в экземпляр int[], например потому что byteSize() % 4 != 0 или byteSize() / 4 > Integer.MAX_VALUE

toArray

float[] toArray(ValueLayout.OfFloat elementLayout)

Копирует содержимое этого сегмента памяти в новый массив float.

Параметры:: elementLayout — схема расположения исходного элемента. Если порядок байтов, связанный со схемой расположения, отличается от нативного порядка, для каждого элемента массива будет выполнена перестановка байтов
Возвращает:: новый массив float, содержимое которого скопировано из этого сегмента памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если содержимое этого сегмента нельзя скопировать в экземпляр float[], например потому что byteSize() % 4 != 0 или byteSize() / 4 > Integer.MAX_VALUE

toArray

long[] toArray(ValueLayout.OfLong elementLayout)

Копирует содержимое этого сегмента памяти в новый массив long.

Параметры:: elementLayout — схема расположения исходного элемента. Если порядок байтов, связанный со схемой расположения, отличается от нативного порядка, для каждого элемента массива будет выполнена перестановка байтов
Возвращает:: новый массив long, содержимое которого скопировано из этого сегмента памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если содержимое этого сегмента нельзя скопировать в экземпляр long[], например потому что byteSize() % 8 != 0 или byteSize() / 8 > Integer.MAX_VALUE

toArray

double[] toArray(ValueLayout.OfDouble elementLayout)

Копирует содержимое этого сегмента памяти в новый массив double.

Параметры:: elementLayout — схема расположения исходного элемента. Если порядок байтов, связанный со схемой расположения, отличается от нативного порядка, для каждого элемента массива будет выполнена перестановка байтов
Возвращает:: новый массив double, содержимое которого скопировано из этого сегмента памяти
Вызывает исключения:: IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalStateException — если содержимое этого сегмента нельзя скопировать в экземпляр double[], например потому что byteSize() % 8 != 0 или byteSize() / 8 > Integer.MAX_VALUE

getString

String getString(long offset)

Читает строку с нулевым завершителем из этого сегмента по заданному смещению, используя кодировку UTF-8.

Вызов этого метода эквивалентен следующему коду:

 getString(offset, StandardCharsets.UTF_8);

Параметры:: offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа
Возвращает:: строку Java, сформированную из байтов, прочитанных с заданного начального адреса до первого символа завершителя '\0' (не включая его, если он найден)
Вызывает исключения:: IllegalArgumentException — если размер строки превышает максимальный размер строки, поддерживаемый платформой; IndexOutOfBoundsException — если offset < 0; IndexOutOfBoundsException — если в этом сегменте между заданным offset и концом сегмента отсутствует завершающий символ строки (например, '\0').; IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false

getString

String getString(long offset, Charset charset)

Читает строку с нулевым завершителем из этого сегмента по заданному смещению, используя указанную кодировку.

Этот метод всегда заменяет некорректные входные данные и последовательности несопоставимых символов строкой замены, заданной по умолчанию для этой кодировки. Если требуется более точно контролировать процесс декодирования, следует использовать класс CharsetDecoder.

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

    byte[] bytes = new byte[length];
    MemorySegment.copy(segment, JAVA_BYTE, offset, bytes, 0, length);
    return new String(bytes, charset);

Параметры:: offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа; charset — кодировка, используемая для декодирования байтов строки. charset должна быть стандартной кодировкой
Возвращает:: строку Java, сформированную из байтов, прочитанных с заданного начального адреса до первого символа завершителя '\0' (не включая его, если он найден)
Вызывает исключения:: IllegalArgumentException — если размер строки превышает максимальный размер строки, поддерживаемый платформой; IndexOutOfBoundsException — если offset < 0; IndexOutOfBoundsException — если в этом сегменте между заданным offset и концом сегмента отсутствует завершающий символ строки (например, '\0'). Размер завершающего символа строки в байтах зависит от выбранной charset. Например, он равен 1 для StandardCharsets.US_ASCII и 2 для StandardCharsets.UTF_16; IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если charset не является стандартной кодировкой

setString

void setString(long offset, String str)

Записывает заданную строку в этот сегмент по указанному смещению, преобразуя ее в последовательность байтов с нулевым завершителем с использованием кодировки UTF-8.

Вызов этого метода эквивалентен следующему коду:

 setString(offset, str, StandardCharsets.UTF_8);

Параметры:: offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа; конечный адрес этой операции записи можно выразить как address() + offset.; str — строка Java, которую требуется записать в этот сегмент
Вызывает исключения:: IndexOutOfBoundsException — если offset < 0; IndexOutOfBoundsException — если offset > byteSize() - (B + 1), где B — размер строки в байтах при кодировании с использованием UTF-8 str.getBytes(StandardCharsets.UTF_8).length); IllegalStateException — если область действия, связанная с этим сегментом, не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если этот сегмент доступен только для чтения

setString

void setString(long offset, String str, Charset charset)

Записывает заданную строку в этот сегмент по указанному смещению, преобразуя ее в последовательность байтов с нулевым завершителем с использованием указанной кодировки.

Если заданная строка содержит символы '\0', они также будут скопированы. Это означает, что в зависимости от метода, используемого для чтения строки, например getString(long), при повторном чтении строка будет выглядеть усеченной.

Параметры:

offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа; конечный адрес этой операции записи можно выразить как address() + offset

str — строка Java, которую требуется записать в этот сегмент

charset — кодировка, используемая для кодирования байтов строки. charset должна быть стандартной кодировкой

Вызывает исключения:

IndexOutOfBoundsException — если offset < 0

IndexOutOfBoundsException — если offset > byteSize() - (B + N), где:

B — размер строки в байтах при кодировании с использованием указанной кодировки (например, str.getBytes(charset).length);
N — размер (в байтах) символа-завершителя в соответствии с указанной кодировкой. Например, он равен 1 для StandardCharsets.US_ASCII и 2 для StandardCharsets.UTF_16.

IllegalStateException — если область действия, связанная с этим сегментом, не является активной

WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false

IllegalArgumentException — если charset не является стандартной кодировкой

IllegalArgumentException — если этот сегмент доступен только для чтения

ofBuffer

static MemorySegment ofBuffer(Buffer buffer)

Создает сегмент памяти, поддерживаемый той же областью памяти, что и указанный экземпляр Buffer. Начало сегмента соответствует позиции буфера (включительно), а конец — его пределу (не включая его).

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

Если предоставленный буфер был получен вызовом asByteBuffer() для сегмента памяти, чья область действия является S, возвращенный сегмент будет связан с той же областью действия S. В противном случае областью действия возвращенного сегмента будет автоматическая область, поддерживающая доступность предоставленного буфера. Поэтому, если предоставленный буфер является прямым, его резервная область памяти не будет освобождена, пока возвращенный сегмент или любой из его срезов остается достижимым.

Параметры:: buffer — экземпляр буфера, который требуется преобразовать в новый сегмент памяти
Возвращает:: сегмент памяти, полученный на основе указанного экземпляра буфера
Вызывает исключения:: IllegalArgumentException — если предоставленный buffer является буфером кучи, но не поддерживается массивом. Например, буферы, прямо или косвенно полученные с помощью (CharBuffer.wrap(CharSequence) или CharBuffer.wrap(char[], int, int), не поддерживаются массивом.

ofArray

static MemorySegment ofArray(byte[] byteArray)

Создает сегмент кучи, поддерживаемый находящейся в куче областью памяти, содержащей указанный массив byte. Областью действия возвращенного сегмента является автоматическая область, которая поддерживает доступность указанного массива. Возвращенный сегмент всегда доступен из любого потока. Его address() установлен в ноль.

Параметры:: byteArray — примитивный массив, поддерживающий сегмент памяти кучи
Возвращает:: сегмент памяти кучи, поддерживаемый массивом byte

ofArray

static MemorySegment ofArray(char[] charArray)

Создает сегмент кучи, поддерживаемый находящейся в куче областью памяти, содержащей указанный массив char. Областью действия возвращенного сегмента является автоматическая область, которая поддерживает доступность указанного массива. Возвращенный сегмент всегда доступен из любого потока. Его address() установлен в ноль.

Параметры:: charArray — примитивный массив, поддерживающий сегмент кучи
Возвращает:: сегмент памяти кучи, поддерживаемый массивом char

ofArray

static MemorySegment ofArray(short[] shortArray)

Создает сегмент кучи, поддерживаемый находящейся в куче областью памяти, содержащей указанный массив short. Областью действия возвращенного сегмента является автоматическая область, которая поддерживает доступность указанного массива. Возвращенный сегмент всегда доступен из любого потока. Его address() установлен в ноль.

Параметры:: shortArray — примитивный массив, поддерживающий сегмент кучи
Возвращает:: сегмент памяти кучи, поддерживаемый массивом short

ofArray

static MemorySegment ofArray(int[] intArray)

Создает сегмент кучи, поддерживаемый находящейся в куче областью памяти, содержащей указанный массив int. Областью действия возвращенного сегмента является автоматическая область, которая поддерживает доступность указанного массива. Возвращенный сегмент всегда доступен из любого потока. Его address() установлен в ноль.

Параметры:: intArray — примитивный массив, поддерживающий сегмент кучи
Возвращает:: сегмент памяти кучи, поддерживаемый массивом int

ofArray

static MemorySegment ofArray(float[] floatArray)

Создает сегмент кучи, поддерживаемый находящейся в куче областью памяти, содержащей указанный массив float. Областью действия возвращенного сегмента является автоматическая область, которая поддерживает доступность указанного массива. Возвращенный сегмент всегда доступен из любого потока. Его address() установлен в ноль.

Параметры:: floatArray — примитивный массив, поддерживающий сегмент кучи
Возвращает:: сегмент памяти кучи, поддерживаемый массивом float

ofArray

static MemorySegment ofArray(long[] longArray)

Создает сегмент кучи, поддерживаемый находящейся в куче областью памяти, содержащей указанный массив long. Областью действия возвращенного сегмента является автоматическая область, которая поддерживает доступность указанного массива. Возвращенный сегмент всегда доступен из любого потока. Его address() установлен в ноль.

Параметры:: longArray — примитивный массив, поддерживающий сегмент кучи
Возвращает:: сегмент памяти кучи, поддерживаемый массивом long

ofArray

static MemorySegment ofArray(double[] doubleArray)

Создает сегмент кучи, поддерживаемый находящейся в куче областью памяти, содержащей указанный массив double. Областью действия возвращенного сегмента является автоматическая область, которая поддерживает доступность указанного массива. Возвращенный сегмент всегда доступен из любого потока. Его address() установлен в ноль.

Параметры:: doubleArray — примитивный массив, поддерживающий сегмент кучи
Возвращает:: сегмент памяти кучи, поддерживаемый массивом double

ofAddress

static MemorySegment ofAddress(long address)

Создает нативный сегмент нулевой длины из указанного значения адреса.

Возвращаемый сегмент связан с глобальной областью видимости и доступен из любого потока.

На 32-разрядных платформах указанное значение адреса будет нормализовано таким образом, что старшие («левые») 32 бита address возвращаемого сегмента памяти будут установлены в ноль.

Параметры:: address — адрес возвращаемого нативного сегмента
Возвращает:: нативный сегмент нулевой длины с указанным адресом

copy

static void copy(MemorySegment srcSegment, long srcOffset, MemorySegment dstSegment, long dstOffset, long bytes)

Выполняет массовое копирование из исходного сегмента в целевой сегмент. В частности, байты с позиции srcOffset по srcOffset + bytes - 1 исходного сегмента копируются в целевой сегмент с позиции dstOffset по dstOffset + bytes - 1.

Если исходный сегмент перекрывается с целевым сегментом, копирование выполняется так, как если бы байты с позиции srcOffset по srcOffset + bytes - 1 исходного сегмента сначала были скопированы во временный сегмент размером bytes, а затем содержимое временного сегмента было скопировано в целевой сегмент с позиции dstOffset по dstOffset + bytes - 1.

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

Вызов этого метода эквивалентен следующему коду:

MemorySegment.copy(srcSegment, ValueLayout.JAVA_BYTE, srcOffset, dstSegment, ValueLayout.JAVA_BYTE, dstOffset, bytes);

Параметры:: srcSegment — исходный сегмент; srcOffset — начальное смещение в байтах в исходном сегменте; dstSegment — целевой сегмент; dstOffset — начальное смещение в байтах в целевом сегменте; bytes — количество копируемых байтов
Исключения:: IllegalStateException — если связанная с srcSegment область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что srcSegment.isAccessibleBy(T) == false; IllegalStateException — если связанная с dstSegment область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что dstSegment.isAccessibleBy(T) == false; IndexOutOfBoundsException — если srcOffset > srcSegment.byteSize() - bytes; IndexOutOfBoundsException — если dstOffset > dstSegment.byteSize() - bytes; IndexOutOfBoundsException — если srcOffset, dstOffset или bytes являются < 0; IllegalArgumentException — если dstSegment доступен только для чтения

copy

static void copy(MemorySegment srcSegment, ValueLayout srcElementLayout, long srcOffset, MemorySegment dstSegment, ValueLayout dstElementLayout, long dstOffset, long elementCount)

Выполняет массовое копирование из исходного сегмента в целевой сегмент. В частности, если S — размер в байтах макетов элементов, байты с позиции srcOffset по srcOffset + (elementCount * S) - 1 исходного сегмента копируются в целевой сегмент с позиции dstOffset по dstOffset + (elementCount * S) - 1.

Копирование выполняется поэлементно: байты исходного сегмента интерпретируются как последовательность элементов с макетом srcElementLayout, а байты целевого сегмента — как последовательность элементов с макетом dstElementLayout. Размеры обоих макетов элементов должны совпадать и составлять S. Если порядок байтов в двух указанных макетах элементов различается, байты каждого копируемого элемента переставляются соответствующим образом в процессе копирования.

Если исходный сегмент перекрывается с целевым сегментом, копирование выполняется так, как если бы байты с позиции srcOffset по srcOffset + (elementCount * S) - 1 исходного сегмента сначала были скопированы во временный сегмент размером bytes, а затем содержимое временного сегмента было скопировано в целевой сегмент с позиции dstOffset по dstOffset + (elementCount * S) - 1.

Параметры:: srcSegment — исходный сегмент; srcElementLayout — макет элемента, связанный с исходным сегментом; srcOffset — начальное смещение в байтах в исходном сегменте; dstSegment — целевой сегмент; dstElementLayout — макет элемента, связанный с целевым сегментом; dstOffset — начальное смещение в байтах в целевом сегменте; elementCount — количество копируемых элементов
Исключения:: IllegalArgumentException — если размеры макетов элементов различаются или если исходный (соответственно целевой) сегмент/смещение не соответствует ограничению выравнивания исходного (соответственно целевого) макета элемента; IllegalArgumentException — если srcElementLayout.byteAlignment() > srcElementLayout.byteSize(); IllegalArgumentException — если dstElementLayout.byteAlignment() > dstElementLayout.byteSize(); IllegalStateException — если связанная с srcSegment область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что srcSegment.isAccessibleBy(T) == false; IllegalStateException — если связанная с dstSegment область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что dstSegment.isAccessibleBy(T) == false; IllegalArgumentException — если dstSegment доступен только для чтения; IndexOutOfBoundsException — если происходит переполнение elementCount * srcLayout.byteSize(); IndexOutOfBoundsException — если происходит переполнение elementCount * dtsLayout.byteSize(); IndexOutOfBoundsException — если srcOffset > srcSegment.byteSize() - (elementCount * srcLayout.byteSize()); IndexOutOfBoundsException — если dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize()); IndexOutOfBoundsException — если srcOffset, dstOffset или elementCount являются < 0

get

byte get(ValueLayout.OfByte layout, long offset)

Читает байт из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.
Возвращает:: значение байта, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfByte layout, long offset, byte value)

Записывает байт в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.; value — значение байта для записи.
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

boolean get(ValueLayout.OfBoolean layout, long offset)

Читает логическое значение из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа
Возвращает:: логическое значение, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfBoolean layout, long offset, boolean value)

Записывает логическое значение в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа; value — логическое значение для записи
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

char get(ValueLayout.OfChar layout, long offset)

Читает символ char из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа
Возвращает:: значение char, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfChar layout, long offset, char value)

Записывает символ char в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.; value — значение char для записи
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

short get(ValueLayout.OfShort layout, long offset)

Читает значение типа short из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа
Возвращает:: значение short, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfShort layout, long offset, short value)

Записывает значение типа short в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.; value — значение short для записи
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

int get(ValueLayout.OfInt layout, long offset)

Читает значение типа int из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.
Возвращает:: значение int, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfInt layout, long offset, int value)

Записывает значение типа int в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа; value — значение int для записи
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

float get(ValueLayout.OfFloat layout, long offset)

Читает значение типа float из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа
Возвращает:: значение float, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfFloat layout, long offset, float value)

Записывает значение типа float в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа; value — значение float для записи
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

long get(ValueLayout.OfLong layout, long offset)

Читает значение типа long из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.
Возвращает:: значение long, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfLong layout, long offset, long value)

Записывает значение типа long в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.; value — значение long для записи.
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

double get(ValueLayout.OfDouble layout, long offset)

Читает значение типа double из этого сегмента по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа
Возвращает:: значение double, прочитанное из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(ValueLayout.OfDouble layout, long offset, double value)

Записывает значение типа double в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа; value — значение double для записи
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

get

MemorySegment get(AddressLayout layout, long offset)

Читает адрес из этого сегмента по указанному смещению с использованием указанного макета. Прочитанный адрес оборачивается в нативный сегмент, связанный с глобальной областью видимости. В обычных условиях размер возвращаемого сегмента равен 0. Однако если указанный макет адреса имеет целевой макет T, размер возвращаемого сегмента устанавливается равным T.byteSize().

Параметры:: layout — макет области памяти, которую нужно прочитать; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа
Возвращает:: нативный сегмент, оборачивающий адрес, прочитанный из этого сегмента
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IllegalArgumentException — если указанный макет адреса имеет целевой макет T, а адрес возвращаемого сегмента не соответствует ограничению выравнивания в T; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0

set

void set(AddressLayout layout, long offset, MemorySegment value)

Записывает адрес в этот сегмент по указанному смещению с использованием указанного макета.

Параметры:: layout — макет области памяти, в которую нужно выполнить запись; offset — смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена эта операция доступа.; value — значение адреса для записи.
Исключения:: IllegalStateException — если связанная с этим сегментом область видимости не является активной; WrongThreadException — если этот метод вызван из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа не соответствует ограничению выравнивания указанного макета; IndexOutOfBoundsException — если offset > byteSize() - layout.byteSize() или offset < 0; IllegalArgumentException — если value не является нативным сегментом; IllegalArgumentException — если этот сегмент доступен только для чтения

getAtIndex

byte getAtIndex(ValueLayout.OfByte layout, long index)

Читает байт из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа byte, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

getAtIndex

boolean getAtIndex(ValueLayout.OfBoolean layout, long index)

Читает значение boolean из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа boolean, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

getAtIndex

char getAtIndex(ValueLayout.OfChar layout, long index)

Читает значение char из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа char, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

setAtIndex

void setAtIndex(ValueLayout.OfChar layout, long index, char value)

Записывает значение char в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение char, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

getAtIndex

short getAtIndex(ValueLayout.OfShort layout, long index)

Читает значение short из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа short, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

setAtIndex

void setAtIndex(ValueLayout.OfByte layout, long index, byte value)

Записывает байт в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение short, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

setAtIndex

void setAtIndex(ValueLayout.OfBoolean layout, long index, boolean value)

Записывает значение boolean в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение short, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

setAtIndex

void setAtIndex(ValueLayout.OfShort layout, long index, short value)

Записывает значение short в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение short, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

getAtIndex

int getAtIndex(ValueLayout.OfInt layout, long index)

Читает значение int из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать.; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа int, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

setAtIndex

void setAtIndex(ValueLayout.OfInt layout, long index, int value)

Записывает значение int в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение int, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

getAtIndex

float getAtIndex(ValueLayout.OfFloat layout, long index)

Читает значение float из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа float, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

setAtIndex

void setAtIndex(ValueLayout.OfFloat layout, long index, float value)

Записывает значение float в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение float, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

getAtIndex

long getAtIndex(ValueLayout.OfLong layout, long index)

Читает значение long из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа long, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

setAtIndex

void setAtIndex(ValueLayout.OfLong layout, long index, long value)

Записывает значение long в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение long, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

getAtIndex

double getAtIndex(ValueLayout.OfDouble layout, long index)

Читает значение double из этого сегмента по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: значение типа double, прочитанное из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

setAtIndex

void setAtIndex(ValueLayout.OfDouble layout, long index, double value)

Записывает значение double в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение double, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если этот сегмент доступен только для чтения

getAtIndex

MemorySegment getAtIndex(AddressLayout layout, long index)

Читает адрес из этого сегмента по указанному индексу, масштабированному на размер заданного макета. Прочитанный адрес оборачивается в нативный сегмент, связанный с глобальной областью действия. В обычных условиях размер возвращаемого сегмента равен 0. Однако если предоставленный макет адреса содержит целевой макет T, размер возвращаемого сегмента устанавливается равным T.byteSize().

Параметры:: layout — макет области памяти, которую необходимо прочитать; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).
Возвращает:: нативный сегмент, оборачивающий адрес, прочитанный из этого сегмента
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете.; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IllegalArgumentException — если предоставленный макет адреса содержит целевой макет T, а адрес возвращаемого сегмента несовместим с ограничением выравнивания в T; IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0

setAtIndex

void setAtIndex(AddressLayout layout, long index, MemorySegment value)

Записывает адрес в этот сегмент по указанному индексу, масштабированному на размер заданного макета.

Параметры:: layout — макет области памяти, в которую необходимо выполнить запись; index — логический индекс. Смещение в байтах (относительно адреса этого сегмента), по которому будет выполнена операция доступа, можно выразить как (index * layout.byteSize()).; value — значение адреса, которое необходимо записать
Вызывает исключения:: IllegalStateException — если связанная с этим сегментом область действия не активна; WrongThreadException — если этот метод вызывается из потока T, так что isAccessibleBy(T) == false; IllegalArgumentException — если операция доступа несовместима с ограничением выравнивания в предоставленном макете.; IllegalArgumentException — если layout.byteAlignment() > layout.byteSize(); IndexOutOfBoundsException — если index * layout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если index * layout.byteSize() > byteSize() - layout.byteSize() или index < 0; IllegalArgumentException — если value не является нативным сегментом; IllegalArgumentException — если этот сегмент доступен только для чтения

equals

boolean equals(Object that)

Сравнивает указанный объект с этим сегментом памяти на равенство. Возвращает true тогда и только тогда, когда указанный объект также является сегментом памяти и оба сегмента ссылаются на одно и то же местоположение в некоторой области памяти.

Точнее, чтобы два сегмента s1 и s2 считались равными, должны выполняться все следующие условия:

s1.heapBase().equals(s2.heapBase()), то есть оба сегмента должны быть одного типа: либо оба являются нативными сегментами, использующими память вне кучи, либо оба используют один и тот же объект Java в куче Java;
s1.address() == s2.address(), то есть адреса обоих сегментов должны совпадать. Это означает, что оба сегмента либо ссылаются на одно и то же местоположение в некоторой области вне кучи, либо на одно и то же смещение внутри связанного с ними объекта Java.

Переопределяет:

equals в классе Object

Примечание к API:

Этот метод не выполняет структурное сравнение содержимого двух сегментов памяти. Клиенты могут структурно сравнивать сегменты памяти с помощью метода mismatch(MemorySegment). Обратите внимание, что этот метод не сравнивает временные и пространственные границы двух сегментов. Поэтому он подходит для проверки того, имеют ли два сегмента одинаковый адрес.

Параметры:

that — объект, который необходимо сравнить с этим сегментом памяти на равенство

Возвращает:

true, если указанный объект равен этому сегменту памяти

См. также:

hashCode

int hashCode()

Возвращает хеш-код этого сегмента памяти.

Переопределяет:

hashCode в классе Object

Возвращает:

хеш-код этого сегмента памяти

См. также:

copy

static void copy(MemorySegment srcSegment, ValueLayout srcLayout, long srcOffset, Object dstArray, int dstIndex, int elementCount)

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

Поддерживаются массивы следующих типов: byte[], char[], short[], int[], float[], long[] и double[].

Параметры:: srcSegment — исходный сегмент; srcLayout — раскладка элементов источника. Если порядок байтов, связанный с раскладкой, отличается от порядка байтов платформы, для каждого элемента массива будет выполнена операция перестановки байтов; srcOffset — начальное смещение исходного сегмента в байтах; dstArray — массив назначения; dstIndex — начальный индекс массива назначения; elementCount — количество элементов массива для копирования
Исключения:: IllegalStateException — если область, связанная с srcSegment, не активна; WrongThreadException — если этот метод вызван из потока T, такого что srcSegment.isAccessibleBy(T) == false; IllegalArgumentException — если dstArray не является массивом или является массивом неподдерживаемого типа; IllegalArgumentException — если тип компонентов массива назначения не соответствует srcLayout.carrier(); IllegalArgumentException — если offset несовместимо с ограничением выравнивания в раскладке исходного элемента; IllegalArgumentException — если srcLayout.byteAlignment() > srcLayout.byteSize(); IndexOutOfBoundsException — если elementCount * srcLayout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если srcOffset > srcSegment.byteSize() - (elementCount * srcLayout.byteSize()); IndexOutOfBoundsException — если dstIndex > dstArray.length - elementCount; IndexOutOfBoundsException — если srcOffset, dstIndex или elementCount являются < 0

copy

static void copy(Object srcArray, int srcIndex, MemorySegment dstSegment, ValueLayout dstLayout, long dstOffset, int elementCount)

Копирует заданное количество элементов из исходного массива в целевой сегмент памяти.

Элементы, размер и ограничения выравнивания которых заданы указанной раскладкой, считываются из исходного массива, начиная с указанного индекса, и копируются в целевой сегмент, начиная с указанного смещения (в байтах).

Поддерживаются массивы следующих типов: byte[], char[], short[], int[], float[], long[] и double[].

Параметры:: srcArray — исходный массив; srcIndex — начальный индекс исходного массива; dstSegment — целевой сегмент; dstLayout — раскладка элементов назначения. Если порядок байтов, связанный с раскладкой, отличается от порядка байтов платформы, для каждого элемента массива будет выполнена операция перестановки байтов.; dstOffset — начальное смещение целевого сегмента в байтах; elementCount — количество элементов массива для копирования
Исключения:: IllegalStateException — если область, связанная с dstSegment, не активна; WrongThreadException — если этот метод вызван из потока T, такого что dstSegment.isAccessibleBy(T) == false; IllegalArgumentException — если srcArray не является массивом или является массивом неподдерживаемого типа; IllegalArgumentException — если тип компонентов исходного массива не соответствует srcLayout.carrier(); IllegalArgumentException — если offset несовместимо с ограничением выравнивания в раскладке исходного элемента; IllegalArgumentException — если dstLayout.byteAlignment() > dstLayout.byteSize(); IllegalArgumentException — если dstSegment доступен только для чтения; IndexOutOfBoundsException — если elementCount * dstLayout.byteSize() приводит к переполнению; IndexOutOfBoundsException — если dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize()); IndexOutOfBoundsException — если srcIndex > srcArray.length - elementCount; IndexOutOfBoundsException — если srcIndex, dstOffset или elementCount являются < 0

mismatch

static long mismatch(MemorySegment srcSegment, long srcFromOffset, long srcToOffset, MemorySegment dstSegment, long dstFromOffset, long dstToOffset)

Находит и возвращает относительное смещение в байтах первого несовпадения между исходным и целевым сегментами. В частности, байты со смещения srcFromOffset по srcToOffset - 1 в исходном сегменте сравниваются с байтами со смещения dstFromOffset по dstToOffset - 1 в целевом сегменте.

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

Параметры:

srcSegment — исходный сегмент.

srcFromOffset — смещение (включительно) первого проверяемого байта в исходном сегменте

srcToOffset — смещение (не включительно) последнего проверяемого байта в исходном сегменте

dstSegment — целевой сегмент

dstFromOffset — смещение (включительно) первого проверяемого байта в целевом сегменте

dstToOffset — смещение (не включительно) последнего проверяемого байта в целевом сегменте

Возвращает:

относительное смещение в байтах первого несовпадения между исходным и целевым сегментами; если несовпадений нет, возвращает -1

Исключения:

IllegalStateException — если область, связанная с srcSegment, не активна

WrongThreadException — если этот метод вызван из потока T, такого что srcSegment.isAccessibleBy(T) == false

IllegalStateException — если область, связанная с dstSegment, не активна

WrongThreadException — если этот метод вызван из потока T, такого что dstSegment.isAccessibleBy(T) == false

IndexOutOfBoundsException — если srcFromOffset < 0, srcToOffset < srcFromOffset или srcToOffset > srcSegment.byteSize()

IndexOutOfBoundsException — если dstFromOffset < 0, dstToOffset < dstFromOffset или dstToOffset > dstSegment.byteSize()

См. также:

© 1993, 2025, 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/25/docs/api/java.base/java/lang/foreign/MemorySegment.html