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

インタフェースValueLayout

すべてのスーパー・インタフェース:
MemoryLayoutPREVIEW
既知のすべてのサブインタフェース:
ValueLayout.OfAddressPREVIEW, ValueLayout.OfBooleanPREVIEW, ValueLayout.OfBytePREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfDoublePREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfShortPREVIEW
public sealed interface ValueLayout extends MemoryLayoutPREVIEW permits ValueLayout.OfBytePREVIEW, ValueLayout.OfShortPREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfDoublePREVIEW, ValueLayout.OfBooleanPREVIEW, ValueLayout.OfAddressPREVIEW
ValueLayoutは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでValueLayoutを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
基本データ型の値をモデル化するレイアウト。 値レイアウトによってモデル化された値の例には、「整数」値(署名済または未署名)、floating-point値およびaddress値があります。

各値レイアウトには、サイズ、整列(ビット単位)、「バイト・オーダー」および「キャリア」があります。つまり、値レイアウトを使用してメモリーのリージョンを「アクセス」PREVIEWするときに使用するJavaタイプです。

このクラスは、Javaプリミティブ型およびアドレスの有用な値レイアウト定数を定義します。 このクラスのレイアウト定数は、暗黙的な整列とバイト順序の想定を行います: このクラスのすべてのレイアウト定数はバイト揃えで、バイト順序は「プラットフォームのデフォルト」に設定されるため、配列やByteBufferなどの他のAPIを簡単に操作できます。

実装要件:
クラスおよびサブクラスの実装は、不変、スレッド・セーフおよびvalue-basedです。
導入されたバージョン:
19

  • ﾌｨｰﾙﾄﾞ詳細

    • ADDRESS

      static final ValueLayout.OfAddressPREVIEW ADDRESS
      サイズがマシン・アドレス(size_t)と同じ値レイアウト定数で、ビット整列がsizeof(size_t) * 8に設定され、バイト順序がByteOrder.nativeOrder()に設定されています。 次のコードと同等です: 
      MemoryLayout.valueLayout(MemorySegment.class, ByteOrder.nativeOrder());

    • JAVA_BYTE

      static final ValueLayout.OfBytePREVIEW JAVA_BYTE
      Java byteと同じサイズの値レイアウト定数、8に設定されたビット整列、およびByteOrder.nativeOrder()に設定されたバイト順序。 次のコードと同等です: 
      MemoryLayout.valueLayout(byte.class, ByteOrder.nativeOrder());

    • JAVA_BOOLEAN

      static final ValueLayout.OfBooleanPREVIEW JAVA_BOOLEAN
      Java booleanと同じサイズの値レイアウト定数、8に設定されたビット整列、およびByteOrder.nativeOrder()に設定されたバイト順序。 次のコードと同等です: 
      MemoryLayout.valueLayout(boolean.class, ByteOrder.nativeOrder());

    • JAVA_CHAR

      static final ValueLayout.OfCharPREVIEW JAVA_CHAR
      サイズがJava char、ビット位置合わせが16、バイト順序がByteOrder.nativeOrder()に設定された値レイアウト定数。 次のコードと同等です: 
      MemoryLayout.valueLayout(char.class, ByteOrder.nativeOrder());

    • JAVA_SHORT

      static final ValueLayout.OfShortPREVIEW JAVA_SHORT
      サイズがJava short、ビット位置合わせが16、バイト順序がByteOrder.nativeOrder()に設定された値レイアウト定数。 次のコードと同等です: 
      MemoryLayout.valueLayout(short.class, ByteOrder.nativeOrder());

    • JAVA_INT

      static final ValueLayout.OfIntPREVIEW JAVA_INT
      サイズがJava int、ビット位置合わせが32、バイト順序がByteOrder.nativeOrder()に設定されている値レイアウト定数。 次のコードと同等です: 
      MemoryLayout.valueLayout(int.class, ByteOrder.nativeOrder());

    • JAVA_LONG

      static final ValueLayout.OfLongPREVIEW JAVA_LONG
      Java longと同じサイズ、64に設定されたビット整列、ByteOrder.nativeOrder()に設定されたバイト順序を持つ値レイアウト定数。 次のコードと同等です: 
      MemoryLayout.valueLayout(long.class, ByteOrder.nativeOrder());

    • JAVA_FLOAT

      static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT
      サイズがJava float、ビット位置合わせが32、バイト順序がByteOrder.nativeOrder()に設定されている値レイアウト定数。 次のコードと同等です: 
      MemoryLayout.valueLayout(float.class, ByteOrder.nativeOrder()).withBitAlignment(32);

    • JAVA_DOUBLE

      static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE
      Java doubleと同じサイズ、64に設定されたビット整列、ByteOrder.nativeOrder()に設定されたバイト順序を持つ値レイアウト定数。 次のコードと同等です: 
      MemoryLayout.valueLayout(double.class, ByteOrder.nativeOrder());

    • ADDRESS_UNALIGNED

      static final ValueLayout.OfAddressPREVIEW ADDRESS_UNALIGNED
      サイズがマシン・アドレス(size_t)と同じで、バイト順序がByteOrder.nativeOrder()に設定されている、整列されていない値レイアウト定数。 次のコードと同等です: 
      ADDRESS.withBitAlignment(8);
      APIのノート:
      調整されていない値レイアウトを使用すると、パフォーマンスや移植性の問題が発生する可能性があるため、注意する必要があります。

    • JAVA_CHAR_UNALIGNED

      static final ValueLayout.OfCharPREVIEW JAVA_CHAR_UNALIGNED
      サイズがJavaのcharと同じで、バイト順序がByteOrder.nativeOrder()に設定されている整列されていない値レイアウト定数。 次のコードと同等です: 
      JAVA_CHAR.withBitAlignment(8);
      APIのノート:
      調整されていない値レイアウトを使用すると、パフォーマンスや移植性の問題が発生する可能性があるため、注意する必要があります。

    • JAVA_SHORT_UNALIGNED

      static final ValueLayout.OfShortPREVIEW JAVA_SHORT_UNALIGNED
      サイズがJavaのshortと同じで、バイト順序がByteOrder.nativeOrder()に設定されている整列されていない値レイアウト定数。 次のコードと同等です: 
      JAVA_SHORT.withBitAlignment(8);
      APIのノート:
      調整されていない値レイアウトを使用すると、パフォーマンスや移植性の問題が発生する可能性があるため、注意する必要があります。

    • JAVA_INT_UNALIGNED

      static final ValueLayout.OfIntPREVIEW JAVA_INT_UNALIGNED
      サイズがJavaのintと同じで、バイト順序がByteOrder.nativeOrder()に設定されている整列されていない値レイアウト定数。 次のコードと同等です: 
      JAVA_INT.withBitAlignment(8);
      APIのノート:
      調整されていない値レイアウトを使用すると、パフォーマンスや移植性の問題が発生する可能性があるため、注意する必要があります。

    • JAVA_LONG_UNALIGNED

      static final ValueLayout.OfLongPREVIEW JAVA_LONG_UNALIGNED
      サイズがJavaのlongと同じで、バイト順序がByteOrder.nativeOrder()に設定されている整列されていない値レイアウト定数。 次のコードと同等です: 
      JAVA_LONG.withBitAlignment(8);
      APIのノート:
      調整されていない値レイアウトを使用すると、パフォーマンスや移植性の問題が発生する可能性があるため、注意する必要があります。

    • JAVA_FLOAT_UNALIGNED

      static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT_UNALIGNED
      サイズがJavaのfloatと同じで、バイト順序がByteOrder.nativeOrder()に設定されている整列されていない値レイアウト定数。 次のコードと同等です: 
      JAVA_FLOAT.withBitAlignment(8);
      APIのノート:
      調整されていない値レイアウトを使用すると、パフォーマンスや移植性の問題が発生する可能性があるため、注意する必要があります。

    • JAVA_DOUBLE_UNALIGNED

      static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE_UNALIGNED
      サイズがJavaのdoubleと同じで、バイト順序がByteOrder.nativeOrder()に設定されている整列されていない値レイアウト定数。 次のコードと同等です: 
      JAVA_DOUBLE.withBitAlignment(8);
      APIのノート:
      調整されていない値レイアウトを使用すると、パフォーマンスや移植性の問題が発生する可能性があるため、注意する必要があります。

  • メソッドの詳細

    • order

      ByteOrder order()
      値のバイト順を返します。
      戻り値:
      値のバイト順

    • withOrder

      ValueLayoutPREVIEW withOrder(ByteOrder order)
      この値レイアウトと同じ運送業者、整列制約および名前で、指定されたバイト順の値レイアウトを返します。
      パラメータ:
      order - 必要なバイト順。
      戻り値:
      指定されたバイト順の値レイアウト。

    • arrayElementVarHandle

      VarHandle arrayElementVarHandle(int... shape)
      メモリー・セグメントに多ディメンション配列としてアクセスするために使用できる「ストライドされた」 varハンドルを作成します。 この配列のレイアウトは、shape.lengthネストされた順序レイアウトを含む順序レイアウトです。 深さshape.lengthでの順序レイアウトの要素レイアウトは、この値のレイアウトです。 その結果、shape.length == 0の場合、配列レイアウトには1つのディメンションのみが含まれます。

      結果のvarハンドルは、long型のsizes.length + 1座標を備えており、これはマルチディメンション配列の索引として使用されます。

      たとえば、次のメソッド・コールがあります: 

      VarHandle arrayHandle = ValueLayout.JAVA_INT.arrayElementVarHandle(10, 20);
      次のレイアウトを持つ多ディメンション配列にアクセスするために使用できます: 
       SequenceLayout arrayLayout = MemoryLayout.sequenceLayout(
                                      MemoryLayout.sequenceLayout(10,
                                                  MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));
      結果のvarハンドルarrayHandleは、タイプlongの3つの座標を備えています。各座標は、対応する順序レイアウトへの索引として解釈されます。 左から右にそれぞれx、yおよびzとして可変ハンドル座標を参照する場合、varハンドルによってアクセスされる最終オフセットは次の式を使用して計算できます: 
      
 offset = (10 * 20 * 4 * x) + (20 * 4 * y) + (4 * z)
      また、x、yおよびzの値は、次のように制約されます:
      • 0 <= x < arrayLayout.elementCount()
      • 0 <= y < 10
      • 0 <= z < 20

      次のアクセス式について考えます: 

      int value1 = arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176
int value2 = arrayHandle.get(0, 0, 30); // out of bounds value for z
      最初のケースでは、x、yおよびzの値が前述の境界に適合するため、アクセスは整形式です。 2番目のケースでは、zの値が指定された範囲外であるため、IndexOutOfBoundsExceptionを使用してアクセスが失敗します。

      パラメータ:
      shape - ネストされた配列ディメンションのサイズ。
      戻り値:
      shape.length + 1 long座標を備えた多ディメンション配列としてメモリー・セグメントにアクセスするために使用できるvarハンドル。
      例外:
      IllegalArgumentException - shape[i] < 0の場合、少なくとも1つの索引i。
      UnsupportedOperationException - bitAlignment() > bitSize()の場合。
      関連項目:

    • carrier

      Class<?> carrier()
      この値レイアウトに関連付けられたキャリアを返します。
      戻り値:
      この値レイアウトに関連付けられたキャリア

    • withName

      ValueLayoutPREVIEW withName(String name)
      このレイアウトと同じサイズおよび整列制約を持つ、指定された名前の同じタイプのメモリー・レイアウトを返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のwithName
      パラメータ:
      name - レイアウト名。
      戻り値:
      指定された名前のメモリー・レイアウト。
      関連項目:

    • withBitAlignment

      ValueLayoutPREVIEW withBitAlignment(long bitAlignment)
      このレイアウトと同じサイズおよび名前を持つ同じタイプのメモリー・レイアウトを返しますが、指定された整列制約(ビット単位)を使用します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のwithBitAlignment
      パラメータ:
      bitAlignment - レイアウト位置合せ制約。ビットで表されます。
      戻り値:
      指定された境界整列制約を持つメモリー・レイアウト。