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

インタフェースSegmentAllocator

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

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

  • nativeAllocator(SegmentScope)は、ネイティブ・セグメントの割当てに使用できる単純なロケータを取得
  • slicingAllocator(MemorySegment)は、指定されたメモリー・セグメントを繰り返しスライスすることでメモリーが割り当てられる、効率的なスライス・ロケータを取得
  • 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, 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 - 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またはalignmentBytesが2の累乗でない場合。

    • slicingAllocator

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

      返されたロケータが割当てリクエストを満たせない場合(リクエストされたサイズで指定されたセグメントのスライスが見つからない場合など)、IndexOutOfBoundsExceptionがスローされます。

      パラメータ:
      segment - 戻されたロケータのスライス元のセグメント。
      戻り値:
      新しいロケータ

    • prefixAllocator

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

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

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

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

    • nativeAllocator

      static SegmentAllocatorPREVIEW nativeAllocator(SegmentScopePREVIEW scope)
      ネイティブ・セグメントの割当てに使用されるシンプルなロケータ。 返されたロケータは、指定されたバイト・サイズと整列制約を使用して、メモリーの新しいオフ・ヒープ・リージョンによって支えられたネイティブ・セグメントを返すことによって、割り当てリクエストに応答します。

      返されるロケータによって取得される各ネイティブ・セグメントは、指定されたスコープに関連付けられます。 そのため、返されるセグメントをバックするオフ・ヒープ・リージョンは、スコープがalivePREVIEWではなくなったときに解放されます。

      返されるロケータによって取得されるネイティブ・セグメントのMemorySegment.address()PREVIEWは、セグメントを支える新しく割り当てられたオフ・ヒープ・メモリー・リージョンの開始アドレスです。 さらに、ネイティブ・セグメントのaddressPREVIEWは、指定された整列制約に従って整列されます。

      返されるロケータによって取得されたネイティブ・セグメントをバッキングするメモリーのオフ・ヒープ・リージョンがゼロに初期化されます。

      これは次のコードと等価です。 

      SegmentAllocator nativeAllocator = (byteSize, byteAlignment) ->
    MemorySegment.allocateNative(byteSize, byteAlignment, scope);

      パラメータ:
      scope - ロケータによって返されるセグメントに関連付けられたスコープ。
      戻り値:
      ネイティブ・セグメントの割当てに使用される単純なロケータ。