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

インタフェースSegmentAllocator

関数型インタフェース:
これは関数型インタフェースなので、ラムダ式またはメソッド参照の代入先として使用できます。

@FunctionalInterface public interface SegmentAllocator
このインタフェースは、ロケータをモデル化します。 このインタフェースを実装するクライアントは、allocate(long, long)メソッドを実装する必要があります。 このインタフェースでは、プリミティブや配列などの複数のJava値からセグメントを作成するのに役立つ、いくつかのデフォルトのメソッドを定義します。 このインタフェースは、「作成」ネイティブ・セグメントの基本機能の周りにシン・ラッパーとして表示できます。SegmentAllocator「機能インタフェース」であるため、クライアントはラムダ式またはメソッド参照のいずれかを使用してネイティブ・ロケータを簡単に取得できます。

このインタフェースでは、一般的に使用されるロケータのファクトリも定義されます:

  • nativeAllocator(ResourceScope)は、特定のスコープによってバックアップされる「割り当てる」ネイティブ・セグメントを持つロケータを作成
  • newNativeArena(ResourceScope)は、より効率的なアリーナ形式のネイティブ・ロケータを作成します。メモリーは、より大きなブロックに割り当てられ、割当てリクエストに応じてスライスされます
  • prefixAllocator(MemorySegment)は、セグメント(ヒープまたはオフ・ヒープのいずれか)をラップし、新しい割当てリクエストごとにコンテンツをリサイクルするロケータを作成します。

セグメント・ロケータをAPIに渡すことは、クライアントがwhereと通信する場合、特定の操作(APIによって実行される)の結果をメモリー・セグメントとして格納する必要がある場合に特に役立ちます。 たとえば、「downcallメソッド・ハンドル」は、基礎となるネイティブ関数が変数別の値を返すことがわかっている場合、追加のSegmentAllocatorパラメータを受け入れることができます。 実質的に、ロケータ・パラメータは、ネイティブ関数の戻り値を格納する場所をリンカーのランタイムに伝えます。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    allocate(long bytesSize)
    指定されたサイズとデフォルトの整列制約 (1バイトの整列)でメモリー・セグメントを割り当てます。
    allocate(long bytesSize, long bytesAlignment)
    指定されたサイズおよび整列制約を持つメモリー・セグメントを割り当てます。
    指定されたレイアウトでメモリー・セグメントを割り当てます。
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたアドレス値(Addressableインスタンスとして表現)で初期化します。
    allocate(ValueLayout.OfByte layout, byte value)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたバイト値で初期化します。
    allocate(ValueLayout.OfChar layout, char value)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたchar値で初期化します。
    allocate(ValueLayout.OfDouble layout, double value)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定した倍精度値で初期化します。
    allocate(ValueLayout.OfFloat layout, float value)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定した浮動小数値で初期化します。
    allocate(ValueLayout.OfInt layout, int value)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたint値で初期化します。
    allocate(ValueLayout.OfLong layout, long value)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定した長い値で初期化します。
    allocate(ValueLayout.OfShort layout, short value)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定された短い値で初期化します。
    allocateArray(MemoryLayout elementLayout, long count)
    指定された要素のレイアウトおよびサイズでメモリー・セグメントを割り当てます。
    allocateArray(ValueLayout.OfByte elementLayout, byte[] array)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたバイト配列で初期化します。
    allocateArray(ValueLayout.OfChar elementLayout, char[] array)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたchar配列で初期化します。
    allocateArray(ValueLayout.OfDouble elementLayout, double[] array)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたダブル配列で初期化します。
    allocateArray(ValueLayout.OfFloat elementLayout, float[] array)
    指定されたレイアウトでメモリー・セグメントを割り当て、特定の浮動配列で初期化します。
    allocateArray(ValueLayout.OfInt elementLayout, int[] array)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定されたint配列で初期化します。
    allocateArray(ValueLayout.OfLong elementLayout, long[] array)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定した長い配列で初期化します。
    allocateArray(ValueLayout.OfShort elementLayout, short[] array)
    指定されたレイアウトでメモリー・セグメントを割り当て、指定された短い配列で初期化します。
    Java文字列をUTF-8でエンコードされたNULLで終了するC文字列に変換し、結果をメモリー・セグメントに格納します。
    独立した「暗黙的なスコープ」でセグメントを割り当てるネイティブ・ロケータを返します。
    指定されたスコープに関連付けられたネイティブ・ロケータを返します。
    newNativeArena(long arenaSize, long blockSize, ResourceScope scope)
    指定されたスコープに関連付けられたネイティブ・アリーナ・ベースのロケータを、指定されたアリーナ・サイズおよびブロック・サイズで返します。
    newNativeArena(long arenaSize, ResourceScope scope)
    指定された範囲に関連付けられた指定したアリーナ・サイズにブロック・サイズが設定されたネイティブのバインドされていないアリーナ・ベースのロケータを、指定されたアリーナ・サイズで返します。
    指定されたスコープに関連付けられた事前定義済のブロック・サイズおよび最大アリーナ・サイズを持つ、ネイティブのバインドされていないアリーナ・ベースのロケータを返します。
    1つのセグメントのリサイクルによって割当てリクエストに応答するセグメント・ロケータを返します。つまり、新しい割当てリクエストごとに、セグメント・オフセット0 (整列制約はこのロケータによって無視されます)から始まる新しいスライスが返されるため、「プリフィクス・ロケータ」という名前が返されます。
  • メソッドの詳細

    • allocateUtf8String

      default MemorySegment allocateUtf8String(String str)
      Java文字列をUTF-8でエンコードされたNULLで終了するC文字列に変換し、結果をメモリー・セグメントに格納します。

      このメソッドは、不正入力シーケンスやマップ不可文字シーケンスを、この文字セットのデフォルトの置換バイト配列で置き換えます。 エンコード処理をより強力に制御する必要がある場合は、CharsetEncoderクラスを使用してください。

      実装要件:
      このメソッドのデフォルト実装は、指定されたJava文字列の内容を、this.allocate(str.length() + 1)をコールして取得した新しいメモリー・セグメントにコピーします。
      パラメータ:
      str - C文字列に変換するJava文字列。
      戻り値:
      変換されたC文字列を含む新しいネイティブ・メモリー・セグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfByte layout, byte value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたバイト値で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfChar layout, char value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたchar値で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfShort layout, short value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定された短い値で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfInt layout, int value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたint値で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfFloat layout, float value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定した浮動小数値で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfLong layout, long value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定した長い値で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfDouble layout, double value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定した倍精度値で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(ValueLayout.OfAddress layout, Addressable value)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたアドレス値(Addressableインスタンスとして表現)で初期化します。 アドレス値は、プラットフォームのアドレス・サイズ(ValueLayout.ADDRESSを参照してください)に応じて絞り込まれることがあります。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout)をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      value - 新しく割り当てられたメモリー・ブロックに設定する値。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(ValueLayout.OfByte elementLayout, byte[] array)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたバイト配列で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(ValueLayout.OfShort elementLayout, short[] array)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定された短い配列で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(ValueLayout.OfChar elementLayout, char[] array)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたchar配列で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(ValueLayout.OfInt elementLayout, int[] array)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたint配列で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(ValueLayout.OfFloat elementLayout, float[] array)
      指定されたレイアウトでメモリー・セグメントを割り当て、特定の浮動配列で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(ValueLayout.OfLong elementLayout, long[] array)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定した長い配列で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(ValueLayout.OfDouble elementLayout, double[] array)
      指定されたレイアウトでメモリー・セグメントを割り当て、指定されたダブル配列で初期化します。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(MemoryLayout layout)
      指定されたレイアウトでメモリー・セグメントを割り当てます。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(layout.byteSize(), layout.byteAlignment())をコールします。
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocateArray

      default MemorySegment allocateArray(MemoryLayout elementLayout, long count)
      指定された要素のレイアウトおよびサイズでメモリー・セグメントを割り当てます。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))をコールします。
      パラメータ:
      elementLayout - 配列要素のレイアウト。
      count - 配列要素のカウント。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      default MemorySegment allocate(long bytesSize)
      指定されたサイズとデフォルトの整列制約 (1バイトの整列)でメモリー・セグメントを割り当てます。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocate(bytesSize, 1)をコールします。
      パラメータ:
      bytesSize - 割り当てるメモリー・ブロックのサイズ(バイト単位)。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • allocate

      MemorySegment allocate(long bytesSize, long bytesAlignment)
      指定されたサイズおよび整列制約を持つメモリー・セグメントを割り当てます。
      パラメータ:
      bytesSize - 割り当てるメモリー・ブロックのサイズ(バイト単位)。
      bytesAlignment - 割り当てるメモリー・ブロックの整列(バイト単位)。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
    • newNativeArena

      static SegmentAllocator newNativeArena(ResourceScope scope)
      指定されたスコープに関連付けられた事前定義済のブロック・サイズおよび最大アリーナ・サイズを持つ、ネイティブのバインドされていないアリーナ・ベースのロケータを返します。 次のコードと同等です:
      SegmentAllocator.newNativeArena(Long.MAX_VALUE, predefinedBlockSize, scope);
      
      パラメータ:
      scope - アリーナ・ベースのロケータによって返されるセグメントに関連付けられたスコープ。
      戻り値:
      バインドされていない新しいアリーナ・ベースのロケータ
      例外:
      IllegalStateException - scopeがすでにクローズされている場合、またはscopeを所有するスレッド以外のスレッドからアクセスが発生した場合。
    • newNativeArena

      static SegmentAllocator newNativeArena(long arenaSize, ResourceScope scope)
      指定された範囲に関連付けられた指定したアリーナ・サイズにブロック・サイズが設定されたネイティブのバインドされていないアリーナ・ベースのロケータを、指定されたアリーナ・サイズで返します。 次のコードと同等です:
      SegmentAllocator.newNativeArena(arenaSize, arenaSize, scope);
      
      パラメータ:
      arenaSize - 割当てアリーナのサイズ(バイト単位)。
      scope - アリーナ・ベースのロケータによって返されるセグメントに関連付けられたスコープ。
      戻り値:
      バインドされていない新しいアリーナ・ベースのロケータ
      例外:
      IllegalArgumentException - arenaSize <= 0の場合。
      IllegalStateException - scopeがすでにクローズされている場合、またはscopeを所有するスレッド以外のスレッドからアクセスが発生した場合。
    • newNativeArena

      static SegmentAllocator newNativeArena(long arenaSize, long blockSize, ResourceScope scope)
      指定されたスコープに関連付けられたネイティブ・アリーナ・ベースのロケータを、指定されたアリーナ・サイズおよびブロック・サイズで返します。

      戻されたロケータは、指定されたブロック・サイズのメモリー・セグメントS「割り当てる」し、次のいずれかの方法で割当てリクエストに応答します:

      • 割当てリクエストのサイズがSのサイズよりも小さく、Sにその割当てリクエストに適合する「無料」スライスS'がある場合は、S'を返します。
      • 割当てリクエストのサイズがSのサイズより小さく、Sにその割当てリクエストに適合する「無料」スライスがない場合は、Sと同じサイズの新しいセグメントS'を割り当て、S = S'を設定します。その後、ロケータは同じ割当てリクエストに再度応答しようとします。
      • 割当てリクエストのサイズがSのサイズより大きい場合は、割当てリクエストを満たす十分なサイズを持つ新しいセグメントS'を割り当て、S'を返します。

      このロケータは、クライアントが割り当てリクエストごとに新しいオフ・ヒープ・メモリー・リージョンの割り当てに関連するコストを避けるために、複数の割り当てリクエストを実行する場合に便利です。

      このロケータで割り当てられた合計メモリーがアリーナ・サイズまたはシステム容量を超えた場合、返されるロケータはOutOfMemoryErrorをスローすることがあります。 さらに、返されるロケータはスレッド・セーフではありません。 同時割当ては同期プリミティブで保護する必要があります。

      パラメータ:
      arenaSize - 割当てアリーナのサイズ(バイト単位)。
      blockSize - アリーナ・ベースのロケータに関連付けられたブロック・サイズ。
      scope - アリーナ・ベースのロケータによって返されるセグメントに関連付けられたスコープ。
      戻り値:
      バインドされていない新しいアリーナ・ベースのロケータ
      例外:
      IllegalArgumentException - blockSize <= 0の場合、arenaSize <= 0の場合、またはarenaSize < blockSizeの場合。
      IllegalStateException - scopeがすでにクローズされている場合、またはscopeを所有するスレッド以外のスレッドからアクセスが発生した場合。
    • prefixAllocator

      static SegmentAllocator prefixAllocator(MemorySegment segment)
      1つのセグメントのリサイクルによって割当てリクエストに応答するセグメント・ロケータを返します。つまり、新しい割当てリクエストごとに、セグメント・オフセット0 (整列制約はこのロケータによって無視されます)から始まる新しいスライスが返されるため、「プリフィクス・ロケータ」という名前が返されます。 (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです:
      MemorySegment segment = ...
      SegmentAllocator prefixAllocator = (size, align) -> segment.asSlice(0, size);
      

      このロケータは、後続の割当リクエストが実行される前に、割り当てられたセグメントの内容が完全に処理されたことをクライアントが認識した場合に、配賦リクエストを制限するのに役立ちます。

      このメソッドによって返されるロケータはthread-safeですが、同じロケータでの同時アクセスにより、スレッドによって、基になるセグメントに書き込まれた内容が別のスレッドによって上書きされる可能性があります。

      パラメータ:
      segment - 返されたロケータによってリサイクルされるメモリー・セグメント。
      戻り値:
      新しい配賦リクエストごとに既存のセグメントをリサイクルするロケータ。
    • nativeAllocator

      static SegmentAllocator nativeAllocator(ResourceScope scope)
      指定されたスコープに関連付けられたネイティブ・ロケータを返します。 (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです:
      ResourceScope scope = ...
      SegmentAllocator nativeAllocator = (size, align) -> MemorySegment.allocateNative(size, align, scope);
      
      パラメータ:
      scope - 返されるロケータに関連付けられたスコープ。
      戻り値:
      提供されたスコープに関連付けられたネイティブ・ロケータ。
    • implicitAllocator

      static SegmentAllocator implicitAllocator()
      独立した「暗黙的なスコープ」でセグメントを割り当てるネイティブ・ロケータを返します。 (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです:
      SegmentAllocator implicitAllocator = (size, align) -> MemorySegment.allocateNative(size, align, ResourceScope.newImplicitScope());
      
      戻り値:
      独立した「暗黙的なスコープ」でセグメントを割り当てるネイティブ・ロケータ。