[Vector API] Why to talk about lanes, shapes and species in the API doc?

[Dietmar Lippold]

Hi,

why is it necessary to talk about "lanes", "shapes" and "species" in the API doc?  From my point of view a Vector should be similar to an array, in particular it could have an arbitrary number of _elements_ (up to Integer.MAX_VALUE) and it should not be necessary to know something about the hardware (CPU or GPU).

On the page of JEP 417 (https://openjdk.java.net/jeps/417) there is the code:

  static final VectorSpecies<Float> SPECIES = FloatVector.SPECIES_PREFERRED;

  void vectorComputation(float[] a, float[] b, float[] c) {
      int i = 0;
      int upperBound = SPECIES.loopBound(a.length);
      for (; i < upperBound; i += SPECIES.length()) {
          // FloatVector va, vb, vc;
          var va = FloatVector.fromArray(SPECIES, a, i);
          var vb = FloatVector.fromArray(SPECIES, b, i);
          var vc = va.mul(va)
                     .add(vb.mul(vb))
                     .neg();
          vc.intoArray(c, i);
      }
      for (; i < a.length; i++) {
          c[i] = (a[i] * a[i] + b[i] * b[i]) * -1.0f;
      }
  }

It should be possible to write instead:

  void vectorComputation(float[] a, float[] b, float[] c) {
      // FloatVector va, vb, vc;
      var va = FloatVector.fromArray(a);
      var vb = FloatVector.fromArray(b);
      var vc = va.mul(va)
                 .add(vb.mul(vb))
                 .neg();
      vc.intoArray(c);
  }

To make that possible the current class Vector (as well as its subclasses) could be converted into an inner class VectorHelp (or named similar) and that could handle all things of lanes, shapes and species.

Btw: Please add a link to the API doc of the Vector package (https://docs.oracle.com/en/java/javase/18/docs/api/jdk.incubator.vector/jdk/incubator/vector/package-summary.html) to the page of the JEP 417 (https://openjdk.java.net/jeps/417).

Dietmar