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 /**
27 * <p>Provides low-level access to memory and functions outside the Java runtime.
28 *
29 * <h2 id="fma">Foreign memory access</h2>
30 *
31 * <p>
32 * The main abstraction introduced to support foreign memory access is {@link java.lang.foreign.MemorySegment}, which
33 * models a contiguous region of memory, residing either inside or outside the Java heap. Memory segments are
34 * typically allocated using an {@link java.lang.foreign.Arena}, which controls the lifetime of the regions of memory
35 * backing the segments it allocates. The contents of a memory segment can be described using a
36 * {@link java.lang.foreign.MemoryLayout memory layout}, which provides basic operations to query sizes, offsets and
37 * alignment constraints. Memory layouts also provide an alternate, more abstract way, to
38 * <a href=MemorySegment.html#segment-deref>access memory segments</a> using
39 * {@linkplain java.lang.foreign.MemoryLayout#varHandle(java.lang.foreign.MemoryLayout.PathElement...) var handles},
40 * which can be computed using <a href="MemoryLayout.html#layout-paths"><em>layout paths</em></a>.
41 *
42 * For example, to allocate an off-heap region of memory big enough to hold 10 values of the primitive type {@code int},
43 * and fill it with values ranging from {@code 0} to {@code 9}, we can use the following code:
44 *
45 * {@snippet lang = java:
46 * try (Arena arena = Arena.ofConfined()) {
47 * MemorySegment segment = arena.allocate(10 * 4);
48 * for (int i = 0 ; i < 10 ; i++) {
49 * segment.setAtIndex(ValueLayout.JAVA_INT, i, i);
50 * }
51 * }
52 * }
53 *
54 * This code creates a <em>native</em> memory segment, that is, a memory segment backed by
55 * off-heap memory; the size of the segment is 40 bytes, enough to store 10 values of the primitive type {@code int}.
56 * The native segment is allocated using a {@linkplain java.lang.foreign.Arena#ofConfined() confined arena}.
57 * As such, access to the native segment is restricted to the current thread (the thread that created the arena).
58 * Moreover, when the arena is closed, the native segment is invalidated, and its backing region of memory is
59 * deallocated. Note the use of the <em>try-with-resources</em> construct: this idiom ensures that the off-heap region
60 * of memory backing the native segment will be released at the end of the block, according to the semantics described
61 * in Section {@jls 14.20.3} of <cite>The Java Language Specification</cite>.
62 * <p>
63 * Memory segments provide strong safety guarantees when it comes to memory access. First, when accessing a memory segment,
64 * the access coordinates are validated (upon access), to make sure that access does not occur at any address which resides
65 * <em>outside</em> the boundaries of the memory segment used by the access operation. We call this guarantee <em>spatial safety</em>;
66 * in other words, access to memory segments is bounds-checked, in the same way as array access is, as described in
67 * Section {@jls 15.10.4} of <cite>The Java Language Specification</cite>.
68 * <p>
69 * Additionally, to prevent a region of memory from being accessed <em>after</em> it has been deallocated
70 * (i.e. <em>use-after-free</em>), a segment is also validated (upon access) to make sure that the arena from which it
71 * has been obtained has not been closed. We call this guarantee <em>temporal safety</em>.
72 * <p>
73 * Together, spatial and temporal safety ensure that each memory access operation either succeeds - and accesses a valid
74 * location within the region of memory backing the memory segment - or fails.
75 *
76 * <h2 id="ffa">Foreign function access</h2>
77 * The key abstractions introduced to support foreign function access are {@link java.lang.foreign.SymbolLookup},
78 * {@link java.lang.foreign.FunctionDescriptor} and {@link java.lang.foreign.Linker}. The first is used to look up symbols
79 * inside libraries; the second is used to model the signature of foreign functions, while the third is used
80 * to link foreign functions as {@link java.lang.invoke.MethodHandle} instances,
81 * so that clients can perform foreign function calls directly in Java, without the need for intermediate layers of C/C++
82 * code (as is the case with the <a href="{@docRoot}/../specs/jni/index.html">Java Native Interface (JNI)</a>).
83 * <p>
84 * For example, to compute the length of a string using the C standard library function {@code strlen} on a Linux/x64 platform,
85 * we can use the following code:
86 *
87 * {@snippet lang = java:
88 * Linker linker = Linker.nativeLinker();
89 * SymbolLookup stdlib = linker.defaultLookup();
90 * MethodHandle strlen = linker.downcallHandle(
91 * stdlib.find("strlen").orElseThrow(),
92 * FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
93 * );
94 *
95 * try (Arena arena = Arena.ofConfined()) {
96 * MemorySegment cString = arena.allocateUtf8String("Hello");
97 * long len = (long)strlen.invokeExact(cString); // 5
98 * }
99 *}
100 *
101 * Here, we obtain a {@linkplain java.lang.foreign.Linker#nativeLinker() native linker} and we use it
102 * to {@linkplain java.lang.foreign.SymbolLookup#find(java.lang.String) look up} the {@code strlen} function in the
103 * standard C library; a <em>downcall method handle</em> targeting said function is subsequently
104 * {@linkplain java.lang.foreign.Linker#downcallHandle(FunctionDescriptor, Linker.Option...) obtained}.
105 * To complete the linking successfully, we must provide a {@link java.lang.foreign.FunctionDescriptor} instance,
106 * describing the signature of the {@code strlen} function.
107 * From this information, the linker will uniquely determine the sequence of steps which will turn
108 * the method handle invocation (here performed using {@link java.lang.invoke.MethodHandle#invokeExact(java.lang.Object...)})
109 * into a foreign function call, according to the rules specified by the ABI of the underlying platform.
110 * The {@link java.lang.foreign.Arena} class also provides many useful methods for
111 * interacting with foreign code, such as
112 * {@linkplain java.lang.foreign.SegmentAllocator#allocateUtf8String(java.lang.String) converting} Java strings into
113 * zero-terminated, UTF-8 strings, as demonstrated in the above example.
114 *
115 * <h2 id="restricted">Restricted methods</h2>
116 * Some methods in this package are considered <em>restricted</em>. Restricted methods are typically used to bind native
117 * foreign data and/or functions to first-class Java API elements which can then be used directly by clients. For instance
118 * the restricted method {@link java.lang.foreign.MemorySegment#reinterpret(long)}
119 * can be used to create a fresh segment with the same address and temporal bounds,
120 * but with the provided size. This can be useful to resize memory segments obtained when interacting with native functions.
121 * <p>
122 * Binding foreign data and/or functions is generally unsafe and, if done incorrectly, can result in VM crashes,
123 * or memory corruption when the bound Java API element is accessed. For instance, incorrectly resizing a native
124 * memory sgement using {@link java.lang.foreign.MemorySegment#reinterpret(long)} can lead to a JVM crash, or, worse,
125 * lead to silent memory corruption when attempting to access the resized segment. For these reasons, it is crucial for
126 * code that calls a restricted method to never pass arguments that might cause incorrect binding of foreign data and/or
127 * functions to a Java API.
128 * <p>
129 * Given the potential danger of restricted methods, the Java runtime issues a warning on the standard error stream
130 * every time a restricted method is invoked. Such warnings can be disabled by granting access to restricted methods
131 * to selected modules. This can be done either via implementation-specific command line options, or programmatically, e.g. by calling
132 * {@link java.lang.ModuleLayer.Controller#enableNativeAccess(java.lang.Module)}.
133 * <p>
134 * For every class in this package, unless specified otherwise, any method arguments of reference
135 * type must not be null, and any null argument will elicit a {@code NullPointerException}. This fact is not individually
136 * documented for methods of this API.
137 *
138 * @apiNote Usual memory model guarantees, for example stated in {@jls 6.6} and {@jls 10.4}, do not apply
139 * when accessing native memory segments as these segments are backed by off-heap regions of memory.
140 *
141 * @implNote
142 * In the reference implementation, access to restricted methods can be granted to specific modules using the command line option
143 * {@code --enable-native-access=M1,M2, ... Mn}, where {@code M1}, {@code M2}, {@code ... Mn} are module names
144 * (for the unnamed module, the special value {@code ALL-UNNAMED} can be used). If this option is specified, access to
145 * restricted methods is only granted to the modules listed by that option. If this option is not specified,
146 * access to restricted methods is enabled for all modules, but access to restricted methods will result in runtime warnings.
147 *
148 * @spec jni/index.html Java Native Interface Specification
149 *
150 * @since 19
151 */
152 @PreviewFeature(feature=PreviewFeature.Feature.FOREIGN)
153 package java.lang.foreign;
154
155 import jdk.internal.javac.PreviewFeature;