JDK-8266327 : Vector API enhancements
  • Type: CSR
  • Component: hotspot
  • Sub-Component: compiler
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 17
  • Submitted: 2021-04-29
  • Updated: 2021-05-10
  • Resolved: 2021-05-09
Related Reports
CSR :  
Description
Summary
-------

Enhancements for loading/storing a `short` vector from/to a `char` array, loading/storing a `byte` vector from/to a `boolean` array, and new vector comparison operators for unsigned comparisons with integral vectors.

Problem
-------

The Vector API does not provide specializations for vectors whose lane element type is `char` or `boolean`.

Solution
--------

Rather than adding a new class `CharVector`, leverage the existing `ShortVector` class by providing methods to load/store a `ShortVector` from/to `char` arrays.

Since a `ShortVector` may be loaded from a source of unsigned data (such as a `char` array), with no loss of information, it is useful to provide unsigned comparison operators. Thus signed vector lane elements may be operated on as if they are unsigned values. In general, the unsigned comparison operators are supported on all vectors whose element type is an integral type.

Rather than adding a new class `BooleanVector` (or reusing `VectorMask<E>`), leverage the existing `ByteVector` class by providing methods to load/store a `ByteVector` from/to `boolean` arrays.

Specification
-------------

Please see the JavaDoc and specdiff linked here and attached:

http://cr.openjdk.java.net/~psandoz/panama/JEP-JDK-8261663-vector-api-review/docs/api/jdk.incubator.vector/jdk/incubator/vector/package-summary.html

http://cr.openjdk.java.net/~psandoz/panama/JEP-JDK-8261663-vector-api-review/specdiff/overview-summary.html

Summarizing the main changes herein. The following methods are added to `ShortVector` to load/store a `short` vector from/to a `char` array:

```
 public static  ShortVector fromCharArray���(VectorSpecies<Short> species,
    char[] a, int offset) 
 public static  ShortVector fromCharArray���(VectorSpecies<Short> species, 
    char[] a, int offset, 
    VectorMask<Short> m) 
 public static  ShortVector fromCharArray���(VectorSpecies<Short> species, 
    char[] a, int offset, 
    int[] indexMap, int mapOffset) 
 public static  ShortVector fromCharArray���(VectorSpecies<Short> species, 
    char[] a, int offset, 
    int[] indexMap, int mapOffset, VectorMask<Short> m) 

 public final  void intoCharArray���(char[] a, int offset) 
 public final  void intoCharArray���(char[] a, int offset, 
    VectorMask<Short> m) 
 public final  void intoCharArray���(char[] a, int offset, 
    int[] indexMap, int mapOffset) 
 public final  void intoCharArray���(char[] a, int offset, 
    int[] indexMap, int mapOffset, VectorMask<Short> m) 
```

The following methods are added to `ByteVector` to load/store a `byte` vector from/to a `boolean` array:

```
 public static  ByteVector fromBooleanArray���(VectorSpecies<Byte> species, 
    boolean[] a, int offset) 
 public static  ByteVector fromBooleanArray���(VectorSpecies<Byte> species,
    boolean[] a, int offset, 
    VectorMask<Byte> m) 
 public static  ByteVector fromBooleanArray���(VectorSpecies<Byte> species, 
    boolean[] a, int offset, 
    int[] indexMap, int mapOffset) 
 public static  ByteVector fromBooleanArray���(VectorSpecies<Byte> species, 
    boolean[] a, int offset, 
    int[] indexMap, int mapOffset, VectorMask<Byte> m) 

 public final  void intoBooleanArray���(boolean[] a, int offset) 
 public final  void intoBooleanArray���(boolean[] a, int offset, 
    VectorMask<Byte> m) 
 public final  void intoBooleanArray���(boolean[] a, int offset, 
    int[] indexMap, int mapOffset) 
 public final  void intoBooleanArray���(boolean[] a, int offset, 
    int[] indexMap, int mapOffset, VectorMask<Byte> m) 
```


The following operators are added as constant fields to `VectorOperators`:

```
 public static final  VectorOperators.Comparison UNSIGNED_LT 
 public static final  VectorOperators.Comparison UNSIGNED_LE 
 public static final  VectorOperators.Comparison UNSIGNED_GT 
 public static final  VectorOperators.Comparison UNSIGNED_GE 
```

Comments
[~darcy]I updated to include @see refs to the relevant methods, see ([here][1]) [1]: https://github.com/openjdk/jdk/pull/3803/commits/aa6bb717752bc8e641154f8fc170a9676c6e4bc0
10-05-2021

Code review comment: for the new VectorOperators, please add javadoc linkage to {Integer, Long}.compareUnsigned. Moving to Approved for JDK 17.
09-05-2021

[~epavlova] at least some subset of (from/to)CharArray should be covered by the tests in the vectorIntrinsics branch of the panama repository. The lack of coverage is more likely for the scatter/gather methods. My intention is to follow up with more expansive testing as a separate issue (as part of that work i would like to do some refactoring to better consolidate load/store tests).
29-04-2021

New tests are also needed to cover this new functionality. Based on latest CC report for panama-vector.git:vectorIntrinsics ShortVector (from/to)CharArray char[] methods are not covered and as result CC for jdk.incubator.vector.ShortVector dropped from 100% to 95%.
29-04-2021