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 where each lane element is set to a given
 134      * {@code int} value logically AND'ed by the species length minus one.
 135      * <p>
 136      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 137      * the {@code int} value at index {@code N} logically AND'ed by
 138      * {@code species.length() - 1} is placed into the resulting shuffle at
 139      * lane index {@code N}.
 140      *
 141      * @param species shuffle species
 142      * @param ixs the given {@code int} values
 143      * @return a shuffle where each lane element is set to a given
 144      * {@code int} value
 145      * @throws IndexOutOfBoundsException if the number of int values is
 146      * {@code < species.length()}
 147      */
 148     @ForceInline
 149     public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species, int... ixs) {
 150         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, 0);
 151     }
 152 
 153     /**
 154      * Loads a shuffle from an {@code int} array starting at an offset.
 155      * <p>
 156      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 157      * array element at index {@code i + N} logically AND'ed by
 158      * {@code species.length() - 1} is placed into the resulting shuffle at lane
 159      * index {@code N}.
 160      *
 161      * @param species shuffle species
 162      * @param ixs the {@code int} array
 163      * @param i the offset into the array
 164      * @return a shuffle loaded from the {@code int} array
 165      * @throws IndexOutOfBoundsException if {@code i < 0}, or
 166      * {@code i > a.length - species.length()}
 167      */
 168     @ForceInline
 169     public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] ixs, int i) {
 170         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, i);
 171     }
 172 
 173     /**
 174      * Returns an {@code int} array containing the lane elements of this
 175      * shuffle.
 176      * <p>
 177      * This method behaves as if it {@link #intoArray(int[], int)} stores}
 178      * this shuffle into an allocated array and returns that array as
 179      * follows:
 180      * <pre>{@code
 181      *   int[] a = new int[this.length()];
 182      *   VectorShuffle.intoArray(a, 0);
 183      *   return a;
 184      * }</pre>
 185      *
 186      * @return an array containing the the lane elements of this vector
 187      */
 188     public abstract int[] toArray();
 189 
 190     /**
 191      * Stores this shuffle into an {@code int} array starting at offset.
 192      * <p>
 193      * For each shuffle lane, where {@code N} is the shuffle lane index,
 194      * the lane element at index {@code N} is stored into the array at index
 195      * {@code i + N}.
 196      *
 197      * @param a the array
 198      * @param i the offset into the array
 199      * @throws IndexOutOfBoundsException if {@code i < 0}, or
 200      * {@code i > a.length - this.length()}
 201      */
 202     public abstract void intoArray(int[] a, int i);
 203 
 204     /**
 205      * Converts this shuffle into a vector, creating a vector from shuffle
 206      * lane elements (int values) cast to the vector element type.
 207      * <p>
 208      * This method behaves as if it returns the result of creating a
 209      * vector given an {@code int} array obtained from this shuffle's
 210      * lane elements, as follows:
 211      * <pre>{@code
 212      *   int[] sa = this.toArray();
 213      *   $type$[] va = new $type$[a.length];
 214      *   for (int i = 0; i < a.length; i++) {
 215      *       va[i] = ($type$) sa[i];
 216      *   }
 217      *   return IntVector.fromArray(va, 0);
 218      * }</pre>
 219      *
 220      * @return a vector representation of this shuffle
 221      */
 222     public abstract Vector<E> toVector();
 223 
 224     /**
 225      * Gets the {@code int} lane element at lane index {@code i}
 226      *
 227      * @param i the lane index
 228      * @return the {@code int} lane element at lane index {@code i}
 229      */
 230     public int getElement(int i) { return toArray()[i]; }
 231 
 232     /**
 233      * Rearranges the lane elements of this shuffle selecting lane indexes
 234      * controlled by another shuffle.
 235      * <p>
 236      * For each lane of the specified shuffle, at lane index {@code N} with lane
 237      * element {@code I}, the lane element at {@code I} from this shuffle is
 238      * selected and placed into the resulting shuffle at {@code N}.
 239      *
 240      * @param s the shuffle controlling lane index selection
 241      * @return the rearrangement of the lane elements of this shuffle
 242      */
 243     public abstract VectorShuffle<E> rearrange(VectorShuffle<E> s);
 244 }