1 /*
2 * Copyright (c) 2019, 2023, 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
26 package java.lang.foreign;
27
28 import jdk.internal.foreign.layout.SequenceLayoutImpl;
29 import jdk.internal.javac.PreviewFeature;
30
31 /**
32 * A compound layout that denotes a homogeneous repetition of a given <em>element layout</em>.
33 * The repetition count is said to be the sequence layout's <em>element count</em>. A sequence layout can be thought of as a
34 * struct layout where the sequence layout's element layout is repeated a number of times that is equal to the sequence
35 * layout's element count. In other words this layout:
36 *
37 * {@snippet lang=java :
38 * MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
39 * }
40 *
41 * is equivalent to the following layout:
42 *
43 * {@snippet lang=java :
44 * MemoryLayout.structLayout(
45 * ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
46 * ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
47 * ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
48 * }
49 *
50 * @implSpec
51 * This class is immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
52 *
53 * @since 19
54 */
55 @PreviewFeature(feature=PreviewFeature.Feature.FOREIGN)
56 public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayoutImpl {
57
58
59 /**
60 * {@return the element layout of this sequence layout}
61 */
62 MemoryLayout elementLayout();
63
64 /**
65 * {@return the element count of this sequence layout}
66 */
67 long elementCount();
68
69 /**
70 * {@return a sequence layout with the same characteristics of this layout, but with the given element count}
71 * @param elementCount the new element count.
72 * @throws IllegalArgumentException if {@code elementCount} is negative.
73 * @throws IllegalArgumentException if {@code elementLayout.bitSize() * elementCount} overflows.
74 */
75 SequenceLayout withElementCount(long elementCount);
76
77 /**
78 * Rearranges the elements in this sequence layout into a multi-dimensional sequence layout.
79 * The resulting layout is a sequence layout where element layouts in the {@linkplain #flatten() flattened projection}
80 * of this sequence layout are rearranged into one or more nested sequence layouts
81 * according to the provided element counts. This transformation preserves the layout size;
82 * that is, multiplying the provided element counts must yield the same element count
83 * as the flattened projection of this sequence layout.
84 * <p>
85 * For instance, given a sequence layout of the kind:
86 * {@snippet lang=java :
87 * var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
88 * }
89 * calling {@code seq.reshape(2, 6)} will yield the following sequence layout:
90 * {@snippet lang=java :
91 * var reshapeSeq = MemoryLayout.sequenceLayout(2, MemoryLayout.sequenceLayout(6, ValueLayout.JAVA_INT));
92 * }
93 * <p>
94 * If one of the provided element count is the special value {@code -1}, then the element
95 * count in that position will be inferred from the remaining element counts and the
96 * element count of the flattened projection of this layout. For instance, a layout equivalent to
97 * the above {@code reshapeSeq} can also be computed in the following ways:
98 * {@snippet lang=java :
99 * var reshapeSeqImplicit1 = seq.reshape(-1, 6);
100 * var reshapeSeqImplicit2 = seq.reshape(2, -1);
101 * }
102 * @param elementCounts an array of element counts, of which at most one can be {@code -1}.
103 * @return a sequence layout where element layouts in the {@linkplain #flatten() flattened projection} of this
104 * sequence layout (see {@link #flatten()}) are re-arranged into one or more nested sequence layouts.
105 * @throws IllegalArgumentException if two or more element counts are set to {@code -1}, or if one
106 * or more element count is {@code <= 0} (but other than {@code -1}) or, if, after any required inference,
107 * multiplying the element counts does not yield the same element count as the flattened projection of this
108 * sequence layout.
109 */
110 SequenceLayout reshape(long... elementCounts);
111
112 /**
113 * Returns a flattened sequence layout. The element layout of the returned sequence layout
114 * is the first non-sequence layout found by inspecting (recursively, if needed) the element layout of this sequence layout:
115 * {@snippet lang=java :
116 * MemoryLayout flatElementLayout(SequenceLayout sequenceLayout) {
117 * return switch (sequenceLayout.elementLayout()) {
118 * case SequenceLayout nestedSequenceLayout -> flatElementLayout(nestedSequenceLayout);
119 * case MemoryLayout layout -> layout;
120 * };
121 * }
122 * }
123 * <p>
124 * This transformation preserves the layout size; nested sequence layout in this sequence layout will
125 * be dropped and their element counts will be incorporated into that of the returned sequence layout.
126 * For instance, given a sequence layout of the kind:
127 * {@snippet lang=java :
128 * var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
129 * }
130 * calling {@code seq.flatten()} will yield the following sequence layout:
131 * {@snippet lang=java :
132 * var flattenedSeq = MemoryLayout.sequenceLayout(12, ValueLayout.JAVA_INT);
133 * }
134 * @return a sequence layout with the same size as this layout (but, possibly, with different
135 * element count), whose element layout is not a sequence layout.
136 */
137 SequenceLayout flatten();
138
139 /**
140 * {@inheritDoc}
141 */
142 @Override
143 SequenceLayout withName(String name);
144
145 /**
146 * {@inheritDoc}
147 */
148 @Override
149 MemoryLayout withoutName();
150
151 /**
152 * {@inheritDoc}
153 * @throws IllegalArgumentException {@inheritDoc}
154 * @throws IllegalArgumentException if {@code byteAlignment < elementLayout().byteAlignment()}.
155 */
156 SequenceLayout withByteAlignment(long byteAlignment);
157 }