モジュール jdk.incubator.vector
パッケージ jdk.incubator.vector

インタフェースVectorSpecies<E>

型パラメータ:
E - ETYPEのボックス版、ベクトルの要素型

public interface VectorSpecies<E>
「要素型」 (ETYPE)とshapeの同じ組合せのすべてのベクトルを管理するためのインタフェース。
APIのノート:
ユーザー・コードはこのインタフェースを実装しないでください。 この型の将来のリリースでは、実装が同じパッケージのメンバーになるように制限される可能性があります。
実装上のノート:
このインタフェースのインスタンスの文字列表現は、"Species [ETYPE, VLENGTH, SHAPE]"という形式になります。 ETYPEはプリミティブ「レーン・タイプ」VLENGTHは種に関連付けられた「ベクトル・レーン・カウント」SHAPEは種に関連付けられた「ベクトル・シェイプ」です。

ベクトル種オブジェクトは、ローカルおよびパラメータにstatic final定数として格納できますが、意味的には有効ですが、他のJavaフィールドまたは配列要素に格納すると、パフォーマンスが低下する可能性があります。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    broadcast(long e)
    すべてのレーン要素がプリミティブ値eに設定されている、指定された種のベクトルを返します。
    check(Class<F> elementType)
    この種が指定された要素型を持っているかどうかを判定し、この種をそのまま返します。
    long
    checkValue(long e)
    この種が指定された要素値を表すことができることを確認し、値を変更せずに返します。
    int
    この種のベクトルのレーンのサイズをビット単位で返します。
    static int
    elementSize(Class<?> elementType)
    指定されたベクトル要素型(ETYPE)のビット・サイズを返します。
    この種のベクトルのプリミティブ要素型を返します。
    boolean
    この種がほかのオブジェクトと同一かどうかを示します。
    fromArray(Object a, int offset)
    指定されたオフセットの指定された配列からレーン要素が初期化される、この種のベクトルを返します。
    fromByteArray(byte[] a, int offset, ByteOrder bo)
    オフセットから始まるバイト配列からこの種のベクトルをロードします。
    int
    ベクトルのシェイプと要素の型に基づいて、種のハッシュ・コード値を返します。
    indexInRange(int offset, int limit)
    調整されたインデックスN+offset[0..limit-1]の範囲内にあるように、インデックスNのレーンだけが設定されているこの種のマスクを返します。
    iotaShuffle(int start, int step, boolean wrap)
    startから始まり、指定されたstepによってステップ実行される連続値に設定されたソース索引を使用してシャッフルを作成します。
    int
    この種のベクトル内のレーンの数を返します。
    loadMask(boolean[] bits, int offset)
    指定されたオフセットの指定された配列からレーン要素が初期化される、この種のマスクを返します。
    int
    loopBound(int length)
    指定されたlength値以下のVLENGTHの最大の倍数を返すループ制御関数。
    maskAll(boolean bit)
    この種のマスクを返します。各レーンは、指定された単一のbooleanに従って設定または設定解除され、すべてのレーンにブロードキャストされます。
    Class<? extends VectorMask<E>>
    この種のベクトル・マスク・タイプを返します。
    static <E> VectorSpecies<E>
    of(Class<E> elementType, VectorShape shape)
    要素の型とシェイプの種を検索します。
    static <E> VectorSpecies<E>
    指定された要素型の最大のベクトル種を検索します。
    static <E> VectorSpecies<E>
    ofPreferred(Class<E> etype)
    指定されたベクトル要素型について、現在のプラットフォームが優先する種を検索します。
    int
    partLimit(VectorSpecies<?> outputSpecies, boolean lanewise)
    この種と別の種を指定すると、「再解釈キャスト」またはlane-wise conversionのサイズを変更する(潜在的)のネット拡張または縮小が、この種から秒にレポートされます。
    shuffleFromArray(int[] sourceIndexes, int offset)
    オフセットから始まるint配列から、この種のシャッフルを作成します。
    範囲[0..VLENGTH-1]に適用される演算子の連続する値から、この種のシャッフルを作成します。
    shuffleFromValues(int... sourceIndexes)
    一連のソース・インデックスからこの種のシャッフルを作成します。
    "Species [ETYPE, VLENGTH, SHAPE]"という形式の文字列を返します。ETYPEはプリミティブ「レーン・タイプ」VLENGTHは種に関連付けられた「ベクトル・レーン・カウント」 SHAPEは種に関連付けられた「ベクトル・シェイプ」です。
    int
    この種のベクトルの合計ベクトル・サイズ(ビット単位)を返します。
    int
    この種のベクトルの合計ベクトル・サイズ(バイト単位)を返します。
    この種によって生成されたベクトルのシェイプを返します。
    Class<? extends Vector<E>>
    この種のベクトル型を返します。
    withLanes(Class<F> newType)
    指定された要素タイプとこの種と同じシェイプを持つ種を検索します。
    指定されたシェイプとこの種と同じelementTypeを持つ種を検索します。
    すべてのレーン要素がデフォルトのプリミティブ値である(ETYPE)0に設定されている、この種のベクトルを返します。
  • メソッドの詳細

    • elementType

      Class<E> elementType()
      この種のベクトルのプリミティブ要素型を返します。
      戻り値:
      プリミティブ要素の型(ETYPE)
      関連項目:
    • vectorType

      Class<? extends Vector<E>> vectorType()
      この種のベクトル型を返します。 ベクトルがこの種であるのは、対応するベクトル型である場合だけです。
      戻り値:
      この種のベクトル・タイプ
    • maskType

      Class<? extends VectorMask<E>> maskType()
      この種のベクトル・マスク・タイプを返します。
      戻り値:
      マスク・タイプ
    • elementSize

      int elementSize()
      この種のベクトルのレーンのサイズをビット単位で返します。
      戻り値:
      要素のサイズ(ビット単位)
    • vectorShape

      VectorShape vectorShape()
      この種によって生成されたベクトルのシェイプを返します。
      戻り値:
      この種のベクトルのシェイプ
    • length

      int length()
      この種のベクトル内のレーンの数を返します。
      APIのノート:
      これは、この種のベクトルに関連付けられたマスクまたはシャッフル内のレーンの数でもあります。
      戻り値:
      ベクトル・レーンの数
    • vectorBitSize

      int vectorBitSize()
      この種のベクトルの合計ベクトル・サイズ(ビット単位)を返します。 これは、this.vectorShape().vectorBitSize()と同じ値です。
      APIのノート:
      このサイズは、この種のマスクまたはシャッフルのビット単位のサイズとは異なる場合があります。
      戻り値:
      ベクトルの合計サイズ(ビット単位)
    • vectorByteSize

      int vectorByteSize()
      この種のベクトルの合計ベクトル・サイズ(バイト単位)を返します。 これは、this.vectorShape().vectorBitSize() / Byte.SIZEと同じ値です。
      APIのノート:
      このサイズは、この種のマスクまたはシャッフルのビット単位のサイズとは異なる場合があります。
      戻り値:
      ベクトルの合計サイズ(バイト単位)
    • loopBound

      int loopBound(int length)
      指定されたlength値以下のVLENGTHの最大の倍数を返すループ制御関数。 ここで、VLENGTHthis.length()の結果であり、lengthはいくつかのレーンとして解釈されます。 結果の値Rは、次の不等式を満たします:
      R <= length < R+VLENGTH
       

      具体的には、このメソッドはlength - floorMod(length, VLENGTH)を計算し、floorModはその商を負の無限大に丸めて剰余値を計算します。 VLENGTHが2の累乗であるかぎり、結果もlength & ~(VLENGTH - 1)と等しくなります。

      パラメータ:
      length - 入力長
      戻り値:
      指定された長さ以下のベクトル長の最大の倍数
      例外:
      IllegalArgumentException - lengthが負で、結果が正の値にオーバーフローする場合
      関連項目:
    • indexInRange

      VectorMask<E> indexInRange(int offset, int limit)
      調整されたインデックスN+offset[0..limit-1]の範囲内にあるように、インデックスNのレーンだけが設定されているこの種のマスクを返します。

      このメソッドは、式maskAll(true).indexInRange(offset, limit)の値を戻します

      パラメータ:
      offset - 開始インデックス
      limit - インデックス範囲の上限(exclusive)
      戻り値:
      範囲外のレーンが設定されたマスク
      関連項目:
    • check

      <F> VectorSpecies<F> check(Class<F> elementType)
      この種が指定された要素型を持っているかどうかを判定し、この種をそのまま返します。 効果は次の疑似コードのようになります : elementType == elementType() ? this : throw new ClassCastException()
      型パラメータ:
      F - 必要なレーン型のボックス化された要素型
      パラメータ:
      elementType - 必要なレーン・タイプ
      戻り値:
      同じ種
      例外:
      ClassCastException - 種の要素タイプが間違っている場合
      関連項目:
    • partLimit

      int partLimit(VectorSpecies<?> outputSpecies, boolean lanewise)
      この種と別の種を指定すると、「再解釈キャスト」またはlane-wise conversionのサイズを変更する(潜在的)のネット拡張または縮小が、この種から秒にレポートされます。 戻り値の符号と大きさは、提案された入力と出力のshapesのサイズの違いに依存し、(オプションで、lanewiseがtrueの場合)は提案された入力と出力の「レーン」のサイズの違いにも依存します。
      • 最初に、論理結果サイズが決定されます。 lanewiseがfalseの場合、このサイズは入力VSHAPEのサイズです。 lanewiseがtrueの場合、論理結果サイズは、入力VLENGTHoutput ETYPEのサイズを掛けた積になります。
      • 次に、論理結果サイズを提案された出力シェイプのサイズと比較して、どのように適合するかを確認します。
      • 論理結果が出力シェイプに正確に収まる場合、戻り値はゼロであり、ネット拡張や縮小がないことを意味します。
      • 論理結果が出力シェイプをオーバーフローする場合、戻り値は(より小さい)出力サイズに対する論理結果サイズの比率(次より大きい)です。 この比率は、結果が出力ベクトルに収まるように、入力から削除する必要がある"削除された入力ビット"の比率を測定しているとみなすことができます。 また、入力種を出力種に変換するメソッドに対するpartパラメータの上限である「パーツ限界」でもあります。
      • 論理結果が余裕のある領域とともに出力シェイプにドロップされる場合、戻り値は、出力サイズと(より小さい)論理結果サイズの間の絶対値が(次より大きい)である負数になります。 この比率は、出力ベクトルを埋めるために論理結果に追加する必要がある"余分なパディング・ビット"の比率の測定とみなすことができます。 また、入力種を出力種に変換するメソッドに対するpartパラメータの排他的な下限である「パーツ限界」でもあります。
      パラメータ:
      outputSpecies - 提案された出力種
      lanewise - レーンのサイズを考慮するかどうか
      戻り値:
      符号付きの比率またはゼロとしてのサイズ変更を示す
      関連項目:
    • withLanes

      <F> VectorSpecies<F> withLanes(Class<F> newType)
      指定された要素タイプとこの種と同じシェイプを持つ種を検索します。 VectorSpecies.of(newType, this.vectorShape())と同じ値を返します。
      型パラメータ:
      F - boxed要素型
      パラメータ:
      newType - 新しい要素型
      戻り値:
      新しい要素タイプと同じシェイプの種
      例外:
      IllegalArgumentException - 指定された要素の型とシェイプの組合せに対してそのような種が存在しない場合、または指定された型が有効なETYPEでない場合
      関連項目:
    • withShape

      VectorSpecies<E> withShape(VectorShape newShape)
      指定されたシェイプとこの種と同じelementTypeを持つ種を検索します。 VectorSpecies.of(this.elementType(), newShape)と同じ値を返します。
      パラメータ:
      newShape - 新しいシェイプ
      戻り値:
      同じ要素タイプと新しいシェイプの種
      例外:
      IllegalArgumentException - 指定された要素タイプとシェイプの組合せに対してそのような種が存在しない場合
      関連項目:
    • of

      static <E> VectorSpecies<E> of(Class<E> elementType, VectorShape shape)
      要素の型とシェイプの種を検索します。
      型パラメータ:
      E - boxed要素型
      パラメータ:
      elementType - 要素の型
      shape - シェイプ
      戻り値:
      指定された要素の型とシェイプの種
      例外:
      IllegalArgumentException - 指定された要素の型とシェイプの組合せに対してそのような種が存在しない場合、または指定された型が有効なETYPEでない場合
      関連項目:
    • ofLargestShape

      static <E> VectorSpecies<E> ofLargestShape(Class<E> etype)
      指定された要素型の最大のベクトル種を検索します。

      返される種は、プラットフォームによって選択される種で、指定された要素型に対して可能な最大のビット・サイズを持つシェイプを持ちます。 基礎となるベクトル・シェイプでは、一部のプラットフォームで他のレーン・タイプがサポートされない場合があり、これにより「再解釈キャスト」の適用が制限される可能性があります。 プラットフォーム「優先種」を使用する場合、再解釈キャストを必要とするベクトル・アルゴリズムの移植性が向上します。

      型パラメータ:
      E - boxed要素型
      パラメータ:
      etype - 要素の型
      戻り値:
      要素型の優先種
      例外:
      IllegalArgumentException - そのような種が要素型に存在しない場合、または指定された型が有効なETYPEでない場合
      関連項目:
    • ofPreferred

      static <E> VectorSpecies<E> ofPreferred(Class<E> etype)
      指定されたベクトル要素型について、現在のプラットフォームが優先する種を検索します。 これは、VectorSpecies.of(etype, VectorShape.preferredShape())と同じ値です。

      この種は、すべてのレーン要素型をサポートする最大のシェイプを持つように、プラットフォームによって選択されます。 これは次のような意味合いを持ちます:

      • 様々な要素タイプの様々な優先種は、基礎となるシェイプが同じになります。
      • 優先種から作成されたすべてのベクトルには、共通のビット・サイズおよび情報容量があります。
      • 優先種のベクトル間の「再解釈キャスト」では、レーンの切捨てやデフォルト値の入力は行われません。
      • 特定の要素タイプについて、プラットフォームによっては、(トレードオフとして)がすべての可能な要素タイプをサポートしていない「ベクトル・シェイプの拡大」を提供する場合があります。

      実装上のノート:
      多くのプラットフォームでは、ofLargestShapeofPreferredの動作に違いはありません。これは、通常、すべてのレーン・タイプで使用可能なシェイプが最も大きいためです。 したがって、ほとんどのベクトル・アルゴリズムはofLargestShapeなしで正常に実行されます。
      型パラメータ:
      E - boxed要素型
      パラメータ:
      etype - 要素の型
      戻り値:
      この要素型の優先種
      例外:
      IllegalArgumentException - そのような種が要素型に存在しない場合、または指定された型が有効なETYPEでない場合
      関連項目:
    • elementSize

      static int elementSize(Class<?> elementType)
      指定されたベクトル要素型(ETYPE)のビット・サイズを返します。 要素タイプは、ラッパー・タイプやその他のオブジェクト・タイプではなく、有効なETYPEである必要があります。 要素タイプ引数は、byte.classint.classdouble.classなどの有効なベクトルETYPEのミラーである必要があります。 このような型のビット・サイズは、対応するラッパー・クラス(Byte.SIZEInteger.SIZEDouble.SIZEなど)のSIZE定数です。
      パラメータ:
      elementType - ベクトル要素型(ETYPE)
      戻り値:
      elementTypeのビット・サイズ(int.classの場合は32など)
      例外:
      IllegalArgumentException - 指定されたelementType引数が有効なベクトルETYPEでない場合
    • zero

      Vector<E> zero()
      すべてのレーン要素がデフォルトのプリミティブ値である(ETYPE)0に設定されている、この種のベクトルを返します。 この種に対応するベクトル・タイプのIntVector.zero(this)または同等のzeroメソッドと同等です。
      戻り値:
      指定された種のゼロ・ベクトル
      関連項目:
    • fromArray

      Vector<E> fromArray(Object a, int offset)
      指定されたオフセットの指定された配列からレーン要素が初期化される、この種のベクトルを返します。 配列は正しいETYPEである必要があります。 この種に対応するベクトル・タイプのIntVector.fromArray(this,a,offset)または同等のfromArrayメソッドと同等です。
      パラメータ:
      a - この種のETYPEの配列
      offset - ロードする最初のレーン値のインデックス
      戻り値:
      配列から塗りつぶされた指定された種のベクトル
      例外:
      IndexOutOfBoundsException - ベクトル内のレーンNoffset+N < 0またはoffset+N >= a.lengthの場合
      関連項目:
    • fromByteArray

      Vector<E> fromByteArray(byte[] a, int offset, ByteOrder bo)
      オフセットから始まるバイト配列からこの種のベクトルをロードします。 バイトは、指定されたバイト順序に従ってプリミティブなレーン要素に構成されます。 ベクトルは、「メモリーの順序」に従ってレーンに配置されます。

      この種に対応するベクトル・タイプのIntVector.fromByteArray(this,a,offset,bo)または同等のfromByteArrayメソッドと同等です。

      パラメータ:
      a - バイト配列
      offset - ロードする最初のバイトのインデックス
      bo - 目的のバイト・オーダー
      戻り値:
      byte配列から塗りつぶされた指定された種のベクトル
      例外:
      IndexOutOfBoundsException - ベクトル内のレーンNoffset+N*ESIZE < 0またはoffset+(N+1)*ESIZE > a.lengthの場合
      関連項目:
    • loadMask

      VectorMask<E> loadMask(boolean[] bits, int offset)
      指定されたオフセットの指定された配列からレーン要素が初期化される、この種のマスクを返します。 VectorMask.fromArray(this,a,offset)と等価です。
      パラメータ:
      bits - boolean配列
      offset - 配列へのオフセット
      戻り値:
      boolean配列からロードされたマスク
      例外:
      IndexOutOfBoundsException - ベクトル・マスク内のレーンNoffset+N < 0またはoffset+N >= a.lengthの場合
      関連項目:
    • maskAll

      VectorMask<E> maskAll(boolean bit)
      この種のマスクを返します。各レーンは、指定された単一のbooleanに従って設定または設定解除され、すべてのレーンにブロードキャストされます。
      パラメータ:
      bit - 複製される指定されたマスク・ビット
      戻り値:
      指定されたビットに従って各レーンが設定または設定解除されるマスク
      関連項目:
    • broadcast

      Vector<E> broadcast(long e)
      すべてのレーン要素がプリミティブ値eに設定されている、指定された種のベクトルを返します。

      このメソッドは、この式の値を戻します: EVector.broadcast(this, (ETYPE)e)EVectorは、この種のETYPEに固有のベクトル・クラスです。 e==(long)(ETYPE)eの場合、long値はETYPEで正確に表現できる必要があります。

      パラメータ:
      e - ブロードキャストする値
      戻り値:
      すべてのレーン要素がプリミティブ値eに設定されているベクトル
      例外:
      IllegalArgumentException - 指定されたlong値をベクトル種ETYPEで表現できない場合
      関連項目:
    • checkValue

      long checkValue(long e)
      この種が指定された要素値を表すことができることを確認し、値を変更せずに返します。 long値は、e==(long)(ETYPE)eのようにベクトル種のETYPEで正確に表現できる必要があります。 効果は次の疑似コードのようになります : e == (long)(ETYPE)e ? e : throw new IllegalArgumentException()
      パラメータ:
      e - チェックされる値
      戻り値:
      e
      例外:
      IllegalArgumentException - 指定されたlong値をベクトル種ETYPEで表現できない場合
      関連項目:
    • shuffleFromValues

      VectorShuffle<E> shuffleFromValues(int... sourceIndexes)
      一連のソース・インデックスからこの種のシャッフルを作成します。

      Nがシャッフル・レーンのインデックスであるシャッフル・レーンごとに、Nのthインデックス値が種VLENGTHに対して検証され、(無効な場合)は[-VLENGTH..-1]の範囲内の例外インデックスに部分的にラップされます。

      パラメータ:
      sourceIndexes - シャッフルの描画元のソース・インデックス
      戻り値:
      各レーンのソース・インデックスが指定されたint値に設定されているシャッフル。例外の場合は部分的にラップされる
      例外:
      IndexOutOfBoundsException - sourceIndexes.length != VLENGTHの場合
      関連項目:
    • shuffleFromArray

      VectorShuffle<E> shuffleFromArray(int[] sourceIndexes, int offset)
      オフセットから始まるint配列から、この種のシャッフルを作成します。

      Nがシャッフル・レーンのインデックスであるシャッフル・レーンごとに、インデックスi + Nの配列要素が種VLENGTHに対して検証され、(無効な場合)は[-VLENGTH..-1]の範囲内の例外的なインデックスに部分的にラップされます。

      パラメータ:
      sourceIndexes - シャッフルの描画元のソース・インデックス
      offset - 配列へのオフセット
      戻り値:
      各レーンのソース・インデックスが指定されたint値に設定されているシャッフル。例外の場合は部分的にラップされる
      例外:
      IndexOutOfBoundsException - offset < 0またはoffset > sourceIndexes.length - VLENGTHの場合
      関連項目:
    • shuffleFromOp

      VectorShuffle<E> shuffleFromOp(IntUnaryOperator fn)
      範囲[0..VLENGTH-1]に適用される演算子の連続する値から、この種のシャッフルを作成します。

      Nがシャッフル・レーンのインデックスであるシャッフル・レーンごとに、Nのthインデックス値が種VLENGTHに対して検証され、(無効な場合)は[-VLENGTH..-1]の範囲内の例外インデックスに部分的にラップされます。

      このメソッドから生成されたVectorShuffle値が定数として使用されるように注意して、コードが最適に生成されるようにしてください。 たとえば、シャッフル値は、static finalフィールドまたはループ不変ローカル変数に保持できます。

      このメソッドは、マップされた索引の配列からシャッフルが作成されたかのように動作します:

      
         int[] a = new int[VLENGTH];
         for (int i = 0; i < a.length; i++) {
             a[i] = fn.applyAsInt(i);
         }
         return VectorShuffle.fromArray(this, a, 0);
       

      パラメータ:
      fn - レーン索引マッピング関数
      戻り値:
      マップされたインデックスのシャッフル
      関連項目:
    • iotaShuffle

      VectorShuffle<E> iotaShuffle(int start, int step, boolean wrap)
      startから始まり、指定されたstepによってステップ実行される連続値に設定されたソース索引を使用してシャッフルを作成します。

      このメソッドは、式VectorSpecies.shuffleFromOp(i -> R(start + i * step))の値を戻します。ここで、Rwrapがtrueの場合はwrapIndexで、それ以外の場合はアイデンティティ関数です。

      wrapがfalseの場合、各索引は種VLENGTHに対して検証され、(無効な場合)は[-VLENGTH..-1]の範囲の例外的な索引に部分的にラップされます。 それ以外の場合、wrapがtrueであれば、wrapIndexによる場合と同様に、各索引を有効範囲[0..VLENGTH-1]に減らします。

      APIのノート:
      無効なソース索引をラップする場合は、wrapパラメータを trueに設定する必要があります。 それ以外の場合は、falseに設定すると、unary rearrangeなどの後続の演算で無効なソース索引を範囲チェックできます。
      パラメータ:
      start - ソース索引シーケンスの開始値(通常は0)
      step - 隣接するソース索引(通常は1)間の差異
      wrap - 結果の索引をVLENGTHにラップするかどうか
      戻り値:
      シーケンシャル・レーン・インデックスのシャッフル
      関連項目:
    • toString

      String toString()
      "Species [ETYPE, VLENGTH, SHAPE]"という形式の文字列を返します。ETYPEはプリミティブ「レーン・タイプ」VLENGTHは種に関連付けられた「ベクトル・レーン・カウント」 SHAPEは種に関連付けられた「ベクトル・シェイプ」です。
      オーバーライド:
      toString 、クラス:  Object
      戻り値:
      "Species [ETYPE, VLENGTH, SHAPE]"形式の文字列
    • equals

      boolean equals(Object obj)
      この種がほかのオブジェクトと同一かどうかを示します。 2つの種は、同じシェイプと同じ要素タイプを持つ場合にのみ同一です。
      オーバーライド:
      equals 、クラス:  Object
      パラメータ:
      obj - 比較対象の参照オブジェクト。
      戻り値:
      この種がほかのオブジェクトと同一かどうか
      関連項目:
    • hashCode

      int hashCode()
      ベクトルのシェイプと要素の型に基づいて、種のハッシュ・コード値を返します。
      オーバーライド:
      hashCode 、クラス:  Object
      戻り値:
      この種のハッシュ・コード値
      関連項目: