モジュール jdk.incubator.foreign
パッケージ jdk.incubator.foreign

インタフェースMemorySegment

すべてのスーパー・インタフェース:
AutoCloseable
既知のすべてのサブインタフェース:
MappedMemorySegment
public interface MemorySegment
extends AutoCloseable
メモリー・セグメントは、連続するメモリー・リージョンをモデル化します。 メモリー・セグメントは、空間境界および時間的境界の両方に関連付けられます。 空間境界は、メモリー・セグメントに対するメモリー・アクセス操作が、「外部」にアクセスされるメモリー・セグメントの境界よりも少ないメモリーのロケーションに影響を与えないようにします。 一時境界を使用すると、メモリー・セグメントが(close()を参照してください)でクローズされた後に、セグメントに対するメモリー・アクセス操作を実行できなくなります。

このインタフェースのすべての実装はvalue-basedである必要があります。MemorySegmentのインスタンスでアイデンティティに依存する操作(参照の等価性の(==)、アイデンティティ・ハッシュ・コード、同期化など)を使用すると、予期しない結果が生じる可能性があるため、使用しないでください。 比較する場合は、equalsメソッドを使用することをお薦めします。

非プラットフォーム・クラスは、MemorySegmentを直接実装することはできません。

異なるソースからのメモリー・セグメントの構成

メモリー・セグメントを取得する方法は複数あります。 最初に、(allocateNative(MemoryLayout)、allocateNative(long)およびallocateNative(long, long)を参照してください。)から提供される数多くのファクトリ・メソッドのいずれかを使用して、ヒープ外メモリーによってバックアップされるメモリー・セグメントを割り当てることができます。 この方法で取得されたメモリー・セグメントは「ネイティブ・メモリー・セグメント」と呼ばれます。

また、用意されているファクトリ・メソッド(e.g. ofArray(int[]))のいずれかを使用して、既存のヒープ割当てJava配列に連動するメモリー・セグメントを取得することもできます。 この方法で取得されたメモリー・セグメントは「配列メモリー・セグメント」と呼ばれます。

ofByteBuffer(ByteBuffer)ファクトリ・メソッドを使用して、既存のJavaバイト・バッファ(ByteBufferを参照してください)に連動するメモリー・セグメントを取得できます。 この方法で取得されたメモリー・セグメントは「バッファ・メモリー・セグメント」と呼ばれます。 バッファ・メモリー・セグメントは、セグメントが関連付けられているバイト・バッファ・インスタンスの特性に応じて、システム固有のメモリー(ネイティブ・メモリー・セグメントの場合と同様)またはヒープ・メモリー(配列メモリー・セグメントの場合と同様)によってバッキングされる場合があります。 たとえば、ByteBuffer.allocateDirect(int)メソッドで作成されたバイト・バッファから取得されたバッファ・メモリー・セグメントは、ネイティブ・メモリーによってバックアップされます。

最後に、ファクトリ・メソッドmapFromPath(Path, long, long, FileChannel.MapMode)を使用して、メモリー・マップ・ファイルでバックアップされたメモリー・セグメントを取得することもできます。 このようなメモリー・セグメントは、「マッピングされたメモリー・セグメント」 (MappedMemorySegmentを参照してください)と呼ばれます。

配列セグメントおよびバッファ・セグメントは、既存のメモリー・リージョン全体で効果的に「ビュー」となり、それらから導出されたセグメントのライフサイクルを上回り、他のクライアントから直接(配列アクセスやByteBuffer APIの直接使用など)を操作することもできます。 そのため、配列セグメントまたはバッファ・セグメントを共有することは可能ですが、そのようなセグメントに関連付けられた基礎となるメモリー・ソースがアクセス不可能なままであること、および同時に複数のセグメントによって別名が設定されないことを確認するために、クライアントは追加の注意を払うことを強くお薦めします - たとえば、配列またはバッファ・セグメントの内容が同時に変更されないようにします。

メモリー・セグメントを閉じる

メモリー・セグメントは明示的に(close()を参照してください)でクローズされます。 セグメントがクローズされると、そのセグメントはaliveではなくなります(isAlive()を参照してください。セグメント(またはそれから導出されたMemoryAddressインスタンス)に対する後続の操作はIllegalStateExceptionで失敗します。

セグメントをクローズすると、考慮されるメモリー・セグメントの種類に応じて、指定されたセグメントに関連付けられた基礎となるメモリー・リソースの解放がトリガーされる場合があります:

  • ネイティブ・メモリー・セグメントを閉じると、「解放」のネイティブ・メモリーがそのセグメントに関連付けられます。
  • マップされたメモリー・セグメントを閉じると、バッキング・マップのファイルがマップ解除されます
  • バッファを閉じる、またはヒープ・セグメントに副次効果がない(セグメントを「生きていない」 (isAlive()を参照してください)とマークする以外)。 また、バッファおよびヒープ・セグメントは元のバッファまたは配列インスタンスへの強力な参照を維持しているため、クライアントはこれらのセグメントが適時に破棄されるようにする必要があります。したがって、ガベージ・コレクションによって基礎となるオブジェクトの再利用を妨げないようにする必要があります。

アクセス・モード

メモリー・セグメントでは、ゼロ個以上の「アクセス・モード」がサポートされます。 サポートされているアクセス・モードは、READ、WRITE、CLOSE、ACQUIREおよびHANDOFFです。 セグメントでサポートされているアクセス・モードのセットによって、そのセグメントでサポートされている一連の操作が変更されます。 たとえば、CLOSEアクセス・モードをサポートしていないセグメントでclose()をコールしようとすると、例外が発生します。

サポートされているアクセス・モードのセットは、より厳密な(「より少ない」アクセス・モードのサポート)にのみできます。 つまり、セグメントの作成者がセグメントへのアクセス方法を制御する必要がある場合は、セグメントを他のクライアントと共有する前に、セグメントでサポートされるアクセス・モードのセットを制限することをお薦めします。

メモリー・セグメント・ビュー

メモリー・セグメントは「ビュー」をサポートしています。 たとえば、次のようにメモリー・セグメントの「不変」ビューを作成することで、サポートされているアクセス・モードのセットを変更できます: 

MemorySegment segment = ...
MemorySegment roSegment = segment.withAccessModes(segment.accessModes() & ~WRITE);
空間境界が元のセグメント(asSlice(long, long)を参照してください)のものより厳密であるビューを作成することもできます。

元のセグメントの一時的境界はビューによって継承されます。つまり、分割されたビューなどのセグメント・ビューを閉じると、元のセグメントが閉じます。複数のクライアント間でビューを共有する場合は、特別な注意を払う必要があります。 別のアクターによるセグメントの早期クローズからクライアント自体を保護する場合は、別のクライアントとビューを共有する前に、サポートされているアクセス・モードのセットからCLOSEを削除するなどの保護対策を講じる必要があります。

既存のコードとの相互運用性を確保するために、バイト・バッファ・ビューはメモリー・セグメント(asByteBuffer()を参照してください)から取得できます。 これは、たとえばByteBuffer APIを使用したままにする必要があるクライアントでは有用ですが、大量のメモリー・セグメントで操作する必要があります。 このような方法で取得されたバイト・バッファでは、元のメモリー・セグメントに関連付けられた空間および一時的なアクセス制限がサポートされます。

スレッド制限

メモリー・セグメントは、強力なスレッド定義の保証をサポートしています。 作成時に、「所有者スレッド」に割り当てられるのは通常、作成操作を開始したスレッドです。 作成後は、所有者のスレッドだけがメモリー・セグメント(例:メモリー・セグメントを閉じます)を直接操作したり、メモリー・アクセスのvarハンドルを使用してセグメントに関連する基になるメモリーにアクセスしたりできます。 所有者スレッド以外のスレッドからこのような操作を実行しようとすると、実行時に失敗します。

メモリー・セグメントは「シリアル・スレッド制限」をサポートします。つまり、メモリー・セグメントの所有権は(withOwnerThread(Thread)を参照してください)を変更できます。 これにより、たとえば、AとBの2つのスレッドで、制御された協調的で競合のない方法でセグメントを共有できます。

場合によっては、複数のスレッドが同じメモリー・セグメントの内容を同時に(例:パラレル処理の場合)で処理すると便利なことがあります。一方、メモリー・セグメントは強い制限保証を提供しますが、セグメントからSpliteratorを取得することもできます。これは、セグメントをスライスし、複数のスレッドが非結合セグメント・スライス(これは、アクセス・モードACQUIREが設定されていることを前提としています。)で並行して動作できるようにするために使用できます。 たとえば、次のコードを使用すると、メモリー・セグメント内のすべてのint値を並列に合計できます: 


MemorySegment segment = ...
SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.ofSequence(1024, MemoryLayouts.JAVA_INT);
VarHandle VH_int = SEQUENCE_LAYOUT.elementLayout().varHandle(int.class);
int sum = StreamSupport.stream(MemorySegment.spliterator(segment, SEQUENCE_LAYOUT), true)
                       .mapToInt(s -> (int)VH_int.get(s.baseAddress()))
                       .sum();

APIのノート:
将来、Java言語で許可される場合、MemorySegmentはsealedインタフェースになり、MappedMemorySegmentおよび他の明示的に許可されたサブタイプ以外のサブクラス化が禁止される可能性があります。
実装要件:
このインタフェースの実装は不変、スレッド・セーフ、およびvalue-basedです。

  • フィールドのサマリー

    フィールド
    修飾子と型 フィールド 説明
    static int ACQUIRE
    アクセス・モードを取得します。このセグメントは、スプリッテレータ(spliterator(MemorySegment, SequenceLayout)を参照してください)を介した所有者スレッド以外のスレッドとの共有をサポートします。
    static int ALL_ACCESS
    デフォルトのアクセス・モード。これは、メモリー・セグメントでサポートされているすべてのアクセス・モードの和集合です。
    static int CLOSE
    アクセス・モードをクローズします。close()のコールは、このアクセス・モードをサポートするセグメントでサポートされます。
    static int HANDOFF
    ハンド・オフ・アクセス・モード。このセグメントは、スレッド所有権変更(withOwnerThread(Thread)を参照してください)を介したシリアル・スレッド定義をサポートします。
    static int READ
    読取りアクセス・モード。読取り操作は、このアクセス・モードをサポートするセグメントでサポートされます。
    static int WRITE
    書込みアクセス・モード。書込み操作は、このアクセス・モードをサポートするセグメントでサポートされます。

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    int accessModes()
    このセグメントに関連付けられた「アクセス・モード」を返します。結果は、READ、WRITE、CLOSE、ACQUIREおよびHANDOFFからのORed値として表されます。
    static MemorySegment allocateNative​(long bytesSize)
    指定されたサイズ(バイト単位)で新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。
    static MemorySegment allocateNative​(long bytesSize, long alignmentBytes)
    指定されたサイズおよび位置合せ制約(バイト単位)を使用して、新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。
    static MemorySegment allocateNative​(MemoryLayout layout)
    指定されたレイアウトで新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。
    ByteBuffer asByteBuffer()
    ByteBufferでこのセグメントをラップします。
    MemorySegment asSlice​(long offset, long newSize)
    ベース・アドレスがこのセグメントのベース・アドレスと指定されたオフセットに加えて、指定の引数で新しいサイズが指定されている、新しいメモリー・セグメントのビューを取得します。
    MemoryAddress baseAddress()
    このメモリー・セグメントに関連付けられているベース・メモリー・アドレス。
    long byteSize()
    このメモリー・セグメントのサイズは(バイト単位)です。
    void close()
    このメモリー・セグメントを閉じます。
    void copyFrom​(MemorySegment src)
    指定されたソース・セグメントからこのセグメントへの一括コピーを実行します。
    MemorySegment fill​(byte value)
    このメモリー・セグメントに値を入力します。
    boolean hasAccessModes​(int accessModes)
    このセグメントは特定のアクセス・モードのセットをサポートしていますか。
    boolean isAlive()
    このセグメントは動作していますか。
    static MappedMemorySegment mapFromPath​(Path path, long bytesOffset, long bytesSize, FileChannel.MapMode mapMode)
    指定されたパスからファイルのメモリー・マップのリージョンをモデル化する、新しいマップ済メモリー・セグメントを作成します。
    long mismatch​(MemorySegment other)
    このセグメントと指定された他のセグメント間の最初の不一致のオフセットをバイト単位で検索して返します。
    static MemorySegment ofArray​(byte[] arr)
    指定のヒープ割当てバイト配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。
    static MemorySegment ofArray​(char[] arr)
    指定のヒープ割当て文字配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。
    static MemorySegment ofArray​(double[] arr)
    指定のヒープ割当て済二重配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。
    static MemorySegment ofArray​(float[] arr)
    指定のヒープ割当て浮動小数配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。
    static MemorySegment ofArray​(int[] arr)
    指定のヒープ割当て済int配列に関連付けられているメモリーをモデル化する新しい配列メモリー・セグメントを作成します。
    static MemorySegment ofArray​(long[] arr)
    指定のヒープ割当て済ロング配列に関連付けられているメモリーをモデル化する新しい配列メモリー・セグメントを作成します。
    static MemorySegment ofArray​(short[] arr)
    指定のヒープ割当て済短い配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。
    static MemorySegment ofByteBuffer​(ByteBuffer bb)
    指定されたバイト・バッファに関連付けられたメモリーをモデル化する新しいバッファ・メモリー・セグメントを作成します。
    static MemorySegment ofNativeRestricted​(MemoryAddress addr, long bytesSize, Thread owner, Runnable cleanup, Object attachment)
    指定されたベース・アドレスとサイズを持つ新しいネイティブ・メモリー・セグメントを返します。返されるセグメントには独自の時間的境界があるため、閉じることができます。そのようなセグメントを閉じると、オプションでユーザー指定のクリーンアップ・アクションが呼び出される可能性があります。
    Thread ownerThread()
    このセグメントを所有しているスレッド。
    static <S extends MemorySegment>
    Spliterator<S>    		 spliterator​(S segment, SequenceLayout layout)
    指定されたメモリー・セグメントのスプリッテレータを返します。
    byte[] toByteArray()
    このメモリー・セグメントの内容を新しいバイト配列にコピーします。
    MemorySegment withAccessModes​(int accessModes)
    特定の「アクセス・モード」を持つセグメント・ビューを取得します。
    MemorySegment withOwnerThread​(Thread newOwner)
    このセグメントと同じ基礎となるメモリー・リージョンに連動しているが、所有者スレッドが異なる新しいメモリー・セグメントを取得します。

  • フィールド詳細

  • メソッドの詳細

    • baseAddress

      MemoryAddress baseAddress()
      このメモリー・セグメントに関連付けられているベース・メモリー・アドレス。 返されるアドレスはcheckedメモリー・アドレスであるため、(MemoryAddressを参照してください)のリフレッシュ操作で使用できます。
      戻り値:
      ベース・メモリー・アドレス。

    • spliterator

      static <S extends MemorySegment> Spliterator<S> spliterator​(S segment, SequenceLayout layout)
      指定されたメモリー・セグメントのスプリッテレータを返します。 返されるスプリッテレータは、Spliterator.SIZED、Spliterator.SUBSIZED、Spliterator.IMMUTABLE、Spliterator.NONNULLおよびSpliterator.ORDEREDの特性を報告します。

      返されたスプリッテレータは、指定されたシーケンス・レイアウトに従ってセグメントを分割します。つまり、指定されたレイアウトが要素数がNのシーケンス・レイアウトである場合、Spliterator.trySplit()を呼び出すとスプリッテレータは概算のN/2要素(nが偶数かどうかによって異なります。)を提供します。 そのため、N >= 2であれば分割が可能です。 スプリッテレータは、指定されたセグメントからCLOSEアクセス・モードを引いたものと同じ「アクセス・モード」を特徴とするセグメントを返します。

      返されたスプリッテレータを使用すると、セグメントを分割して非結合のサブ・セグメントにし、複数のスレッド(アクセス・モードACQUIREが設定されている場合)で並行して処理できます。 保留中の同時実行中にセグメント(close()を参照してください)をクローズすると、通常は例外で失敗しますが、スプリッテレータが取得されたが、Spliterator.tryAdvance(Consumer)を使用してアクティブに動作しているスレッドがない場合は、セグメントをクローズできます。このような場合、Spliterator.tryAdvance(Consumer)への後続のコールは例外で失敗します。

      型パラメータ:
      S - メモリー・セグメント・タイプ
      パラメータ:
      segment - 分割に使用されるセグメント。
      layout - 分割に使用されるレイアウト。
      戻り値:
      このセグメントの要素スプリッテレータ
      例外:
      IllegalStateException - セグメントがaliveでない場合、またはこのセグメントを所有するスレッド以外のスレッドからアクセスが発生した場合

    • ownerThread

      Thread ownerThread()
      このセグメントを所有しているスレッド。
      戻り値:
      このセグメントを所有しているスレッド。

    • withOwnerThread

      MemorySegment withOwnerThread​(Thread newOwner)
      このセグメントと同じ基礎となるメモリー・リージョンに連動しているが、所有者スレッドが異なる新しいメモリー・セグメントを取得します。 副作用として、このセグメントは「生きていない」としてマークされ、このセグメントに対する後続の操作でランタイム・エラーが発生します。

      現在の所有者スレッドから新しい所有者スレッドへのhappens-beforeハンド・オーバーのセグメント・コンテンツへの書込みアクセス権。これにより、「以前に発生」は新しい所有者スレッド上のセグメント・コンテンツへの読取りアクセス権を持ちます。

      パラメータ:
      newOwner - 新しい所有者スレッド。
      戻り値:
      newOwnerが所有する、このセグメントと同じ基礎となるメモリー・リージョンに連動する新しいメモリー・セグメント。
      例外:
      IllegalStateException - このセグメントがaliveでない場合、またはこのセグメントを所有するスレッド以外のスレッドからアクセスが発生した場合、または別のスレッド(spliterator(MemorySegment, SequenceLayout)を参照してください)によって操作されているためにセグメントを閉じることができない場合。
      NullPointerException - newOwner == nullの場合
      IllegalArgumentException - セグメントがnewOnwerによって制限付きセグメント所有者である場合。
      UnsupportedOperationException - このセグメントがHANDOFFアクセス・モードをサポートしていない場合。

    • byteSize

      long byteSize()
      このメモリー・セグメントのサイズは(バイト単位)です。
      戻り値:
      このメモリー・セグメントのサイズは(バイト単位)です。

    • withAccessModes

      MemorySegment withAccessModes​(int accessModes)
      特定の「アクセス・モード」を持つセグメント・ビューを取得します。 サポートされているアクセス・モードは、READ、WRITE、CLOSE、ACQUIREおよびHANDOFFです。 一般に、より厳密なアクセス・モードのセグメントからより厳密でないアクセス・モードのセグメントに移動することはできません。 たとえば、読取り専用セグメントにWRITEアクセス・モードを追加しようとすると、例外が発生します。
      パラメータ:
      accessModes - ゼロ個以上のアクセス・モードのORedマスク。
      戻り値:
      特定のアクセス・モードを持つセグメント・ビュー。
      例外:
      IllegalArgumentException - maskがこのセグメントでサポートされているアクセス・マスクよりも厳密でない場合、またはサポートされているどのアクセス・モードにも関連付けられていないビットがmaskに含まれている場合。

    • hasAccessModes

      boolean hasAccessModes​(int accessModes)
      このセグメントは特定のアクセス・モードのセットをサポートしていますか。
      パラメータ:
      accessModes - ゼロ個以上のアクセス・モードのORedマスク。
      戻り値:
      accessModesのアクセス・モードがこのセグメントでサポートされているアクセス・モードより厳しい場合はtrue。
      例外:
      IllegalArgumentException - サポートされているどのアクセス・モードにも関連付けられていないビットがmaskに含まれている場合。

    • accessModes

      int accessModes()
      このセグメントに関連付けられた「アクセス・モード」を返します。結果は、READ、WRITE、CLOSE、ACQUIREおよびHANDOFFからのORed値として表されます。
      戻り値:
      このセグメントに関連付けられたアクセス・モード。

    • asSlice

      MemorySegment asSlice​(long offset, long newSize)
      ベース・アドレスがこのセグメントのベース・アドレスと指定されたオフセットに加えて、指定の引数で新しいサイズが指定されている、新しいメモリー・セグメントのビューを取得します。
      パラメータ:
      offset - 新しいセグメント・ベース・オフセット(現在のセグメント・ベース・アドレスとの相対)(バイト単位)です。
      newSize - 新しいセグメント・サイズ(バイト単位で指定)。
      戻り値:
      ベース/制限アドレスが更新された新しいメモリー・セグメント・ビュー。
      例外:
      IndexOutOfBoundsException - offset < 0、offset > byteSize()、newSize < 0またはnewSize > byteSize() - offsetの場合

    • isAlive

      boolean isAlive()
      このセグメントは動作していますか。
      戻り値:
      true:セグメントが有効な場合。
      関連項目:
      close()

    • close

      void close()
      このメモリー・セグメントを閉じます。 メモリー・セグメントがクローズされると、そのメモリー・セグメントを使用しようとしたり、関連付けられているMemoryAddressインスタンスにアクセスしようとすると、IllegalStateExceptionで失敗します。 クローズされるメモリー・セグメントの種類に応じて、このメソッドをコールすると、メモリー・セグメントに関連付けられているすべてのリソースの割当て解除がさらにトリガーされます。
      定義:
      close、インタフェース: AutoCloseable
      例外:
      IllegalStateException - このセグメントがaliveでない場合、またはこのセグメントを所有するスレッド以外のスレッドからアクセスが発生した場合、または別のスレッド(spliterator(MemorySegment, SequenceLayout)を参照してください)によって操作されているためにセグメントを閉じることができない場合。
      UnsupportedOperationException - このセグメントがCLOSEアクセス・モードをサポートしていない場合。

    • 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.baseAddress(), l, value);
}
      設定される特定のメモリー要素の順序を考慮または保証しません。

      フィルは、セグメントのメモリーを初期化またはリセットする場合に便利です。

      パラメータ:
      value - このセグメントに入力する値
      戻り値:
      このメモリー・セグメント
      例外:
      IllegalStateException - このセグメントがaliveでない場合、またはこのセグメントを所有するスレッド以外のスレッドからアクセスが発生した場合
      UnsupportedOperationException - このセグメントがWRITEアクセス・モードをサポートしていない場合

    • copyFrom

      void copyFrom​(MemorySegment src)
      指定されたソース・セグメントからこのセグメントへの一括コピーを実行します。 具体的には、ソース・セグメントのオフセット0からsrc.byteSize() - 1までのバイトは、src.byteSize() - 1を介したオフセット0でこのセグメントにコピーされます。 ソース・セグメントがこのセグメントと重複する場合、コピーは、ソース・セグメント内のsrc.byteSize() - 1を介してオフセット0のバイトが最初にサイズがbytesの一時セグメントにコピーされたかのように実行され、一時セグメントの内容がsrc.byteSize() - 1を介してオフセット0でこのセグメントにコピーされます。

      ソース・セグメントとこのセグメントが重複せず、異なるアドレスを使用して同じバッキング・ストレージの重複するリージョンを参照している場合、一括コピーの結果は不確定です。 たとえば、同じファイルが複数のセグメントに対してmappedである場合に発生することがあります。

      パラメータ:
      src - ソース・セグメント。
      例外:
      IndexOutOfBoundsException - src.byteSize() > this.byteSize()の場合。
      IllegalStateException - ソース・セグメントまたはこのセグメントがすでにクローズされている場合、またはいずれかのセグメントを所有しているスレッド以外のスレッドからアクセスが発生した場合。
      UnsupportedOperationException - ソース・セグメントまたはこのセグメントのいずれかが必要なアクセス・モードを機能していない場合。具体的には、srcは少なくともREADアクセス・モードを機能させ、このセグメントは少なくともWRITEアクセス・モードを機能させる必要があります。

    • mismatch

      long mismatch​(MemorySegment other)
      このセグメントと指定された他のセグメント間の最初の不一致のオフセットをバイト単位で検索して返します。 オフセットは各セグメントのbase addressに対して相対的で、小さいメモリー・セグメント(exclusive)のsize (バイト単位)までの0 (inclusive)の範囲になります。

      2つのセグメントが共通のプレフィクスを共有している場合、返されるオフセットは共通のプレフィクスの長さであり、各セグメント内のそのオフセットにある2つのセグメント間に不一致があることに従います。 一方のセグメントが他方のセグメントの適切なプレフィクスである場合、返されるオフセットはセグメント・サイズの小さい方になり、オフセットは大きいセグメントに対してのみ有効であることに従います。 それ以外の場合、不一致はなく、 -1が返されます。

      パラメータ:
      other - このセグメントとの不一致をテストするセグメント
      戻り値:
      このセグメントと指定された他のセグメント間の最初の不一致の相対オフセット(バイト)。不一致がない場合は -1
      例外:
      IllegalStateException - 他のセグメントのこのセグメントがすでにクローズされている場合、またはいずれかのセグメントを所有しているスレッド以外のスレッドからアクセスが発生した場合
      UnsupportedOperationException - このセグメントまたは他のセグメントが少なくともREADアクセス・モードを機能していない場合

    • asByteBuffer

      ByteBuffer asByteBuffer()
      ByteBufferでこのセグメントをラップします。 返されたバッファのプロパティの一部は、このセグメントのプロパティにリンクされています。 たとえば、このセグメントが「不変」 (たとえば、セグメントにはアクセス・モードREADがありますが、WRITEはありません。)の場合、結果のバッファはread-onlyになります(Buffer.isReadOnly()を参照)。 また、これがネイティブ・メモリー・セグメントの場合は、結果のバッファはdirect (ByteBuffer.isDirect()を参照してください)になります。

      返されるバッファのライフサイクルは、このセグメントのライフサイクルと関連します。 これは、このセグメントが閉じられている場合(close()を参照)、返されたバッファにアクセスするとIllegalStateExceptionがスローされることを意味します。

      生成されるバッファ・バイト順はByteOrder.BIG_ENDIANです。これは、ByteBuffer.order(java.nio.ByteOrder)を使用して変更できます。

      戻り値:
      このメモリー・セグメントのByteBufferビュー。
      例外:
      UnsupportedOperationException - このセグメントをByteBufferインスタンスにマップできない場合(たとえば、byte[]に基づかないヒープ・ベースのセグメントをモデル化する場合)、そのサイズがInteger.MAX_VALUEより大きい場合、またはセグメントがREADアクセス・モードをサポートしていない場合。

    • toByteArray

      byte[] toByteArray()
      このメモリー・セグメントの内容を新しいバイト配列にコピーします。
      戻り値:
      このメモリー・セグメントの新しいバイト配列のコピー。
      例外:
      UnsupportedOperationException - このセグメントがREADアクセス・モードを機能していない場合、またはこのセグメントの内容をbyteインスタンスにコピーできない場合(たとえば、サイズがInteger.MAX_VALUEより大きい場合)、
      IllegalStateException - このセグメントがクローズされている場合、またはこのセグメントを所有しているスレッド以外のスレッドからアクセスが発生した場合。

    • ofByteBuffer

      static MemorySegment ofByteBuffer​(ByteBuffer bb)
      指定されたバイト・バッファに関連付けられたメモリーをモデル化する新しいバッファ・メモリー・セグメントを作成します。 セグメントはバッファ位置(inclusive)から相対的に始まり、バッファ制限(exclusive)に対して相対的に終わります。

      指定されたバッファがread-onlyでないかぎり、セグメントはすべての「アクセス・モード」 (ALL_ACCESSを参照してください)を機能します。この場合、セグメントはWRITEアクセス・モードを機能しません。

      結果のメモリー・セグメントは、バッキングバッファへの参照を保持しているため、セグメントの有効期間「到達可能」のままです。

      パラメータ:
      bb - バッファ・メモリー・セグメントをバッキングするバイト・バッファ。
      戻り値:
      新しいバッファ・メモリー・セグメント。

    • ofArray

      static MemorySegment ofArray​(byte[] arr)
      指定のヒープ割当てバイト配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。

      結果のメモリー・セグメントは、バッキング配列への参照を保持し、セグメントの有効期間中「到達可能」を保持します。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。

      パラメータ:
      arr - 配列メモリー・セグメントにバックアップするプリミティブ配列。
      戻り値:
      新しい配列メモリー・セグメント。

    • ofArray

      static MemorySegment ofArray​(char[] arr)
      指定のヒープ割当て文字配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。

      結果のメモリー・セグメントは、バッキング配列への参照を保持し、セグメントの有効期間中「到達可能」を保持します。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。

      パラメータ:
      arr - 配列メモリー・セグメントにバックアップするプリミティブ配列。
      戻り値:
      新しい配列メモリー・セグメント。

    • ofArray

      static MemorySegment ofArray​(short[] arr)
      指定のヒープ割当て済短い配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。

      結果のメモリー・セグメントは、バッキング配列への参照を保持し、セグメントの有効期間中「到達可能」を保持します。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。

      パラメータ:
      arr - 配列メモリー・セグメントにバックアップするプリミティブ配列。
      戻り値:
      新しい配列メモリー・セグメント。

    • ofArray

      static MemorySegment ofArray​(int[] arr)
      指定のヒープ割当て済int配列に関連付けられているメモリーをモデル化する新しい配列メモリー・セグメントを作成します。

      結果のメモリー・セグメントは、バッキング配列への参照を保持し、セグメントの有効期間中「到達可能」を保持します。 セグメントはすべての「アクセス・モード」を特徴とします。

      パラメータ:
      arr - 配列メモリー・セグメントにバックアップするプリミティブ配列。
      戻り値:
      新しい配列メモリー・セグメント。

    • ofArray

      static MemorySegment ofArray​(float[] arr)
      指定のヒープ割当て浮動小数配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。

      結果のメモリー・セグメントは、バッキング配列への参照を保持し、セグメントの有効期間中「到達可能」を保持します。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。

      パラメータ:
      arr - 配列メモリー・セグメントにバックアップするプリミティブ配列。
      戻り値:
      新しい配列メモリー・セグメント。

    • ofArray

      static MemorySegment ofArray​(long[] arr)
      指定のヒープ割当て済ロング配列に関連付けられているメモリーをモデル化する新しい配列メモリー・セグメントを作成します。

      結果のメモリー・セグメントは、バッキング配列への参照を保持し、セグメントの有効期間中「到達可能」を保持します。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。

      パラメータ:
      arr - 配列メモリー・セグメントにバックアップするプリミティブ配列。
      戻り値:
      新しい配列メモリー・セグメント。

    • ofArray

      static MemorySegment ofArray​(double[] arr)
      指定のヒープ割当て済二重配列に関連付けられたメモリーをモデル化する新しい配列メモリー・セグメントを作成します。

      結果のメモリー・セグメントは、バッキング配列への参照を保持し、セグメントの有効期間中「到達可能」を保持します。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。

      パラメータ:
      arr - 配列メモリー・セグメントにバックアップするプリミティブ配列。
      戻り値:
      新しい配列メモリー・セグメント。

    • allocateNative

      static MemorySegment allocateNative​(MemoryLayout layout)
      指定されたレイアウトで新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。

      これは次のコードと等価です。 

      
    allocateNative(layout.bytesSize(), layout.bytesAlignment());

      実装上のノート:
      返されたネイティブ・メモリー・セグメントに関連するoff-heapメモリーのブロックは、ゼロに初期化されます。 さらに、クライアントはネイティブ・メモリー・セグメントでclose()をコールし、それに応じてバッキング・オフ・ヒープ・マージ・ブロックが割当て解除されるようにします。 これを行わなかった場合、ヒープ外のメモリー・リークが発生します。
      パラメータ:
      layout - ネイティブ・メモリー・セグメントのバッキングの非ヒープ・メモリー・ブロックのレイアウト。
      戻り値:
      新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalArgumentException - 指定されたレイアウトに不正なサイズ制約または位置合せ制約がある場合。

    • allocateNative

      static MemorySegment allocateNative​(long bytesSize)
      指定されたサイズ(バイト単位)で新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。

      これは次のコードと等価です。 

      
allocateNative(bytesSize, 1);

      実装上のノート:
      返されたネイティブ・メモリー・セグメントに関連するoff-heapメモリーのブロックは、ゼロに初期化されます。 さらに、クライアントはネイティブ・メモリー・セグメントでclose()をコールし、それに応じてバッキング・オフ・ヒープ・マージ・ブロックが割当て解除されるようにします。 これを行わなかった場合、ヒープ外のメモリー・リークが発生します。
      パラメータ:
      bytesSize - ネイティブ・メモリー・セグメントのバッキングのヒープ外メモリー・ブロックのサイズ(バイト単位)。
      戻り値:
      新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalArgumentException - bytesSize < 0の場合。

    • mapFromPath

      static MappedMemorySegment mapFromPath​(Path path, long bytesOffset, long bytesSize, FileChannel.MapMode mapMode) throws IOException
      指定されたパスからファイルのメモリー・マップのリージョンをモデル化する、新しいマップ済メモリー・セグメントを作成します。

      指定されたマッピング・モードがREAD_ONLYでないかぎり、セグメントはすべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。この場合、セグメントはWRITEアクセス・モードを特徴としません。

      実装上のノート:
      新たに作成されたファイルからマップされたセグメントを取得する場合、返されたマップ済メモリー・セグメントに関連付けられているマップ済メモリー・ブロックのコンテンツの初期化状態は未指定であり、判断すべきではありません。
      パラメータ:
      path - メモリー・マップへのファイルのパス。
      bytesOffset - マップされたセグメントを開始するファイル内のオフセット(バイトで表されます。)。
      bytesSize - メモリー・セグメントをバッキングするマップ済メモリーのサイズ(バイト単位)。
      mapMode - ファイル・マッピング・モード。FileChannel.map(FileChannel.MapMode, long, long)を参照してください。選択したマッピング・モードは、返されるメモリー・マップ・セグメント(MappedMemorySegment.force()を参照してください)の動作に影響する可能性があります。
      戻り値:
      新しいマッピング済メモリー・セグメント。
      例外:
      IllegalArgumentException - bytesOffset < 0の場合。
      IllegalArgumentException - bytesSize < 0の場合。
      UnsupportedOperationException - サポートされていないマップ・モードが指定された場合。
      IOException - 指定したパスが既存のファイルを指し示していないか、他のI/Oエラーが発生した場合。

    • allocateNative

      static MemorySegment allocateNative​(long bytesSize, long alignmentBytes)
      指定されたサイズおよび位置合せ制約(バイト単位)を使用して、新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。
      実装上のノート:
      返されたネイティブ・メモリー・セグメントに関連するoff-heapメモリーのブロックは、ゼロに初期化されます。 さらに、クライアントはネイティブ・メモリー・セグメントでclose()をコールし、それに応じてバッキング・オフ・ヒープ・マージ・ブロックが割当て解除されるようにします。 これを行わなかった場合、ヒープ外のメモリー・リークが発生します。
      パラメータ:
      bytesSize - ネイティブ・メモリー・セグメントのバッキングのヒープ外メモリー・ブロックのサイズ(バイト単位)。
      alignmentBytes - ネイティブ・メモリー・セグメントのバッキングのヒープ外メモリー・ブロックの位置合せ制約(バイト単位)。
      戻り値:
      新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalArgumentException - bytesSize < 0、alignmentBytes < 0またはalignmentBytesが2の累乗でない場合。

    • ofNativeRestricted

      static MemorySegment ofNativeRestricted​(MemoryAddress addr, long bytesSize, Thread owner, Runnable cleanup, Object attachment)
      指定されたベース・アドレスとサイズを持つ新しいネイティブ・メモリー・セグメントを返します。返されるセグメントには独自の時間的境界があるため、閉じることができます。そのようなセグメントを閉じると、オプションでユーザー指定のクリーンアップ・アクションが呼び出される可能性があります。 このメソッドは、基礎となるメモリー・リージョンへのアドレスが通常ネイティブ・コード(プレーンlong値として使用されることが多い)から取得されるカスタム・ネイティブ・メモリー・ソース(例:カスタム・ロケータ、GPUメモリーなど。)と対話する場合に非常に役立ちます。 セグメントは、すべての「アクセス・モード」 (ALL_ACCESSを参照してください)を特徴とします。

      このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      パラメータ:
      addr - 目的のベース・アドレス
      bytesSize - 目的のサイズ。
      owner - 目的の所有者スレッド。 owner == nullの場合、返されるセグメントは制限されません。
      cleanup - 戻されたセグメントでclose()メソッドがコールされたときに実行されるクリーンアップ・アクション。 cleanup == nullの場合、クリーンアップ・アクションは実行されません。
      attachment - 返されたセグメントによって保持される必要があるオブジェクト。これは、返されたセグメントがメモリーに依存し、特定のオブジェクトが到達不能と判断された場合に解放される可能性がある場合に便利です。 ほとんどの場合、これはnullに設定されます。
      戻り値:
      指定されたベース・アドレス、サイズ、所有者、クリーンアップ・アクションおよびオブジェクト添付を持つ新しいネイティブ・メモリー・セグメント。
      例外:
      IllegalArgumentException - bytesSize <= 0の場合。
      UnsupportedOperationException - addrがヒープ・セグメントに関連付けられている場合。
      IllegalAccessError - ランタイム・プロパティforeign.restrictedがpermit、warnまたはdebug (デフォルト値はdenyに設定されています)のいずれにも設定されていない場合。
      NullPointerException - addr == nullの場合。