模块 java.base
包 java.lang.foreign

接口 Arena

所有父级接口：
AutoCloseable , SegmentAllocatorPREVIEW
public interface Arena extends SegmentAllocator PREVIEW , AutoCloseable
Arena 是 Java 平台的预览 API。
程序只能在启用预览功能时使用 Arena。
预览功能可能会在未来的版本中删除，或升级为 Java 平台的永久功能。
arena 控制内存段的生命周期，提供灵活的分配和及时的释放。

竞技场有一个 scope ，称为竞技场范围。当竞技场是 关闭 时，竞技场范围不再是 活PREVIEW .结果，所有与 arena 作用域关联的段都被安全地和原子地失效，它们的后备内存区域被释放（如果适用）并且在 arena 关闭后不能再被访问：

 try (Arena arena = Arena.openConfined()) {
   MemorySegment segment = MemorySegment.allocateNative(100, arena.scope());
   ...
 } // memory released here
此外，竞技场是SegmentAllocator PREVIEW . arena 的所有段 分配的 都与 arena 范围相关联。这使得 arenas 在与外部代码交互时非常有用，如下所示： 
 try (Arena arena = Arena.openConfined()) {
   MemorySegment nativeArray = arena.allocateArray(ValueLayout.JAVA_INT, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
   MemorySegment nativeString = arena.allocateUtf8String("Hello!");
   MemorySegment upcallStub = linker.upcallStub(handle, desc, arena.scope());
   ...
 } // memory released here

安全和线程限制

竞技场提供强大的时间安全保证：无法访问竞技场分配的内存段after竞技场已关闭。提供此保证的成本根据有权访问由 arena 分配的内存段的线程数而有所不同。例如，如果一个 arena 总是由一个线程创建和关闭，并且与 arena 范围关联的内存段总是由同一个线程访问，那么确保正确性是微不足道的。

相反，如果 arena 分配的段可以被多个线程访问，或者如果 arena 可以被访问线程以外的线程关闭，那么确保正确性要复杂得多。例如，分配了竞技场的段可能会被访问while另一个线程同时尝试关闭竞技场。为了提供强大的时间安全保证而不强迫每个客户端，即使是简单的客户端，也会对性能产生影响，arenas 分为thread-confinedarenas 和sharedarenas。

受限竞技场，支持强大的线程限制保证。创建时，它们会被分配一个 所有者线程 ，通常是发起创建操作的线程。受限竞技场创建的段只能是访问过PREVIEW 由所有者线程。此外，任何从所有者线程以外的线程关闭受限区域的尝试都将失败并返回 WrongThreadException 。

另一方面，共享竞技场没有所有者线程。共享区域创建的段可以是访问过PREVIEW 通过任何线程。当多个线程需要同时访问同一个内存段时（例如，在并行处理的情况下），这可能很有用。此外，任何线程共享一个 arena 可以关闭。

自从：
20

  • 方法详情

    • allocate

      default MemorySegment PREVIEW  allocate(long byteSize, long byteAlignment)
      返回具有给定大小（以字节为单位）和对齐约束（以字节为单位）的本机内存段。返回的段与竞技场范围相关联。该段的address PREVIEW 是支持该段的已分配堆外内存区域的起始地址，该地址根据提供的对齐约束进行对齐。
      指定者：
      allocate 在接口 SegmentAllocatorPREVIEW 中
      实现要求：
      此方法的默认实现等效于以下代码： 
       MemorySegment.allocateNative(bytesSize, byteAlignment, scope());
      更一般地，此方法的实现必须返回具有请求大小的本机段，并且与提供的对齐约束兼容。此外，对于此方法返回的任意两个段 S1, S2，必须满足以下不变量： 
       S1.overlappingSlice(S2).isEmpty() == true
      参数：
      byteSize - 支持本机内存段的堆外内存块的大小（以字节为单位）。
      byteAlignment - 支持本机内存段的堆外内存区域的对齐约束（以字节为单位）。
      返回：
      一个新的本机内存段。
      抛出：
      IllegalArgumentException - 如果 bytesSize < 0 、 alignmentBytes <= 0 或 alignmentBytes 不是 2 的幂。
      IllegalStateException - 如果竞技场已经是 关闭 。
      WrongThreadException - 如果从线程 T 调用此方法，则 scope().isAccessibleBy(T) == false 。
      参见：

    • scope

      SegmentScope PREVIEW  scope()
      返回竞技场范围。
      返回：
      竞技场范围

    • close

      void close()
      关闭这个竞技场。如果此方法正常完成，则竞技场范围不再是 活PREVIEW ，并且与它相关联的所有内存段都不能再被访问。此外，任何支持与该范围关联的段的堆外内存区域也将被释放。
      指定者：
      close 在接口 AutoCloseable 中
      API 注意：
      此操作不是幂等的；也就是说，关闭一个已经关闭的 arena always 会导致抛出异常。这反映了一种深思熟虑的设计选择：未能关闭竞技场可能会揭示底层应用程序逻辑中的错误。
      抛出：
      IllegalStateException - 如果竞技场已经关闭。
      IllegalStateException - 如果竞技场范围是 保持活力PREVIEW .
      WrongThreadException - 如果从线程 T 调用此方法，则 isCloseableBy(T) == false 。
      参见：

    • isCloseableBy

      boolean isCloseableBy(Thread  thread)
      如果提供的线程可以关闭此竞技场，则返回 true。
      参数：
      thread - 要测试的线程。
      返回：
      true 如果提供的线程可以关闭这个竞技场

    • openConfined

      static Arena PREVIEW  openConfined()
      返回一个新的受限竞技场，由当前线程拥有。
      返回：
      一个新的受限竞技场，由当前线程拥有

    • openShared

      static Arena PREVIEW  openShared()
      返回一个新的共享区域。
      返回：
      一个新的共享舞台