1 /*
2 * Copyright (c) 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.ValueLayouts;
29 import jdk.internal.reflect.CallerSensitive;
30
31 import java.lang.foreign.Linker.Option;
32 import java.lang.invoke.MethodHandle;
33 import java.nio.ByteOrder;
34 import java.util.Optional;
35
36 /**
37 * A value layout used to model the address of some region of memory. The carrier associated with an address layout is
38 * {@code MemorySegment.class}. The size and alignment of an address layout are platform-dependent
39 * (e.g. on a 64-bit platform, the size and alignment of an address layout are set to 8 bytes).
40 * <p>
41 * An address layout may optionally feature a {@linkplain #targetLayout() target layout}. An address layout with
42 * target layout {@code T} can be used to model the address of a region of memory whose layout is {@code T}.
43 * For instance, an address layout with target layout {@link ValueLayout#JAVA_INT} can be used to model the address
44 * of a region of memory that is 4 bytes long. Specifying a target layout can be useful in the following situations:
45 * <ul>
46 * <li>When accessing a memory segment that has been obtained by reading an address from another
47 * memory segment, e.g. using {@link MemorySegment#getAtIndex(AddressLayout, long)};</li>
48 * <li>When creating a downcall method handle, using {@link Linker#downcallHandle(FunctionDescriptor, Option...)};
49 * <li>When creating an upcall stub, using {@link Linker#upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...)}.
50 * </ul>
51 *
52 * @implSpec
53 * This class is immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
54 *
55 * @see #ADDRESS
56 * @see #ADDRESS_UNALIGNED
57 * @since 22
58 */
59 public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.OfAddressImpl {
60
61 /**
62 * {@inheritDoc}
63 */
64 @Override
65 AddressLayout withName(String name);
66
67 /**
68 * {@inheritDoc}
69 */
70 @Override
71 AddressLayout withoutName();
72
73 /**
74 * {@inheritDoc}
75 */
76 @Override
77 AddressLayout withByteAlignment(long byteAlignment);
78
79 /**
80 * {@inheritDoc}
81 */
82 @Override
83 AddressLayout withOrder(ByteOrder order);
84
85 /**
86 * Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
87 * but associated with the specified target layout. The returned address layout allows raw addresses to be accessed
88 * as {@linkplain MemorySegment memory segments} whose size is set to the size of the specified layout. Moreover,
89 * if the accessed raw address is not compatible with the alignment constraint in the provided layout,
90 * {@linkplain IllegalArgumentException} will be thrown.
91 * @apiNote
92 * This method can also be used to create an address layout which, when used, creates native memory
93 * segments with maximal size (e.g. {@linkplain Long#MAX_VALUE}). This can be done by using a target sequence
94 * layout with unspecified size, as follows:
95 * {@snippet lang = java:
96 * AddressLayout addressLayout = ...
97 * AddressLayout unboundedLayout = addressLayout.withTargetLayout(
98 * MemoryLayout.sequenceLayout(Long.MAX_VALUE, ValueLayout.JAVA_BYTE));
99 *}
100 * <p>
101 * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
102 * Restricted methods are unsafe, and, if used incorrectly, their use might crash
103 * the JVM or, worse, silently result in memory corruption.
104 *
105 * @param layout the target layout.
106 * @return an address layout with same characteristics as this layout, but with the provided target layout.
107 * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
108 * @see #targetLayout()
109 */
110 @CallerSensitive
111 AddressLayout withTargetLayout(MemoryLayout layout);
112
113 /**
114 * Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
115 * but with no target layout.
116 *
117 * @apiNote This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
118 *
119 * @return an address layout with same characteristics as this layout, but with no target layout.
120 * @see #targetLayout()
121 */
122 AddressLayout withoutTargetLayout();
123
124 /**
125 * {@return the target layout associated with this address layout (if any)}.
126 */
127 Optional<MemoryLayout> targetLayout();
128
129 }