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

インタフェースValueLayout

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

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

このクラスは、Javaプリミティブ型およびアドレスの有用な値レイアウト定数を定義します。

APIのノート:
Javaレイアウト定数のいくつかの特性は、プラットフォームに依存します。 たとえば、これらの定数のバイト順序は「ネイティブ・バイト順序」に設定されているため、配列やByteBufferなどの他のAPIを簡単に操作できます。 さらに、64ビット・プラットフォームではJAVA_LONGとJAVA_DOUBLEの境界整列制約が8バイトに設定されていますが、32ビット・プラットフォームでは4バイトのみに設定されています。
実装要件:
クラスおよびサブクラスの実装は、不変、スレッド・セーフおよびvalue-basedです。
シール済クラス階層グラフ:
ValueLayoutの密封されたクラス階層グラフValueLayoutの密封されたクラス階層グラフ
導入されたバージョン:
19

  • フィールド詳細

    • ADDRESS

      static final AddressLayoutPREVIEW ADDRESS
      sizeof(size_t)に設定されたマシン・アドレス (size_t)のバイト整列と同じサイズを持つアドレス配列定数。ByteOrder.nativeOrder()に設定されたバイト順序。

    • JAVA_BYTE

      static final ValueLayout.OfBytePREVIEW JAVA_BYTE
      サイズがJava byte、1に設定されたバイト整列、およびByteOrder.nativeOrder()に設定されたバイト順序と同じ値レイアウト定数。

    • JAVA_BOOLEAN

      static final ValueLayout.OfBooleanPREVIEW JAVA_BOOLEAN
      サイズがJava boolean、1に設定されたバイト整列、およびByteOrder.nativeOrder()に設定されたバイト順序と同じ値レイアウト定数。

    • JAVA_CHAR

      static final ValueLayout.OfCharPREVIEW JAVA_CHAR
      サイズがJava char、2に設定されたバイト整列、およびByteOrder.nativeOrder()に設定されたバイト順序と同じ値レイアウト定数。

    • JAVA_SHORT

      static final ValueLayout.OfShortPREVIEW JAVA_SHORT
      サイズがJava short、2に設定されたバイト整列、およびByteOrder.nativeOrder()に設定されたバイト順序と同じ値レイアウト定数。

    • JAVA_INT

      static final ValueLayout.OfIntPREVIEW JAVA_INT
      サイズがJava int、4に設定されたバイト整列、およびByteOrder.nativeOrder()に設定されたバイト順序と同じ値レイアウト定数。

    • JAVA_LONG

      static final ValueLayout.OfLongPREVIEW JAVA_LONG
      サイズがJava long、(platform-dependent)バイトの整列がADDRESS.byteSize()、バイト順序がByteOrder.nativeOrder()に設定されている値レイアウト定数。

    • JAVA_FLOAT

      static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT
      サイズがJava float、4に設定されたバイト整列、およびByteOrder.nativeOrder()に設定されたバイト順序と同じ値レイアウト定数。

    • JAVA_DOUBLE

      static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE
      サイズがJava double、(platform-dependent)バイトの整列がADDRESS.byteSize()、バイト順序がByteOrder.nativeOrder()に設定されている値レイアウト定数。

    • ADDRESS_UNALIGNED

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

    • JAVA_CHAR_UNALIGNED

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

    • JAVA_SHORT_UNALIGNED

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

    • JAVA_INT_UNALIGNED

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

    • JAVA_LONG_UNALIGNED

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

    • JAVA_FLOAT_UNALIGNED

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

    • JAVA_DOUBLE_UNALIGNED

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

  • メソッドの詳細

    • order

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

    • withOrder

      ValueLayoutPREVIEW withOrder(ByteOrder order)
      このレイアウトと同じ特性を持つ値レイアウトを、指定されたバイト順序で返します。
      パラメータ:
      order - 必要なバイト順。
      戻り値:
      このレイアウトと同じ特性を持つが、指定されたバイト順序を持つ値レイアウト

    • withoutName

      ValueLayoutPREVIEW withoutName()
      このレイアウトと同じ特性を持つメモリー・レイアウトを名前なしで返します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のwithoutName
      戻り値:
      このレイアウトと同じ特性を持つが名前のないメモリー・レイアウト
      関連項目:

    • arrayElementVarHandle

      VarHandle arrayElementVarHandle(int... shape)
      メモリー・セグメントに多ディメンション配列としてアクセスするために使用できる「ストライドされた」 varハンドルを作成します。 この配列には、shape.lengthのネストされた順序レイアウトを備えたノーショナル順序レイアウトがあります。 ノーショナル順序レイアウト内の最も内側の順序レイアウトの要素レイアウトは、この値レイアウトです。 結果のvarハンドルは、想定レイアウトでMemoryLayout.varHandle(PathElement...)PREVIEWメソッドをコールする場合と同様に取得され、レイアウト・パスには正確にshape.length + 1 「オープン順序レイアウト・パス要素」PREVIEWが含まれます。

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

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

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

      int value1 = (int) arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176
int value2 = (int) 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 - byteAlignment() > byteSize()の場合。
      関連項目:

    • carrier

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

    • withName

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

    • withByteAlignment

      ValueLayoutPREVIEW withByteAlignment(long byteAlignment)
      このレイアウトと同じ特性を持つメモリー・レイアウトを返しますが、指定された整列制約(バイト単位)を使用します。
      定義:
      インタフェースMemoryLayoutPREVIEW内のwithByteAlignment
      パラメータ:
      byteAlignment - バイト単位で表されるレイアウト整列制約。
      戻り値:
      このレイアウトと同じ特性を持つメモリー・レイアウト。ただし、指定された整列制約(バイト単位)
      例外:
      IllegalArgumentException - byteAlignmentが2の累乗でない場合。