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

クラスValueLayout

java.lang.Object
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 class ValueLayout extends Object implements 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タイプなど、基本データ型の値に関連付けられたメモリー・レイアウトをモデル化するために使用します。 各値レイアウトには、サイズ、整列(ビット単位)、byte orderおよびcarrierがあります。つまり、値レイアウトを使用してメモリー・リージョンをaccessingPREVIEWするときに使用するJavaタイプです。

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

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

  • フィールド詳細

    • ADDRESS

      public static final ValueLayout.OfAddressPREVIEW ADDRESS
      マシン・アドレス(size_t)と同じサイズ、ビット位置合わせをsizeof(size_t) * 8に設定し、バイト順序をByteOrder.nativeOrder()に設定した値レイアウト定数。 次のコードと同等です: 
      MemoryLayout.valueLayout(MemoryAddress.class, ByteOrder.nativeOrder())
            .withBitAlignment(<address size>);

    • JAVA_BYTE

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

    • JAVA_BOOLEAN

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

    • JAVA_CHAR

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

    • JAVA_SHORT

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

    • JAVA_INT

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

    • JAVA_LONG

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

    • JAVA_FLOAT

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

    • JAVA_DOUBLE

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

  • メソッドの詳細

    • order

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

    • withOrder

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

    • toString

      public String toString()
      このレイアウトの文字列表現を返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のtoString
      戻り値:
      このレイアウトの文字列表現

    • equals

      public boolean equals(Object other)
      指定されたオブジェクトをこのレイアウトと比較し、等価性を維持します。 指定されたオブジェクトもレイアウトであり、このレイアウトと等しい場合にのみ、trueを返します。 2つのレイアウトが同じ種類であり、同じサイズ、名前および位置合せ制約を持つ場合は、それらが等価であるとみなされます。 また、レイアウトの種類に応じて、追加の条件を満たす必要があります:
      定義:
      インタフェースMemoryLayoutPREVIEW内のequals
      パラメータ:
      other - このレイアウトと等価性を持たせるために比較するオブジェクト。
      戻り値:
      指定されたオブジェクトがこのレイアウトに等しい場合、true。
      関連項目:

    • arrayElementVarHandle

      public VarHandle arrayElementVarHandle(int... shape)
      マルチディメンション配列の間接参照に使用できる「アカド」アクセス変数ハンドルを作成します。 この配列のレイアウトは、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(-1,
                                     MemoryLayout.sequenceLayout(10,
                                                 MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));
      結果のvarハンドルarrayHandleは、タイプlongの3つの座標を備えています。各座標は、対応する順序レイアウトへの索引として解釈されます。 varハンドルの座標を左から右にそれぞれ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

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

    • hashCode

      public int hashCode()
      このレイアウトのハッシュ・コード値を返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のhashCode
      戻り値:
      このレイアウトのハッシュ・コード値
      関連項目:

    • withName

      public ValueLayoutPREVIEW withName(String name)
      サイズと位置合わせの制約がこのレイアウトと同じですが、指定された名前でメモリー・レイアウトを返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のwithName
      パラメータ:
      name - レイアウト名。
      戻り値:
      指定された名前のメモリー・レイアウト。
      関連項目:

    • withBitAlignment

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

    • name

      public final Optional<String> name()
      インタフェースからコピーされた説明:MemoryLayout
      このレイアウトに関連付けられている名前(もしあれば)を返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のname
      戻り値:
      このレイアウトに関連付けられている名前(もしあれば)
      関連項目:

    • bitAlignment

      public final long bitAlignment()
      インタフェースからコピーされた説明:MemoryLayout
      このレイアウトに関連付けられている配置制約をビット単位で返します。 レイアウトの位置合せにより、レイアウトのビット単位の位置合せである2つのAの機能が定義されます。 A <= 8の場合、A/8は、このレイアウトを適切にポイントするポインタに対して整列する必要があるバイト数です。 このため、:
      • A=8では、すべての(通常の意味で)がパケットで共有されないことを意味します。
      • A=64は、aligned (on LP64)、A=32 int aligned、A=16 short alignedなどの単語を意味します。
      • A=512は、x86/SV ABI (AVX-512データ)で必要とされる最も厳密な位置合せです。
      このレイアウト(MemoryLayout.withBitAlignment(long)PREVIEWを参照してください)に明示的な位置合せ制約が設定されていない場合、このメソッドは、このレイアウトに関連付けられている「自然整列」制約(ビット単位)を返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のbitAlignment
      戻り値:
      レイアウト位置合せ制約をビット単位で指定します。

    • byteSize

      public long byteSize()
      インタフェースからコピーされた説明:MemoryLayout
      レイアウト・サイズをバイト単位で返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のbyteSize
      戻り値:
      レイアウト・サイズ(バイト)

    • bitSize

      public long bitSize()
      インタフェースからコピーされた説明:MemoryLayout
      レイアウト・サイズをビット単位で返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のbitSize
      戻り値:
      レイアウト・サイズ(ビット単位)

    • isPadding

      public boolean isPadding()
      インタフェースからコピーされた説明:MemoryLayout
      このレイアウトがパディング・レイアウトの場合、trueを返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のisPadding
      戻り値:
      このレイアウトがパディング・レイアウトの場合、true