--- /dev/null 2019-04-11 15:42:53.000000000 -0700 +++ new/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Shuffle.java 2019-04-11 15:42:51.883996700 -0700 @@ -0,0 +1,244 @@ +/* + * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have + * questions. + */ +package jdk.incubator.vector; + +import jdk.internal.vm.annotation.ForceInline; +import java.util.function.IntUnaryOperator; + +/** + * A {@code Shuffle} represents an ordered immutable sequence of + * {@code int} values. A Shuffle can be used with a shuffle accepting + * vector operation to control the rearrangement of lane elements of input + * vectors + *
+ * The number of values in the sequence is referred to as the Shuffle + * {@link #length() length}. The length also corresponds to the number of + * Shuffle lanes. The lane element at lane index {@code N} (from {@code 0}, + * inclusive, to length, exclusive) corresponds to the {@code N + 1}'th + * value in the sequence. + * A Shuffle and Vector of the same element type and shape have the same + * number of lanes. + *
+ * A Shuffle describes how a lane element of a vector may cross lanes from
+ * its lane index, {@code i} say, to another lane index whose value is the
+ * Shuffle's lane element at lane index {@code i}. Shuffle lane elements
+ * will be in the range of {@code 0} (inclusive) to the shuffle length
+ * (exclusive), and therefore cannot induce out of bounds errors when
+ * used with vectors operations and vectors of the same length.
+ *
+ * @param
+ * For each shuffle lane, where {@code N} is the lane index, the
+ * shuffle element at index {@code N} is placed, unmodified, into the
+ * resulting shuffle at index {@code N}.
+ *
+ * @param species species of desired shuffle
+ * @param
+ * 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:
+ *
+ * This method behaves as if a shuffle is created from an identity
+ * index mapping function as follows:
+ *
+ * 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
+ * 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
+ * This method behaves as if it {@link #intoArray(int[], int)} stores}
+ * this shuffle into an allocated array and returns that array as
+ * follows:
+ *
+ * For each shuffle lane, where {@code N} is the shuffle lane index,
+ * the lane element at index {@code N} is stored into the array at index
+ * {@code i + N}.
+ *
+ * @param a the array
+ * @param i the offset into the array
+ * @throws IndexOutOfBoundsException if {@code i < 0}, or
+ * {@code i > a.length - this.length()}
+ */
+ public abstract void intoArray(int[] a, int i);
+
+ /**
+ * Converts this shuffle into a vector, creating a vector from shuffle
+ * lane elements (int values) cast to the vector element type.
+ *
+ * This method behaves as if it returns the result of creating a
+ * vector given an {@code int} array obtained from this shuffle's
+ * lane elements, as follows:
+ *
+ * For each lane of the shuffle, at lane index {@code N} with lane
+ * element {@code I}, the lane element at {@code I} from this shuffle is
+ * selected and placed into the resulting shuffle at {@code N}.
+ *
+ * @param s the shuffle controlling lane index selection
+ * @return the rearrangement of the lane elements of this shuffle
+ */
+ public abstract Shuffle{@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 {@code
+ * return this.shuffle(i -> i);
+ * }
+ *
+ * @param species shuffle species
+ * @return a shuffle of lane indexes
+ */
+ @ForceInline
+ public static {@code
+ * int[] a = new int[this.length()];
+ * this.intoArray(a, 0);
+ * return a;
+ * }
+ *
+ * @return an array containing the the lane elements of this vector
+ */
+ public abstract int[] toArray();
+
+ /**
+ * Stores this shuffle into an {@code int} array starting at offset.
+ * {@code
+ * int[] sa = this.toArray();
+ * $type$[] va = new $type$[a.length];
+ * for (int i = 0; i < a.length; i++) {
+ * va[i] = ($type$) sa[i];
+ * }
+ * return this.species().fromArray(va, 0);
+ * }
+ *
+ * @return a vector representation of this shuffle
+ */
+ public abstract Vector