モジュール java.base
パッケージ java.lang.foreign

インタフェースArena

すべてのスーパー・インタフェース:
AutoCloseable, SegmentAllocatorPREVIEW
public interface Arena extends SegmentAllocatorPREVIEW, AutoCloseable
Arenaは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでArenaを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
アリーナはメモリー・セグメントのライフサイクルを制御し、柔軟な割り当てとタイムリな割り当て解除の両方を提供します。

アリーナには、アリーナ・スコープと呼ばれるscopeがあります。 アリーナがclosedの場合、アリーナ・スコープはalivePREVIEWではなくなります。 その結果、アリーナ・スコープに関連付けられたすべてのセグメントは、安全かつ不可分に無効化され、そのバッキング・メモリー・リージョンは(該当する場合)の割当てが解除され、アリーナのクローズ後にアクセスできなくなります: 

 try (Arena arena = Arena.openConfined()) {
     MemorySegment segment = MemorySegment.allocateNative(100, arena.scope());
     ...
 } // memory released here
さらに、アリーナはSegmentAllocatorPREVIEWです。 アリーナによるすべてのセグメント「割当済」は、アリーナ・スコープに関連付けられます。 これは、次に示すように、外部コードと対話する場合に非常に役立ちます: 
 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

安全性とスレッドの制約

Arenasは強力な時間的安全保証を提供: アリーナが割り当てたメモリー・セグメントには、そのアリーナを閉じたあとはアクセスできません。 この保証を提供するコストは、アリーナによって割り当てられたメモリー・セグメントにアクセスできるスレッドの数によって異なります。 たとえば、アリーナが常に1つのスレッドによって作成およびクローズされ、アリーナのスコープに関連付けられたメモリー・セグメントに常に同じスレッドからアクセスされる場合は、正確さが微妙であることを確認します。

逆に、アリーナが複数のスレッドからアクセスできるセグメントを割り当てる場合や、アクセスしているスレッド以外のスレッドでアリーナをクローズできる場合は、正確さがはるかに複雑になります。 たとえば、アリーナに割り当てられているセグメントには、whileにもう一度アクセスして、アリーナを閉じようとします。 すべてのクライアント(単純なクライアントでも)パフォーマンスへの影響を発生させることなく、強力な時間的安全保証を提供するために、領域がthread-confined領域およびshared領域に分割されます。

限られた領域で、強力なスレッド制約の保証をサポートします。 作成時に、「所有者スレッド」(通常は作成演算を開始したスレッド)が割り当てられます。 限定されたアリーナによって作成されたセグメントは、所有者スレッドによってのみ「アクセス済」PREVIEWにできます。 さらに、所有者スレッド以外のスレッドから制限されたアリーナを閉じようとすると、WrongThreadExceptionで失敗します。

一方、共有領域には所有者スレッドがありません。 共有アリーナによって作成されたセグメントは、どのスレッドでも「アクセス済」PREVIEWにすることができます。 これは、複数のスレッドが同じメモリー・セグメントに同時に(例:パラレル処理の場合)にアクセスする必要がある場合に役立ちます。 また、任意のスレッドによる共有アリーナ「クローズ可能」。

導入されたバージョン:
20

  • メソッドの詳細

    • allocate

      default MemorySegmentPREVIEW allocate(long byteSize, long byteAlignment)
      指定されたサイズ(バイト単位)および整列制約(バイト単位)のネイティブ・メモリー・セグメントを返します。 返されるセグメントは、アリーナ・スコープに関連付けられます。 セグメントのaddressPREVIEWは、セグメントを支える割当て済のオフ・ヒープ・メモリー・リージョンの開始アドレスで、指定された整列制約に従ってアドレスが整列されます。
      定義:
      インタフェースSegmentAllocatorPREVIEW内のallocate
      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です: 
       MemorySegment.allocateNative(bytesSize, byteAlignment, scope());
      より一般的には、このメソッドの実装では、リクエストされたサイズを持つネイティブ・セグメントを返す必要があり、指定された整列制約と互換性があります。 さらに、このメソッドによって返される2つのセグメントS1, S2の場合、次の不変量を保持する必要があります: 
       S1.overlappingSlice(S2).isEmpty() == true
      パラメータ:
      byteSize - ネイティブ・メモリー・セグメントのバッキングのヒープ外メモリー・ブロックのサイズ(バイト単位)。
      byteAlignment - ネイティブ・メモリー・セグメントをバッキングするメモリーのオフ・ヒープ・リージョンの境界整列制約 (バイト単位)。
      戻り値:
      新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalArgumentException - bytesSize < 0、alignmentBytes <= 0またはalignmentBytesが2の累乗でない場合。
      IllegalStateException - アリーナがすでにclosedである場合。
      WrongThreadException - このメソッドがスレッドTから呼び出された場合(scope().isAccessibleBy(T) == falseなど)。
      関連項目:

    • scope

      SegmentScopePREVIEW scope()
      arenaスコープを返します。
      戻り値:
      arenaスコープ

    • close

      void close()
      このアリーナを閉じます。 このメソッドが正常に完了すると、アリーナ・スコープはalivePREVIEWではなくなり、それに関連付けられたすべてのメモリー・セグメントにアクセスできなくなります。 さらに、そのスコープに関連付けられたセグメントをバッキングするメモリーのオフ・ヒープ・リージョンも解放されます。
      定義:
      close、インタフェースAutoCloseable
      APIのノート:
      この操作はべき等ではありません。つまり、すでに閉じているアリーナalwaysを閉じると、例外がスローされます。 これは意図的な設計の選択を反映しています: アリーナのクローズに失敗すると、基礎となるアプリケーション・ロジックにバグが表示される場合があります。
      例外:
      IllegalStateException - アリーナがすでに閉まっている場合。
      IllegalStateException - arenaスコープが「生かし」PREVIEWの場合。
      WrongThreadException - このメソッドがスレッドTから呼び出された場合(isCloseableBy(T) == falseなど)。
      関連項目:

    • isCloseableBy

      boolean isCloseableBy(Thread thread)
      指定されたスレッドがこのアリーナを閉じることができる場合は、trueを返します。
      パラメータ:
      thread - テストするスレッド。
      戻り値:
      指定されたスレッドがこのアリーナを閉じることができる場合はtrue

    • openConfined

      static ArenaPREVIEW openConfined()
      現在のスレッドが所有する新しい限定されたアリーナを返します。
      戻り値:
      現在のスレッドが所有する新しい限定アリーナ

    • openShared

      static ArenaPREVIEW openShared()
      新しい共有領域を返します。
      戻り値:
      新しい共有アリーナ