Module jdk.incubator.vector
Package jdk.incubator.vector

Class VectorMask<E>

java.lang.Object
jdk.incubator.vector.VectorMask<E>
Type Parameters:
E - the boxed version of ETYPE, the element type of a vector

Value-based classes and identity operations

VectorMask, along with Vector, is a value-based class. With VectorMask, identity-sensitive operations such as == may yield unpredictable results, or reduced performance. Oddly enough, v.equals(w) is likely to be faster than v==w, since equals is not an identity sensitive method. (Neither is toString nor hashCode.) Also, vector mask 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.
public abstract class VectorMask<E> extends Object
A VectorMask represents an ordered immutable sequence of boolean values.

A VectorMask and Vector of the same element type (ETYPE) and shape have the same number of lanes, and are therefore compatible (specifically, their vector species are compatible).

Some vector operations accept (compatible) masks to control the selection and operation of lane elements of input vectors.

The number of values in the sequence is referred to as the VectorMask length. The length also corresponds to the number of VectorMask lanes. The lane element at lane index N (from 0, inclusive, to length, exclusive) corresponds to the N + 1'th value in the sequence.

A lane is said to be set if the lane element is true, otherwise a lane is said to be unset if the lane element is false.

VectorMask declares a limited set of unary, binary and reduction operations.

  • A lane-wise unary operation operates on one input mask and produces a result mask. For each lane of the input mask the lane element is operated on using the specified scalar unary operation and the boolean result is placed into the mask result at the same lane. The following pseudocode illustrates the behavior of this operation category: 
    
 VectorMask<E> a = ...;
 boolean[] ar = new boolean[a.length()];
 for (int i = 0; i < a.length(); i++) {
     ar[i] = scalar_unary_op(a.laneIsSet(i));
 }
 VectorMask<E> r = VectorMask.fromArray(a.vectorSpecies(), ar, 0);
  • A lane-wise binary operation operates on two input masks to produce a result mask. For each lane of the two input masks a and b, the corresponding lane elements from a and b are operated on using the specified scalar binary operation and the boolean result is placed into the mask result at the same lane. The following pseudocode illustrates the behavior of this operation category: 
    
 VectorMask<E> a = ...;
 VectorMask<E> b = ...;
 boolean[] ar = new boolean[a.length()];
 for (int i = 0; i < a.length(); i++) {
     ar[i] = scalar_binary_op(a.laneIsSet(i), b.laneIsSet(i));
 }
 VectorMask<E> r = VectorMask.fromArray(a.vectorSpecies(), ar, 0);
  • A cross-lane reduction operation accepts an input mask and produces a scalar result. For each lane of the input mask the lane element is operated on, together with a scalar accumulation value, using the specified scalar binary operation. The scalar result is the final value of the accumulator. The following pseudocode illustrates the behaviour of this operation category: 
    
 Mask<E> a = ...;
 int acc = zero_for_scalar_binary_op;  // 0, or 1 for &
 for (int i = 0; i < a.length(); i++) {
      acc = scalar_binary_op(acc, a.laneIsSet(i) ? 1 : 0);  // & | +
 }
 return acc;  // maybe boolean (acc != 0)