1 /*
   2  * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have
  23  * questions.
  24  */
  25 package jdk.incubator.vector;
  26 
  27 import jdk.internal.vm.annotation.ForceInline;
  28 import java.util.function.IntUnaryOperator;
  29 
  30 /**
  31  * A {@code VectorShuffle} represents an ordered immutable sequence of
  32  * {@code int} values.  A VectorShuffle can be used with a shuffle accepting
  33  * vector operation to control the rearrangement of lane elements of input
  34  * vectors
  35  * <p>
  36  * The number of values in the sequence is referred to as the shuffle
  37  * {@link #length() length}.  The length also corresponds to the number of
  38  * shuffle lanes.  The lane element at lane index {@code N} (from {@code 0},
  39  * inclusive, to length, exclusive) corresponds to the {@code N + 1}'th
  40  * value in the sequence.
  41  * A VectorShuffle and Vector of the same element type and shape have the same
  42  * number of lanes.
  43  * <p>
  44  * A VectorShuffle describes how a lane element of a vector may cross lanes from
  45  * its lane index, {@code i} say, to another lane index whose value is the
  46  * shuffle's lane element at lane index {@code i}.  VectorShuffle lane elements
  47  * will be in the range of {@code 0} (inclusive) to the shuffle length
  48  * (exclusive), and therefore cannot induce out of bounds errors when
  49  * used with vectors operations and vectors of the same length.
  50  *
  51  * @param <E> the boxed element type of this mask
  52  */
  53 public abstract class VectorShuffle<E> {
  54     VectorShuffle() {}
  55 
  56     /**
  57      * Returns the species of this shuffle.
  58      *
  59      * @return the species of this shuffle
  60      */
  61     public abstract VectorSpecies<E> species();
  62 
  63     /**
  64      * Returns the number of shuffle lanes (the length).
  65      *
  66      * @return the number of shuffle lanes
  67      */
  68     public int length() { return species().length(); }
  69 
  70     /**
  71      * Converts this shuffle to a shuffle of the given species of element type {@code F}.
  72      * <p>
  73      * For each shuffle lane, where {@code N} is the lane index, the
  74      * shuffle element at index {@code N} is placed, unmodified, into the
  75      * resulting shuffle at index {@code N}.
  76      *
  77      * @param species species of desired shuffle
  78      * @param <F> the boxed element type of the species
  79      * @return a shuffle converted by shape and element type
  80      * @throws IllegalArgumentException if this shuffle length and the
  81      * species length differ
  82      */
  83     public abstract <F> VectorShuffle<F> cast(VectorSpecies<F> species);
  84 
  85     /**
  86      * Returns a shuffle of mapped indexes where each lane element is
  87      * the result of applying a mapping function to the corresponding lane
  88      * index.
  89      * <p>
  90      * Care should be taken to ensure VectorShuffle values produced from this
  91      * method are consumed as constants to ensure optimal generation of
  92      * code.  For example, values held in static final fields or values
  93      * held in loop constant local variables.
  94      * <p>
  95      * This method behaves as if a shuffle is created from an array of
  96      * mapped indexes as follows:
  97      * <pre>{@code
  98      *   int[] a = new int[species.length()];
  99      *   for (int i = 0; i < a.length; i++) {
 100      *       a[i] = f.applyAsInt(i);
 101      *   }
 102      *   return VectorShuffle.fromValues(a);
 103      * }</pre>
 104      *
 105      * @param species shuffle species
 106      * @param f the lane index mapping function
 107      * @return a shuffle of mapped indexes
 108      * @see Vector#shuffle(IntUnaryOperator)
 109      */
 110     @ForceInline
 111     public static <E> VectorShuffle<E> shuffle(VectorSpecies<E> species, IntUnaryOperator f) {
 112         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(f);
 113     }
 114 
 115     /**
 116      * Returns a shuffle where each lane element is the value of its
 117      * corresponding lane index.
 118      * <p>
 119      * This method behaves as if a shuffle is created from an identity
 120      * index mapping function as follows:
 121      * <pre>{@code
 122      *   return VectorShuffle.shuffle(i -> i);
 123      * }</pre>
 124      *
 125      * @param species shuffle species
 126      * @return a shuffle of lane indexes
 127      * @see Vector#shuffleIota()
 128      */
 129     @ForceInline
 130     public static <E> VectorShuffle<E> shuffleIota(VectorSpecies<E> species) {
 131         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(AbstractShuffle.IDENTITY);
 132     }
 133 
 134     /**
 135      * Returns a shuffle with lane elements set to sequential {@code int} values starting from {@code start}.
 136      * <p>
 137      * This method behaves as if a shuffle is created from an identity
 138      * index mapping function as follows:
 139      * <pre>{@code
 140      *   return VectorShuffle.shuffle(i -> i + start);
 141      * }</pre>
 142      *
 143      * @param species shuffle species
 144      * @param start starting value of sequence
 145      * @return a shuffle of lane indexes
 146      * @see Vector#shuffleIota(int)
 147      */
 148     @ForceInline
 149     @SuppressWarnings("unchecked")
 150     public static <E> VectorShuffle<E> shuffleIota(VectorSpecies<E> species, int start) {
 151        Class<?> elementType = species.elementType();
 152        if (elementType == byte.class) {
 153            return (VectorShuffle) ByteVector.shuffleIotaHelper((VectorSpecies<Byte>) species, start);
 154        } else if (elementType == short.class) {
 155            return (VectorShuffle) ShortVector.shuffleIotaHelper((VectorSpecies<Short>) species, start);
 156        } else if (elementType == int.class) {
 157            return (VectorShuffle) IntVector.shuffleIotaHelper((VectorSpecies<Integer>) species, start);
 158        } else if (elementType == long.class) {
 159            return (VectorShuffle) LongVector.shuffleIotaHelper((VectorSpecies<Long>) species, start);
 160        } else if (elementType == float.class) {
 161            return (VectorShuffle) FloatVector.shuffleIotaHelper((VectorSpecies<Float>) species, start);
 162        } else if (elementType == double.class) {
 163            return (VectorShuffle) DoubleVector.shuffleIotaHelper((VectorSpecies<Double>) species, start);
 164        } else {
 165            throw new UnsupportedOperationException("Bad lane type for shuffleIota.");
 166        }
 167     }
 168 
 169     /**
 170      * Returns a shuffle with lane elements set to sequential {@code int} values starting from {@code start}
 171      * and looping around species length.
 172      * <p>
 173      * This method behaves as if a shuffle is created from an identity
 174      * index mapping function as follows:
 175      * <pre>{@code
 176      *   return VectorShuffle.shuffle(i -> (i + start) & (species.length() - 1));
 177      * }</pre>
 178      *
 179      * @param species shuffle species
 180      * @param start starting value of sequence
 181      * @return a shuffle of lane indexes
 182      * @see Vector#shuffleOffset(int)
 183      */
 184     @ForceInline
 185     public static <E> VectorShuffle<E> shuffleOffset(VectorSpecies<E> species, int start) {
 186         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(i -> (i + start) & (species.length() - 1));
 187     }
 188 
 189     /**
 190      * Returns a shuffle where each lane element is set to a given
 191      * {@code int} value logically AND'ed by the species length minus one.
 192      * <p>
 193      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 194      * the {@code int} value at index {@code N} logically AND'ed by
 195      * {@code species.length() - 1} is placed into the resulting shuffle at
 196      * lane index {@code N}.
 197      *
 198      * @param species shuffle species
 199      * @param ixs the given {@code int} values
 200      * @return a shuffle where each lane element is set to a given
 201      * {@code int} value
 202      * @throws IndexOutOfBoundsException if the number of int values is
 203      * {@code < species.length()}
 204      * @see Vector#shuffleFromValues(int...)
 205      */
 206     @ForceInline
 207     public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species, int... ixs) {
 208         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, 0);
 209     }
 210 
 211     /**
 212      * Loads a shuffle from an {@code int} array starting at an offset.
 213      * <p>
 214      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 215      * array element at index {@code i + N} logically AND'ed by
 216      * {@code species.length() - 1} is placed into the resulting shuffle at lane
 217      * index {@code N}.
 218      *
 219      * @param species shuffle species
 220      * @param ixs the {@code int} array
 221      * @param offset the offset into the array
 222      * @return a shuffle loaded from the {@code int} array
 223      * @throws IndexOutOfBoundsException if {@code offset < 0}, or
 224      * {@code offset > ixs.length - species.length()}
 225      * @see Vector#shuffleFromArray(int[], int)
 226      */
 227     @ForceInline
 228     public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] ixs, int offset) {
 229         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, offset);
 230     }
 231 
 232     /**
 233      * Returns an {@code int} array containing the lane elements of this
 234      * shuffle.
 235      * <p>
 236      * This method behaves as if it {@link #intoArray(int[], int)} stores}
 237      * this shuffle into an allocated array and returns that array as
 238      * follows:
 239      * <pre>{@code
 240      *   int[] a = new int[this.length()];
 241      *   VectorShuffle.intoArray(a, 0);
 242      *   return a;
 243      * }</pre>
 244      *
 245      * @return an array containing the the lane elements of this vector
 246      */
 247     public abstract int[] toArray();
 248 
 249     /**
 250      * Stores this shuffle into an {@code int} array starting at offset.
 251      * <p>
 252      * For each shuffle lane, where {@code N} is the shuffle lane index,
 253      * the lane element at index {@code N} is stored into the array at index
 254      * {@code i + N}.
 255      *
 256      * @param a the array
 257      * @param offset the offset into the array
 258      * @throws IndexOutOfBoundsException if {@code i < 0}, or
 259      * {@code offset > a.length - this.length()}
 260      */
 261     public abstract void intoArray(int[] a, int offset);
 262 
 263     /**
 264      * Converts this shuffle into a vector, creating a vector from shuffle
 265      * lane elements (int values) cast to the vector element type.
 266      * <p>
 267      * This method behaves as if it returns the result of creating a
 268      * vector given an {@code int} array obtained from this shuffle's
 269      * lane elements, as follows:
 270      * <pre>{@code
 271      *   int[] sa = this.toArray();
 272      *   $type$[] va = new $type$[a.length];
 273      *   for (int i = 0; i < a.length; i++) {
 274      *       va[i] = ($type$) sa[i];
 275      *   }
 276      *   return IntVector.fromArray(va, 0);
 277      * }</pre>
 278      *
 279      * @return a vector representation of this shuffle
 280      */
 281     public abstract Vector<E> toVector();
 282 
 283     /**
 284      * Gets the {@code int} lane element at lane index {@code i}
 285      *
 286      * @param i the lane index
 287      * @return the {@code int} lane element at lane index {@code i}
 288      */
 289     public int lane(int i) { return toArray()[i]; }
 290 
 291     /**
 292      * Rearranges the lane elements of this shuffle selecting lane indexes
 293      * controlled by another shuffle.
 294      * <p>
 295      * For each lane of the specified shuffle, at lane index {@code N} with lane
 296      * element {@code I}, the lane element at {@code I} from this shuffle is
 297      * selected and placed into the resulting shuffle at {@code N}.
 298      *
 299      * @param s the shuffle controlling lane index selection
 300      * @return the rearrangement of the lane elements of this shuffle
 301      */
 302     public abstract VectorShuffle<E> rearrange(VectorShuffle<E> s);
 303 }