モジュール java.base
パッケージ java.lang.foreign

インタフェースSegmentAllocator

既知のすべてのサブインタフェース:
MemorySessionPREVIEW
関数型インタフェース:
これは関数型インタフェースなので、ラムダ式またはメソッド参照の代入先として使用できます。
@FunctionalInterface public interface SegmentAllocator
SegmentAllocatorは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでSegmentAllocatorを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
「メモリー・セグメント」PREVIEWの割当てに使用できるオブジェクト。 このインタフェースを実装するクライアントは、allocate(long, long)メソッドを実装する必要があります。 このインタフェースでは、プリミティブや配列などの複数のJava値からセグメントを作成するのに役立つ、いくつかのデフォルトのメソッドを定義します。 このインタフェースは機能インタフェースです: クライアントは、ラムダ式またはメソッド参照を使用して、新しいロケータを簡単に取得できます。

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

  • newNativeArena(MemorySession)は、より効率的なアリーナ・スタイルのロケータを作成します。オフ・ヒープ・メモリーはより大きいブロックに割り当てられ、その後、割当てリクエストに適合するようにスライスされます
  • implicitAllocator()は、ネイティブ・メモリー・セグメントを独立した「暗黙的なメモリー・セッション」PREVIEWで割り当てるロケータを取得
  • prefixAllocator(MemorySegment)は、セグメント(オン・ヒープまたはオフ・ヒープのいずれか)をラップするロケータを取得し、新しい割当てリクエストごとにそのコンテンツをリサイクルします。

セグメント・ロケータをAPIに渡すことは、クライアントがwhereと通信する場合、特定の操作(APIによって実行される)の結果をメモリー・セグメントとして格納する必要がある場合に特に役立ちます。 たとえば、基礎となる外部関数が構造体バイ・バリューを返すことがわかっている場合、「ダウンコール・メソッド・ハンドル」PREVIEWは追加のSegmentAllocatorPREVIEWパラメータを受け入れることができます。 事実上、ロケータ・パラメータはリンカー・ランタイムに、外部関数の戻り値を格納する場所を指示します。

  • メソッドの詳細

    • allocateUtf8String

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

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

      指定された文字列に'\0'文字が含まれている場合、それらもコピーされます。 つまり、文字列の読取りに使用されたメソッド(MemorySegment.getUtf8String(long)PREVIEWなど)に応じて、再度読み取るときに文字列が切り捨てられます。

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocate

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocateArray

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

    • allocate

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

    • allocateArray

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

    • allocate

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

    • allocate

      MemorySegmentPREVIEW allocate(long bytesSize, long bytesAlignment)
      指定されたサイズおよび整列制約を使用してメモリー・セグメントを割り当てます。
      パラメータ:
      bytesSize - 割り当てるメモリー・ブロックのサイズ(バイト単位)。
      bytesAlignment - 割り当てるメモリー・ブロックの整列(バイト単位)。
      戻り値:
      新しく割り当てられたメモリー・ブロックのセグメント。
      例外:
      IllegalArgumentException - bytesSize < 0、alignmentBytes <= 0またはalignmentBytesが2の累乗でない場合。

    • newNativeArena

      static SegmentAllocatorPREVIEW newNativeArena(MemorySessionPREVIEW session)
      ネイティブ・メモリー・セグメントを割り当てるために使用される無制限のロケータを作成します。 返されるロケータは、事前定義されたブロック・サイズと最大アリーナ・サイズを備え、割り当てられるセグメントは指定されたメモリー・セッションに関連付けられます。 次のコードと同等です: 
      SegmentAllocator.newNativeArena(Long.MAX_VALUE, predefinedBlockSize, session);
      パラメータ:
      session - arenaベースのロケータによって割り当てられたセグメントに関連付けられたメモリー・セッション。
      戻り値:
      バインドされていない新しいアリーナ・ベースのロケータ
      例外:
      IllegalStateException - sessionがalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、sessionを「所有している」PREVIEWスレッド以外のスレッドからコールされる場合。

    • newNativeArena

      static SegmentAllocatorPREVIEW newNativeArena(long arenaSize, MemorySessionPREVIEW session)
      ネイティブ・メモリー・セグメントを割り当てるために使用されるアリーナ・ベースのロケータを作成します。 返されるロケータは、指定されたアリーナ・サイズに設定されたブロック・サイズを備え、割り当てられるネイティブ・セグメントは指定されたメモリー・セッションに関連付けられます。 次のコードと同等です: 
      SegmentAllocator.newNativeArena(arenaSize, arenaSize, session);
      パラメータ:
      arenaSize - 割当てアリーナのサイズ(バイト単位)。
      session - arenaベースのロケータによって割り当てられたセグメントに関連付けられたメモリー・セッション。
      戻り値:
      バインドされていない新しいアリーナ・ベースのロケータ
      例外:
      IllegalArgumentException - arenaSize <= 0の場合。
      IllegalStateException - sessionがalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、sessionを「所有している」PREVIEWスレッド以外のスレッドからコールされる場合。

    • newNativeArena

      static SegmentAllocatorPREVIEW newNativeArena(long arenaSize, long blockSize, MemorySessionPREVIEW session)
      ネイティブ・メモリー・セグメントを割り当てるために使用されるアリーナ・ベースのロケータを作成します。 返されるロケータは、指定されたブロック・サイズBと指定されたアリーナ・サイズAを特長とし、それによって割り当てられるネイティブ・セグメントは、指定されたメモリー・セッションに関連付けられます。

      ロケータ・アリーナは、最初に「割り当て」PREVIEWによってサイズBのネイティブ・メモリー・セグメントSに初期化されます。 ロケータは、次のいずれかの方法で割り当てリクエストに応答します:

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

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

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

      パラメータ:
      arenaSize - 割当てアリーナのサイズ(バイト単位)。
      blockSize - アリーナ・ベースのロケータに関連付けられたブロック・サイズ。
      session - arenaベースのロケータによって返されるセグメントに関連付けられたメモリー・セッション。
      戻り値:
      バインドされていない新しいアリーナ・ベースのロケータ
      例外:
      IllegalArgumentException - blockSize <= 0の場合、arenaSize <= 0の場合、またはarenaSize < blockSizeの場合。
      IllegalStateException - sessionがalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、sessionを「所有している」PREVIEWスレッド以外のスレッドからコールされる場合。

    • prefixAllocator

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

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

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

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

    • implicitAllocator

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