102. Covering Vector API structure and terminology
The Vector API is mapped by the jdk.incubator.vector module (and a package with the same name). A jdk.incubator.vector.Vector starts from a generic abstract combination characterized by a type and a shape. A vector is an instance of the Vector<E> class.
The Vector element type
A Vector<E> has an element type (ETYPE) which is one of the Java primitive types: byte, float, double, short, int, or long. When we write Vector<E> we say that E is the boxed version of ETYPE (for instance, when we write Vector<Float>, E is Float, and ETYPE is float). For more convenience, Java declares for each element type a specialized subtype as in the following figure:
Figure 5.3 – Specialized vector subtypes
Even if E is a boxed type there is no boxing-unboxing overhead because Vector<E> works internally on ETYPE so on primitive types.Beside the element type, a vector is characterized by a shape.
The Vector shape
A vector is also characterized by a shape (also referred to as VSHAPE) representing the size or capacity in bits of the vector. It can be 64, 128, 256, or 512 bits. Each of these values is wrapped by the VectorShape enumeration (for instance, the S_128_BIT enum item represents a shape of length 128 bits) next to an extra enum item representing the maximum length supported on the platform (S_Max_BIT). This is determined automatically on the currently running Java platform.
The Vector species
A vector characterized by its element type and shape determines a unique vector species, which is a fixed instance of VectorSpecies<E>. This instance is shared by all vectors having the same shape and ETYPE. We can think of VectorSpecies<E> as a factory used to create vectors of the required element type and shape. For instance, we can define a factory for creating vectors of the double type having a size of 512 bits as follows:
static final VectorSpecies<Double> VS = VectorSpecies.of(
double.class, VectorShape.S_512_BIT);
If you just need a factory for vectors of the maximal bit-size supported by the current platform independent of the element type then rely on S_Max_BIT:
static final VectorSpecies<Double> VS = VectorSpecies.of(
double.class, VectorShape.S_Max_BIT);
If you just need the largest vector species for your element type (here, double) for the current platform then rely on ofLargestShape(). This vector species is chosen by the platform and it has a shape with the largest possible bit-size for your element type (don’t confuse this with S_Max_BIT which is independent of the element type):
static final VectorSpecies<Double> VS =
VectorSpecies.ofLargestShape(double.class);
Or, maybe you need the vector preferred species by the current platform for your element type. This can be achieved via ofPreferred() as follows:
static final VectorSpecies<Double> VS = VectorSpecies.ofPreferred(double.class);
The preferred species is the most convenient approach when you don’t want to bother specifying an explicit shape.
The preferred species is the most optimal shape for the given element type on the current platform (runtime).
Moreover, for convenience, each specialized Vector (IntVector, FloatVector, and so on) defines a set of static fields for covering all possible species. For example, the static field DoubleVector.SPECIES_512 can be used for species representing DoubleVector instances of 512-bit size (VectorShape.S_512_BIT):
static final VectorSpecies<Double> VS =
DoubleVector.SPECIES_512;
If you want the maximal species then rely on SPECIES_MAX:
static final VectorSpecies<Double> VS =
DoubleVector.SPECIES_MAX;
Or, if you want the preferred species then rely on SPECIES_PREFERRED:
static final VectorSpecies<Double> VS =
DoubleVector.SPECIES_PREFERRED;
You can easily inspect the element type and shape of a VectorSpecies via elementType() and vectorShape() methods as follows:
System.out.println(“Element type: ” + VS.elementType());
System.out.println(“Shape: ” + VS.vectorShape());
So far, you know how to create vector species (vector factories). But, before starting to create vectors and apply operations on them, let’s talk about vector lanes.