模块 java.base
包 java.lang.foreign

接口 SegmentAllocator

所有已知的子接口：
ArenaPREVIEW
函数接口：
这是一个功能接口，因此可以用作 lambda 表达式或方法引用的赋值目标。
@FunctionalInterface public interface SegmentAllocator
SegmentAllocator 是 Java 平台的预览 API。
程序只能在启用预览功能时使用 SegmentAllocator。
预览功能可能会在未来的版本中删除，或升级为 Java 平台的永久功能。
可用于分配 内存段 的对象PREVIEW .实现此接口的客户端必须实现 allocate(long, long) 方法。此接口定义了几个默认方法，这些方法可用于从多种 Java 值（例如基元和数组）创建段。这个接口是一个 功能接口 ：客户端可以通过使用 lambda 表达式或方法引用轻松获得新的段分配器。

该接口还为常用的分配器定义了工厂：

将段分配器传递给 API 在客户端想要传达where某个操作的结果（由 API 执行）应该存储为内存段的情况下特别有用。例如，向下调用方法句柄PREVIEW 可以接受额外的SegmentAllocator PREVIEW 如果已知基础外部函数按值返回结构，则为参数。实际上，分配器参数告诉链接器运行时在哪里存储外部函数的返回值。

  • 方法详情

    • allocateUtf8String

      default MemorySegment PREVIEW  allocateUtf8String(String  str)
      将 Java 字符串转换为 UTF-8 编码、以 null 结尾的 C 字符串，并将结果存储到内存段中。

      此方法始终用此字符集的默认替换字节数组替换格式错误的输入和不可映射的字符序列。当需要对编码过程进行更多控制时，应使用 CharsetEncoder 类。

      如果给定的字符串包含任何 '\0' 个字符，它们也将被复制。这意味着，取决于用于读取字符串的方法，例如 MemorySegment.getUtf8String(long) PREVIEW , 再次读取时字符串将被截断。

      实现要求：
      此方法的默认实现将提供的 Java 字符串的内容复制到通过调用 this.allocate(str.length() + 1) 获得的新内存段中。
      参数：
      str - 要转换为 C 字符串的 Java 字符串。
      返回：
      包含转换后的 C 字符串的新本地段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfByte PREVIEW  layout, byte value)
      分配具有给定布局的内存段，并使用给定的字节值对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfChar PREVIEW  layout, char value)
      分配具有给定布局的内存段并使用给定的 char 值对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfShort PREVIEW  layout, short value)
      分配具有给定布局的内存段并使用给定的短值对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfInt PREVIEW  layout, int value)
      分配具有给定布局的内存段，并使用给定的 int 值对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfFloat PREVIEW  layout, float value)
      分配具有给定布局的内存段，并使用给定的浮点值对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfLong PREVIEW  layout, long value)
      分配具有给定布局的内存段并使用给定的 long 值对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfDouble PREVIEW  layout, double value)
      分配具有给定布局的内存段，并使用给定的双精度值对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(ValueLayout.OfAddress PREVIEW  layout, MemorySegment PREVIEW  value)
      分配具有给定布局的内存段，并使用给定的地址值对其进行初始化。地址值可能会根据平台地址大小而变窄（参见 ValueLayout.ADDRESS PREVIEW ).
      实现要求：
      此方法的默认实现调用 this.allocate(layout) 。
      参数：
      layout - 要分配的内存块的布局。
      value - 要在新分配的内存块上设置的值。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(ValueLayout.OfByte PREVIEW  elementLayout, byte... elements)
      分配具有给定布局的内存段，并使用给定的字节元素对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocateArray(layout, array.length) 。
      参数：
      elementLayout - 要分配的数组的元素布局。
      elements - 要复制到新分配的内存块的字节元素。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(ValueLayout.OfShort PREVIEW  elementLayout, short... elements)
      分配具有给定布局的内存段，并使用给定的短元素对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocateArray(layout, array.length) 。
      参数：
      elementLayout - 要分配的数组的元素布局。
      elements - 要复制到新分配的内存块的短元素。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(ValueLayout.OfChar PREVIEW  elementLayout, char... elements)
      分配具有给定布局的内存段并使用给定的 char 元素对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocateArray(layout, array.length) 。
      参数：
      elementLayout - 要分配的数组的元素布局。
      elements - 要复制到新分配的内存块的 char 元素。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(ValueLayout.OfInt PREVIEW  elementLayout, int... elements)
      分配具有给定布局的内存段，并使用给定的 int 元素对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocateArray(layout, array.length) 。
      参数：
      elementLayout - 要分配的数组的元素布局。
      elements - 要复制到新分配的内存块的 int 元素。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(ValueLayout.OfFloat PREVIEW  elementLayout, float... elements)
      分配具有给定布局的内存段，并使用给定的浮点元素对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocateArray(layout, array.length) 。
      参数：
      elementLayout - 要分配的数组的元素布局。
      elements - 要复制到新分配的内存块的浮点元素。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(ValueLayout.OfLong PREVIEW  elementLayout, long... elements)
      分配具有给定布局的内存段，并使用给定的 long 元素对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocateArray(layout, array.length) 。
      参数：
      elementLayout - 要分配的数组的元素布局。
      elements - 要复制到新分配的内存块的长元素。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(ValueLayout.OfDouble PREVIEW  elementLayout, double... elements)
      分配具有给定布局的内存段，并使用给定的双精度元素对其进行初始化。
      实现要求：
      此方法的默认实现调用 this.allocateArray(layout, array.length) 。
      参数：
      elementLayout - 要分配的数组的元素布局。
      elements - 要复制到新分配的内存块的双精度元素。
      返回：
      新分配的内存块的段。

    • allocate

      default MemorySegment PREVIEW  allocate(MemoryLayout PREVIEW  layout)
      分配具有给定布局的内存段。
      实现要求：
      此方法的默认实现调用 this.allocate(layout.byteSize(), layout.byteAlignment()) 。
      参数：
      layout - 要分配的内存块的布局。
      返回：
      新分配的内存块的段。

    • allocateArray

      default MemorySegment PREVIEW  allocateArray(MemoryLayout PREVIEW  elementLayout, long count)
      分配具有给定元素布局和大小的内存段。
      实现要求：
      此方法的默认实现调用 this.allocate(MemoryLayout.sequenceLayout(count, elementLayout)) 。
      参数：
      elementLayout - 数组元素布局。
      count - 数组元素计数。
      返回：
      新分配的内存块的段。
      抛出：
      IllegalArgumentException - 如果 count < 0 。

    • allocate

      default MemorySegment PREVIEW  allocate(long byteSize)
      分配给定大小的内存段。
      实现要求：
      此方法的默认实现调用 this.allocate(byteSize, 1) 。
      参数：
      byteSize - 要分配的内存块的大小（以字节为单位）。
      返回：
      新分配的内存块的段。
      抛出：
      IllegalArgumentException - 如果 byteSize < 0

    • allocate

      MemorySegment PREVIEW  allocate(long byteSize, long byteAlignment)
      分配具有给定大小和对齐约束的内存段。
      参数：
      byteSize - 要分配的内存块的大小（以字节为单位）。
      byteAlignment - 要分配的内存块的对齐方式（以字节为单位）。
      返回：
      新分配的内存块的段。
      抛出：
      IllegalArgumentException - 如果 byteSize < 0 、 byteAlignment <= 0 或 alignmentBytes 不是 2 的幂。

    • slicingAllocator

      static SegmentAllocator PREVIEW  slicingAllocator(MemorySegment PREVIEW  segment)
      返回一个段分配器，它通过返回从提供的段中获得的连续切片来响应分配请求。每个新的分配请求将返回一个从当前偏移量开始的新切片（模额外填充以满足对齐约束），具有给定的大小。

      当返回的分配器不能满足分配请求时，例如因为找不到具有请求大小的提供段的切片，将抛出 IndexOutOfBoundsException 。

      参数：
      segment - 返回的分配器应该从中切片的段。
      返回：
      一个新的切片分配器

    • prefixAllocator

      static SegmentAllocator PREVIEW  prefixAllocator(MemorySegment PREVIEW  segment)
      返回一个段分配器，它通过回收单个段来响应分配请求。每个新的分配请求将返回一个从段偏移量 0 开始的新切片（此分配器忽略对齐约束），因此名称为 prefix allocator 。等效于（但可能比）以下代码： 
      MemorySegment segment = ...
SegmentAllocator prefixAllocator = (size, align) -> segment.asSlice(0, size);

      如果客户端知道在后续分配请求发生之前他们已经完全处理了分配段的内容，则此分配器可用于限制分配请求。

      虽然此方法返回的分配器是 thread-safe ，但对同一回收分配器的并发访问可能会导致线程覆盖由不同线程写入底层段的内容。

      参数：
      segment - 返回的分配器要回收的内存段。
      返回：
      一个分配器，它根据每个新的分配请求回收现有的段。

    • nativeAllocator

      static SegmentAllocator PREVIEW  nativeAllocator(SegmentScope PREVIEW  scope)
      用于分配本机段的简单分配器。返回的分配器通过返回由新的堆外内存区域支持的本机段来响应分配请求，具有给定的字节大小和对齐约束。

      返回的分配器获得的每个本机段都与提供的范围相关联。因此，当范围变为 not 活 时，支持返回段的堆外区域被释放PREVIEW .

      MemorySegment.address() PREVIEW 由返回的分配器获得的本机段的起始地址是支持该段的新分配的堆外内存区域的起始地址。此外，addressPREVIEW 本机段的将根据提供的对齐约束对齐。

      支持由返回的分配器获得的本机段的堆外内存区域被初始化为零。

      这等效于以下代码：

      SegmentAllocator nativeAllocator = (byteSize, byteAlignment) ->
  MemorySegment.allocateNative(byteSize, byteAlignment, scope);
      参数：
      scope - 与本机分配器返回的段关联的范围。
      返回：
      用于分配本机段的简单分配器。