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

インタフェースSegmentAllocator

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

SegmentAllocatorは、「機能インタフェース」です。 クライアントは、ラムダ式またはメソッド参照を使用して、新しいセグメント・ロケータを簡単に取得できます: 

SegmentAllocator autoAllocator = (byteSize, byteAlignment) -> Arena.ofAuto().allocate(byteSize, byteAlignment);

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

  • slicingAllocator(MemorySegment)は、指定されたメモリー・セグメントを繰り返しスライスすることでメモリーが割り当てられる、効率的なスライス・ロケータを取得
  • prefixAllocator(MemorySegment)は、セグメントをラップするロケータを取得し、新しい割当てリクエストごとにそのコンテンツをリサイクルします。

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

APIのノート:
特に指定がないかぎり、allocate(long, long)メソッドはスレッド・セーフではありません。 さらに、ロケータによって割り当てられたメモリー・セグメントは、異なる有効期間に関連付けることができ、メモリーのリージョンの重複によって支えられることもあります。 このような理由から、クライアントは通常、所有するロケータとのみ対話する必要があります。

クライアントは、かわりに「アリーナ」PREVIEWの使用を検討する必要があります。これにより、スレッドの安全性、存続期間および重複しない強力な保証が提供されます。

  • メソッドの詳細

    • 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(AddressLayoutPREVIEW layout, MemorySegmentPREVIEW 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 - elementLayout.byteSize() * countがオーバーフローした場合。
      IllegalArgumentException - count < 0の場合。

    • allocate

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

    • allocate

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

    • slicingAllocator

      static SegmentAllocatorPREVIEW slicingAllocator(MemorySegmentPREVIEW segment)
      指定されたセグメントから取得された連続したスライスを返すことにより、配賦リクエストに応答するセグメント配賦子を返します。 新しい割り当てリクエストごとに、現在のオフセット (線形拘束を満たすモジュロ追加パディング)から始まる新しいスライスが、指定されたサイズで返されます。

      返されたロケータは、指定されたセグメントのスライスがリクエストされたサイズと整列で見つからない場合、IndexOutOfBoundsExceptionをスローします。

      実装上のノート:
      ロケータはthread-safeではありません。
      パラメータ:
      segment - 戻されたロケータのスライス元のセグメント。
      戻り値:
      新しいロケータ

    • prefixAllocator

      static SegmentAllocatorPREVIEW prefixAllocator(MemorySegmentPREVIEW segment)
      単一のセグメントのリサイクルによって配賦リクエストに応答するセグメント・ロケータを返します。 新しい各割当てリクエストは、セグメント・オフセット0から始まる新しいスライスを返すため、「ロケータ」という名前が付けられます。 (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです: 
      MemorySegment segment = ...
SegmentAllocator prefixAllocator = (size, align) -> segment.asSlice(0, size, align);
      返されたロケータは、指定されたセグメントのスライスがリクエストされたサイズと整列で見つからない場合、IndexOutOfBoundsExceptionをスローします。
      APIのノート:
      プレフィクス・ロケータは、後続の配賦リクエストが実行される前に、割り当てられたセグメントの内容をクライアントが完全に処理したことを認識している場合に、配賦リクエストを制限するのに役立ちます。
      実装上のノート:
      ロケータがthread-safeである間、同じロケータで同時にアクセスすると、スレッドは、基礎となるセグメントに書き込まれた内容を別のスレッドで上書きする可能性があります。
      パラメータ:
      segment - 返されたロケータによってリサイクルされるメモリー・セグメント。
      戻り値:
      新しい配賦リクエストごとに既存のセグメントをリサイクルするロケータ。