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 java.lang.invoke.VarHandle;
29 import java.nio.ByteOrder;
30 import jdk.internal.foreign.layout.ValueLayouts;
31
32 /**
33 * A layout that models values of basic data types. Examples of values modelled by a value layout are
34 * <em>integral</em> values (either signed or unsigned), <em>floating-point</em> values and
35 * <em>address</em> values.
36 * <p>
37 * Each value layout has a size, an alignment (both expressed in bytes),
38 * a {@linkplain ByteOrder byte order}, and a <em>carrier</em>, that is, the Java type that should be used when
39 * {@linkplain MemorySegment#get(OfInt, long) accessing} a region of memory using the value layout.
40 * <p>
41 * This class defines useful value layout constants for Java primitive types and addresses.
42 * @apiNote Some characteristics of the Java layout constants are platform-dependent. For instance, the byte order of
43 * these constants is set to the {@linkplain ByteOrder#nativeOrder() native byte order}, thus making it easy to work
44 * with other APIs, such as arrays and {@link java.nio.ByteBuffer}. Moreover, the alignment constraint of
45 * {@link ValueLayout#JAVA_LONG} and {@link ValueLayout#JAVA_DOUBLE} is set to 8 bytes on 64-bit platforms, but only to
46 * 4 bytes on 32-bit platforms.
47 *
48 * @implSpec implementing classes and subclasses are immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
49 *
50 * @sealedGraph
51 * @since 22
52 */
53 public sealed interface ValueLayout extends MemoryLayout permits
54 ValueLayout.OfBoolean, ValueLayout.OfByte, ValueLayout.OfChar, ValueLayout.OfShort, ValueLayout.OfInt,
55 ValueLayout.OfFloat, ValueLayout.OfLong, ValueLayout.OfDouble, AddressLayout {
56
57 /**
58 * {@return the value's byte order}
59 */
60 ByteOrder order();
61
62 /**
63 * {@return a value layout with the same characteristics as this layout, but with the given byte order}
64 *
65 * @param order the desired byte order.
66 */
67 ValueLayout withOrder(ByteOrder order);
68
69 /**
70 * {@inheritDoc}
71 */
72 @Override
73 ValueLayout withoutName();
74
75 /**
76 * {@return the carrier associated with this value layout}
77 */
78 Class<?> carrier();
79
80 /**
81 * {@inheritDoc}
82 */
83 @Override
84 ValueLayout withName(String name);
85
86 /**
87 * {@inheritDoc}
88 *
89 * @throws IllegalArgumentException {@inheritDoc}
90 */
91 @Override
92 ValueLayout withByteAlignment(long byteAlignment);
93
94 /**
95 * {@return a var handle which can be used to access values described by this value layout, in a given memory segment.}
96 * <p>
97 * The returned var handle's {@linkplain VarHandle#varType() var type} is the {@linkplain ValueLayout#carrier() carrier type} of
98 * this value layout, and the list of coordinate types is {@code (MemorySegment, long)}, where the memory segment coordinate
99 * corresponds to the memory segment to be accessed, and the {@code long} coordinate corresponds to the byte offset
100 * into the accessed memory segment at which the access occurs.
101 * <p>
102 * The returned var handle checks that accesses are aligned according to this value layout's
103 * {@linkplain MemoryLayout#byteAlignment() alignment constraint}.
104 *
105 * @apiNote This method is similar, but more efficient, than calling {@code MemoryLayout#varHandle(PathElement...)}
106 * with an empty path element array, as it avoids the creation of the var args array.
107 *
108 * @apiNote The returned var handle features certain <a href="MemoryLayout.html#access-mode-restrictions">access mode
109 * restrictions</a> common to all memory access var handles derived from memory layouts.
110 *
111 * @see MemoryLayout#varHandle(PathElement...)
112 */
113 VarHandle varHandle();
114
115 /**
116 * A value layout whose carrier is {@code boolean.class}.
117 *
118 * @see #JAVA_BOOLEAN
119 * @since 22
120 */
121 sealed interface OfBoolean extends ValueLayout permits ValueLayouts.OfBooleanImpl {
122
123 /**
124 * {@inheritDoc}
125 */
126 @Override
127 OfBoolean withName(String name);
128
129 /**
130 * {@inheritDoc}
131 */
132 @Override
133 OfBoolean withoutName();
134
135 /**
136 * {@inheritDoc}
137 * @throws IllegalArgumentException {@inheritDoc}
138 */
139 @Override
140 OfBoolean withByteAlignment(long byteAlignment);
141
142 /**
143 * {@inheritDoc}
144 */
145 @Override
146 OfBoolean withOrder(ByteOrder order);
147
148 }
149
150 /**
151 * A value layout whose carrier is {@code byte.class}.
152 *
153 * @see #JAVA_BYTE
154 * @since 22
155 */
156 sealed interface OfByte extends ValueLayout permits ValueLayouts.OfByteImpl {
157
158 /**
159 * {@inheritDoc}
160 */
161 @Override
162 OfByte withName(String name);
163
164 /**
165 * {@inheritDoc}
166 */
167 @Override
168 OfByte withoutName();
169
170 /**
171 * {@inheritDoc}
172 * @throws IllegalArgumentException {@inheritDoc}
173 */
174 @Override
175 OfByte withByteAlignment(long byteAlignment);
176
177 /**
178 * {@inheritDoc}
179 */
180 @Override
181 OfByte withOrder(ByteOrder order);
182
183 }
184
185 /**
186 * A value layout whose carrier is {@code char.class}.
187 *
188 * @see #JAVA_CHAR
189 * @see #JAVA_CHAR_UNALIGNED
190 * @since 22
191 */
192 sealed interface OfChar extends ValueLayout permits ValueLayouts.OfCharImpl {
193
194 /**
195 * {@inheritDoc}
196 */
197 @Override
198 OfChar withName(String name);
199
200 /**
201 * {@inheritDoc}
202 */
203 @Override
204 OfChar withoutName();
205
206 /**
207 * {@inheritDoc}
208 * @throws IllegalArgumentException {@inheritDoc}
209 */
210 @Override
211 OfChar withByteAlignment(long byteAlignment);
212
213 /**
214 * {@inheritDoc}
215 */
216 @Override
217 OfChar withOrder(ByteOrder order);
218
219 }
220
221 /**
222 * A value layout whose carrier is {@code short.class}.
223 *
224 * @see #JAVA_SHORT
225 * @see #JAVA_SHORT_UNALIGNED
226 * @since 22
227 */
228 sealed interface OfShort extends ValueLayout permits ValueLayouts.OfShortImpl {
229
230 /**
231 * {@inheritDoc}
232 */
233 @Override
234 OfShort withName(String name);
235
236 /**
237 * {@inheritDoc}
238 */
239 @Override
240 OfShort withoutName();
241
242 /**
243 * {@inheritDoc}
244 * @throws IllegalArgumentException {@inheritDoc}
245 */
246 @Override
247 OfShort withByteAlignment(long byteAlignment);
248
249 /**
250 * {@inheritDoc}
251 */
252 @Override
253 OfShort withOrder(ByteOrder order);
254
255 }
256
257 /**
258 * A value layout whose carrier is {@code int.class}.
259 *
260 * @see #JAVA_INT
261 * @see #JAVA_INT_UNALIGNED
262 * @since 22
263 */
264 sealed interface OfInt extends ValueLayout permits ValueLayouts.OfIntImpl {
265
266 /**
267 * {@inheritDoc}
268 */
269 @Override
270 OfInt withName(String name);
271
272 /**
273 * {@inheritDoc}
274 */
275 @Override
276 OfInt withoutName();
277
278 /**
279 * {@inheritDoc}
280 * @throws IllegalArgumentException {@inheritDoc}
281 */
282 @Override
283 OfInt withByteAlignment(long byteAlignment);
284
285 /**
286 * {@inheritDoc}
287 */
288 @Override
289 OfInt withOrder(ByteOrder order);
290
291 }
292
293 /**
294 * A value layout whose carrier is {@code float.class}.
295 *
296 * @see #JAVA_FLOAT
297 * @see #JAVA_FLOAT_UNALIGNED
298 * @since 22
299 */
300 sealed interface OfFloat extends ValueLayout permits ValueLayouts.OfFloatImpl {
301
302 /**
303 * {@inheritDoc}
304 */
305 @Override
306 OfFloat withName(String name);
307
308 /**
309 * {@inheritDoc}
310 */
311 @Override
312 OfFloat withoutName();
313
314 /**
315 * {@inheritDoc}
316 */
317 @Override
318 OfFloat withByteAlignment(long byteAlignment);
319
320 /**
321 * {@inheritDoc}
322 */
323 @Override
324 OfFloat withOrder(ByteOrder order);
325
326 }
327
328 /**
329 * A value layout whose carrier is {@code long.class}.
330 *
331 * @see #JAVA_LONG
332 * @see #JAVA_LONG_UNALIGNED
333 * @since 22
334 */
335 sealed interface OfLong extends ValueLayout permits ValueLayouts.OfLongImpl {
336
337 /**
338 * {@inheritDoc}
339 */
340 @Override
341 OfLong withName(String name);
342
343 /**
344 * {@inheritDoc}
345 */
346 @Override
347 OfLong withoutName();
348
349 /**
350 * {@inheritDoc}
351 * @throws IllegalArgumentException {@inheritDoc}
352 */
353 @Override
354 OfLong withByteAlignment(long byteAlignment);
355
356 /**
357 * {@inheritDoc}
358 */
359 @Override
360 OfLong withOrder(ByteOrder order);
361
362 }
363
364 /**
365 * A value layout whose carrier is {@code double.class}.
366 *
367 * @see #JAVA_DOUBLE
368 * @see #JAVA_DOUBLE_UNALIGNED
369 * @since 22
370 */
371 sealed interface OfDouble extends ValueLayout permits ValueLayouts.OfDoubleImpl {
372
373 /**
374 * {@inheritDoc}
375 */
376 @Override
377 OfDouble withName(String name);
378
379 /**
380 * {@inheritDoc}
381 */
382 @Override
383 OfDouble withoutName();
384
385 /**
386 * {@inheritDoc}
387 * @throws IllegalArgumentException {@inheritDoc}
388 */
389 @Override
390 OfDouble withByteAlignment(long byteAlignment);
391
392 /**
393 * {@inheritDoc}
394 */
395 @Override
396 OfDouble withOrder(ByteOrder order);
397
398 }
399
400 /**
401 * An address layout constant whose size is the same as that of a machine address ({@code size_t}),
402 * byte alignment set to {@code sizeof(size_t)}, byte order set to {@link ByteOrder#nativeOrder()}.
403 */
404 AddressLayout ADDRESS = ValueLayouts.OfAddressImpl.of(ByteOrder.nativeOrder());
405
406 /**
407 * A value layout constant whose size is the same as that of a Java {@code byte},
408 * byte alignment set to 1, and byte order set to {@link ByteOrder#nativeOrder()}.
409 */
410 OfByte JAVA_BYTE = ValueLayouts.OfByteImpl.of(ByteOrder.nativeOrder());
411
412 /**
413 * A value layout constant whose size is the same as that of a Java {@code boolean},
414 * byte alignment set to 1, and byte order set to {@link ByteOrder#nativeOrder()}.
415 */
416 OfBoolean JAVA_BOOLEAN = ValueLayouts.OfBooleanImpl.of(ByteOrder.nativeOrder());
417
418 /**
419 * A value layout constant whose size is the same as that of a Java {@code char},
420 * byte alignment set to 2, and byte order set to {@link ByteOrder#nativeOrder()}.
421 */
422 OfChar JAVA_CHAR = ValueLayouts.OfCharImpl.of(ByteOrder.nativeOrder());
423
424 /**
425 * A value layout constant whose size is the same as that of a Java {@code short},
426 * byte alignment set to 2, and byte order set to {@link ByteOrder#nativeOrder()}.
427 */
428 OfShort JAVA_SHORT = ValueLayouts.OfShortImpl.of(ByteOrder.nativeOrder());
429
430 /**
431 * A value layout constant whose size is the same as that of a Java {@code int},
432 * byte alignment set to 4, and byte order set to {@link ByteOrder#nativeOrder()}.
433 */
434 OfInt JAVA_INT = ValueLayouts.OfIntImpl.of(ByteOrder.nativeOrder());
435
436 /**
437 * A value layout constant whose size is the same as that of a Java {@code long},
438 * (platform-dependent) byte alignment set to {@code ADDRESS.byteSize()},
439 * and byte order set to {@link ByteOrder#nativeOrder()}.
440 */
441 OfLong JAVA_LONG = ValueLayouts.OfLongImpl.of(ByteOrder.nativeOrder());
442
443 /**
444 * A value layout constant whose size is the same as that of a Java {@code float},
445 * byte alignment set to 4, and byte order set to {@link ByteOrder#nativeOrder()}.
446 */
447 OfFloat JAVA_FLOAT = ValueLayouts.OfFloatImpl.of(ByteOrder.nativeOrder());
448
449 /**
450 * A value layout constant whose size is the same as that of a Java {@code double},
451 * (platform-dependent) byte alignment set to {@code ADDRESS.byteSize()},
452 * and byte order set to {@link ByteOrder#nativeOrder()}.
453 */
454 OfDouble JAVA_DOUBLE = ValueLayouts.OfDoubleImpl.of(ByteOrder.nativeOrder());
455
456 /**
457 * An unaligned address layout constant whose size is the same as that of a machine address ({@code size_t}),
458 * and byte order set to {@link ByteOrder#nativeOrder()}.
459 * Equivalent to the following code:
460 * {@snippet lang=java :
461 * ADDRESS.withByteAlignment(1);
462 * }
463 * @apiNote Care should be taken when using unaligned value layouts as they may induce
464 * performance and portability issues.
465 */
466 AddressLayout ADDRESS_UNALIGNED = ADDRESS.withByteAlignment(1);
467
468 /**
469 * An unaligned value layout constant whose size is the same as that of a Java {@code char}
470 * and byte order set to {@link ByteOrder#nativeOrder()}.
471 * Equivalent to the following code:
472 * {@snippet lang=java :
473 * JAVA_CHAR.withByteAlignment(1);
474 * }
475 * @apiNote Care should be taken when using unaligned value layouts as they may induce
476 * performance and portability issues.
477 */
478 OfChar JAVA_CHAR_UNALIGNED = JAVA_CHAR.withByteAlignment(1);
479
480 /**
481 * An unaligned value layout constant whose size is the same as that of a Java {@code short}
482 * and byte order set to {@link ByteOrder#nativeOrder()}.
483 * Equivalent to the following code:
484 * {@snippet lang=java :
485 * JAVA_SHORT.withByteAlignment(1);
486 * }
487 * @apiNote Care should be taken when using unaligned value layouts as they may induce
488 * performance and portability issues.
489 */
490 OfShort JAVA_SHORT_UNALIGNED = JAVA_SHORT.withByteAlignment(1);
491
492 /**
493 * An unaligned value layout constant whose size is the same as that of a Java {@code int}
494 * and byte order set to {@link ByteOrder#nativeOrder()}.
495 * Equivalent to the following code:
496 * {@snippet lang=java :
497 * JAVA_INT.withByteAlignment(1);
498 * }
499 * @apiNote Care should be taken when using unaligned value layouts as they may induce
500 * performance and portability issues.
501 */
502 OfInt JAVA_INT_UNALIGNED = JAVA_INT.withByteAlignment(1);
503
504 /**
505 * An unaligned value layout constant whose size is the same as that of a Java {@code long}
506 * and byte order set to {@link ByteOrder#nativeOrder()}.
507 * Equivalent to the following code:
508 * {@snippet lang=java :
509 * JAVA_LONG.withByteAlignment(1);
510 * }
511 * @apiNote Care should be taken when using unaligned value layouts as they may induce
512 * performance and portability issues.
513 */
514 OfLong JAVA_LONG_UNALIGNED = JAVA_LONG.withByteAlignment(1);
515
516 /**
517 * An unaligned value layout constant whose size is the same as that of a Java {@code float}
518 * and byte order set to {@link ByteOrder#nativeOrder()}.
519 * Equivalent to the following code:
520 * {@snippet lang=java :
521 * JAVA_FLOAT.withByteAlignment(1);
522 * }
523 * @apiNote Care should be taken when using unaligned value layouts as they may induce
524 * performance and portability issues.
525 */
526 OfFloat JAVA_FLOAT_UNALIGNED = JAVA_FLOAT.withByteAlignment(1);
527
528 /**
529 * An unaligned value layout constant whose size is the same as that of a Java {@code double}
530 * and byte order set to {@link ByteOrder#nativeOrder()}.
531 * Equivalent to the following code:
532 * {@snippet lang=java :
533 * JAVA_DOUBLE.withByteAlignment(1);
534 * }
535 * @apiNote Care should be taken when using unaligned value layouts as they may induce
536 * performance and portability issues.
537 */
538 OfDouble JAVA_DOUBLE_UNALIGNED = JAVA_DOUBLE.withByteAlignment(1);
539
540 }