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

インタフェースMemorySegment

すべてのスーパー・インタフェース:
AutoCloseable
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, FileChannel.MapMode)を使用して、メモリー・マップ・ファイルでバックアップされたメモリー・セグメントを取得することもできます。 このようなメモリー・セグメントは、「マッピングされたメモリー・セグメント」と呼ばれます。

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

メモリー・セグメントは明示的に(close()を参照してください)でクローズされます。 一般に、セグメントを閉じると、そのセグメントに関連付けられているすべてのオフ・ヒープ・リソースが解放されます。これは、検討されるメモリー・セグメントの種類に応じて異なる意味を持ちます:
  • ネイティブ・メモリー・セグメントを閉じると、「解放」のネイティブ・メモリーがそのセグメントに関連付けられます。
  • マップされたメモリー・セグメントを閉じると、バッキング・マップのファイルがマップ解除されます
  • 取得したメモリー・セグメントを閉じると、(詳細は、「スレッド制限」の項を参照してください。)のリソース・リリースになりません
  • バッファを閉じる、またはヒープ・セグメントに副次効果がない(セグメントを「生きていない」 (isAlive()を参照してください)とマークする以外)。 また、バッファおよびヒープ・セグメントは元のバッファまたは配列インスタンスへの強力な参照を維持しているため、クライアントはこれらのセグメントが適時に破棄されるようにする必要があります。したがって、ガベージ・コレクションによって基礎となるオブジェクトの再利用を妨げないようにする必要があります。

スレッド制限

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

スレッドAが所有するメモリー・セグメントSをスレッドBで使用する必要がある場合、Bは明示的にacquire Sを作成する必要があります。これにより、B (acquire()を参照してください)が所有する「取得済」メモリー・セグメントがSと同じリソースを所有しているように作成されます。 メモリー・セグメントは、1つ以上のスレッドによって複数回取得できます。この場合、Sから導出された取得済メモリー・セグメントをすべて閉じるまで、メモリー・セグメントsを閉じることはできません。 また、取得済メモリー・セグメントをクローズしても、割当て解除処理はトリガーされません。 したがって、クライアントは、メモリー・セグメントに関連付けられているヒープ外のリソースが解放されることを保証するために、取得したメモリー・セグメントの取得元のセグメントを明示的に閉じる必要があります。

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

メモリー・セグメントは「ビュー」をサポートしています。 書込み操作をサポートしないメモリー・セグメント(asReadOnly()を参照してください)の「不変」ビューを作成できます。 空間境界が元のセグメント(asSlice(long, long)を参照してください)のものより厳密であるビューを作成することもできます。

元のセグメントの一時的境界はビューによって継承されます。つまり、分割されたビューなどのセグメント・ビューを閉じると、元のセグメントが閉じます。複数のクライアント間でビューを共有する場合は、特別な注意を払う必要があります。 クライアントが、別のアクターによるセグメントの早期クローズから保護する必要がある場合、そのクライアントは、別のクライアントとビューを共有する前に、acquire()を呼び出した場合のように、保護対策を講じることを担当します。

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

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

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    MemorySegment acquire()
    現在のスレッドから、このセグメントに関連付けられているメモリーへのアクセスに使用できる「取得済」メモリー・セグメントを取得します。
    static MemorySegment allocateNative​(long bytesSize)
    指定されたサイズ(バイト単位)で新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。
    static MemorySegment allocateNative​(long bytesSize, long alignmentBytes)
    指定されたサイズおよび位置合せ制約(バイト単位)を使用して、新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。
    static MemorySegment allocateNative​(MemoryLayout layout)
    指定されたレイアウトで新しく割り当てられたヒープ外メモリーのブロックをモデル化する新しいネイティブ・メモリー・セグメントを作成します。
    ByteBuffer asByteBuffer()
    ByteBufferでこのセグメントをラップします。
    MemorySegment asReadOnly()
    このセグメントの読取り専用ビューを取得します。
    MemorySegment asSlice​(long offset, long newSize)
    ベース・アドレスがこのセグメントのベース・アドレスと指定されたオフセットに加えて、指定の引数で新しいサイズが指定されている、新しいメモリー・セグメントのビューを取得します。
    MemoryAddress baseAddress()
    このメモリー・セグメントに関連付けられているベース・メモリー・アドレス。
    long byteSize()
    このメモリー・セグメントのサイズは(バイト単位)です。
    void close()
    このメモリー・セグメントを閉じます。
    boolean isAlive()
    このセグメントは動作していますか。
    boolean isReadOnly()
    このセグメントは読取り専用ですか。
    static MemorySegment mapFromPath​(Path path, long bytesSize, FileChannel.MapMode mapMode)
    指定されたパスからファイルのメモリー・マップのリージョンをモデル化する、新しいマップ済メモリー・セグメントを作成します。
    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)
    指定されたバイト・バッファに関連付けられたメモリーをモデル化する新しいバッファ・メモリー・セグメントを作成します。
    Thread ownerThread()
    このセグメントを所有しているスレッド。
    byte[] toByteArray()
    このメモリー・セグメントの内容を新しいバイト配列にコピーします。

  • メソッドの詳細

    • baseAddress

      MemoryAddress baseAddress()
      このメモリー・セグメントに関連付けられているベース・メモリー・アドレス。
      戻り値:
      ベース・メモリー・アドレス。

    • acquire

      MemorySegment acquire()
      現在のスレッドから、このセグメントに関連付けられているメモリーへのアクセスに使用できる「取得済」メモリー・セグメントを取得します。 副次的効果として、取得したビューが(close()を参照してください)を終了するまでは、このセグメントを閉じることはできません。
      戻り値:
      現在のスレッドから、このセグメントに関連付けられたメモリーにアクセスするために使用できる「取得済」メモリー・セグメント。
      例外:
      IllegalStateException - このセグメントがクローズされている場合。

    • ownerThread

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

    • byteSize

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

    • asReadOnly

      MemorySegment asReadOnly()
      このセグメントの読取り専用ビューを取得します。 読取り専用メモリー・セグメントに関連付けられているメモリーを書き込もうとすると、UnsupportedOperationExceptionでは失敗します。
      戻り値:
      このセグメントの読取り専用ビュー。
      例外:
      IllegalStateException - このセグメントがクローズされている場合、またはこのセグメントを所有しているスレッド以外のスレッドからアクセスが発生した場合。

    • asSlice

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

    • isAlive

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

    • isReadOnly

      boolean isReadOnly()
      このセグメントは読取り専用ですか。
      戻り値:
      true:セグメントが読取り専用の場合。
      関連項目:
      asReadOnly()

    • close

      void close()
      このメモリー・セグメントを閉じます。 メモリー・セグメントが閉じられると、メモリー・セグメントを使用しようとしたり、セグメントに関連付けられているメモリーにアクセスしようとすると、IllegalStateExceptionで失敗します。 クローズされるメモリー・セグメントの種類によっては、このメソッドをコールすると、メモリー・セグメントに関連付けられているすべてのリソースの割当解除ロケーションがさらにトリガーされます。
      定義:
      close、インタフェース: AutoCloseable
      例外:
      IllegalStateException - このセグメントがクローズされている場合、またはこのセグメントを所有しているスレッド以外のスレッドからアクセスが発生した場合、またはこのセグメントの既存の取得済ビューがまだ(acquire()を参照してください)を使用中である場合。

    • asByteBuffer

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

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

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

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

    • toByteArray

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

    • ofByteBuffer

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

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

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

    • ofArray

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

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

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

    • ofArray

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

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

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

    • ofArray

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

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

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

    • ofArray

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

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

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

    • ofArray

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

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

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

    • ofArray

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

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

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

    • ofArray

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

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

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

    • allocateNative

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