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      */
 109     @ForceInline
 110     public static <E> VectorShuffle<E> shuffle(VectorSpecies<E> species, IntUnaryOperator f) {
 111         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(f);
 112     }
 113 
 114     /**
 115      * Returns a shuffle where each lane element is the value of its
 116      * corresponding lane index.
 117      * <p>
 118      * This method behaves as if a shuffle is created from an identity
 119      * index mapping function as follows:
 120      * <pre>{@code
 121      *   return VectorShuffle.shuffle(i -> i);
 122      * }</pre>
 123      *
 124      * @param species shuffle species
 125      * @return a shuffle of lane indexes
 126      */
 127     @ForceInline
 128     public static <E> VectorShuffle<E> shuffleIota(VectorSpecies<E> species) {
 129         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(AbstractShuffle.IDENTITY);
 130     }
 131 
 132     /**
 133      * Returns a shuffle with lane elements set to sequential {@code int} values starting from {@code start}.
 134      * <p>
 135      * This method behaves as if a shuffle is created from an identity
 136      * index mapping function as follows:
 137      * <pre>{@code
 138      *   return VectorShuffle.shuffle(i -> i + start);
 139      * }</pre>
 140      *
 141      * @param species shuffle species
 142      * @param start starting value of sequence
 143      * @return a shuffle of lane indexes
 144      */
 145     @ForceInline
 146     public static <E> VectorShuffle<E> shuffleIota(VectorSpecies<E> species, int start) {
 147         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(i -> i + start);
 148     }
 149 
 150     /**
 151      * Returns a shuffle with lane elements set to sequential {@code int} values starting from {@code start}
 152      * and looping around species length.
 153      * <p>
 154      * This method behaves as if a shuffle is created from an identity
 155      * index mapping function as follows:
 156      * <pre>{@code
 157      *   return VectorShuffle.shuffle(i -> (i + start) & (species.length() - 1));
 158      * }</pre>
 159      *
 160      * @param species shuffle species
 161      * @param start starting value of sequence
 162      * @return a shuffle of lane indexes
 163      */
 164     @ForceInline
 165     public static <E> VectorShuffle<E> shuffleOffset(VectorSpecies<E> species, int start) {
 166         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(i -> (i + start) & (species.length() - 1));
 167     }
 168 
 169     /**
 170      * Returns a shuffle where each lane element is set to a given
 171      * {@code int} value logically AND'ed by the species length minus one.
 172      * <p>
 173      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 174      * the {@code int} value at index {@code N} logically AND'ed by
 175      * {@code species.length() - 1} is placed into the resulting shuffle at
 176      * lane index {@code N}.
 177      *
 178      * @param species shuffle species
 179      * @param ixs the given {@code int} values
 180      * @return a shuffle where each lane element is set to a given
 181      * {@code int} value
 182      * @throws IndexOutOfBoundsException if the number of int values is
 183      * {@code < species.length()}
 184      */
 185     @ForceInline
 186     public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species, int... ixs) {
 187         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, 0);
 188     }
 189 
 190     /**
 191      * Loads a shuffle from an {@code int} array starting at an offset.
 192      * <p>
 193      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 194      * array element at index {@code i + N} logically AND'ed by
 195      * {@code species.length() - 1} is placed into the resulting shuffle at lane
 196      * index {@code N}.
 197      *
 198      * @param species shuffle species
 199      * @param ixs the {@code int} array
 200      * @param offset the offset into the array
 201      * @return a shuffle loaded from the {@code int} array
 202      * @throws IndexOutOfBoundsException if {@code offset < 0}, or
 203      * {@code offset > a.length - species.length()}
 204      */
 205     @ForceInline
 206     public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] ixs, int offset) {
 207         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, offset);
 208     }
 209 
 210     /**
 211      * Returns an {@code int} array containing the lane elements of this
 212      * shuffle.
 213      * <p>
 214      * This method behaves as if it {@link #intoArray(int[], int)} stores}
 215      * this shuffle into an allocated array and returns that array as
 216      * follows:
 217      * <pre>{@code
 218      *   int[] a = new int[this.length()];
 219      *   VectorShuffle.intoArray(a, 0);
 220      *   return a;
 221      * }</pre>
 222      *
 223      * @return an array containing the the lane elements of this vector
 224      */
 225     public abstract int[] toArray();
 226 
 227     /**
 228      * Stores this shuffle into an {@code int} array starting at offset.
 229      * <p>
 230      * For each shuffle lane, where {@code N} is the shuffle lane index,
 231      * the lane element at index {@code N} is stored into the array at index
 232      * {@code i + N}.
 233      *
 234      * @param a the array
 235      * @param offset the offset into the array
 236      * @throws IndexOutOfBoundsException if {@code i < 0}, or
 237      * {@code offset > a.length - this.length()}
 238      */
 239     public abstract void intoArray(int[] a, int offset);
 240 
 241     /**
 242      * Converts this shuffle into a vector, creating a vector from shuffle
 243      * lane elements (int values) cast to the vector element type.
 244      * <p>
 245      * This method behaves as if it returns the result of creating a
 246      * vector given an {@code int} array obtained from this shuffle's
 247      * lane elements, as follows:
 248      * <pre>{@code
 249      *   int[] sa = this.toArray();
 250      *   $type$[] va = new $type$[a.length];
 251      *   for (int i = 0; i < a.length; i++) {
 252      *       va[i] = ($type$) sa[i];
 253      *   }
 254      *   return IntVector.fromArray(va, 0);
 255      * }</pre>
 256      *
 257      * @return a vector representation of this shuffle
 258      */
 259     public abstract Vector<E> toVector();
 260 
 261     /**
 262      * Gets the {@code int} lane element at lane index {@code i}
 263      *
 264      * @param i the lane index
 265      * @return the {@code int} lane element at lane index {@code i}
 266      */
 267     public int lane(int i) { return toArray()[i]; }
 268 
 269     /**
 270      * Rearranges the lane elements of this shuffle selecting lane indexes
 271      * controlled by another shuffle.
 272      * <p>
 273      * For each lane of the specified shuffle, at lane index {@code N} with lane
 274      * element {@code I}, the lane element at {@code I} from this shuffle is
 275      * selected and placed into the resulting shuffle at {@code N}.
 276      *
 277      * @param s the shuffle controlling lane index selection
 278      * @return the rearrangement of the lane elements of this shuffle
 279      */
 280     public abstract VectorShuffle<E> rearrange(VectorShuffle<E> s);
 281 }