Spec-Zone.ru › OpenJDK 21

Интерфейс SegmentAllocator

Все известные подинтерфейсы:
ArenaPREVIEW
Функциональный интерфейс:
Это функциональный интерфейс и поэтому может быть использован в качестве цели присваивания лямбда-выражения или ссылки на метод.
@FunctionalInterface public interface SegmentAllocator
SegmentAllocator является предварительным API платформы Java.
Программы могут использовать SegmentAllocator только при включённых предварительных функциях.
Предварительные функции могут быть удалены в будущих релизах или обновлены до постоянных функций платформы Java.
Объект, который может использоваться для выделения сегментов памятиПРЕДПРОСМОТР. Клиенты, реализующие этот интерфейс, должны реализовать метод allocate(long, long). Выделение сегментов памяти определяется несколькими методами, которые могут быть полезны для создания сегментов из различных типов значений Java, таких как примитивы и массивы.

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

SegmentAllocator autoAllocator = (byteSize, byteAlignment) -> Arena.ofAuto().allocate(byteSize, byteAlignment);

Этот интерфейс определяет фабрики для часто используемых выделенцев:

  • slicingAllocator(MemorySegment) получает эффективный выделец сечений, где память выделяется путем многократного сечения предоставленного сегмента памяти;
  • prefixAllocator(MemorySegment) получает выделец, который оборачивает сегмент и переиспользует его содержимое при каждом новом запросе на выделение.

Передача выделения сегментов в API может быть особенно полезной в ситуациях, когда клиент хочет указать, где должны быть сохранены результаты определённой операции (выполняемой API), как сегмент памяти. Например, обработчики вызовов внизПРЕДПРОСМОТР могут принимать дополнительный параметр SegmentAllocatorПРЕДПРОСМОТР, если известно, что базовая внешняя функция возвращает структуру по значению. Эффективно, параметр выделения указывает линкеру, куда сохранить возвращаемое значение внешней функции.

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

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

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

Модификатор и тип Метод Описание
default MemorySegmentPREVIEW allocate(long byteSize)
Выделяет сегмент памяти заданного размера.
MemorySegmentPREVIEW allocate(long byteSize, long byteAlignment)
Выделяет сегмент памяти заданного размера и ограничения выравнивания.
default MemorySegmentPREVIEW allocate(AddressLayoutPREVIEW layout, MemorySegmentPREVIEW value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного адреса.
default MemorySegmentPREVIEW allocate(MemoryLayoutPREVIEW layout)
Выделяет сегмент памяти с заданной структурой.
default MemorySegmentPREVIEW allocate(ValueLayout.OfBytePREVIEW layout, byte value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного байта.
default MemorySegmentPREVIEW allocate(ValueLayout.OfCharPREVIEW layout, char value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного символа.
default MemorySegmentPREVIEW allocate(ValueLayout.OfDoublePREVIEW layout, double value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного двойного значения.
default MemorySegmentPREVIEW allocate(ValueLayout.OfFloatPREVIEW layout, float value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного плавающего значения.
default MemorySegmentPREVIEW allocate(ValueLayout.OfIntPREVIEW layout, int value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного целого числа.
default MemorySegmentPREVIEW allocate(ValueLayout.OfLongPREVIEW layout, long value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного длинного целого числа.
default MemorySegmentPREVIEW allocate(ValueLayout.OfShortPREVIEW layout, short value)
Выделяет сегмент памяти с заданной структурой и инициализирует его значением заданного короткого целого числа.
default MemorySegmentPREVIEW allocateArray(MemoryLayoutPREVIEW elementLayout, long count)
Выделяет сегмент памяти с заданной структурой элемента и размером.
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfBytePREVIEW elementLayout, byte... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными байтовыми элементами.
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfCharPREVIEW elementLayout, char... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными символами.
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfDoublePREVIEW elementLayout, double... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными двойными элементами.
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfFloatPREVIEW elementLayout, float... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными плавающими элементами.
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfIntPREVIEW elementLayout, int... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными целыми элементами.
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfLongPREVIEW elementLayout, long... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными длинными элементами.
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfShortPREVIEW elementLayout, short... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными короткими элементами.
default MemorySegmentPREVIEW allocateUtf8String(String str)
Преобразует строку Java в UTF-8 кодированную, завершающуюся нулём строку C, сохраняя результат в сегменте памяти.
static SegmentAllocatorPREVIEW prefixAllocator(MemorySegmentPREVIEW segment)
Возвращает выделенный сегмент, который отвечает на запросы выделения, перерабатывая один сегмент.
static SegmentAllocatorPREVIEW slicingAllocator(MemorySegmentPREVIEW segment)
Возвращает выделенный сегмент, который отвечает на запросы выделения, возвращая последовательные части, полученные из предоставленного сегмента.

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

allocateUtf8String

default MemorySegmentPREVIEW allocateUtf8String(String str)
Преобразует строку Java в строку C, закодированную в UTF-8 и завершающуюся нулём, сохраняя результат в сегменте памяти.

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

Если заданная строка содержит '\0' символы, они также будут скопированы. Это означает, что в зависимости от метода чтения строки, например, MemorySegment.getUtf8String(long)ПРЕВЬЮ, строка будет отображаться усечённой при повторном чтении.

Требования к реализации:
стандартная реализация этого метода копирует содержимое предоставленной строки Java в новый сегмент памяти, полученный путём вызова this.allocate(str.length() + 1).
Параметры:
str - строка Java, которая должна быть преобразована в строку C.
Возвращает:
новый системный сегмент, содержащий преобразованную строку C.

allocate

default MemorySegmentPREVIEW allocate(ValueLayout.OfBytePREVIEW layout, byte value)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданным значением байта.
Требования к реализации:
стандартная реализация этого метода вызывает this.allocate(layout).
Параметры:
layout - структура блока памяти, который необходимо выделить.
value - значение, которое необходимо установить в новом блоке памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

allocate

default MemorySegmentPREVIEW allocate(ValueLayout.OfCharPREVIEW layout, char value)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданным значением char.
Требования к реализации:
стандартная реализация этого метода вызывает this.allocate(layout).
Параметры:
layout - структура блока памяти, который необходимо выделить.
value - значение, которое необходимо установить в новом блоке памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

выделить

default MemorySegmentPREVIEW allocate(ValueLayout.OfShortPREVIEW layout, short value)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданным значением типа short.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocate(layout).
Параметры:
layout - структура блока памяти, подлежащего выделению.
value - значение, которое должно быть установлено в вновь выделенном блоке памяти.
Возвращает:
сегмент для вновь выделенного блока памяти.

выделить

default MemorySegmentPREVIEW allocate(ValueLayout.OfIntPREVIEW layout, int value)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданным значением типа int.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocate(layout).
Параметры:
layout - структура блока памяти, подлежащего выделению.
value - значение, которое должно быть установлено в вновь выделенном блоке памяти.
Возвращает:
сегмент для вновь выделенного блока памяти.

выделить

default MemorySegmentPREVIEW allocate(ValueLayout.OfFloatPREVIEW layout, float value)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданным значением типа float.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocate(layout).
Параметры:
layout - структура блока памяти, подлежащего выделению.
value - значение, которое должно быть установлено в вновь выделенном блоке памяти.
Возвращает:
сегмент для вновь выделенного блока памяти.

выделить

default MemorySegmentPREVIEW allocate(ValueLayout.OfLongPREVIEW layout, long value)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданным значением типа long.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocate(layout).
Параметры:
layout - структура блока памяти, подлежащего выделению.
value - значение, которое должно быть установлено в вновь выделенном блоке памяти.
Возвращает:
сегмент для вновь выделенного блока памяти.

выделить

default MemorySegmentPREVIEW allocate(ValueLayout.OfDoublePREVIEW layout, double value)
Выделяет сегмент памяти с заданным представлением и инициализирует его заданным значением double.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocate(layout).
Параметры:
layout - представление блока памяти, подлежащего выделению.
value - значение, которое нужно установить в новом блоке памяти.
Возвращает:
сегмент для вновь выделенного блока памяти.

выделить

default MemorySegmentPREVIEW allocate(AddressLayoutPREVIEW layout, MemorySegmentPREVIEW value)
Выделяет сегмент памяти с заданным представлением и инициализирует его заданным адресом. Значение адреса может быть сужено в соответствии с размером адреса платформы (см. ValueLayout.ADDRESSПРОСМОТР).
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocate(layout).
Параметры:
layout - представление блока памяти, подлежащего выделению.
value - значение, которое нужно установить в новом блоке памяти.
Возвращает:
сегмент для вновь выделенного блока памяти.

выделитьМассив

default MemorySegmentPREVIEW allocateArray(ValueLayout.OfBytePREVIEW elementLayout, byte... elements)
Выделяет сегмент памяти с заданным представлением и инициализирует его заданными байтовыми элементами.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocateArray(layout, array.length).
Параметры:
elementLayout - представление элемента массива, подлежащего выделению.
elements - байтовые элементы, которые нужно скопировать в новый выделенный блок памяти.
Возвращает:
сегмент для вновь выделенного блока памяти.

allocateArray

default MemorySegmentPREVIEW allocateArray(ValueLayout.OfShortPREVIEW elementLayout, short... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными элементами типа short.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocateArray(layout, array.length).
Параметры:
elementLayout - структура элемента массива, который должен быть выделен.
elements - элементы типа short, которые должны быть скопированы в новый выделенный блок памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

allocateArray

default MemorySegmentPREVIEW allocateArray(ValueLayout.OfCharPREVIEW elementLayout, char... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными элементами типа char.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocateArray(layout, array.length).
Параметры:
elementLayout - структура элемента массива, который должен быть выделен.
elements - элементы типа char, которые должны быть скопированы в новый выделенный блок памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

allocateArray

default MemorySegmentPREVIEW allocateArray(ValueLayout.OfIntPREVIEW elementLayout, int... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными элементами типа int.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocateArray(layout, array.length).
Параметры:
elementLayout - структура элемента массива, который должен быть выделен.
elements - элементы типа int, которые должны быть скопированы в новый выделенный блок памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

allocateArray

default MemorySegmentPREVIEW allocateArray(ValueLayout.OfFloatPREVIEW elementLayout, float... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными элементами типа float.
Требования к реализации:
реализация по умолчанию для этого метода вызывает this.allocateArray(layout, array.length).
Параметры:
elementLayout - структура элемента массива, который должен быть выделен.
elements - элементы типа float, которые должны быть скопированы в новый выделенный блок памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

allocateArray

default MemorySegmentPREVIEW allocateArray(ValueLayout.OfLongPREVIEW elementLayout, long... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными элементами типа long.
Требования к реализации:
стандартная реализация этого метода вызывает this.allocateArray(layout, array.length).
Параметры:
elementLayout - структура элемента массива, который необходимо выделить.
elements - элементы типа long, которые нужно скопировать в новый выделенный блок памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

allocateArray

default MemorySegmentPREVIEW allocateArray(ValueLayout.OfDoublePREVIEW elementLayout, double... elements)
Выделяет сегмент памяти с заданной структурой и инициализирует его заданными элементами типа double.
Требования к реализации:
стандартная реализация этого метода вызывает this.allocateArray(layout, array.length).
Параметры:
elementLayout - структура элемента массива, который необходимо выделить.
elements - элементы типа double, которые нужно скопировать в новый выделенный блок памяти.
Возвращает:
сегмент для нового выделенного блока памяти.

allocate

default MemorySegmentPREVIEW allocate(MemoryLayoutPREVIEW layout)
Выделяет сегмент памяти с заданной структурой.
Требования к реализации:
стандартная реализация этого метода вызывает this.allocate(layout.byteSize(), layout.byteAlignment()).
Параметры:
layout - структура блока памяти, который необходимо выделить.
Возвращает:
сегмент для нового выделенного блока памяти.

allocateArray

default MemorySegmentPREVIEW allocateArray(MemoryLayoutPREVIEW elementLayout, long count)
Выделяет сегмент памяти с заданной структурой элемента и размером.
Требования к реализации:
стандартная реализация этого метода вызывает this.allocate(MemoryLayout.sequenceLayout(count, elementLayout)).
Параметры:
elementLayout - структура элемента массива.
count - количество элементов массива.
Возвращает:
сегмент для нового выделенного блока памяти.
Исключение:
IllegalArgumentException - если elementLayout.byteSize() * count переполняется.
IllegalArgumentException - если count < 0.

выделить

default MemorySegmentPREVIEW allocate(long byteSize)
Выделяет сегмент памяти заданного размера.
Требования к реализации:
стандартная реализация этого метода вызывает this.allocate(byteSize, 1).
Параметры:
byteSize - размер (в байтах) выделяемого блока памяти.
Возвращает:
сегмент для нового выделенного блока памяти.
Исключения:
IllegalArgumentException - если byteSize < 0

выделить

MemorySegmentPREVIEW allocate(long byteSize, long byteAlignment)
Выделяет сегмент памяти заданного размера и ограничения выравнивания.
Параметры:
byteSize - размер (в байтах) выделяемого блока памяти.
byteAlignment - выравнивание (в байтах) выделяемого блока памяти.
Возвращает:
сегмент для нового выделенного блока памяти.
Исключения:
IllegalArgumentException - если byteSize < 0, byteAlignment <= 0, или если byteAlignment не является степенью двойки.

slicingAllocator

static SegmentAllocatorPREVIEW slicingAllocator(MemorySegmentPREVIEW segment)
Возвращает выделенщик сегментов, который отвечает на запросы выделения, возвращая последовательные фрагменты, полученные из предоставленного сегмента. Каждый новый запрос выделения вернет новый фрагмент, начиная с текущего смещения (с учетом дополнительной подгонки для удовлетворения ограничений выравнивания), с заданным размером.

Возвращаемый выделенщик выбрасывает IndexOutOfBoundsException, когда фрагмент предоставленного сегмента с запрошенным размером и выравниванием не может быть найден.

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

prefixAllocator

static SegmentAllocatorPREVIEW prefixAllocator(MemorySegmentPREVIEW segment)
Возвращает сегментный аллокатор, который отвечает на запросы выделения, переиспользуя единственный сегмент. Каждый новый запрос выделения вернёт новый срез, начиная с смещения сегмента 0, отсюда и название prefix allocator. Эквивалентно (но, вероятно, более эффективно), чем следующий код: 
MemorySegment segment = ...
SegmentAllocator prefixAllocator = (size, align) -> segment.asSlice(0, size, align);
Возвращаемый аллокатор выбрасывает IndexOutOfBoundsException, когда срез предоставленного сегмента с запрошенным размером и выравниванием не может быть найден.
Примечание API:
Префиксный аллокатор может быть полезен для ограничения запросов выделения в случае, если клиент знает, что он полностью обработает содержимое выделенного сегмента до момента следующего запроса выделения.
Примечание реализации:
Хотя префиксный аллокатор безопасен для потоков, одновременный доступ к одному и тому же аллокатору переиспользования может привести к тому, что поток перезапишет содержимое, записанное в основной сегмент другим потоком.
Параметры:
segment - сегмент памяти, который будет переиспользоваться возвращаемым аллокатором.
Возвращает:
аллокатор, который переиспользует существующий сегмент при каждом новом запросе выделения.

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

Spec-Zone.ru

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