< prev index next >

src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Vector.java

Print this page

   1 /*
   2  * Copyright (c) 2017, 2020, 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 any

1022  * These operations are:
1023  * <ul>
1024  *
1025  * <li>The {@link #slice(int,Vector) slice()} family of methods,
1026  * which extract contiguous slice of {@code VLENGTH} fields from
1027  * a given origin point within a concatenated pair of vectors.
1028  *
1029  * <li>The {@link #unslice(int,Vector,int) unslice()} family of
1030  * methods, which insert a contiguous slice of {@code VLENGTH} fields
1031  * into a concatenated pair of vectors at a given origin point.
1032  *
1033  * <li>The {@link #rearrange(VectorShuffle) rearrange()} family of
1034  * methods, which select an arbitrary set of {@code VLENGTH} lanes
1035  * from one or two input vectors, and assemble them in an arbitrary
1036  * order.  The selection and order of lanes is controlled by a
1037  * {@code VectorShuffle} object, which acts as an routing table
1038  * mapping source lanes to destination lanes.  A {@code VectorShuffle}
1039  * can encode a mathematical permutation as well as many other
1040  * patterns of data movement.
1041  *






1042  * </ul>
1043  * <p> Some vector operations are not lane-wise, but rather move data
1044  * across lane boundaries.  Such operations are typically rare in SIMD
1045  * code, though they are sometimes necessary for specific algorithms
1046  * that manipulate data formats at a low level, and/or require SIMD
1047  * data to move in complex local patterns.  (Local movement in a small
1048  * window of a large array of data is relatively unusual, although
1049  * some highly patterned algorithms call for it.)  In this API such
1050  * methods are always clearly recognizable, so that simpler lane-wise
1051  * reasoning can be confidently applied to the rest of the code.
1052  *
1053  * <p> In some cases, vector lane boundaries are discarded and
1054  * "redrawn from scratch", so that data in a given input lane might
1055  * appear (in several parts) distributed through several output lanes,
1056  * or (conversely) data from several input lanes might be consolidated
1057  * into a single output lane.  The fundamental method which can redraw
1058  * lanes boundaries is
1059  * {@link #reinterpretShape(VectorSpecies,int) reinterpretShape()}.
1060  * Built on top of this method, certain convenience methods such
1061  * as {@link #reinterpretAsBytes() reinterpretAsBytes()} or

2672      *
2673      * <p> This method returns the value of this pseudocode:
2674      * <pre>{@code
2675      * Vector<E> r1 = this.rearrange(s.wrapIndexes());
2676      * // or else: r1 = this.rearrange(s, s.laneIsValid());
2677      * Vector<E> r2 = v.rearrange(s.wrapIndexes());
2678      * return r2.blend(r1,s.laneIsValid());
2679      * }</pre>
2680      *
2681      * @param s the shuffle controlling lane selection from both input vectors
2682      * @param v the second input vector
2683      * @return the rearrangement of lane elements of this vector and
2684      *         a second input vector
2685      * @see #rearrange(VectorShuffle)
2686      * @see #rearrange(VectorShuffle,VectorMask)
2687      * @see VectorShuffle#laneIsValid()
2688      * @see #slice(int,Vector)
2689      */
2690     public abstract Vector<E> rearrange(VectorShuffle<E> s, Vector<E> v);
2691 






































2692     /**
2693      * Using index values stored in the lanes of this vector,
2694      * assemble values stored in second vector {@code v}.
2695      * The second vector thus serves as a table, whose
2696      * elements are selected by indexes in the current vector.
2697      *
2698      * This is a cross-lane operation that rearranges the lane
2699      * elements of the argument vector, under the control of
2700      * this vector.
2701      *
2702      * For each lane {@code N} of this vector, and for each lane
2703      * value {@code I=this.lane(N)} in this vector,
2704      * the output lane {@code N} obtains the value from
2705      * the argument vector at lane {@code I}.
2706      *
2707      * In this way, the result contains only values stored in the
2708      * argument vector {@code v}, but presented in an order which
2709      * depends on the index values in {@code this}.
2710      *
2711      * The result is the same as the expression

   1 /*
   2  * Copyright (c) 2017, 2021, 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 any

1022  * These operations are:
1023  * <ul>
1024  *
1025  * <li>The {@link #slice(int,Vector) slice()} family of methods,
1026  * which extract contiguous slice of {@code VLENGTH} fields from
1027  * a given origin point within a concatenated pair of vectors.
1028  *
1029  * <li>The {@link #unslice(int,Vector,int) unslice()} family of
1030  * methods, which insert a contiguous slice of {@code VLENGTH} fields
1031  * into a concatenated pair of vectors at a given origin point.
1032  *
1033  * <li>The {@link #rearrange(VectorShuffle) rearrange()} family of
1034  * methods, which select an arbitrary set of {@code VLENGTH} lanes
1035  * from one or two input vectors, and assemble them in an arbitrary
1036  * order.  The selection and order of lanes is controlled by a
1037  * {@code VectorShuffle} object, which acts as an routing table
1038  * mapping source lanes to destination lanes.  A {@code VectorShuffle}
1039  * can encode a mathematical permutation as well as many other
1040  * patterns of data movement.
1041  *
1042  * <li>The {@link #compress(VectorMask)} and {@link #expand(VectorMask)}
1043  * methods, which select up to {@code VLENGTH} lanes from an
1044  * input vector, and assemble them in lane order.  The selection of lanes
1045  * is controlled by a {@code VectorMask}, with set lane elements mapping, by
1046  * compression or expansion in lane order, source lanes to destination lanes.
1047  *
1048  * </ul>
1049  * <p> Some vector operations are not lane-wise, but rather move data
1050  * across lane boundaries.  Such operations are typically rare in SIMD
1051  * code, though they are sometimes necessary for specific algorithms
1052  * that manipulate data formats at a low level, and/or require SIMD
1053  * data to move in complex local patterns.  (Local movement in a small
1054  * window of a large array of data is relatively unusual, although
1055  * some highly patterned algorithms call for it.)  In this API such
1056  * methods are always clearly recognizable, so that simpler lane-wise
1057  * reasoning can be confidently applied to the rest of the code.
1058  *
1059  * <p> In some cases, vector lane boundaries are discarded and
1060  * "redrawn from scratch", so that data in a given input lane might
1061  * appear (in several parts) distributed through several output lanes,
1062  * or (conversely) data from several input lanes might be consolidated
1063  * into a single output lane.  The fundamental method which can redraw
1064  * lanes boundaries is
1065  * {@link #reinterpretShape(VectorSpecies,int) reinterpretShape()}.
1066  * Built on top of this method, certain convenience methods such
1067  * as {@link #reinterpretAsBytes() reinterpretAsBytes()} or

2678      *
2679      * <p> This method returns the value of this pseudocode:
2680      * <pre>{@code
2681      * Vector<E> r1 = this.rearrange(s.wrapIndexes());
2682      * // or else: r1 = this.rearrange(s, s.laneIsValid());
2683      * Vector<E> r2 = v.rearrange(s.wrapIndexes());
2684      * return r2.blend(r1,s.laneIsValid());
2685      * }</pre>
2686      *
2687      * @param s the shuffle controlling lane selection from both input vectors
2688      * @param v the second input vector
2689      * @return the rearrangement of lane elements of this vector and
2690      *         a second input vector
2691      * @see #rearrange(VectorShuffle)
2692      * @see #rearrange(VectorShuffle,VectorMask)
2693      * @see VectorShuffle#laneIsValid()
2694      * @see #slice(int,Vector)
2695      */
2696     public abstract Vector<E> rearrange(VectorShuffle<E> s, Vector<E> v);
2697 
2698     /**
2699      * Compresses the lane elements of this vector selecting lanes
2700      * under the control of a specific mask.
2701      *
2702      * This is a cross-lane operation that compresses the lane
2703      * elements of this vector as selected by the specified mask.
2704      *
2705      * For each lane {@code N} of the mask, if the mask at
2706      * lane {@code N} is set, the element at lane {@code N}
2707      * of input vector is selected and stored into the output
2708      * vector contiguously starting from the lane {@code 0}.
2709      * All the upper remaining lanes, if any, of the output
2710      * vector are set to zero.
2711      *
2712      * @param m the mask controlling the compression
2713      * @return the compressed lane elements of this vector
2714      */
2715     public abstract Vector<E> compress(VectorMask<E> m);
2716 
2717     /**
2718      * Expands the lane elements of this vector
2719      * under the control of a specific mask.
2720      *
2721      * This is a cross-lane operation that expands the contiguous lane
2722      * elements of this vector into lanes of an output vector
2723      * as selected by the specified mask.
2724      *
2725      * For each lane {@code N} of the mask, if the mask at
2726      * lane {@code N} is set, the next contiguous element of input vector
2727      * starting from lane {@code 0} is selected and stored into the output
2728      * vector at lane {@code N}.
2729      * All the remaining lanes, if any, of the output vector are set to zero.
2730      *
2731      * @param m the mask controlling the compression
2732      * @return the expanded lane elements of this vector
2733      */
2734     public abstract Vector<E> expand(VectorMask<E> m);
2735 
2736     /**
2737      * Using index values stored in the lanes of this vector,
2738      * assemble values stored in second vector {@code v}.
2739      * The second vector thus serves as a table, whose
2740      * elements are selected by indexes in the current vector.
2741      *
2742      * This is a cross-lane operation that rearranges the lane
2743      * elements of the argument vector, under the control of
2744      * this vector.
2745      *
2746      * For each lane {@code N} of this vector, and for each lane
2747      * value {@code I=this.lane(N)} in this vector,
2748      * the output lane {@code N} obtains the value from
2749      * the argument vector at lane {@code I}.
2750      *
2751      * In this way, the result contains only values stored in the
2752      * argument vector {@code v}, but presented in an order which
2753      * depends on the index values in {@code this}.
2754      *
2755      * The result is the same as the expression
< prev index next >