インタフェースSegmentAllocator

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

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

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

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

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

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

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

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

導入されたバージョン:
22

  • メソッドの詳細

    • allocateFrom

      default MemorySegment allocateFrom(String str)
      UTF-8文字セットを使用してJava文字列をNULLで終了するC文字列に変換し、その結果をメモリー・セグメントに格納します。

      このメソッドの呼出しは、次のコードと同じです: 

       allocateFrom(str, StandardCharsets.UTF_8);

      パラメータ:
      str - C文字列に変換されるJava文字列
      戻り値:
      変換されたC文字列を含む新しいネイティブ・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(String str, Charset charset)
      指定された文字セットを使用してJava文字列をNULLで終了するC文字列に変換し、その結果をメモリー・セグメントに格納します。

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

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

      実装要件:
      このメソッドのデフォルト実装では、指定されたJava文字列の内容が、this.allocate(B + N)をコールして取得された新しいメモリー・セグメントにコピーされます。ここでは:
      • B は、指定された文字セット(e.g. str.getBytes(charset).length)を使用してエンコードされた文字列のサイズ(バイト単位)です。
      • N は、指定された文字セットに従った終了文字文字の(バイト単位)サイズです。 たとえば、これはStandardCharsets.US_ASCIIの場合は1、StandardCharsets.UTF_16の場合は2です。
      パラメータ:
      str - C文字列に変換されるJava文字列
      charset - 文字列バイトの「エンコード」に使用される文字セット
      戻り値:
      変換されたC文字列を含む新しいネイティブ・セグメント
      例外:
      IllegalArgumentException - charsetが「標準文字セット」でない場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfByte layout, byte value)
      指定されたバイト値で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたバイト値で初期化された新しいメモリー・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfChar layout, char value)
      指定されたchar値で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたchar値で初期化された新しいメモリー・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfShort layout, short value)
      指定されたshort値で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたshort値で初期化された新しいメモリー・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfInt layout, int value)
      指定されたint値で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたint値で初期化された新しいメモリー・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfFloat layout, float value)
      指定されたfloat値で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたfloat値で初期化された新しいメモリー・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfLong layout, long value)
      指定されたlong値で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたlong値で初期化された新しいメモリー・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfDouble layout, double value)
      指定されたdouble値で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたdouble値で初期化された新しいメモリー・セグメント

    • allocateFrom

      default MemorySegment allocateFrom(AddressLayout layout, MemorySegment value)
      指定されたメモリー・セグメントのaddressで初期化された新しいメモリー・セグメントを返します。

      アドレス値は、プラットフォームのアドレス・サイズ(ValueLayout.ADDRESSを参照してください)に応じて絞り込まれることがあります。

      割り当てられたメモリー・セグメントのサイズは、指定されたレイアウトのsizeです。 指定された値は、指定されたレイアウトのバイト順序および整列制約に従ってセグメントに書き込まれます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
       Objects.requireNonNull(value);
 MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      パラメータ:
      layout - 割り当てるメモリー・ブロックのレイアウト
      value - 新しく割り当てられたメモリー・セグメントに設定される値
      戻り値:
      指定されたメモリー・セグメントのaddressで初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - valueが「ネイティブ」セグメントでない場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout elementLayout, MemorySegment source, ValueLayout sourceElementLayout, long sourceOffset, long elementCount)
      指定されたセグメントの内容で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズは、elementLayout.byteSize() * elementCountです。 ソース・セグメントの内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
      MemorySegment dest = this.allocate(elementLayout, elementCount);
MemorySegment.copy(source, sourceElementLayout, sourceOffset, dest, elementLayout, 0, elementCount);
return dest;
      パラメータ:
      elementLayout - 割り当てられた配列の要素レイアウト
      source - ソース・セグメント
      sourceElementLayout - ソース・セグメントの要素レイアウト
      sourceOffset - ソース・セグメントの開始オフセット(バイト単位)
      elementCount - コピーするソース・セグメント内の要素の数
      戻り値:
      指定されたセグメントの内容で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteSize() != sourceElementLayout.byteSize()の場合
      IllegalArgumentException - ソース要素レイアウトでソース・セグメント/オフセットが「線形制約と互換性がありません」の場合
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合
      IllegalArgumentException - sourceElementLayout.byteAlignment() > sourceElementLayout.byteSize()の場合
      IllegalStateException - sourceに関連付けられているscopeがaliveでない場合
      WrongThreadException - このメソッドがスレッドTからコールされる場合(source.isAccessibleBy(T) == falseなど)
      IllegalArgumentException - elementCount * sourceElementLayout.byteSize()がオーバーフローした場合
      IllegalArgumentException - elementCount < 0の場合
      IndexOutOfBoundsException - sourceOffset > source.byteSize() - (elementCount * sourceElementLayout.byteSize())の場合
      IndexOutOfBoundsException - sourceOffset < 0の場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfByte elementLayout, byte... elements)
      指定されたバイト配列の要素で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズはelementLayout.byteSize() * elements.lengthです。 ソース配列の内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
       this.allocateFrom(layout, MemorySegment.ofArray(array),
                   ValueLayout.JAVA_BYTE, 0, array.length)
      パラメータ:
      elementLayout - 割り当てる配列の要素レイアウト
      elements - 新しく割り当てられたメモリー・ブロックにコピーされるbyte要素
      戻り値:
      指定されたバイト配列の要素で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfShort elementLayout, short... elements)
      指定されたshort配列の要素で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズはelementLayout.byteSize() * elements.lengthです。 ソース配列の内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
       this.allocateFrom(layout, MemorySegment.ofArray(array),
                   ValueLayout.JAVA_SHORT, 0, array.length)
      パラメータ:
      elementLayout - 割り当てる配列の要素レイアウト
      elements - 新しく割り当てられたメモリー・ブロックにコピーされるshort要素
      戻り値:
      指定されたshort配列の要素で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfChar elementLayout, char... elements)
      指定されたchar配列の要素で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズはelementLayout.byteSize() * elements.lengthです。 ソース配列の内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
       this.allocateFrom(layout, MemorySegment.ofArray(array),
                   ValueLayout.JAVA_CHAR, 0, array.length)
      パラメータ:
      elementLayout - 割り当てる配列の要素レイアウト
      elements - 新しく割り当てられたメモリー・ブロックにコピーされるchar要素
      戻り値:
      指定されたchar配列の要素で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfInt elementLayout, int... elements)
      指定されたint配列の要素で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズはelementLayout.byteSize() * elements.lengthです。 ソース配列の内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
       this.allocateFrom(layout, MemorySegment.ofArray(array),
                   ValueLayout.JAVA_INT, 0, array.length)
      パラメータ:
      elementLayout - 割り当てる配列の要素レイアウト
      elements - 新しく割り当てられたメモリー・ブロックにコピーされるint要素
      戻り値:
      指定されたint配列の要素で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfFloat elementLayout, float... elements)
      指定されたfloat配列の要素で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズはelementLayout.byteSize() * elements.lengthです。 ソース配列の内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
       this.allocateFrom(layout, MemorySegment.ofArray(array),
                   ValueLayout.JAVA_FLOAT, 0, array.length)
      パラメータ:
      elementLayout - 割り当てる配列の要素レイアウト
      elements - 新しく割り当てられたメモリー・ブロックにコピーされるfloat要素
      戻り値:
      指定されたfloat配列の要素で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfLong elementLayout, long... elements)
      指定されたlong配列の要素で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズはelementLayout.byteSize() * elements.lengthです。 ソース配列の内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
       this.allocateFrom(layout, MemorySegment.ofArray(array),
                   ValueLayout.JAVA_LONG, 0, array.length)
      パラメータ:
      elementLayout - 割り当てる配列の要素レイアウト
      elements - 新しく割り当てられたメモリー・ブロックにコピーされるlong要素
      戻り値:
      指定されたlong配列の要素で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合

    • allocateFrom

      default MemorySegment allocateFrom(ValueLayout.OfDouble elementLayout, double... elements)
      指定されたdouble配列の要素で初期化された新しいメモリー・セグメントを返します。

      割り当てられたメモリー・セグメントのサイズはelementLayout.byteSize() * elements.lengthです。 ソース配列の内容は、指定された要素レイアウトのバイト順序および整列制約に従って、要素ごとに結果セグメント要素にコピーされます。

      実装要件:
      このメソッドのデフォルト実装は、次のコードと同等です。 
       this.allocateFrom(layout, MemorySegment.ofArray(array),
                   ValueLayout.JAVA_DOUBLE, 0, array.length)
      パラメータ:
      elementLayout - 割り当てる配列の要素レイアウト
      elements - 新しく割り当てられたメモリー・ブロックにコピーされるdouble要素
      戻り値:
      指定された二重配列の要素で初期化された新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteAlignment() > elementLayout.byteSize()の場合

    • allocate

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

    • allocate

      default MemorySegment allocate(MemoryLayout elementLayout, long count)
      指定されたelementLayoutおよびcountを持つ新しいメモリー・セグメントを戻します。
      実装要件:
      このメソッドのデフォルト実装では、this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))がコールされます。
      パラメータ:
      elementLayout - 配列要素のレイアウト
      count - 配列要素数
      戻り値:
      指定されたelementLayoutおよびcountを持つ新しいメモリー・セグメント
      例外:
      IllegalArgumentException - elementLayout.byteSize() * countがオーバーフローした場合
      IllegalArgumentException - count < 0の場合

    • allocate

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

    • allocate

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

    • slicingAllocator

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

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

      実装上のノート:
      ロケータはthread-safeではありません。
      パラメータ:
      segment - 返されたロケータがスライスされるセグメント
      戻り値:
      新しいロケータ
      例外:
      IllegalArgumentException - segmentがread-onlyの場合

    • prefixAllocator

      static SegmentAllocator prefixAllocator(MemorySegment segment)
      単一のセグメントをリサイクルして配賦リクエストに応答するセグメント・ロケータを返します。 新しい各割当てリクエストは、セグメント・オフセット0から始まる新しいスライスを返すため、「ロケータ」という名前が付けられます。

      (ただし、より効率的である可能性があります。)と同等のコードは次のとおりです: 

      MemorySegment segment = ...
SegmentAllocator prefixAllocator = (size, align) -> segment.asSlice(0, size, align);
      返されたロケータは、指定されたセグメントのスライスがリクエストされたサイズと整列で見つからない場合、IndexOutOfBoundsExceptionをスローします。

      APIのノート:
      プレフィクス・ロケータは、後続の配賦リクエストが実行される前に、割り当てられたセグメントの内容をクライアントが完全に処理したことを認識している場合に、配賦リクエストを制限するのに役立ちます。
      実装上のノート:
      ロケータがthread-safeである間、同じロケータで同時にアクセスすると、スレッドは、基礎となるセグメントに書き込まれた内容を別のスレッドで上書きする可能性があります。
      パラメータ:
      segment - 返されたロケータによってリサイクルされるメモリー・セグメント
      戻り値:
      新しい配賦リクエストごとに既存のセグメントをリサイクルするロケータ
      例外:
      IllegalArgumentException - segmentがread-onlyの場合