- すべてのスーパー・インタフェース:
Addressable
ResourceScope
)の両方に関連付けられています。 空間境界は、メモリー・セグメントに対するメモリー・アクセス操作が、「外部」にアクセスされるメモリー・セグメントの境界よりも少ないメモリーのロケーションに影響を与えないようにします。 時間境界は、メモリー・セグメントに関連付けられたリソース・スコープが(ResourceScope.close()
を参照してください)に閉じられた後に、セグメントに対するメモリー・アクセス操作が発生しないようにします。
このインタフェースのすべての実装はvalue-basedである必要があります。プログラマは、equalのインスタンスを交換可能として扱う必要があり、同期にインスタンスを使用しないでください。そうしないと、予期しない動作が発生する可能性があります。 たとえば、将来のリリースでは、同期が失敗する可能性があります。 比較する場合は、equals
メソッドを使用することをお薦めします。
非プラットフォーム・クラスは、MemorySegmentを直接実装することはできません。
特に指定がないかぎり、null
引数、またはこのクラスのメソッドに1つ以上のnull
要素を含む配列引数を渡すと、NullPointerException
がスローされます。
メモリー・セグメントの構築
メモリー・セグメントを取得する方法は複数あります。 最初に、提供される数多くのファクトリ・メソッドのいずれかを使用して、ヒープ外メモリーによってバックアップされるメモリー・セグメントを割り当てることができます (allocateNative(MemoryLayout, ResourceScope)
、allocateNative(long, ResourceScope)
およびallocateNative(long, long, ResourceScope)
を参照してください。)。 この方法で取得されたメモリー・セグメントは「ネイティブ・メモリー・セグメント」と呼ばれます。
また、用意されているファクトリ・メソッド(e.g. ofArray(int[])
)のいずれかを使用して、既存のヒープ割当てJava配列に連動するメモリー・セグメントを取得することもできます。 この方法で取得されたメモリー・セグメントは「配列メモリー・セグメント」と呼ばれます。
ofByteBuffer(ByteBuffer)
ファクトリ・メソッドを使用して、既存のJavaバイト・バッファ(ByteBuffer
を参照してください)に連動するメモリー・セグメントを取得できます。 この方法で取得されたメモリー・セグメントは「バッファ・メモリー・セグメント」と呼ばれます。 バッファ・メモリー・セグメントは、セグメントが関連付けられているバイト・バッファ・インスタンスの特性に応じて、システム固有のメモリー(ネイティブ・メモリー・セグメントの場合と同様)またはヒープ・メモリー(配列メモリー・セグメントの場合と同様)によってバッキングされる場合があります。 たとえば、ByteBuffer.allocateDirect(int)
メソッドで作成されたバイト・バッファから取得されたバッファ・メモリー・セグメントは、ネイティブ・メモリーによってバックアップされます。
ファイルからのメモリー・セグメントのマッピング
また、ファクトリ・メソッドmapFile(Path, long, long, FileChannel.MapMode, ResourceScope)
を使用して、メモリー・マップ・ファイルによって支えられたネイティブ・メモリー・セグメントを取得することもできます。 このようなネイティブ・メモリー・セグメントは「マッピングされたメモリー・セグメント」と呼ばれ、マップされたメモリー・セグメントは基礎となるファイル記述子に関連付けられます。
マップされたメモリー・セグメントの内容は、基礎となるファイルとの間の「持続」および「ロード済」です。これらの機能は、MappedByteBuffer
クラスの一部の機能に適しています。 セグメントをバイト・バッファ(asByteBuffer()
を参照してください)にマップし、MappedByteBuffer.force()
のようにコールできますが、これは、ByteBuffer APIに固有のサイズ制限のため、ソース・セグメントが十分小さい場合にのみ実行できます。
マップされたメモリー・セグメントに対する高度な制御を必要とするクライアントは、カスタム・マップされたメモリー・セグメント・ファクトリの作成を検討する必要があります。たとえば、Linuxでは、mmap
を必要なパラメータでコールできます。返されるアドレスは、MemoryAddress.ofLong(long)
およびMemoryAddress.asSegment(long, Runnable, ResourceScope)
を使用してメモリー・セグメントに簡単にラップできます。
ライフサイクルおよび制約
メモリー・セグメントは、scope()
メソッドを使用してアクセスできるリソース・スコープ(ResourceScope
を参照してください)に関連付けられています。 リソース・スコープに関連付けられているすべてのリソースについて、対応するスコープが閉じられた後にセグメントにアクセスすることはできません。 たとえば、次のコードは例外になります:
また、メモリー・セグメントへのアクセスは、所有スコープによって強制されるスレッド調整チェックの対象となります。つまり、セグメントが共有スコープに関連付けられている場合は、複数のスレッドからアクセスできます。制限されたスコープに関連付けられている場合は、スコープを所有するスレッドのみがアクセスできます。MemorySegment segment = null; try (ResourceScope scope = ResourceScope.newConfinedScope()) { segment = MemorySegment.allocateNative(8, 1, scope); } MemoryAccess.getLong(segment); // already closed!
ヒープ・セグメントとバッファ・セグメントは、常に「グローバル」共有スコープに関連付けられます。 このスコープは閉じられず、「いつも」と見なすことができます。
メモリー・セグメント・ビュー
メモリー・セグメントは「ビュー」をサポートしています。 たとえば、次のように、メモリー・セグメントの「不変」ビューを作成できます:空間境界が元のセグメント(MemorySegment segment = ... MemorySegment roSegment = segment.asReadOnly();
asSlice(long, long)
を参照してください)のものより厳密であるビューを作成することもできます。
元のセグメントの一時的な境界はビューによって継承されます。つまり、セグメントに関連付けられたスコープが閉じられると、そのセグメントに関連付けられたすべてのビューにアクセスできなくなります。
既存のコードとの相互運用性を確保するために、バイト・バッファ・ビューはメモリー・セグメント(asByteBuffer()
を参照してください)から取得できます。 これは、たとえばByteBuffer
APIを使用したままにする必要があるクライアントでは有用ですが、大量のメモリー・セグメントで操作する必要があります。 このような方法で取得したバイトは、元のメモリー・セグメントに関連付けられた同じ空間および時間アクセス制限をサポートします。
ストリーム・サポート
クライアントがセグメントからStream
を取得すると、セグメント(特定の要素レイアウトに従って)をスライスし、複数のスレッドを分離したセグメント・スライス(このためには、セグメントを共有スコープに関連付ける必要があります)に対して並行して作業できます。 次のコードを使用すると、メモリー・セグメント内のすべてのint値を並列に合計できます:
try (ResourceScope scope = ResourceScope.newSharedScope()) { SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, MemoryLayouts.JAVA_INT); MemorySegment segment = MemorySegment.allocateNative(SEQUENCE_LAYOUT, scope); VarHandle VH_int = SEQUENCE_LAYOUT.elementLayout().varHandle(int.class); int sum = segment.elements(MemoryLayouts.JAVA_INT).parallel() .mapToInt(s -> (int)VH_int.get(s.address())) .sum(); }
- 実装要件:
- このインタフェースの実装は不変、スレッド・セーフ、およびvalue-basedです。
-
メソッドのサマリー
修飾子と型メソッド説明address()
このメモリー・セグメントに関連付けられているベース・メモリー・アドレス。static MemorySegment
allocateNative
(long bytesSize, long alignmentBytes, ResourceScope scope) 指定されたサイズ(バイト単位)、位置合わせ制約(バイト単位)およびリソース・スコープで、オフ・ヒープ・メモリーの新しく割り当てられたブロックをモデル化する、新しい限定されたネイティブ・メモリー・セグメントを作成します。static MemorySegment
allocateNative
(long bytesSize, ResourceScope scope) 指定されたサイズ(バイト単位)およびリソース・スコープを持つオフ・ヒープ・メモリーの新しく割り当てられたブロックをモデル化する、限定された新しいネイティブ・メモリー・セグメントを作成します。static MemorySegment
allocateNative
(MemoryLayout layout, ResourceScope scope) 指定されたレイアウトおよびリソース・スコープを持つ、オフ・ヒープ・メモリーの新しく割り当てられたブロックをモデル化する、新しい限定されたネイティブ・メモリー・セグメントを作成します。ByteBuffer
でこのセグメントをラップします。このセグメントの読取り専用ビューを取得します。default MemorySegment
asSlice
(long offset) ベース・アドレスがこのセグメントのベース・アドレスに指定されたオフセットを加えたものと同じであり、その新しいサイズがこのセグメント・サイズから指定されたオフセットを引いて計算される新しいメモリー・セグメント・ビューを取得します。asSlice
(long offset, long newSize) ベース・アドレスがこのセグメントのベース・アドレスと指定されたオフセットに加えて、指定の引数で新しいサイズが指定されている、新しいメモリー・セグメントのビューを取得します。default MemorySegment
asSlice
(MemoryAddress newBase) ベース・アドレスが指定されたアドレスであり、このセグメント・サイズからこのセグメント(MemoryAddress.segmentOffset(MemorySegment)
を参照してください)に相対的なアドレス・オフセットを減算して新しいサイズが計算される新しいメモリー・セグメント・ビューを取得します。default MemorySegment
asSlice
(MemoryAddress newBase, long newSize) ベース・アドレスが指定されたアドレスであり、新しいサイズが指定された引数で指定されている新しいメモリー・セグメント・ビューを取得します。long
byteSize()
このメモリー・セグメントのサイズは(バイト単位)です。void
copyFrom
(MemorySegment src) 指定されたソース・セグメントからこのセグメントへの一括コピーを実行します。elements
(MemoryLayout elementLayout) このセグメント内の分離スライス(指定したレイアウトのサイズと一致するサイズ)に対して連続したStream
を返します。fill
(byte value) このメモリー・セグメントに値を入力します。void
force()
マップされたセグメント・ファイル記述子によって記述されたストレージ・デバイスに、このマップされたセグメントの内容に加えた変更を強制的に書き込みます。static MemorySegment
ベース・アドレスがMemoryAddress.NULL
で、サイズがLong.MAX_VALUE
のネイティブ・メモリー・セグメントを返します。boolean
isLoaded()
このマップされたセグメントのコンテンツが物理メモリーに存在するかどうかを指示します。boolean
isMapped()
これはマップ済セグメントですか?boolean
isNative()
これはネイティブ・セグメントですか。boolean
このセグメントは読取り専用ですか。void
load()
このマップされたセグメントの内容を物理メモリーにロードします。static MemorySegment
mapFile
(Path path, long bytesOffset, long bytesSize, FileChannel.MapMode mapMode, ResourceScope scope) 指定されたパスからファイルのメモリー・マップのリージョンをモデル化する、新しいマップ済メモリー・セグメントを作成します。long
mismatch
(MemorySegment other) このセグメントと指定された他のセグメント間の最初の不一致のオフセットをバイト単位で検索して返します。static MemorySegment
ofArray
(byte[] arr) 指定されたヒープ割当てのバイト配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。static MemorySegment
ofArray
(char[] arr) 指定されたヒープ割当てのchar配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。static MemorySegment
ofArray
(double[] arr) 指定されたヒープ割当てのdouble配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。static MemorySegment
ofArray
(float[] arr) 指定されたヒープ割当てのfloat配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。static MemorySegment
ofArray
(int[] arr) 指定されたヒープ割当てのint配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。static MemorySegment
ofArray
(long[] arr) 指定されたヒープ割当てのlong配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。static MemorySegment
ofArray
(short[] arr) 指定されたヒープ割当てのshort配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。static MemorySegment
指定されたbyteバッファに関連付けられたメモリーをモデル化する、新しい制限付きバッファ・メモリー・セグメントを作成します。scope()
このメモリー・セグメントに関連付けられたリソース・スコープを返します。spliterator
(MemoryLayout elementLayout) このメモリー・セグメントのスプリッテレータを返します。byte[]
このメモリー・セグメントの内容を新しいバイト配列にコピーします。char[]
このメモリー・セグメントの内容を新しいchar配列にコピーします。double[]
このメモリー・セグメントの内容を新しいdouble配列にコピーします。float[]
このメモリー・セグメントの内容を新しいfloat配列にコピーします。int[]
このメモリー・セグメントの内容を新しいint配列にコピーします。long[]
このメモリー・セグメントの内容を新しいlong配列にコピーします。short[]
このメモリー・セグメントの内容を新しいshort配列にコピーします。void
unload()
このマップされたセグメントの内容を物理メモリーからアンロードします。
-
メソッドの詳細
-
address
MemoryAddress address()このメモリー・セグメントに関連付けられているベース・メモリー・アドレス。 返されるメモリー・アドレスは、このセグメントに関連付けられたものと同じリソース・スコープに関連付けられます。- 定義:
- インタフェース
Addressable
内のaddress
- 戻り値:
- ベース・メモリー・アドレス。
-
spliterator
Spliterator<MemorySegment> spliterator(MemoryLayout elementLayout) このメモリー・セグメントのスプリッテレータを返します。 返されるスプリッテレータは、Spliterator.SIZED
、Spliterator.SUBSIZED
、Spliterator.IMMUTABLE
、Spliterator.NONNULL
およびSpliterator.ORDERED
の特性を報告します。戻されたスプリッタータは、指定された要素レイアウトに従ってこのセグメントを分割します。つまり、指定されたレイアウトにサイズNがある場合、
Spliterator.trySplit()
を呼び出すと、スプリッタは約S/N/2
要素(nが偶数かどうかによって異なります。)をカバーします。ここで、S
はこのセグメントのサイズです。 そのため、S/N >= 2
であれば分割が可能です。 スプリケータは、指定されたセグメントと同じスコープを持つセグメントを返します。返されたスプリッタータは事実上、このセグメントを分離したサブ・セグメントに分割でき、複数のスレッドで並行して処理できます。
- パラメータ:
elementLayout
- 分割に使用されるレイアウト。- 戻り値:
- このセグメントの要素スプリッテレータ
- 例外:
IllegalArgumentException
-elementLayout
サイズがゼロの場合、またはセグメント・サイズ・モジュロの場合、elementLayout
サイズは0より大きくなります。
-
elements
Stream<MemorySegment> elements(MemoryLayout elementLayout) このセグメント内の分離スライス(指定したレイアウトのサイズと一致するサイズ)に対して連続したStream
を返します。 このメソッドの呼出しは、次のコードと同じです:StreamSupport.stream(segment.spliterator(elementLayout), false);
- パラメータ:
elementLayout
- 分割に使用されるレイアウト。- 戻り値:
- このセグメント内の連続した
Stream
スライス。 - 例外:
IllegalArgumentException
-elementLayout
サイズがゼロの場合、またはセグメント・サイズ・モジュロの場合、elementLayout
サイズは0より大きくなります。
-
scope
ResourceScope scope()このメモリー・セグメントに関連付けられたリソース・スコープを返します。- 戻り値:
- このメモリー・セグメントに関連付けられたリソース・スコープ。
-
byteSize
long byteSize()このメモリー・セグメントのサイズは(バイト単位)です。- 戻り値:
- このメモリー・セグメントのサイズは(バイト単位)です。
-
asSlice
MemorySegment asSlice(long offset, long newSize) ベース・アドレスがこのセグメントのベース・アドレスと指定されたオフセットに加えて、指定の引数で新しいサイズが指定されている、新しいメモリー・セグメントのビューを取得します。- パラメータ:
offset
- 新しいセグメント・ベース・オフセット(現在のセグメント・ベース・アドレスとの相対)(バイト単位)です。newSize
- 新しいセグメント・サイズ(バイト単位で指定)。- 戻り値:
- ベース/制限アドレスが更新された新しいメモリー・セグメント・ビュー。
- 例外:
IndexOutOfBoundsException
-offset < 0
、offset > byteSize()
、newSize < 0
またはnewSize > byteSize() - offset
の場合- 関連項目:
-
asSlice
default MemorySegment asSlice(MemoryAddress newBase, long newSize) ベース・アドレスが指定されたアドレスであり、新しいサイズが指定された引数で指定されている新しいメモリー・セグメント・ビューを取得します。次のコードと同等です:
asSlice(newBase.segmentOffset(this), newSize);
- パラメータ:
newBase
- 新しいセグメント・ベース・アドレス。newSize
- 新しいセグメント・サイズ(バイト単位で指定)。- 戻り値:
- ベース/制限アドレスが更新された新しいメモリー・セグメント・ビュー。
- 例外:
IndexOutOfBoundsException
-offset < 0
、offset > byteSize()
、newSize < 0
またはnewSize > byteSize() - offset
の場合- 関連項目:
-
asSlice
default MemorySegment asSlice(long offset) ベース・アドレスがこのセグメントのベース・アドレスに指定されたオフセットを加えたものと同じであり、その新しいサイズがこのセグメント・サイズから指定されたオフセットを引いて計算される新しいメモリー・セグメント・ビューを取得します。次のコードと同等です:
asSlice(offset, byteSize() - offset);
- パラメータ:
offset
- 新しいセグメント・ベース・オフセット(現在のセグメント・ベース・アドレスとの相対)(バイト単位)です。- 戻り値:
- ベース/制限アドレスが更新された新しいメモリー・セグメント・ビュー。
- 例外:
IndexOutOfBoundsException
- ifoffset < 0
,またはoffset > byteSize()
。- 関連項目:
-
asSlice
default MemorySegment asSlice(MemoryAddress newBase) ベース・アドレスが指定されたアドレスであり、このセグメント・サイズからこのセグメント(MemoryAddress.segmentOffset(MemorySegment)
を参照してください)に相対的なアドレス・オフセットを減算して新しいサイズが計算される新しいメモリー・セグメント・ビューを取得します。次のコードと同等です:
asSlice(newBase.segmentOffset(this));
- パラメータ:
newBase
- 新しいセグメント・ベース・オフセット(現在のセグメント・ベース・アドレスとの相対)(バイト単位)です。- 戻り値:
- ベース/制限アドレスが更新された新しいメモリー・セグメント・ビュー。
- 例外:
IndexOutOfBoundsException
- ifaddress.segmentOffset(this) < 0
,またはaddress.segmentOffset(this) > byteSize()
。- 関連項目:
-
isReadOnly
boolean isReadOnly()このセグメントは読取り専用ですか。- 戻り値:
true
、このセグメントが読取り専用の場合。- 関連項目:
-
asReadOnly
MemorySegment asReadOnly()このセグメントの読取り専用ビューを取得します。 結果のセグメントはこのセグメントと同一になりますが、返されたセグメントの内容を上書きしようとすると、ランタイム例外が発生します。- 戻り値:
- このセグメントの読取り専用ビュー
- 関連項目:
-
isNative
boolean isNative()これはネイティブ・セグメントですか。 このセグメントがallocateNative(long, ResourceScope)
(および関連)ファクトリを使用して作成されたネイティブ・メモリー・セグメント、またはofByteBuffer(ByteBuffer)
ファクトリを使用して直接ByteBuffer
から導出されたバッファ・セグメント、または「マップ済」セグメントである場合はtrueを返します。- 戻り値:
- このセグメントがネイティブ・セグメントの場合は
true
。
-
isMapped
boolean isMapped()これはマップ済セグメントですか? このセグメントが、mapFile(Path, long, long, FileChannel.MapMode, ResourceScope)
ファクトリを使用して作成されたマップ済みメモリー・セグメントである場合、またはofByteBuffer(ByteBuffer)
ファクトリを使用してMappedByteBuffer
から派生したバッファ・セグメントである場合にtrueを返します。- 戻り値:
- このセグメントがマップされたセグメントである場合は
true
。
-
fill
MemorySegment fill(byte value) このメモリー・セグメントに値を入力します。具体的には、指定された値がこのセグメントの各アドレスに入力されます。 (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです:
設定される特定のメモリー要素の順序を考慮または保証しません。byteHandle = MemoryLayout.ofSequence(MemoryLayouts.JAVA_BYTE) .varHandle(byte.class, MemoryLayout.PathElement.sequenceElement()); for (long l = 0; l < segment.byteSize(); l++) { byteHandle.set(segment.address(), l, value); }
フィルは、セグメントのメモリーを初期化またはリセットする場合に便利です。
- パラメータ:
value
- このセグメントに入力する値- 戻り値:
- このメモリー・セグメント
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生する場合、UnsupportedOperationException
- このセグメントが読取り専用(isReadOnly()
を参照してください)の場合。
-
copyFrom
void copyFrom(MemorySegment src) 指定されたソース・セグメントからこのセグメントへの一括コピーを実行します。 具体的には、ソース・セグメントのオフセット0
からsrc.byteSize() - 1
までのバイトは、src.byteSize() - 1
を介したオフセット0
でこのセグメントにコピーされます。 ソース・セグメントがこのセグメントと重複する場合、コピーは、ソース・セグメント内のsrc.byteSize() - 1
を介してオフセット0
のバイトが最初にサイズがbytes
の一時セグメントにコピーされたかのように実行され、一時セグメントの内容がsrc.byteSize() - 1
を介してオフセット0
でこのセグメントにコピーされます。ソース・セグメントとこのセグメントが重複せず、異なるアドレスを使用して同じバッキング・ストレージの重複するリージョンを参照している場合、一括コピーの結果は不確定です。 たとえば、同じファイルが複数のセグメントに対して「マップ済」である場合に発生することがあります。
- パラメータ:
src
- ソース・セグメント。- 例外:
IndexOutOfBoundsException
-src.byteSize() > this.byteSize()
の場合。IllegalStateException
- ソース・セグメントに関連付けられたスコープまたはこのセグメントに関連付けられたスコープがすでにクローズされている場合、またはどちらか一方のスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。UnsupportedOperationException
- このセグメントが読取り専用(isReadOnly()
を参照してください)の場合。
-
mismatch
long mismatch(MemorySegment other) このセグメントと指定された他のセグメント間の最初の不一致のオフセットをバイト単位で検索して返します。 オフセットは各セグメントの「拠点アドレス」を基準とし、0 (inclusive)から小さいメモリー・セグメント(exclusive)のsize (バイト単位)までの範囲になります。2つのセグメントが共通のプレフィクスを共有している場合、返されるオフセットは共通のプレフィクスの長さであり、各セグメント内のそのオフセットにある2つのセグメント間に不一致があることに従います。 一方のセグメントが他方のセグメントの適切なプレフィクスである場合、返されるオフセットはセグメント・サイズの小さい方になり、オフセットは大きいセグメントに対してのみ有効であることに従います。 それ以外の場合、不一致はなく、
-1
が返されます。- パラメータ:
other
- このセグメントとの不一致をテストするセグメント- 戻り値:
- このセグメントと指定された他のセグメント間の最初の不一致の相対オフセット(バイト)。不一致がない場合は -1
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープまたはother
セグメントに関連付けられたスコープがすでにクローズされている場合、またはどちらか一方のスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。
-
isLoaded
boolean isLoaded()このマップされたセグメントのコンテンツが物理メモリーに存在するかどうかを指示します。true
の戻り値は、このセグメントのすべてのデータが物理メモリーに常駐している可能性が高いため、仮想メモリーのページ・フォルトやI/O操作を発生させずにアクセスできることを意味します。 戻り値のfalse
は、このセグメント・コンテンツが物理メモリーに存在していないことを必ずしも意味しません。返される値は、保証ではなくヒントです。これは、基礎となるオペレーティング・システムが、このメソッドを呼び出したときにこのセグメント・データの一部をページアウトしたためです。
- 戻り値:
- このセグメントの内容が物理メモリーに存在する可能性がある場合は
true
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。UnsupportedOperationException
- このセグメントがマップされたメモリー・セグメントでない場合(例:isMapped() == false
)。
-
load
void load()このマップされたセグメントの内容を物理メモリーにロードします。このメソッドを使用すると、このセグメントのこの内容が物理メモリーに常駐していることを確認できます。 このメソッドを呼び出すと、ページ違反や入出力操作が発生する可能性があります。
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。UnsupportedOperationException
- このセグメントがマップされたメモリー・セグメントでない場合(例:isMapped() == false
)。
-
unload
void unload()このマップされたセグメントの内容を物理メモリーからアンロードします。このメソッドは、このセグメントのコンテンツが物理メモリーに存在しなくなるように最善の努力をします。 このメソッドを呼び出した後にこのセグメントの内容にアクセスすると、いくつかのページ・フォルトおよびI/O操作が(このセグメント・コンテンツはページ・インする必要がある可能性があるため)に発生する可能性があります。
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。UnsupportedOperationException
- このセグメントがマップされたメモリー・セグメントでない場合(例:isMapped() == false
)。
-
force
void force()マップされたセグメント・ファイル記述子によって記述されたストレージ・デバイスに、このマップされたセグメントの内容に加えた変更を強制的に書き込みます。このマップされたセグメントに関連付けられているファイル記述子がローカル・ストレージ・デバイスに存在する場合、このメソッドが返すとき、このセグメントが作成されてからこのセグメントに加えられたすべての変更、またはこのメソッドが最後に呼び出されてから、そのデバイスに書き込まれていることが保証されます。
このマップされたセグメントに関連付けられているファイル記述子がローカル・デバイスに存在しない場合は、そのような保証は行われません。
このセグメントが読取り/書込みモードの(
FileChannel.MapMode.READ_WRITE
)でマップされていない場合、このメソッドを呼び出しても効果がない可能性があります。 特に、このメソッドは、読取り専用またはプライベート・マッピング・モードでマップされたセグメントには影響しません。 このメソッドは、実装固有のマッピング・モードに有効である場合も、そうでない場合もあります。- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。UnsupportedOperationException
- このセグメントがマップされたメモリー・セグメントでない場合(例:isMapped() == false
)。UncheckedIOException
- このセグメントの内容を関連するストレージ・デバイスに書き込むI/Oエラーがある場合
-
asByteBuffer
ByteBuffer asByteBuffer()ByteBuffer
でこのセグメントをラップします。 返されたバッファのプロパティの一部は、このセグメントのプロパティにリンクされています。 たとえば、このセグメントが「不変」 (たとえば、セグメントは読取り専用セグメントです。isReadOnly()
を参照してください)の場合、生成されるバッファはread-onlyです(Buffer.isReadOnly()
を参照)。 また、これがネイティブ・メモリー・セグメントの場合は、結果のバッファはdirect (ByteBuffer.isDirect()
を参照してください)になります。戻されるバッファ位置(
Buffer.position()
を参照)。一方、戻されるバッファ容量および制限の(Buffer.capacity()
およびBuffer.limit()
をそれぞれ参照)は、このセグメントのサイズ(byteSize()
を参照してください)に設定されます。 このため、このセグメントのサイズがInteger.MAX_VALUE
より大きい場合、byteバッファは返されません。返されるバッファのライフサイクルは、このセグメントのライフサイクルと関連します。 つまり、このセグメントに関連付けられたスコープがクローズされた後に返されるバッファにアクセスすると、
IllegalStateException
がスローされます(ResourceScope.close()
を参照)。このセグメントが限定されたスコープに関連付けられている場合、結果のバッファに対する読取り/書込みI/O操作を呼び出すと、未指定の例外がスローされることがあります。 このような問題のある操作の例としては、
AsynchronousSocketChannel.read(ByteBuffer)
およびAsynchronousSocketChannel.write(ByteBuffer)
があります。最後に、結果のバッファ・バイト順序は
ByteOrder.BIG_ENDIAN
です。これは、ByteBuffer.order(java.nio.ByteOrder)
を使用して変更できます。- 戻り値:
- このメモリー・セグメントの
ByteBuffer
ビュー。 - 例外:
UnsupportedOperationException
- このセグメントをByteBuffer
インスタンスにマップできない場合(たとえば、byte[]
に基づいていないヒープ・ベースのセグメントをモデル化するため)、またはそのサイズがInteger.MAX_VALUE
より大きい場合。
-
toByteArray
byte[] toByteArray()このメモリー・セグメントの内容を新しいバイト配列にコピーします。- 戻り値:
- このメモリー・セグメントの新しいバイト配列のコピー。
- 例外:
IllegalStateException
- このセグメントに関連付けられているスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生する場合、またはこのセグメントの内容をbyte
インスタンスにコピーできない場合(たとえば、そのサイズはInteger.MAX_VALUE
より大きい場合)。
-
toShortArray
short[] toShortArray()このメモリー・セグメントの内容を新しいshort配列にコピーします。- 戻り値:
- このメモリー・セグメントの新しいshort配列コピー。
- 例外:
IllegalStateException
- このセグメントに関連付けられているスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合、またはこのセグメントの内容をshort
インスタンスにコピーできない場合(たとえば、byteSize() % 2 != 0
やbyteSize() / 2 > Integer#MAX_VALUE
など)
-
toCharArray
char[] toCharArray()このメモリー・セグメントの内容を新しいchar配列にコピーします。- 戻り値:
- このメモリー・セグメントの新しいchar配列コピー。
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生する場合、またはこのセグメントの内容をchar
インスタンスにコピーできない場合(byteSize() % 2 != 0
やbyteSize() / 2 > Integer#MAX_VALUE
など)、。
-
toIntArray
int[] toIntArray()このメモリー・セグメントの内容を新しいint配列にコピーします。- 戻り値:
- このメモリー・セグメントの新しいint配列コピー。
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生する場合、またはこのセグメントの内容をint
インスタンスにコピーできない場合(byteSize() % 4 != 0
やbyteSize() / 4 > Integer#MAX_VALUE
など)、。
-
toFloatArray
float[] toFloatArray()このメモリー・セグメントの内容を新しいfloat配列にコピーします。- 戻り値:
- このメモリー・セグメントの新しいfloat配列コピー。
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生する場合、またはこのセグメントの内容をfloat
インスタンスにコピーできない場合(byteSize() % 4 != 0
やbyteSize() / 4 > Integer#MAX_VALUE
など)、。
-
toLongArray
long[] toLongArray()このメモリー・セグメントの内容を新しいlong配列にコピーします。- 戻り値:
- このメモリー・セグメントの新しいlong配列コピー。
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生する場合、またはこのセグメントの内容をlong
インスタンスにコピーできない場合(byteSize() % 8 != 0
やbyteSize() / 8 > Integer#MAX_VALUE
など)、。
-
toDoubleArray
double[] toDoubleArray()このメモリー・セグメントの内容を新しいdouble配列にコピーします。- 戻り値:
- このメモリー・セグメントの新しいdouble配列コピー。
- 例外:
IllegalStateException
- このセグメントに関連付けられたスコープがクローズされている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生する場合、またはこのセグメントの内容をdouble
インスタンスにコピーできない場合(byteSize() % 8 != 0
やbyteSize() / 8 > Integer#MAX_VALUE
など)、。
-
ofByteBuffer
static MemorySegment ofByteBuffer(ByteBuffer bb) 指定されたbyteバッファに関連付けられたメモリーをモデル化する、新しい制限付きバッファ・メモリー・セグメントを作成します。 セグメントはバッファ位置(inclusive)から相対的に始まり、バッファ制限(exclusive)に対して相対的に終わります。バッファが
read-only
の場合、結果のセグメントもread-only
になります。 このセグメントに関連付けられたスコープは、バッファが独立して作成された場合や、asByteBuffer()
を使用してバッファが取得された場合に備えて、「グローバル」リソース・スコープ、その他の(かも)リソース・スコープのいずれかになります。作成されたメモリー・セグメントは、バッキング・バッファへの参照を維持し、「到達可能」のままにします。
- パラメータ:
bb
- バッファ・メモリー・セグメントをバッキングするバイト・バッファ。- 戻り値:
- 新しいバッファ・メモリー・セグメント。
-
ofArray
static MemorySegment ofArray(byte[] arr) 指定されたヒープ割当てのバイト配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。 返されるセグメント・リソース・スコープは、「グローバル」リソース・スコープに設定されます。- パラメータ:
arr
- 配列メモリー・セグメントにバックアップするプリミティブ配列。- 戻り値:
- 新しい配列メモリー・セグメント。
-
ofArray
static MemorySegment ofArray(char[] arr) 指定されたヒープ割当てのchar配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。 返されるセグメント・リソース・スコープは、「グローバル」リソース・スコープに設定されます。- パラメータ:
arr
- 配列メモリー・セグメントにバックアップするプリミティブ配列。- 戻り値:
- 新しい配列メモリー・セグメント。
-
ofArray
static MemorySegment ofArray(short[] arr) 指定されたヒープ割当てのshort配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。 返されるセグメント・リソース・スコープは、「グローバル」リソース・スコープに設定されます。- パラメータ:
arr
- 配列メモリー・セグメントにバックアップするプリミティブ配列。- 戻り値:
- 新しい配列メモリー・セグメント。
-
ofArray
static MemorySegment ofArray(int[] arr) 指定されたヒープ割当てのint配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。 返されるセグメント・リソース・スコープは、「グローバル」リソース・スコープに設定されます。- パラメータ:
arr
- 配列メモリー・セグメントにバックアップするプリミティブ配列。- 戻り値:
- 新しい配列メモリー・セグメント。
-
ofArray
static MemorySegment ofArray(float[] arr) 指定されたヒープ割当てのfloat配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。 返されるセグメント・リソース・スコープは、「グローバル」リソース・スコープに設定されます。- パラメータ:
arr
- 配列メモリー・セグメントにバックアップするプリミティブ配列。- 戻り値:
- 新しい配列メモリー・セグメント。
-
ofArray
static MemorySegment ofArray(long[] arr) 指定されたヒープ割当てのlong配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。 返されるセグメント・リソース・スコープは、「グローバル」リソース・スコープに設定されます。- パラメータ:
arr
- 配列メモリー・セグメントにバックアップするプリミティブ配列。- 戻り値:
- 新しい配列メモリー・セグメント。
-
ofArray
static MemorySegment ofArray(double[] arr) 指定されたヒープ割当てのdouble配列に関連付けられたメモリーをモデル化する新しい制限付き配列メモリー・セグメントを作成します。 返されるセグメント・リソース・スコープは、「グローバル」リソース・スコープに設定されます。- パラメータ:
arr
- 配列メモリー・セグメントにバックアップするプリミティブ配列。- 戻り値:
- 新しい配列メモリー・セグメント。
-
allocateNative
static MemorySegment allocateNative(MemoryLayout layout, ResourceScope scope) 指定されたレイアウトおよびリソース・スコープを持つ、オフ・ヒープ・メモリーの新しく割り当てられたブロックをモデル化する、新しい限定されたネイティブ・メモリー・セグメントを作成します。 クライアントは、セグメントが使用されなくなったときに、返されたセグメントに関連付けられたリソース・スコープがクローズされていることを確認します。 これを行わなかった場合、ヒープ外のメモリー・リークが発生します。これは次のコードと等価です。
allocateNative(layout.bytesSize(), layout.bytesAlignment(), scope);
返されたネイティブ・メモリー・セグメントに関連するoff-heapメモリーのブロックは、ゼロに初期化されます。
- パラメータ:
layout
- ネイティブ・メモリー・セグメントのバッキングの非ヒープ・メモリー・ブロックのレイアウト。scope
- 。セグメント範囲を指定します。- 戻り値:
- 新しいネイティブ・メモリー・セグメント。
- 例外:
IllegalArgumentException
- 指定されたレイアウトに不正なサイズ制約または位置合せ制約がある場合。IllegalStateException
-scope
がすでにクローズされている場合、またはscope
を所有するスレッド以外のスレッドからアクセスが発生した場合。
-
allocateNative
static MemorySegment allocateNative(long bytesSize, ResourceScope scope) 指定されたサイズ(バイト単位)およびリソース・スコープを持つオフ・ヒープ・メモリーの新しく割り当てられたブロックをモデル化する、限定された新しいネイティブ・メモリー・セグメントを作成します。 クライアントは、セグメントが使用されなくなったときに、返されたセグメントに関連付けられたリソース・スコープがクローズされていることを確認します。 これを行わなかった場合、ヒープ外のメモリー・リークが発生します。これは次のコードと等価です。
allocateNative(bytesSize, 1, scope);
返されたネイティブ・メモリー・セグメントに関連するoff-heapメモリーのブロックは、ゼロに初期化されます。
- パラメータ:
bytesSize
- ネイティブ・メモリー・セグメントのバッキングのヒープ外メモリー・ブロックのサイズ(バイト単位)。scope
- 。セグメント範囲を指定します。- 戻り値:
- 新しいネイティブ・メモリー・セグメント。
- 例外:
IllegalArgumentException
-bytesSize <= 0
の場合。IllegalStateException
-scope
がすでにクローズされている場合、またはscope
を所有するスレッド以外のスレッドからアクセスが発生した場合。
-
allocateNative
static MemorySegment allocateNative(long bytesSize, long alignmentBytes, ResourceScope scope) 指定されたサイズ(バイト単位)、位置合わせ制約(バイト単位)およびリソース・スコープで、オフ・ヒープ・メモリーの新しく割り当てられたブロックをモデル化する、新しい限定されたネイティブ・メモリー・セグメントを作成します。 クライアントは、セグメントが使用されなくなったときに、返されたセグメントに関連付けられたリソース・スコープがクローズされていることを確認します。 これを行わなかった場合、ヒープ外のメモリー・リークが発生します。返されたネイティブ・メモリー・セグメントに関連するoff-heapメモリーのブロックは、ゼロに初期化されます。
- パラメータ:
bytesSize
- ネイティブ・メモリー・セグメントのバッキングのヒープ外メモリー・ブロックのサイズ(バイト単位)。alignmentBytes
- ネイティブ・メモリー・セグメントのバッキングのヒープ外メモリー・ブロックの位置合せ制約(バイト単位)。scope
- 。セグメント範囲を指定します。- 戻り値:
- 新しいネイティブ・メモリー・セグメント。
- 例外:
IllegalArgumentException
-bytesSize <= 0
、alignmentBytes <= 0
またはalignmentBytes
が2の累乗でない場合。IllegalStateException
-scope
がすでにクローズされている場合、またはscope
を所有するスレッド以外のスレッドからアクセスが発生した場合。
-
mapFile
static MemorySegment mapFile(Path path, long bytesOffset, long bytesSize, FileChannel.MapMode mapMode, ResourceScope scope) throws IOException 指定されたパスからファイルのメモリー・マップのリージョンをモデル化する、新しいマップ済メモリー・セグメントを作成します。指定されたマッピング・モードがREAD_ONLYの場合、結果のセグメントは読取り専用(
isReadOnly()
を参照してください)になります。マップされたメモリー・セグメントの内容は、マップされたファイルの対応するリージョンの内容がこの(または別の)プログラムによって変更される場合など、いつでも変更できます。 こうした変更が発生するかどうか、またどのタイミングで発生するかは、オペレーティング・システムによって異なるため、未指定です。
マップされたメモリー・セグメントのすべてまたは一部は、バッキング・マップ・ファイルが切り捨てられた場合など、いつでもアクセスできなくなる可能性があります。 マップされたメモリー・セグメントのアクセス不可能なリージョンにアクセスしようとしても、セグメントの内容は変更されず、アクセス時または後で未指定の例外がスローされます。 したがって、ファイルの内容の読取りまたは書込みを除き、この(または別の)プログラムによるマップ済ファイルの操作を回避するために、適切な注意を払うことを強くお薦めします。
- 実装上のノート:
- 新たに作成されたファイルからマップされたセグメントを取得する場合、返されたマップ済メモリー・セグメントに関連付けられているマップ済メモリー・ブロックのコンテンツの初期化状態は未指定であり、判断すべきではありません。
- パラメータ:
path
- メモリー・マップへのファイルのパス。bytesOffset
- マップされたセグメントを開始するファイル内のオフセット(バイトで表されます。)。bytesSize
- メモリー・セグメントをバッキングするマップ済メモリーのサイズ(バイト単位)。mapMode
- ファイル・マッピング・モード。FileChannel.map(FileChannel.MapMode, long, long)
を参照してください。選択したマッピング・モードは、返されるメモリー・マップ・セグメント(force()
を参照してください)の動作に影響する可能性があります。scope
- 。セグメント範囲を指定します。- 戻り値:
- 新しい制限されたマップ済メモリー・セグメント。
- 例外:
IllegalArgumentException
-bytesOffset < 0
、bytesSize < 0
またはpath
がデフォルトのファイル・システムに関連付けられていない場合。IllegalStateException
-scope
がすでにクローズされている場合、またはscope
を所有するスレッド以外のスレッドからアクセスが発生した場合。UnsupportedOperationException
- サポートされていないマップ・モードが指定された場合。IOException
- 指定したパスが既存のファイルを指し示していないか、他のI/Oエラーが発生した場合。SecurityException
- セキュリティ・マネージャがインストールされ、それが実装によって必要とされる未指定のアクセス権を拒否する場合。 デフォルト・プロバイダで、ファイルが読取り用に開かれた場合は、SecurityManager.checkRead(String)
メソッドが呼び出されてファイルへの読取りアクセスがチェックされます。 ファイルが書込み用に開かれた場合は、SecurityManager.checkWrite(String)
メソッドが呼び出されて書込みアクセスがチェックされます。
-
globalNativeSegment
static MemorySegment globalNativeSegment()ベース・アドレスがMemoryAddress.NULL
で、サイズがLong.MAX_VALUE
のネイティブ・メモリー・セグメントを返します。 このメソッドは、ネイティブ・ライブラリと対話するときに取得したメモリー・アドレスを間接参照する場合に非常に便利です。 返されるセグメントは、「グローバル」リソース・スコープ(ResourceScope.globalScope()
を参照してください)に関連付けられています。 (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです:MemoryAddress.NULL.asSegment(Long.MAX_VALUE)
このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。
- 戻り値:
- ベース・アドレスが
MemoryAddress.NULL
で、サイズがLong.MAX_VALUE
であるメモリー・セグメント。 - 例外:
IllegalCallerException
- このメソッドへのアクセスがモジュールM
から発生し、コマンドライン・オプション--enable-native-access
がない場合、またはモジュール名M
が名前なしモジュールの場合はALL-UNNAMED
は説明しません。
-