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

インタフェースSegmentAllocator

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

このインタフェースは、出荷時のofScope(ResourceScope)を提供します。これは、「スコープ付き」ロケータ、つまり特定のスコープによってバインドされたセグメントを作成するロケータを取得するために使用できます。 これは、try-with-resources構成内で作業する場合に役立ちます: 


try (ResourceScope scope = ResourceScope.newConfinedScope()) {
   SegmentAllocator allocator = SegmentAllocator.ofScope(scope);
   ...
}
また、このインタフェースは、一般的に使用されるロケータのファクトリも定義します。たとえば、arenaAllocator(ResourceScope)やarenaAllocator(long, ResourceScope)はアリーナ形式のロケータです。 最後に、ofSegment(MemorySegment)は、セグメント(オン・ヒープまたはオフ・ヒープ)をラップするロケータを返し、新しい割当てリクエストごとにコンテンツをリサイクルします。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    default MemorySegment
    allocate(long bytesSize)
    デフォルトの位置合せ(1バイト配置)を使用して、指定されたサイズでメモリー・ブロックを割り当てます。
    MemorySegment
    allocate(long bytesSize, long bytesAlignment)
    指定されたサイズと位置合わせの制約で、メモリー・ブロックを割り当てます。
    default MemorySegment
    allocate(MemoryLayout layout)
    指定されたレイアウトでメモリー・ブロックを割り当てます。
    default MemorySegment
    allocate(ValueLayout layout, byte value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたバイト値で初期化します。
    default MemorySegment
    allocate(ValueLayout layout, char value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたchar値で初期化します。
    default MemorySegment
    allocate(ValueLayout layout, double value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたdouble値で初期化します。
    default MemorySegment
    allocate(ValueLayout layout, float value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたfloat値で初期化します。
    default MemorySegment
    allocate(ValueLayout layout, int value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたint値で初期化します。
    default MemorySegment
    allocate(ValueLayout layout, long value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたlong値で初期化します。
    default MemorySegment
    allocate(ValueLayout layout, short value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定された短い値で初期化します。
    default MemorySegment
    allocate(ValueLayout layout, Addressable value)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたアドレス値(Addressableインスタンスとして表現)で初期化します。
    default MemorySegment
    allocateArray(MemoryLayout elementLayout, long count)
    指定された要素のレイアウトとサイズを持つ配列に対応するメモリーのブロックを割り当てます。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, byte[] array)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたバイト配列で初期化します。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, char[] array)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたchar配列で初期化します。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, double[] array)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたdouble配列で初期化します。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, float[] array)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたfloat配列で初期化します。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, int[] array)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定されたint配列で初期化します。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, long[] array)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定された長い配列で初期化します。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, short[] array)
    指定されたレイアウトでメモリー・ブロックを割り当て、指定された短い配列で初期化します。
    default MemorySegment
    allocateArray(ValueLayout elementLayout, Addressable[] array)
    指定されたレイアウトでメモリーのブロックを割り当て、指定されたアドレス配列で初期化します。
    static SegmentAllocator
    arenaAllocator(long size, ResourceScope scope)
    特定のサイズ(mallocの使用)の単一のメモリー・セグメントを割り当て、その同じセグメント(これ以上の割り当てが可能になるまで)の異なるスライスを返すことで、割当てリクエストに応答するネイティブなアリーナ・ベースのロケータを返します。
    static SegmentAllocator
    arenaAllocator(ResourceScope scope)
    バインドされていないネイティブなアリーナ・ベースのロケータを返します。
    static SegmentAllocator
    ofScope(ResourceScope scope)
    MemorySegment.allocateNative(long, long, ResourceScope)ファクトリを使用して、指定されたリソース・スコープによってバインドされた新しいセグメントを割り当てることで、割当てリクエストに応答するネイティブ・ロケータを返します。
    static SegmentAllocator
    ofSegment(MemorySegment segment)
    単一のセグメントをリサイクルして、配賦リクエストに応答するロケータを返します。つまり、新しい各割り当てリクエストは、セグメント・オフセット0 (アライメントの制約はこのロケータによって無視されます)から始まる新しいスライスを返します。

  • メソッドの詳細

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

      default MemorySegment allocateArray(ValueLayout elementLayout, Addressable[] array)
      指定されたレイアウトでメモリーのブロックを割り当て、指定されたアドレス配列で初期化します。 各配列要素のアドレス値は、プラットフォームのアドレス・サイズ(MemoryLayouts.ADDRESSを参照してください)に応じて絞り込まれる場合があります。
      実装要件:
      このメソッドのデフォルトの実装では、this.allocateArray(layout, array.length)をコールします。
      パラメータ:
      elementLayout - 割り当てられる配列の要素レイアウト。
      array - 新しく割り当てられたメモリー・ブロックにコピーされる配列。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
      例外:
      IllegalArgumentException - layout.byteSize() != MemoryLayouts.ADDRESS.byteSize()の場合。

    • 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 - 割り当てるメモリー・ブロックの整列(バイト単位)。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。

    • arenaAllocator

      static SegmentAllocator arenaAllocator(long size, ResourceScope scope)
      特定のサイズ(mallocの使用)の単一のメモリー・セグメントを割り当て、その同じセグメント(これ以上の割り当てが可能になるまで)の異なるスライスを返すことで、割当てリクエストに応答するネイティブなアリーナ・ベースのロケータを返します。 これは、クライアントが複数の割り当てリクエストを実行しながら、割り当てリクエストごとに新しいオフ・ヒープ・メモリー・リージョンの割り当てにかかるコストを避ける場合に便利です。

      sharedリソース・スコープに関連付けられたロケータはスレッド・セーフであり、割当てリクエストは同時に実行できます。逆に、アリーナ・ロケータが「精密」リソース・スコープに関連付けられている場合、割当てリクエストは、ロケータ・リソース・スコープを所有するスレッドからのみ実行できます。

      返されたロケータは、受信割り当てリクエストがロケータ容量を超える場合にOutOfMemoryErrorをスローする可能性があります。

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

    • arenaAllocator

      static SegmentAllocator arenaAllocator(ResourceScope scope)
      バインドされていないネイティブなアリーナ・ベースのロケータを返します。

      返されるロケータは、特定の固定サイズ(mallocの使用)のメモリー・セグメントSを割り当て、次のいずれかの方法で割当てリクエストに応答します:

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

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

      sharedリソース・スコープに関連付けられたロケータはスレッド・セーフであり、割当てリクエストは同時に実行できます。逆に、アリーナ・ロケータが「精密」リソース・スコープに関連付けられている場合、割当てリクエストは、ロケータ・リソース・スコープを所有するスレッドからのみ実行できます。

      着信割り当てリクエストがシステム容量を超えると、返されるロケータはOutOfMemoryErrorをスローする可能性があります。

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

    • ofSegment

      static SegmentAllocator ofSegment(MemorySegment segment)
      単一のセグメントをリサイクルして、配賦リクエストに応答するロケータを返します。つまり、新しい各割り当てリクエストは、セグメント・オフセット0 (アライメントの制約はこのロケータによって無視されます)から始まる新しいスライスを返します。 これは、割当てリクエストが後続の割当てリクエストが実行される前に、割当て済セグメントの内容が完全に処理されたことをクライアントが認識した場合に、割当てリクエストを制限する場合に便利です。

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

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

    • ofScope

      static SegmentAllocator ofScope(ResourceScope scope)
      MemorySegment.allocateNative(long, long, ResourceScope)ファクトリを使用して、指定されたリソース・スコープによってバインドされた新しいセグメントを割り当てることで、割当てリクエストに応答するネイティブ・ロケータを返します。 このコードは、次のコードと同等の(効率が向上)です: 
      
    Resource scope = ...
    SegmentAllocator scoped = (size, align) -> MemorySegment.allocateNative(size, align, scope);
      パラメータ:
      scope - 返されたロケータによって作成されたセグメントに関連付けられたリソース・スコープ。
      戻り値:
      指定されたリソース・スコープによってバインドされた新しいメモリー・セグメントを割り当てるロケータ。