archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 23:34:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8308645: Javadoc of FFM API needs to be refreshed

Browse source 
8309398: ValueLayout:: arrayElementVarHandle doesn't throws UnsupportedOperationException - if byteAlignment() > byteSize()
8308812: SequenceLayout::withElementCount(long elementCount) doesn't throw IllegalArgumentException - if elementCount < 0 for some cases

Reviewed-by: jvernee
This commit is contained in:
Maurizio Cimadamore 2023-06-12 15:55:49 +00:00
parent 07275072aa
commit a6ad42e00e
28 changed files with 826 additions and 607 deletions
Download patch file Download diff file Expand all files Collapse all files

34
src/java.base/share/classes/java/lang/foreign/SequenceLayout.java
View file

@ -29,9 +29,9 @@ import jdk.internal.foreign.layout.SequenceLayoutImpl;
import jdk.internal.javac.PreviewFeature;
/**
* A compound layout that denotes a repetition of a given <em>element layout</em>.
* The repetition count is said to be the sequence layout's <em>element count</em>. A finite sequence can be thought of as a
* group layout where the sequence layout's element layout is repeated a number of times that is equal to the sequence
* A compound layout that denotes a homogeneous repetition of a given <em>element layout</em>.
* The repetition count is said to be the sequence layout's <em>element count</em>. A sequence layout can be thought of as a
* struct layout where the sequence layout's element layout is repeated a number of times that is equal to the sequence
* layout's element count. In other words this layout:
*
* {@snippet lang=java :
@ -57,7 +57,7 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo
/**
* {@return the element layout associated with this sequence layout}
* {@return the element layout of this sequence layout}
*/
MemoryLayout elementLayout();
@ -67,18 +67,17 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo
long elementCount();
/**
* Returns a sequence layout with the same element layout, alignment constraint and name as this sequence layout,
* but with the specified element count.
* {@return a sequence layout with the same characteristics of this layout, but with the given element count}
* @param elementCount the new element count.
* @return a sequence layout with the given element count.
* @throws IllegalArgumentException if {@code elementCount < 0}.
* @throws IllegalArgumentException if {@code elementCount} is negative.
* @throws IllegalArgumentException if {@code elementLayout.bitSize() * elementCount} overflows.
*/
SequenceLayout withElementCount(long elementCount);
/**
* Re-arrange the elements in this sequence layout into a multi-dimensional sequence layout.
* The resulting layout is a sequence layout where element layouts in the flattened projection of this
* sequence layout (see {@link #flatten()}) are re-arranged into one or more nested sequence layouts
* Rearranges the elements in this sequence layout into a multi-dimensional sequence layout.
* The resulting layout is a sequence layout where element layouts in the {@linkplain #flatten() flattened projection}
* of this sequence layout are rearranged into one or more nested sequence layouts
* according to the provided element counts. This transformation preserves the layout size;
* that is, multiplying the provided element counts must yield the same element count
* as the flattened projection of this sequence layout.
@ -101,7 +100,7 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo
* var reshapeSeqImplicit2 = seq.reshape(2, -1);
* }
* @param elementCounts an array of element counts, of which at most one can be {@code -1}.
* @return a sequence layout where element layouts in the flattened projection of this
* @return a sequence layout where element layouts in the {@linkplain #flatten() flattened projection} of this
* sequence layout (see {@link #flatten()}) are re-arranged into one or more nested sequence layouts.
* @throws IllegalArgumentException if two or more element counts are set to {@code -1}, or if one
* or more element count is {@code <= 0} (but other than {@code -1}) or, if, after any required inference,
@ -112,7 +111,16 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo
/**
* Returns a flattened sequence layout. The element layout of the returned sequence layout
* is the first non-sequence element layout found by recursively traversing the element layouts of this sequence layout.
* is the first non-sequence layout found by inspecting (recursively, if needed) the element layout of this sequence layout:
* {@snippet lang=java :
* MemoryLayout flatElementLayout(SequenceLayout sequenceLayout) {
* return switch (sequenceLayout.elementLayout()) {
* case SequenceLayout nestedSequenceLayout -> flatElementLayout(nestedSequenceLayout);
* case MemoryLayout layout -> layout;
* };
* }
* }
* <p>
* This transformation preserves the layout size; nested sequence layout in this sequence layout will
* be dropped and their element counts will be incorporated into that of the returned sequence layout.
* For instance, given a sequence layout of the kind: