E
- the boxed version of ETYPE
, the element type of a vectorpublic interface VectorSpecies<E>
VectorSpecies
relies on preview features of the Java platform: VectorSpecies
refers to one or more preview APIs: MemorySegment
.
ETYPE
is the primitive lane type, VLENGTH
is the vector lane count associated with the species, and SHAPE
is the vector shape associated with the species. Vector species objects can be stored in locals and parameters and as static final
constants, but storing them in other Java fields or in array elements, while semantically valid, may incur performance penalties.
Modifier and Type | Method | Description |
---|---|---|
Vector |
broadcast |
Returns a vector of the given species where all lane elements are set to the primitive value e . |
<F> VectorSpecies |
check |
Checks that this species has the given element type, and returns this species unchanged. |
long |
checkValue |
Checks that this species can represent the given element value, and returns the value unchanged. |
int |
elementSize() |
Returns the lane size, in bits, of vectors of this species. |
static int |
elementSize |
Returns the bit-size of the given vector element type ( ETYPE ). |
Class |
elementType() |
Returns the primitive element type of vectors of this species. |
boolean |
equals |
Indicates whether this species is identical to some other object. |
Vector |
fromArray |
Returns a vector of this species where lane elements are initialized from the given array at the given offset. |
Vector |
fromMemorySegment |
Loads a vector of this species from a memory segmentPREVIEW starting at an offset into the memory segment. |
int |
hashCode() |
Returns a hash code value for the species, based on the vector shape and element type. |
VectorMask |
indexInRange |
Returns a mask of this species where only the lanes at index N such that the adjusted index N+offset is in the range [0..limit-1] are set. |
VectorMask |
indexInRange |
Returns a mask of this species where only the lanes at index N such that the adjusted index N+offset is in the range [0..limit-1] are set. |
VectorShuffle |
iotaShuffle |
Creates a shuffle using source indexes set to sequential values starting from start and stepping by the given step . |
int |
length() |
Returns the number of lanes in a vector of this species. |
VectorMask |
loadMask |
Returns a mask of this species where lane elements are initialized from the given array at the given offset. |
int |
loopBound |
Loop control function which returns the largest multiple of VLENGTH that is less than or equal to the given length value. |
long |
loopBound |
Loop control function which returns the largest multiple of VLENGTH that is less than or equal to the given length value. |
VectorMask |
maskAll |
Returns a mask of this species, where each lane is set or unset according to given single boolean, which is broadcast to all lanes. |
Class |
maskType() |
Returns the vector mask type for this species. |
static <E> VectorSpecies |
of |
Finds a species for an element type and shape. |
static <E> VectorSpecies |
ofLargestShape |
Finds the largest vector species of the given element type. |
static <E> VectorSpecies |
ofPreferred |
Finds the species preferred by the current platform for a given vector element type. |
int |
partLimit |
Given this species and a second one, reports the net expansion or contraction of a (potentially) resizing reinterpretation cast or lane-wise conversion from this species to the second. |
VectorShuffle |
shuffleFromArray |
Creates a shuffle for this species from an int array starting at an offset. |
VectorShuffle |
shuffleFromOp |
Creates a shuffle for this species from the successive values of an operator applied to the range [0..VLENGTH-1] . |
VectorShuffle |
shuffleFromValues |
Creates a shuffle for this species from a series of source indexes. |
String |
toString() |
Returns a string of the form "Species[ETYPE, VLENGTH, SHAPE]", where ETYPE is the primitive lane type, VLENGTH is the vector lane count associated with the species, and
SHAPE is the vector shape associated with the species. |
int |
vectorBitSize() |
Returns the total vector size, in bits, of any vector of this species. |
int |
vectorByteSize() |
Returns the total vector size, in bytes, of any vector of this species. |
VectorShape |
vectorShape() |
Returns the shape of vectors produced by this species. |
Class |
vectorType() |
Returns the vector type of this species. |
<F> VectorSpecies |
withLanes |
Finds a species with the given element type and the same shape as this species. |
VectorSpecies |
withShape |
Finds a species with the given shape and the same elementType as this species. |
Vector |
zero() |
Returns a vector of this species where all lane elements are set to the default primitive value, (ETYPE)0 . |
Class<E> elementType()
ETYPE
)Class<? extends Vector<E>> vectorType()
Class<? extends VectorMask<E>> maskType()
int elementSize()
VectorShape vectorShape()
int length()
int vectorBitSize()
this.vectorShape().vectorBitSize()
.int vectorByteSize()
this.vectorShape().vectorBitSize() / Byte.SIZE
.int loopBound(int length)
VLENGTH
that is less than or equal to the given length
value. Here, VLENGTH
is the result of this.length()
, and length
is interpreted as a number of lanes. The resulting value R
satisfies this inequality: R <= length < R+VLENGTH
Specifically, this method computes length - floorMod(length, VLENGTH)
, where floorMod
computes a remainder value by rounding its quotient toward negative infinity. As long as VLENGTH
is a power of two, then the result is also equal to length & ~(VLENGTH - 1)
.
length
- the input lengthIllegalArgumentException
- if the length
is negative and the result would overflow to a positive valuelong loopBound(long length)
VLENGTH
that is less than or equal to the given length
value. Here, VLENGTH
is the result of this.length()
, and length
is interpreted as a number of lanes. The resulting value R
satisfies this inequality: R <= length < R+VLENGTH
Specifically, this method computes length - floorMod(length, VLENGTH)
, where floorMod
computes a remainder value by rounding its quotient toward negative infinity. As long as VLENGTH
is a power of two, then the result is also equal to length & ~(VLENGTH - 1)
.
length
- the input lengthIllegalArgumentException
- if the length
is negative and the result would overflow to a positive valueVectorMask<E> indexInRange(int offset, int limit)
N+offset
is in the range [0..limit-1]
are set. This method returns the value of the expression maskAll(true).indexInRange(offset, limit)
offset
- the starting indexlimit
- the upper-bound (exclusive) of index rangeVectorMask<E> indexInRange(long offset, long limit)
N+offset
is in the range [0..limit-1]
are set. This method returns the value of the expression maskAll(true).indexInRange(offset, limit)
offset
- the starting indexlimit
- the upper-bound (exclusive) of index range<F> VectorSpecies<F> check(Class<F> elementType)
elementType == elementType()
? this
: throw new ClassCastException()
.F
- the boxed element type of the required lane typeelementType
- the required lane typeClassCastException
- if the species has the wrong element typeint partLimit(VectorSpecies<?> outputSpecies, boolean lanewise)
lane-wise conversion
from this species to the second. The sign and magnitude of the return value depends on the size difference between the proposed input and output shapes, and (optionally, if lanewise
is true) also on the size difference between the proposed input and output lanes. lanewise
is false, this size that of the input VSHAPE
. If lanewise
is true, the logical result size is the product of the input VLENGTH
times the size of the output ETYPE
. part
parameter to a method that would transform the input species to the output species. part
parameter to a method that would transform the input species to the output species. outputSpecies
- the proposed output specieslanewise
- whether to take lane sizes into account<F> VectorSpecies<F> withLanes(Class<F> newType)
VectorSpecies.of(newType, this.vectorShape())
.F
- the boxed element typenewType
- the new element typeIllegalArgumentException
- if no such species exists for the given combination of element type and shape or if the given type is not a valid ETYPE
VectorSpecies<E> withShape(VectorShape newShape)
VectorSpecies.of(this.elementType(), newShape)
.newShape
- the new shapeIllegalArgumentException
- if no such species exists for the given combination of element type and shapestatic <E> VectorSpecies<E> of(Class<E> elementType, VectorShape shape)
E
- the boxed element typeelementType
- the element typeshape
- the shapeIllegalArgumentException
- if no such species exists for the given combination of element type and shape or if the given type is not a valid ETYPE
static <E> VectorSpecies<E> ofLargestShape(Class<E> etype)
The returned species is a species chosen by the platform that has a shape with the largest possible bit-size for the given element type. The underlying vector shape might not support other lane types on some platforms, which may limit the applicability of reinterpretation casts. Vector algorithms which require reinterpretation casts will be more portable if they use the platform's preferred species.
E
- the boxed element typeetype
- the element typeIllegalArgumentException
- if no such species exists for the element type or if the given type is not a valid ETYPE
static <E> VectorSpecies<E> ofPreferred(Class<E> etype)
VectorSpecies.of(etype, VectorShape.preferredShape())
. This species is chosen by the platform so that it has the largest possible shape that supports all lane element types. This has the following implications:
ofLargestShape
and ofPreferred
, because the preferred shape is usually also the largest available shape for every lane type. Therefore, most vector algorithms will perform well without ofLargestShape
.E
- the boxed element typeetype
- the element typeIllegalArgumentException
- if no such species exists for the element type or if the given type is not a valid ETYPE
static int elementSize(Class<?> elementType)
ETYPE
). The element type must be a valid ETYPE
, not a wrapper type or other object type. The element type argument must be a mirror for a valid vector ETYPE
, such as byte.class
, int.class
, or double.class
. The bit-size of such a type is the SIZE
constant for the corresponding wrapper class, such as Byte.SIZE
, or Integer.SIZE
, or Double.SIZE
.elementType
- a vector element type (an ETYPE
)elementType
, such as 32 for int.class
IllegalArgumentException
- if the given elementType
argument is not a valid vector ETYPE
Vector<E> zero()
(ETYPE)0
. Equivalent to IntVector.zero(this)
or an equivalent zero
method, on the vector type corresponding to this species.Vector<E> fromArray(Object a, int offset)
ETYPE
. Equivalent to IntVector.fromArray(this,a,offset)
or an equivalent fromArray
method, on the vector type corresponding to this species.a
- an array of the ETYPE
for this speciesoffset
- the index of the first lane value to loadIndexOutOfBoundsException
- if offset+N < 0
or offset+N >= a.length
for any lane N
in the vectorVector<E> fromMemorySegment(MemorySegmentPREVIEW ms, long offset, ByteOrder bo)
Equivalent to IntVector.fromMemorySegment(this,ms,offset,bo)
, on the vector type corresponding to this species.
ms
- the memory segmentoffset
- the offset into the memory segmentbo
- the intended byte orderIndexOutOfBoundsException
- if offset+N*ESIZE < 0
or offset+(N+1)*ESIZE > a.length
for any lane N
in the vectorVectorMask<E> loadMask(boolean[] bits, int offset)
VectorMask.fromArray(this,a,offset)
.bits
- the boolean
arrayoffset
- the offset into the arrayboolean
arrayIndexOutOfBoundsException
- if offset+N < 0
or offset+N >= a.length
for any lane N
in the vector maskVectorMask<E> maskAll(boolean bit)
bit
- the given mask bit to be replicatedVector<E> broadcast(long e)
e
. This method returns the value of this expression: EVector.broadcast(this, (ETYPE)e)
, where EVector
is the vector class specific to the the ETYPE
of this species. The long
value must be accurately representable by ETYPE
, so that e==(long)(ETYPE)e
.
e
- the value to broadcaste
IllegalArgumentException
- if the given long
value cannot be represented by the vector species ETYPE
long checkValue(long e)
long
value must be accurately representable by the ETYPE
of the vector species, so that e==(long)(ETYPE)e
. The effect is similar to this pseudocode: e == (long)(ETYPE)e
? e
: throw new IllegalArgumentException()
.e
- the value to be checkede
IllegalArgumentException
- if the given long
value cannot be represented by the vector species ETYPE
VectorShuffle<E> shuffleFromValues(int... sourceIndexes)
For each shuffle lane, where N
is the shuffle lane index, the N
th index value is validated against the species VLENGTH
, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1]
.
sourceIndexes
- the source indexes which the shuffle will draw fromint
value, partially wrapped if exceptionalIndexOutOfBoundsException
- if sourceIndexes.length != VLENGTH
VectorShuffle<E> shuffleFromArray(int[] sourceIndexes, int offset)
int
array starting at an offset. For each shuffle lane, where N
is the shuffle lane index, the array element at index i + N
is validated against the species VLENGTH
, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1]
.
sourceIndexes
- the source indexes which the shuffle will draw fromoffset
- the offset into the arrayint
value, partially wrapped if exceptionalIndexOutOfBoundsException
- if offset < 0
, or offset > sourceIndexes.length - VLENGTH
VectorShuffle<E> shuffleFromOp(IntUnaryOperator fn)
[0..VLENGTH-1]
. For each shuffle lane, where N
is the shuffle lane index, the N
th index value is validated against the species VLENGTH
, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1]
.
Care should be taken to ensure VectorShuffle
values produced from this method are consumed as constants to ensure optimal generation of code. For example, shuffle values can be held in static final
fields or loop-invariant local variables.
This method behaves as if a shuffle is created from an array of mapped indexes as follows:
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
- the lane index mapping functionVectorShuffle<E> iotaShuffle(int start, int step, boolean wrap)
start
and stepping by the given step
. This method returns the value of the expression VectorSpecies.shuffleFromOp(i -> R(start + i * step))
, where R
is wrapIndex
if wrap
is true, and is the identity function otherwise.
If wrap
is false each index is validated against the species VLENGTH
, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1]
. Otherwise, if wrap
is true, also reduce each index, as if by wrapIndex
, to the valid range [0..VLENGTH-1]
.
wrap
parameter should be set to
true
if invalid source indexes should be wrapped. Otherwise, setting it to false
allows invalid source indexes to be range-checked by later operations such as unary rearrange
.start
- the starting value of the source index sequence, typically 0
step
- the difference between adjacent source indexes, typically 1
wrap
- whether to wrap resulting indexes modulo VLENGTH
String toString()
ETYPE
is the primitive lane type, VLENGTH
is the vector lane count associated with the species, and
SHAPE
is the vector shape associated with the species.boolean equals(Object obj)
int hashCode()
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.incubator.vector/jdk/incubator/vector/VectorSpecies.html
VectorSpecies
when preview features are enabled.