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