- すべてのスーパー・インタフェース:
AutoCloseable
,SegmentAllocatorPREVIEW
Arena
は、JavaプラットフォームのプレビューAPIです。
アリーナには、アリーナ・スコープと呼ばれるscopeがあります。 アリーナがclosedの場合、アリーナ・スコープはalivePREVIEWではなくなります。 その結果、アリーナ・スコープに関連付けられたすべてのセグメントは、安全かつ不可分に無効化され、そのバッキング・メモリー・リージョンは(該当する場合)の割当てが解除され、アリーナのクローズ後にアクセスできなくなります:
try (Arena arena = Arena.openConfined()) {
MemorySegment segment = MemorySegment.allocateNative(100, arena.scope());
...
} // memory released here
SegmentAllocator
PREVIEWです。 アリーナによるすべてのセグメント「割当済」は、アリーナ・スコープに関連付けられます。 これは、次に示すように、外部コードと対話する場合に非常に役立ちます:
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
-
メソッドのサマリー
修飾子と型メソッド説明default MemorySegmentPREVIEW
allocate
(long byteSize, long byteAlignment) 指定されたサイズ(バイト単位)および整列制約(バイト単位)のネイティブ・メモリー・セグメントを返します。void
close()
このアリーナを閉じます。boolean
isCloseableBy
(Thread thread) 指定されたスレッドがこのアリーナを閉じることができる場合は、true
を返します。現在のスレッドが所有する新しい限定されたアリーナを返します。新しい共有領域を返します。scope()
arenaスコープを返します。インタフェースjava.lang.foreign.SegmentAllocatorPREVIEWで宣言されたメソッド
allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateUtf8String
-
メソッドの詳細
-
allocate
default MemorySegmentPREVIEW allocate(long byteSize, long byteAlignment) 指定されたサイズ(バイト単位)および整列制約(バイト単位)のネイティブ・メモリー・セグメントを返します。 返されるセグメントは、アリーナ・スコープに関連付けられます。 セグメントのaddress
PREVIEWは、セグメントを支える割当て済のオフ・ヒープ・メモリー・リージョンの開始アドレスで、指定された整列制約に従ってアドレスが整列されます。- 定義:
- インタフェース
SegmentAllocatorPREVIEW
内のallocate
- 実装要件:
- このメソッドのデフォルト実装は、次のコードと同等です:
MemorySegment.allocateNative(bytesSize, byteAlignment, scope());
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
現在のスレッドが所有する新しい限定されたアリーナを返します。- 戻り値:
- 現在のスレッドが所有する新しい限定アリーナ
-
Arena
を使用できます。