Интерфейс SegmentAllocator

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

@FunctionalInterface public interface SegmentAllocator

Этот интерфейс моделирует аллокатор памяти. Клиенты, реализующие этот интерфейс, должны реализовать метод allocate(long, long). Этот интерфейс определяет несколько методов по умолчанию, которые могут быть полезны для создания сегментов из различных типов значений Java, таких как примитивы и массивы. Этот интерфейс можно рассматривать как тонкий оболочку основных возможностей для создания нативных сегментов (например, MemorySegment.allocateNative(long, long, ResourceScope)); так как SegmentAllocator является функциональным интерфейсом, клиенты могут легко получить нативный аллокатор, используя лямбда-выражение или ссылку на метод.

Этот интерфейс предоставляет фабрику, а именно ofScope(ResourceScope), которая может быть использована для получения ограниченного аллокатора, то есть аллокатора, который создает сегмент, ограниченный заданным scope. Это может быть полезно при работе внутри конструкции try-with-resources:


try (ResourceScope scope = ResourceScope.newConfinedScope()) {
   SegmentAllocator allocator = SegmentAllocator.ofScope(scope);
   ...
}

Кроме того, этот интерфейс также определяет фабрики для часто используемых аллокаторов; например, arenaAllocator(ResourceScope) и arenaAllocator(long, ResourceScope) являются аллокаторами на основе арены. Наконец, ofSegment(MemorySegment) возвращает аллокатор, который оборачивает сегмент (в куче или вне кучи) и перерабатывает его содержимое при каждом новом запросе на выделение.

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

Модификатор и тип	Метод	Описание
`default MemorySegment`	`allocate(long bytesSize)`	Выделение блока памяти заданного размера с выравниванием по умолчанию (выравнивание по 1 байту).
`MemorySegment`	`allocate(long bytesSize, long bytesAlignment)`	Выделение блока памяти заданного размера и ограничения выравнивания.
`default MemorySegment`	`allocate(MemoryLayout layout)`	Выделение блока памяти с заданной структурой.
`default MemorySegment`	`allocate(ValueLayout layout, byte value)`	Выделение блока памяти с заданной структурой и инициализация его заданным байтовым значением.
`default MemorySegment`	`allocate(ValueLayout layout, char value)`	Выделение блока памяти с заданной структурой и инициализация его заданным символьным значением.
`default MemorySegment`	`allocate(ValueLayout layout, double value)`	Выделение блока памяти с заданной структурой и инициализация его заданным двойным значением.
`default MemorySegment`	`allocate(ValueLayout layout, float value)`	Выделение блока памяти с заданной структурой и инициализация его заданным плавающим значением.
`default MemorySegment`	`allocate(ValueLayout layout, int value)`	Выделение блока памяти с заданной структурой и инициализация его заданным целочисленным значением.
`default MemorySegment`	`allocate(ValueLayout layout, long value)`	Выделение блока памяти с заданной структурой и инициализация его заданным длинным значением.
`default MemorySegment`	`allocate(ValueLayout layout, short value)`	Выделение блока памяти с заданной структурой и инициализация его заданным коротким значением.
`default MemorySegment`	`allocate(ValueLayout layout, Addressable value)`	Выделение блока памяти с заданной структурой и инициализация его заданным значением адреса (выраженного как экземпляр `Addressable`).
`default MemorySegment`	`allocateArray(MemoryLayout elementLayout, long count)`	Выделение блока памяти, соответствующего массиву с заданной структурой элементов и размером.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, byte[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным массивом байт.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, char[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным массивом символов.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, double[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным массивом двойных значений.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, float[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным массивом плавающих значений.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, int[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным целочисленным массивом.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, long[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным длинным массивом.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, short[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным коротким массивом.
`default MemorySegment`	`allocateArray(ValueLayout elementLayout, Addressable[] array)`	Выделение блока памяти с заданной структурой и инициализация его заданным массивом адресов.
`static SegmentAllocator`	`arenaAllocator(long size, ResourceScope scope)`	Возвращает аллокатор на основе нативной арены, который выделяет один сегмент памяти заданного размера (используя malloc), а затем реагирует на запросы выделения, возвращая различные фрагменты того же сегмента (пока это возможно).
`static SegmentAllocator`	`arenaAllocator(ResourceScope scope)`	Возвращает неограниченный аллокатор на основе нативной арены.
`static SegmentAllocator`	`ofScope(ResourceScope scope)`	Возвращает нативный аллокатор, который реагирует на запросы выделения, выделяя новые сегменты, ограниченные заданным scope ресурсов, используя фабрику `MemorySegment.allocateNative(long, long, ResourceScope)`.
`static SegmentAllocator`	`ofSegment(MemorySegment segment)`	Возвращает аллокатор сегментов, который реагирует на запросы выделения, перерабатывая один сегмент; то есть, каждый новый запрос на выделение вернет новый срез, начиная с смещения сегмента `0` (ограничения выравнивания игнорируются этим аллокатором).

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

allocate

default MemorySegment allocate(ValueLayout layout, byte value)

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

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

allocate

default MemorySegment allocate(ValueLayout layout, char value)

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

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

allocate

default MemorySegment allocate(ValueLayout layout, short value)

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

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

allocate

default MemorySegment allocate(ValueLayout layout, int value)

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

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

allocate

default MemorySegment allocate(ValueLayout layout, float value)

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

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

allocate

default MemorySegment allocate(ValueLayout layout, long value)

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

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

allocate

default MemorySegment allocate(ValueLayout layout, double value)

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

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

allocate

default MemorySegment allocate(ValueLayout layout, Addressable value)

Выделить блок памяти с заданной компоновкой и инициализировать его заданным адресом (выраженным как экземпляр Addressable). Значение адреса может быть сужено в соответствии с размером адреса платформы (см. MemoryLayouts.ADDRESS).

Требования к реализации:: реализация по умолчанию для этого метода вызывает this.allocate(layout).
Параметры:: layout - компоновка выделяемого блока памяти.; value - значение, которое должно быть установлено в новом блоке памяти.
Возвращает:: сегмент для нового блока выделенной памяти.
Исключения:: IllegalArgumentException - если layout.byteSize() != MemoryLayouts.ADDRESS.byteSize().

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, byte[] array)

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

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

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, short[] array)

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

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

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, char[] array)

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

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

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, int[] array)

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

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

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, float[] array)

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

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

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, long[] array)

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

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

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, double[] array)

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

Требования к реализации:: стандартная реализация этого метода вызывает this.allocateArray(layout, array.length).
Параметры:: elementLayout - структура элемента массива, который будет выделен.; array - массив, который будет скопирован в новый выделенный блок памяти.
Возвращает:: сегмент для нового выделенного блока памяти.
Исключения:: IllegalArgumentException - если elementLayout.byteSize() не соответствует размеру значения double.

allocateArray

default MemorySegment allocateArray(ValueLayout elementLayout, Addressable[] array)

Выделить блок памяти с заданной структурой и инициализировать его заданным массивом адресов. Значение адреса каждого элемента массива может быть сужено в соответствии с размером адреса платформы (см. MemoryLayouts.ADDRESS).

Требования к реализации:: стандартная реализация этого метода вызывает this.allocateArray(layout, array.length).
Параметры:: elementLayout - структура элемента массива, который будет выделен.; array - массив, который будет скопирован в новый выделенный блок памяти.
Возвращает:: сегмент для нового выделенного блока памяти.
Исключения:: IllegalArgumentException - если layout.byteSize() != MemoryLayouts.ADDRESS.byteSize().

allocate

default MemorySegment allocate(MemoryLayout layout)

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

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

allocateArray

default MemorySegment allocateArray(MemoryLayout elementLayout, long count)

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

Требования к реализации:: стандартная реализация этого метода вызывает this.allocate(MemoryLayout.sequenceLayout(count, elementLayout)).
Параметры:: elementLayout - структура элемента массива.; count - количество элементов массива.
Возвращает:: сегмент для нового выделенного блока памяти.

allocate

default MemorySegment allocate(long bytesSize)

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

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

allocate

MemorySegment allocate(long bytesSize, long bytesAlignment)

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

Параметры:: bytesSize - размер (в байтах) блока памяти, который будет выделен.; bytesAlignment - выравнивание (в байтах) блока памяти, который будет выделен.
Возвращает:: сегмент для нового выделенного блока памяти.

arenaAllocator

static SegmentAllocator arenaAllocator(long size, ResourceScope scope)

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

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

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

Параметры:: size - размер области выделения арены (в байтах).; scope - объем ресурсов, связанный с сегментами, возвращаемыми этим аллокатором.
Возвращает:: новый ограниченный аллокатор на основе арены
Исключения:: IllegalArgumentException - если size <= 0.; IllegalStateException - если scope уже закрыт, или если доступ происходит из потока, отличного от потока, владеющего scope.

arenaAllocator

static SegmentAllocator arenaAllocator(ResourceScope scope)

Возвращает неограниченный аллокатор на основе арены.

Возвращаемый аллокатор выделяет сегмент памяти S определенного фиксированного размера (используя malloc), а затем отвечает на запросы выделения одним из следующих способов:

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

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

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

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

Параметры:: scope - объем ресурсов, связанный с сегментами, возвращаемыми этим аллокатором.
Возвращает:: новый неограниченный аллокатор на основе арены
Исключения:: IllegalStateException - если scope уже закрыт, или если доступ происходит из потока, отличного от потока, владеющего scope.

ofSegment

static SegmentAllocator ofSegment(MemorySegment segment)

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

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

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

ofScope

static SegmentAllocator ofScope(ResourceScope scope)

Возвращает аллокатор, который отвечает на запросы выделения, выделяя новые сегменты, ограниченные заданным объемом ресурсов, используя фабрику MemorySegment.allocateNative(long, long, ResourceScope). Этот код эквивалентен (но, вероятно, более эффективен) следующему:


    Resource scope = ...
    SegmentAllocator scoped = (size, align) -> MemorySegment.allocateNative(size, align, scope);

Параметры:: scope - объем ресурсов, связанный с сегментами, созданными возвращаемым аллокатором.
Возвращает:: аллокатор, который выделяет новый сегмент памяти, ограниченный заданным объемом ресурсов.

© 1993, 2021, 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/17/docs/api/jdk.incubator.foreign/jdk/incubator/foreign/SegmentAllocator.html