モジュール jdk.incubator.foreign

パッケージ jdk.incubator.foreign

インタフェースMemorySegment

すべてのスーパー・インタフェース:

Addressable

public sealed interface MemorySegment extends 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です。

メソッドのサマリー

修飾子と型	メソッド	説明
MemoryAddress	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	asByteBuffer()	ByteBufferでこのセグメントをラップします。
MemorySegment	asReadOnly()	このセグメントの読取り専用ビューを取得します。
default MemorySegment	asSlice(long offset)	ベース・アドレスがこのセグメントのベース・アドレスに指定されたオフセットを加えたものと同じであり、その新しいサイズがこのセグメント・サイズから指定されたオフセットを引いて計算される新しいメモリー・セグメント・ビューを取得します。
MemorySegment	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)	指定されたソース・セグメントからこのセグメントへの一括コピーを実行します。
Stream<MemorySegment>	elements(MemoryLayout elementLayout)	このセグメント内の分離スライス(指定したレイアウトのサイズと一致するサイズ)に対して連続したStreamを返します。
MemorySegment	fill(byte value)	このメモリー・セグメントに値を入力します。
void	force()	マップされたセグメント・ファイル記述子によって記述されたストレージ・デバイスに、このマップされたセグメントの内容に加えた変更を強制的に書き込みます。
static MemorySegment	globalNativeSegment()	ベース・アドレスがMemoryAddress.NULLで、サイズがLong.MAX_VALUEのネイティブ・メモリー・セグメントを返します。
boolean	isLoaded()	このマップされたセグメントのコンテンツが物理メモリーに存在するかどうかを指示します。
boolean	isMapped()	これはマップ済セグメントですか?
boolean	isNative()	これはネイティブ・セグメントですか。
boolean	isReadOnly()	このセグメントは読取り専用ですか。
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	ofByteBuffer(ByteBuffer bb)	指定されたbyteバッファに関連付けられたメモリーをモデル化する、新しい制限付きバッファ・メモリー・セグメントを作成します。
ResourceScope	scope()	このメモリー・セグメントに関連付けられたリソース・スコープを返します。
Spliterator<MemorySegment>	spliterator(MemoryLayout elementLayout)	このメモリー・セグメントのスプリッテレータを返します。
byte[]	toByteArray()	このメモリー・セグメントの内容を新しいバイト配列にコピーします。
char[]	toCharArray()	このメモリー・セグメントの内容を新しいchar配列にコピーします。
double[]	toDoubleArray()	このメモリー・セグメントの内容を新しいdouble配列にコピーします。
float[]	toFloatArray()	このメモリー・セグメントの内容を新しいfloat配列にコピーします。
int[]	toIntArray()	このメモリー・セグメントの内容を新しいint配列にコピーします。
long[]	toLongArray()	このメモリー・セグメントの内容を新しいlong配列にコピーします。
short[]	toShortArray()	このメモリー・セグメントの内容を新しい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(long)
• asSlice(MemoryAddress)
• asSlice(MemoryAddress, long)

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(long)
• asSlice(MemoryAddress)
• asSlice(long, long)

asSlice

default MemorySegment asSlice(long offset)

ベース・アドレスがこのセグメントのベース・アドレスに指定されたオフセットを加えたものと同じであり、その新しいサイズがこのセグメント・サイズから指定されたオフセットを引いて計算される新しいメモリー・セグメント・ビューを取得します。

次のコードと同等です:

    asSlice(offset, byteSize() - offset);
 

パラメータ:

offset - 新しいセグメント・ベース・オフセット(現在のセグメント・ベース・アドレスとの相対)(バイト単位)です。

戻り値:

ベース/制限アドレスが更新された新しいメモリー・セグメント・ビュー。

例外:

IndexOutOfBoundsException - if offset < 0,またはoffset > byteSize()。

関連項目:

• asSlice(MemoryAddress)
• asSlice(MemoryAddress, long)
• asSlice(long, long)

asSlice

default MemorySegment asSlice(MemoryAddress newBase)

ベース・アドレスが指定されたアドレスであり、このセグメント・サイズからこのセグメント(MemoryAddress.segmentOffset(MemorySegment)を参照してください)に相対的なアドレス・オフセットを減算して新しいサイズが計算される新しいメモリー・セグメント・ビューを取得します。

次のコードと同等です:

    asSlice(newBase.segmentOffset(this));
 

パラメータ:

newBase - 新しいセグメント・ベース・オフセット(現在のセグメント・ベース・アドレスとの相対)(バイト単位)です。

戻り値:

ベース/制限アドレスが更新された新しいメモリー・セグメント・ビュー。

例外:

IndexOutOfBoundsException - if address.segmentOffset(this) < 0,またはaddress.segmentOffset(this) > byteSize()。

関連項目:

• asSlice(long)
• asSlice(MemoryAddress, long)
• asSlice(long, long)

isReadOnly

boolean isReadOnly()

このセグメントは読取り専用ですか。

戻り値:

true、このセグメントが読取り専用の場合。

関連項目:

• asReadOnly()

asReadOnly

MemorySegment asReadOnly()

このセグメントの読取り専用ビューを取得します。 結果のセグメントはこのセグメントと同一になりますが、返されたセグメントの内容を上書きしようとすると、ランタイム例外が発生します。

戻り値:

このセグメントの読取り専用ビュー

関連項目:

• isReadOnly()

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は説明しません。