< prev index next >

src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorSpecies.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
 23  * questions.
 24  */
 25 package jdk.incubator.vector;
 26 


 27 import java.nio.ByteOrder;
 28 import java.util.function.IntUnaryOperator;
 29 
 30 /**
 31  * Interface for managing all vectors of the same combination
 32  * of <a href="Vector.html#ETYPE">element type</a> ({@code ETYPE})
 33  * and {@link VectorShape shape}.
 34  *
 35  * @apiNote
 36  * User code should not implement this interface.  A future release of
 37  * this type may restrict implementations to be members of the same
 38  * package.
 39  *
 40  * @implNote
 41  * The string representation of an instance of this interface will
 42  * be of the form "Species[ETYPE, VLENGTH, SHAPE]", where {@code
 43  * ETYPE} is the primitive {@linkplain #elementType() lane type},
 44  * {@code VLENGTH} is the {@linkplain #length() vector lane count}
 45  * associated with the species, and {@code SHAPE} is the {@linkplain
 46  * #vectorShape() vector shape} associated with the species.

132     /**
133      * Loop control function which returns the largest multiple of
134      * {@code VLENGTH} that is less than or equal to the given
135      * {@code length} value.
136      * Here, {@code VLENGTH} is the result of {@code this.length()},
137      * and {@code length} is interpreted as a number of lanes.
138      * The resulting value {@code R} satisfies this inequality:
139      * <pre>{@code R <= length < R+VLENGTH}
140      * </pre>
141      * <p> Specifically, this method computes
142      * {@code length - floorMod(length, VLENGTH)}, where
143      * {@link Math#floorMod(int,int) floorMod} computes a remainder
144      * value by rounding its quotient toward negative infinity.
145      * As long as {@code VLENGTH} is a power of two, then the result
146      * is also equal to {@code length & ~(VLENGTH - 1)}.
147      *
148      * @param length the input length
149      * @return the largest multiple of the vector length not greater
150      *         than the given length
151      * @throws IllegalArgumentException if the {@code length} is
152                negative and the result would overflow to a positive value
153      * @see Math#floorMod(int, int)
154      */
155     int loopBound(int length);
156 


























157     /**
158      * Returns a mask of this species where only
159      * the lanes at index N such that the adjusted index
160      * {@code N+offset} is in the range {@code [0..limit-1]}
161      * are set.
162      *
163      * <p>
164      * This method returns the value of the expression
165      * {@code maskAll(true).indexInRange(offset, limit)}
166      *
167      * @param offset the starting index
168      * @param limit the upper-bound (exclusive) of index range
169      * @return a mask with out-of-range lanes unset
170      * @see VectorMask#indexInRange(int, int)
171      */
172     VectorMask<E> indexInRange(int offset, int limit);
173 


















174     /**
175      * Checks that this species has the given element type,
176      * and returns this species unchanged.
177      * The effect is similar to this pseudocode:
178      * {@code elementType == elementType()
179      *        ? this
180      *        : throw new ClassCastException()}.
181      *
182      * @param elementType the required lane type
183      * @param <F> the boxed element type of the required lane type
184      * @return the same species
185      * @throws ClassCastException if the species has the wrong element type
186      * @see Vector#check(Class)
187      * @see Vector#check(VectorSpecies)
188      */
189     <F> VectorSpecies<F> check(Class<F> elementType);
190 
191     /**
192      * Given this species and a second one, reports the net
193      * expansion or contraction of a (potentially) resizing

416      *
417      * Equivalent to
418      * {@code IntVector.fromArray(this,a,offset)}
419      * or an equivalent {@code fromArray} method,
420      * on the vector type corresponding to
421      * this species.
422      *
423      * @param a an array of the {@code ETYPE} for this species
424      * @param offset the index of the first lane value to load
425      * @return a vector of the given species filled from the array
426      * @throws IndexOutOfBoundsException
427      *         if {@code offset+N < 0} or {@code offset+N >= a.length}
428      *         for any lane {@code N} in the vector
429      * @see IntVector#fromArray(VectorSpecies,int[],int)
430      * @see FloatVector#fromArray(VectorSpecies,float[],int)
431      */
432     Vector<E> fromArray(Object a, int offset);
433     // Defined when ETYPE is known.
434 
435     /**
436      * Loads a vector of this species from a byte array starting
437      * at an offset.
438      * Bytes are composed into primitive lane elements according
439      * to the specified byte order.
440      * The vector is arranged into lanes according to
441      * <a href="Vector.html#lane-order">memory ordering</a>.
442      * <p>
443      * Equivalent to
444      * {@code IntVector.fromByteArray(this,a,offset,bo)}
445      * or an equivalent {@code fromByteArray} method,
446      * on the vector type corresponding to
447      * this species.
448      *
449      * @param a a byte array
450      * @param offset the index of the first byte to load
451      * @param bo the intended byte order
452      * @return a vector of the given species filled from the byte array
453      * @throws IndexOutOfBoundsException
454      *         if {@code offset+N*ESIZE < 0}
455      *         or {@code offset+(N+1)*ESIZE > a.length}
456      *         for any lane {@code N} in the vector
457      * @see IntVector#fromByteArray(VectorSpecies,byte[],int,ByteOrder)
458      * @see FloatVector#fromByteArray(VectorSpecies,byte[],int,ByteOrder)

459      */
460     Vector<E> fromByteArray(byte[] a, int offset, ByteOrder bo);
461 
462     /**
463      * Returns a mask of this species
464      * where lane elements are initialized
465      * from the given array at the given offset.
466      *
467      * Equivalent to
468      * {@code VectorMask.fromArray(this,a,offset)}.
469      *
470      * @param bits the {@code boolean} array
471      * @param offset the offset into the array
472      * @return the mask loaded from the {@code boolean} array
473      * @throws IndexOutOfBoundsException
474      *         if {@code offset+N < 0} or {@code offset+N >= a.length}
475      *         for any lane {@code N} in the vector mask
476      * @see VectorMask#fromArray(VectorSpecies,boolean[],int)
477      */
478     VectorMask<E> loadMask(boolean[] bits, int offset);
479 
480     /**

  1 /*
  2  * Copyright (c) 2017, 2022, 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
 23  * questions.
 24  */
 25 package jdk.incubator.vector;
 26 
 27 import jdk.incubator.foreign.MemorySegment;
 28 
 29 import java.nio.ByteOrder;
 30 import java.util.function.IntUnaryOperator;
 31 
 32 /**
 33  * Interface for managing all vectors of the same combination
 34  * of <a href="Vector.html#ETYPE">element type</a> ({@code ETYPE})
 35  * and {@link VectorShape shape}.
 36  *
 37  * @apiNote
 38  * User code should not implement this interface.  A future release of
 39  * this type may restrict implementations to be members of the same
 40  * package.
 41  *
 42  * @implNote
 43  * The string representation of an instance of this interface will
 44  * be of the form "Species[ETYPE, VLENGTH, SHAPE]", where {@code
 45  * ETYPE} is the primitive {@linkplain #elementType() lane type},
 46  * {@code VLENGTH} is the {@linkplain #length() vector lane count}
 47  * associated with the species, and {@code SHAPE} is the {@linkplain
 48  * #vectorShape() vector shape} associated with the species.

134     /**
135      * Loop control function which returns the largest multiple of
136      * {@code VLENGTH} that is less than or equal to the given
137      * {@code length} value.
138      * Here, {@code VLENGTH} is the result of {@code this.length()},
139      * and {@code length} is interpreted as a number of lanes.
140      * The resulting value {@code R} satisfies this inequality:
141      * <pre>{@code R <= length < R+VLENGTH}
142      * </pre>
143      * <p> Specifically, this method computes
144      * {@code length - floorMod(length, VLENGTH)}, where
145      * {@link Math#floorMod(int,int) floorMod} computes a remainder
146      * value by rounding its quotient toward negative infinity.
147      * As long as {@code VLENGTH} is a power of two, then the result
148      * is also equal to {@code length & ~(VLENGTH - 1)}.
149      *
150      * @param length the input length
151      * @return the largest multiple of the vector length not greater
152      *         than the given length
153      * @throws IllegalArgumentException if the {@code length} is
154      *         negative and the result would overflow to a positive value
155      * @see Math#floorMod(int, int)
156      */
157     int loopBound(int length);
158 
159     /**
160      * Loop control function which returns the largest multiple of
161      * {@code VLENGTH} that is less than or equal to the given
162      * {@code length} value.
163      * Here, {@code VLENGTH} is the result of {@code this.length()},
164      * and {@code length} is interpreted as a number of lanes.
165      * The resulting value {@code R} satisfies this inequality:
166      * <pre>{@code R <= length < R+VLENGTH}
167      * </pre>
168      * <p> Specifically, this method computes
169      * {@code length - floorMod(length, VLENGTH)}, where
170      * {@link Math#floorMod(long,int) floorMod} computes a remainder
171      * value by rounding its quotient toward negative infinity.
172      * As long as {@code VLENGTH} is a power of two, then the result
173      * is also equal to {@code length & ~(VLENGTH - 1)}.
174      *
175      * @param length the input length
176      * @return the largest multiple of the vector length not greater
177      *         than the given length
178      * @throws IllegalArgumentException if the {@code length} is
179      *         negative and the result would overflow to a positive value
180      * @see Math#floorMod(long, int)
181      * @since 19
182      */
183     long loopBound(long length);
184 
185     /**
186      * Returns a mask of this species where only
187      * the lanes at index N such that the adjusted index
188      * {@code N+offset} is in the range {@code [0..limit-1]}
189      * are set.
190      *
191      * <p>
192      * This method returns the value of the expression
193      * {@code maskAll(true).indexInRange(offset, limit)}
194      *
195      * @param offset the starting index
196      * @param limit the upper-bound (exclusive) of index range
197      * @return a mask with out-of-range lanes unset
198      * @see VectorMask#indexInRange(int, int)
199      */
200     VectorMask<E> indexInRange(int offset, int limit);
201 
202     /**
203      * Returns a mask of this species where only
204      * the lanes at index N such that the adjusted index
205      * {@code N+offset} is in the range {@code [0..limit-1]}
206      * are set.
207      *
208      * <p>
209      * This method returns the value of the expression
210      * {@code maskAll(true).indexInRange(offset, limit)}
211      *
212      * @param offset the starting index
213      * @param limit the upper-bound (exclusive) of index range
214      * @return a mask with out-of-range lanes unset
215      * @see VectorMask#indexInRange(long, long)
216      * @since 19
217      */
218     VectorMask<E> indexInRange(long offset, long limit);
219 
220     /**
221      * Checks that this species has the given element type,
222      * and returns this species unchanged.
223      * The effect is similar to this pseudocode:
224      * {@code elementType == elementType()
225      *        ? this
226      *        : throw new ClassCastException()}.
227      *
228      * @param elementType the required lane type
229      * @param <F> the boxed element type of the required lane type
230      * @return the same species
231      * @throws ClassCastException if the species has the wrong element type
232      * @see Vector#check(Class)
233      * @see Vector#check(VectorSpecies)
234      */
235     <F> VectorSpecies<F> check(Class<F> elementType);
236 
237     /**
238      * Given this species and a second one, reports the net
239      * expansion or contraction of a (potentially) resizing

462      *
463      * Equivalent to
464      * {@code IntVector.fromArray(this,a,offset)}
465      * or an equivalent {@code fromArray} method,
466      * on the vector type corresponding to
467      * this species.
468      *
469      * @param a an array of the {@code ETYPE} for this species
470      * @param offset the index of the first lane value to load
471      * @return a vector of the given species filled from the array
472      * @throws IndexOutOfBoundsException
473      *         if {@code offset+N < 0} or {@code offset+N >= a.length}
474      *         for any lane {@code N} in the vector
475      * @see IntVector#fromArray(VectorSpecies,int[],int)
476      * @see FloatVector#fromArray(VectorSpecies,float[],int)
477      */
478     Vector<E> fromArray(Object a, int offset);
479     // Defined when ETYPE is known.
480 
481     /**
482      * Loads a vector of this species from a {@linkplain MemorySegment memory segment}
483      * starting at an offset into the memory segment.
484      * Bytes are composed into primitive lane elements according
485      * to the specified byte order.
486      * The vector is arranged into lanes according to
487      * <a href="Vector.html#lane-order">memory ordering</a>.
488      * <p>
489      * Equivalent to
490      * {@code IntVector.fromMemorySegment(this,ms,offset,bo)},

491      * on the vector type corresponding to
492      * this species.
493      *
494      * @param ms the memory segment
495      * @param offset the offset into the memory segment
496      * @param bo the intended byte order
497      * @return a vector of the given species filled from the memory segment
498      * @throws IndexOutOfBoundsException
499      *         if {@code offset+N*ESIZE < 0}
500      *         or {@code offset+(N+1)*ESIZE > a.length}
501      *         for any lane {@code N} in the vector
502      * @see IntVector#fromMemorySegment(VectorSpecies, jdk.incubator.foreign.MemorySegment, long, java.nio.ByteOrder)
503      * @see FloatVector#fromMemorySegment(VectorSpecies, jdk.incubator.foreign.MemorySegment, long, java.nio.ByteOrder)
504      * @since 19
505      */
506     Vector<E> fromMemorySegment(MemorySegment ms, long offset, ByteOrder bo);
507 
508     /**
509      * Returns a mask of this species
510      * where lane elements are initialized
511      * from the given array at the given offset.
512      *
513      * Equivalent to
514      * {@code VectorMask.fromArray(this,a,offset)}.
515      *
516      * @param bits the {@code boolean} array
517      * @param offset the offset into the array
518      * @return the mask loaded from the {@code boolean} array
519      * @throws IndexOutOfBoundsException
520      *         if {@code offset+N < 0} or {@code offset+N >= a.length}
521      *         for any lane {@code N} in the vector mask
522      * @see VectorMask#fromArray(VectorSpecies,boolean[],int)
523      */
524     VectorMask<E> loadMask(boolean[] bits, int offset);
525 
526     /**
< prev index next >