--- old/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/LongVector.java 2019-03-18 17:57:12.452090100 -0700 +++ new/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/LongVector.java 2019-03-18 17:57:11.897659100 -0700 @@ -105,7 +105,8 @@ * Returns a vector where all lane elements are set to the default * primitive value. * - * @return a zero vector + * @param species species of desired vector + * @return a zero vector of given species */ @ForceInline @SuppressWarnings("unchecked") @@ -126,6 +127,7 @@ * return this.fromByteBuffer(ByteBuffer.wrap(a), i, this.maskAllTrue()); * } * + * @param species species of desired vector * @param a the byte array * @param ix the offset into the array * @return a vector loaded from a byte array @@ -161,6 +163,7 @@ * return this.fromByteBuffer(ByteBuffer.wrap(a), i, m); * } * + * @param species species of desired vector * @param a the byte array * @param ix the offset into the array * @param m the mask @@ -185,6 +188,7 @@ * array element at index {@code i + N} is placed into the * resulting vector at lane index {@code N}. * + * @param species species of desired vector * @param a the array * @param i the offset into the array * @return the vector loaded from an array @@ -212,6 +216,7 @@ * {@code N}, otherwise the default element value is placed into the * resulting vector at lane index {@code N}. * + * @param species species of desired vector * @param a the array * @param i the offset into the array * @param m the mask @@ -233,6 +238,7 @@ * array element at index {@code i + indexMap[j + N]} is placed into the * resulting vector at lane index {@code N}. * + * @param species species of desired vector * @param a the array * @param i the offset into the array, may be negative if relative * indexes in the index map compensate to produce a value within the @@ -275,10 +281,12 @@ * index {@code i + indexMap[j + N]} is placed into the resulting vector * at lane index {@code N}. * + * @param species species of desired vector * @param a the array * @param i the offset into the array, may be negative if relative * indexes in the index map compensate to produce a value within the * array bounds + * @param m the mask * @param indexMap the index map * @param j the offset into the index map * @return the vector loaded from an array @@ -310,6 +318,7 @@ * return this.fromByteBuffer(b, i, this.maskAllTrue()) * } * + * @param species species of desired vector * @param bb the byte buffer * @param ix the offset into the byte buffer * @return a vector loaded from a byte buffer @@ -361,8 +370,10 @@ * Vector r = ((ESpecies)this).fromArray(es, 0, m); * } * + * @param species species of desired vector * @param bb the byte buffer * @param ix the offset into the byte buffer + * @param m the mask * @return a vector loaded from a byte buffer * @throws IndexOutOfBoundsException if the offset is {@code < 0}, * or {@code > b.limit()}, @@ -375,6 +386,19 @@ return zero(species).blend(fromByteBuffer(species, bb, ix), m); } + /** + * Returns a mask where each lane is set or unset according to given + * {@code boolean} values + *

+ * For each mask lane, where {@code N} is the mask lane index, + * if the given {@code boolean} value at index {@code N} is {@code true} + * then the mask lane at index {@code N} is set, otherwise it is unset. + * + * @param species mask species + * @param bits the given {@code boolean} values + * @return a mask where each lane is set or unset according to the given {@code boolean} value + * @throws IndexOutOfBoundsException if {@code bits.length < species.length()} + */ @ForceInline public static Mask maskFromValues(LongSpecies species, boolean... bits) { if (species.boxType() == LongMaxVector.class) @@ -413,6 +437,20 @@ } } + /** + * Loads a mask from a {@code boolean} array starting at an offset. + *

+ * For each mask lane, where {@code N} is the mask lane index, + * if the array element at index {@code i + N} is {@code true} then the + * mask lane at index {@code N} is set, otherwise it is unset. + * + * @param species mask species + * @param bits the {@code boolean} array + * @param ix the offset into the array + * @return the mask loaded from a {@code boolean} array + * @throws IndexOutOfBoundsException if {@code ix < 0}, or + * {@code ix > bits.length - species.length()} + */ @ForceInline @SuppressWarnings("unchecked") public static Mask maskFromArray(LongSpecies species, boolean[] bits, int ix) { @@ -424,6 +462,12 @@ (c, idx, s) -> (Mask) ((LongSpecies)s).opm(n -> c[idx + n])); } + /** + * Returns a mask where all lanes are a set. + * + * @param species mask species + * @return a mask where all lanes are a set + */ @ForceInline @SuppressWarnings("unchecked") public static Mask maskAllTrue(LongSpecies species) { @@ -432,6 +476,12 @@ ((z, s) -> trueMask((LongSpecies)s))); } + /** + * Returns a mask where all lanes are a unset. + * + * @param species mask species + * @return a mask where all lanes are a unset + */ @ForceInline @SuppressWarnings("unchecked") public static Mask maskAllFalse(LongSpecies species) { @@ -440,6 +490,30 @@ ((z, s) -> falseMask((LongSpecies)s))); } + /** + * Returns a shuffle of mapped indexes where each lane element is + * the result of applying a mapping function to the corresponding lane + * index. + *

+ * Care should be taken to ensure Shuffle values produced from this + * method are consumed as constants to ensure optimal generation of + * code. For example, values held in static final fields or values + * held in loop constant local variables. + *

+ * This method behaves as if a shuffle is created from an array of + * mapped indexes as follows: + * 

{@code
+     *   int[] a = new int[species.length()];
+     *   for (int i = 0; i < a.length; i++) {
+     *       a[i] = f.applyAsInt(i);
+     *   }
+     *   return this.shuffleFromValues(a);
+     * }
+ * + * @param species shuffle species + * @param f the lane index mapping function + * @return a shuffle of mapped indexes + */ @ForceInline public static Shuffle shuffle(LongSpecies species, IntUnaryOperator f) { if (species.boxType() == LongMaxVector.class) @@ -453,6 +527,19 @@ } } + /** + * Returns a shuffle where each lane element is the value of its + * corresponding lane index. + *

+ * This method behaves as if a shuffle is created from an identity + * index mapping function as follows: + * 

{@code
+     *   return this.shuffle(i -> i);
+     * }
+ * + * @param species shuffle species + * @return a shuffle of lane indexes + */ @ForceInline public static Shuffle shuffleIota(LongSpecies species) { if (species.boxType() == LongMaxVector.class) @@ -466,6 +553,22 @@ } } + /** + * Returns a shuffle where each lane element is set to a given + * {@code int} value logically AND'ed by the species length minus one. + *

+ * For each shuffle lane, where {@code N} is the shuffle lane index, the + * the {@code int} value at index {@code N} logically AND'ed by + * {@code species.length() - 1} is placed into the resulting shuffle at + * lane index {@code N}. + * + * @param species shuffle species + * @param ixs the given {@code int} values + * @return a shuffle where each lane element is set to a given + * {@code int} value + * @throws IndexOutOfBoundsException if the number of int values is + * {@code < species.length()} + */ @ForceInline public static Shuffle shuffleFromValues(LongSpecies species, int... ixs) { if (species.boxType() == LongMaxVector.class) @@ -479,6 +582,21 @@ } } + /** + * Loads a shuffle from an {@code int} array starting at an offset. + *

+ * For each shuffle lane, where {@code N} is the shuffle lane index, the + * array element at index {@code i + N} logically AND'ed by + * {@code species.length() - 1} is placed into the resulting shuffle at lane + * index {@code N}. + * + * @param species shuffle species + * @param ixs the {@code int} array + * @param i the offset into the array + * @return a shuffle loaded from the {@code int} array + * @throws IndexOutOfBoundsException if {@code i < 0}, or + * {@code i > a.length - species.length()} + */ @ForceInline public static Shuffle shuffleFromArray(LongSpecies species, int[] ixs, int i) { if (species.boxType() == LongMaxVector.class) @@ -1021,6 +1139,7 @@ * operation ({@code >>>}) is applied to lane elements. * * @param s the input scalar; the number of the bits to right shift + * @param m the mask controlling lane selection * @return the result of logically right shifting this vector by the * broadcast of an input scalar */ @@ -1202,7 +1321,6 @@ // Type specific horizontal reductions - /** * Adds all lane elements of this vector. *

@@ -1223,35 +1341,11 @@ * and the identity value is {@code 0}. * * @param m the mask controlling lane selection - * @return the addition of all the lane elements of this vector + * @return the addition of the selected lane elements of this vector */ public abstract long addAll(Mask m); /** - * Subtracts all lane elements of this vector. - *

- * This is an associative vector reduction operation where the subtraction - * operation ({@code -}) is applied to lane elements, - * and the identity value is {@code 0}. - * - * @return the subtraction of all the lane elements of this vector - */ - public abstract long subAll(); - - /** - * Subtracts all lane elements of this vector, selecting lane elements - * controlled by a mask. - *

- * This is an associative vector reduction operation where the subtraction - * operation ({@code -}) is applied to lane elements, - * and the identity value is {@code 0}. - * - * @param m the mask controlling lane selection - * @return the subtraction of all the lane elements of this vector - */ - public abstract long subAll(Mask m); - - /** * Multiplies all lane elements of this vector. *

* This is an associative vector reduction operation where the @@ -1280,7 +1374,8 @@ *

* This is an associative vector reduction operation where the operation * {@code (a, b) -> Math.min(a, b)} is applied to lane elements, - * and the identity value is {@link Long#MAX_VALUE}. + * and the identity value is + * {@link Long#MAX_VALUE}. * * @return the minimum lane element of this vector */ @@ -1292,7 +1387,8 @@ *

* This is an associative vector reduction operation where the operation * {@code (a, b) -> Math.min(a, b)} is applied to lane elements, - * and the identity value is {@link Long#MAX_VALUE}. + * and the identity value is + * {@link Long#MAX_VALUE}. * * @param m the mask controlling lane selection * @return the minimum lane element of this vector @@ -1304,7 +1400,8 @@ *

* This is an associative vector reduction operation where the operation * {@code (a, b) -> Math.max(a, b)} is applied to lane elements, - * and the identity value is {@link Long#MIN_VALUE}. + * and the identity value is + * {@link Long#MIN_VALUE}. * * @return the maximum lane element of this vector */ @@ -1316,7 +1413,8 @@ *

* This is an associative vector reduction operation where the operation * {@code (a, b) -> Math.max(a, b)} is applied to lane elements, - * and the identity value is {@link Long#MIN_VALUE}. + * and the identity value is + * {@link Long#MIN_VALUE}. * * @param m the mask controlling lane selection * @return the maximum lane element of this vector @@ -1583,7 +1681,7 @@ * generated primitive value. * * The semantics are equivalent to calling - * {@link (long)ThreadLocalRandom#nextInt() } + * {@code (long)ThreadLocalRandom#nextInt()}. * * @return a vector where each lane elements is set to a randomly * generated primitive value