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.abi.AbstractLinker;
29 import jdk.internal.foreign.abi.LinkerOptions;
30 import jdk.internal.foreign.abi.CapturableState;
31 import jdk.internal.foreign.abi.SharedUtils;
32 import jdk.internal.javac.PreviewFeature;
33 import jdk.internal.reflect.CallerSensitive;
34 import jdk.internal.reflect.Reflection;
35
36 import java.lang.invoke.MethodHandle;
37 import java.nio.ByteOrder;
38 import java.util.Objects;
39 import java.util.Optional;
40 import java.util.Set;
41 import java.util.function.Consumer;
42 import java.util.stream.Collectors;
43 import java.util.stream.Stream;
44
45 /**
46 * A linker provides access to foreign functions from Java code, and access to Java code from foreign functions.
47 * <p>
48 * Foreign functions typically reside in libraries that can be loaded on-demand. Each library conforms to
49 * a specific ABI (Application Binary Interface). An ABI is a set of calling conventions and data types associated with
50 * the compiler, OS, and processor where the library was built. For example, a C compiler on Linux/x64 usually
51 * builds libraries that conform to the SystemV ABI.
52 * <p>
53 * A linker has detailed knowledge of the calling conventions and data types used by a specific ABI.
54 * For any library which conforms to that ABI, the linker can mediate between Java code running
55 * in the JVM and foreign functions in the library. In particular:
56 * <ul>
57 * <li>A linker allows Java code to link against foreign functions, via
58 * {@linkplain #downcallHandle(MemorySegment, FunctionDescriptor, Option...) downcall method handles}; and</li>
59 * <li>A linker allows foreign functions to call Java method handles,
60 * via the generation of {@linkplain #upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...) upcall stubs}.</li>
61 * </ul>
62 * In addition, a linker provides a way to look up foreign functions in libraries that conform to the ABI. Each linker
63 * chooses a set of libraries that are commonly used on the OS and processor combination associated with the ABI.
64 * For example, a linker for Linux/x64 might choose two libraries: {@code libc} and {@code libm}. The functions in these
65 * libraries are exposed via a {@linkplain #defaultLookup() symbol lookup}.
66 *
67 * <h2 id="native-linker">Calling native functions</h2>
68 *
69 * The {@linkplain #nativeLinker() native linker} can be used to link against functions
70 * defined in C libraries (native functions). Suppose we wish to downcall from Java to the {@code strlen} function
71 * defined in the standard C library:
72 * {@snippet lang = c:
73 * size_t strlen(const char *s);
74 * }
75 * A downcall method handle that exposes {@code strlen} is obtained, using the native linker, as follows:
76 *
77 * {@snippet lang = java:
78 * Linker linker = Linker.nativeLinker();
79 * MethodHandle strlen = linker.downcallHandle(
80 * linker.defaultLookup().find("strlen").orElseThrow(),
81 * FunctionDescriptor.of(JAVA_LONG, ADDRESS)
82 * );
83 * }
84 *
85 * Note how the native linker also provides access, via its {@linkplain #defaultLookup() default lookup},
86 * to the native functions defined by the C libraries loaded with the Java runtime. Above, the default lookup
87 * is used to search the address of the {@code strlen} native function. That address is then passed, along with
88 * a <em>platform-dependent description</em> of the signature of the function expressed as a
89 * {@link FunctionDescriptor} (more on that below) to the native linker's
90 * {@link #downcallHandle(MemorySegment, FunctionDescriptor, Option...)} method.
91 * The obtained downcall method handle is then invoked as follows:
92 *
93 * {@snippet lang = java:
94 * try (Arena arena = Arena.ofConfined()) {
95 * MemorySegment str = arena.allocateUtf8String("Hello");
96 * long len = (long) strlen.invokeExact(str); // 5
97 * }
98 * }
99 * <h3 id="describing-c-sigs">Describing C signatures</h3>
100 *
101 * When interacting with the native linker, clients must provide a platform-dependent description of the signature
102 * of the C function they wish to link against. This description, a {@link FunctionDescriptor function descriptor},
103 * defines the layouts associated with the parameter types and return type (if any) of the C function.
104 * <p>
105 * Scalar C types such as {@code bool}, {@code int} are modelled as {@linkplain ValueLayout value layouts}
106 * of a suitable carrier. The mapping between a scalar type and its corresponding layout is dependent on the ABI
107 * implemented by the native linker. For instance, the C type {@code long} maps to the layout constant
108 * {@link ValueLayout#JAVA_LONG} on Linux/x64, but maps to the layout constant {@link ValueLayout#JAVA_INT} on
109 * Windows/x64. Similarly, the C type {@code size_t} maps to the layout constant {@link ValueLayout#JAVA_LONG}
110 * on 64-bit platforms, but maps to the layout constant {@link ValueLayout#JAVA_INT} on 32-bit platforms.
111 * <p>
112 * Composite types are modelled as {@linkplain GroupLayout group layouts}. More specifically, a C {@code struct} type
113 * maps to a {@linkplain StructLayout struct layout}, whereas a C {@code union} type maps to a {@link UnionLayout union
114 * layout}. When defining a struct or union layout, clients must pay attention to the size and alignment constraint
115 * of the corresponding composite type definition in C. For instance, padding between two struct fields
116 * must be modelled explicitly, by adding an adequately sized {@linkplain PaddingLayout padding layout} member
117 * to the resulting struct layout.
118 * <p>
119 * Finally, pointer types such as {@code int**} and {@code int(*)(size_t*, size_t*)} are modelled as
120 * {@linkplain AddressLayout address layouts}. When the spatial bounds of the pointer type are known statically,
121 * the address layout can be associated with a {@linkplain AddressLayout#targetLayout() target layout}. For instance,
122 * a pointer that is known to point to a C {@code int[2]} array can be modelled as an address layout whose
123 * target layout is a sequence layout whose element count is 2, and whose element type is {@link ValueLayout#JAVA_INT}.
124 * <p>
125 * The following table shows some examples of how C types are modelled in Linux/x64:
126 *
127 * <blockquote><table class="plain">
128 * <caption style="display:none">Mapping C types</caption>
129 * <thead>
130 * <tr>
131 * <th scope="col">C type</th>
132 * <th scope="col">Layout</th>
133 * <th scope="col">Java type</th>
134 * </tr>
135 * </thead>
136 * <tbody>
137 * <tr><th scope="row" style="font-weight:normal">{@code bool}</th>
138 * <td style="text-align:center;">{@link ValueLayout#JAVA_BOOLEAN}</td>
139 * <td style="text-align:center;">{@code boolean}</td>
140 * <tr><th scope="row" style="font-weight:normal">{@code char}</th>
141 * <td style="text-align:center;">{@link ValueLayout#JAVA_BYTE}</td>
142 * <td style="text-align:center;">{@code byte}</td>
143 * <tr><th scope="row" style="font-weight:normal">{@code short}</th>
144 * <td style="text-align:center;">{@link ValueLayout#JAVA_SHORT}</td>
145 * <td style="text-align:center;">{@code short}</td>
146 * <tr><th scope="row" style="font-weight:normal">{@code int}</th>
147 * <td style="text-align:center;">{@link ValueLayout#JAVA_INT}</td>
148 * <td style="text-align:center;">{@code int}</td>
149 * <tr><th scope="row" style="font-weight:normal">{@code long}</th>
150 * <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
151 * <td style="text-align:center;">{@code long}</td>
152 * <tr><th scope="row" style="font-weight:normal">{@code long long}</th>
153 * <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
154 * <td style="text-align:center;">{@code long}</td>
155 * <tr><th scope="row" style="font-weight:normal">{@code float}</th>
156 * <td style="text-align:center;">{@link ValueLayout#JAVA_FLOAT}</td>
157 * <td style="text-align:center;">{@code float}</td>
158 * <tr><th scope="row" style="font-weight:normal">{@code double}</th>
159 * <td style="text-align:center;">{@link ValueLayout#JAVA_DOUBLE}</td>
160 * <td style="text-align:center;">{@code double}</td>
161 <tr><th scope="row" style="font-weight:normal">{@code size_t}</th>
162 * <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
163 * <td style="text-align:center;">{@code long}</td>
164 * <tr><th scope="row" style="font-weight:normal">{@code char*}, {@code int**}, {@code struct Point*}</th>
165 * <td style="text-align:center;">{@link ValueLayout#ADDRESS}</td>
166 * <td style="text-align:center;">{@link MemorySegment}</td>
167 * <tr><th scope="row" style="font-weight:normal">{@code int (*ptr)[10]}</th>
168 * <td style="text-align:left;">
169 * <pre>
170 * ValueLayout.ADDRESS.withTargetLayout(
171 * MemoryLayout.sequenceLayout(10,
172 * ValueLayout.JAVA_INT)
183 * );
184 * </pre>
185 * </td>
186 * <td style="text-align:center;">{@link MemorySegment}</td>
187 * <tr><th scope="row" style="font-weight:normal"><code>union Choice { float a; int b; }</code></th>
188 * <td style="text-align:left;">
189 * <pre>
190 * MemoryLayout.unionLayout(
191 * ValueLayout.JAVA_FLOAT.withName("a"),
192 * ValueLayout.JAVA_INT.withName("b")
193 * );
194 * </pre>
195 * </td>
196 * <td style="text-align:center;">{@link MemorySegment}</td>
197 * </tbody>
198 * </table></blockquote>
199 * <p>
200 * All native linker implementations operate on a subset of memory layouts. More formally, a layout {@code L}
201 * is supported by a native linker {@code NL} if:
202 * <ul>
203 * <li>{@code L} is a value layout {@code V} and {@code V.withoutName()} is {@linkplain MemoryLayout#equals(Object) equal}
204 * to one of the following layout constants:
205 * <ul>
206 * <li>{@link ValueLayout#JAVA_BOOLEAN}</li>
207 * <li>{@link ValueLayout#JAVA_BYTE}</li>
208 * <li>{@link ValueLayout#JAVA_CHAR}</li>
209 * <li>{@link ValueLayout#JAVA_SHORT}</li>
210 * <li>{@link ValueLayout#JAVA_INT}</li>
211 * <li>{@link ValueLayout#JAVA_LONG}</li>
212 * <li>{@link ValueLayout#JAVA_FLOAT}</li>
213 * <li>{@link ValueLayout#JAVA_DOUBLE}</li>
214 * </ul></li>
215 * <li>{@code L} is an address layout {@code A} and {@code A.withoutTargetLayout().withoutName()} is
216 * {@linkplain MemoryLayout#equals(Object) equal} to {@link ValueLayout#ADDRESS}</li>
217 * <li>{@code L} is a sequence layout {@code S} and all the following conditions hold:
218 * <ol>
219 * <li>the alignment constraint of {@code S} is set to its <a href="MemoryLayout.html#layout-align">natural alignment</a>, and</li>
220 * <li>{@code S.elementLayout()} is a layout supported by {@code NL}.</li>
221 * </ol>
222 * </li>
223 * <li>{@code L} is a group layout {@code G} and all the following conditions hold:
224 * <ol>
225 * <li>the alignment constraint of {@code G} is set to its <a href="MemoryLayout.html#layout-align">natural alignment</a>;</li>
226 * <li>the size of {@code G} is a multiple of its alignment constraint;</li>
227 * <li>each member layout in {@code G.memberLayouts()} is either a padding layout or a layout supported by {@code NL}, and</li>
228 * <li>{@code G} does not contain padding other than what is strictly required to align its non-padding layout elements, or to satisfy (2).</li>
229 * </ol>
230 * </li>
231 * </ul>
232 *
233 * A native linker only supports function descriptors whose argument/return layouts are layouts supported by that linker
234 * and are not sequence layouts.
235 *
236 * <h3 id="function-pointers">Function pointers</h3>
276 * {@snippet lang = java:
277 * FunctionDescriptor comparDesc = FunctionDescriptor.of(JAVA_INT,
278 * ADDRESS.withTargetLayout(JAVA_INT),
279 * ADDRESS.withTargetLayout(JAVA_INT));
280 * MethodHandle comparHandle = MethodHandles.lookup()
281 * .findStatic(Qsort.class, "qsortCompare",
282 * comparDesc.toMethodType());
283 * }
284 *
285 * First, we create a function descriptor for the function pointer type. Since we know that the parameters passed to
286 * the comparator method will be pointers to elements of a C {@code int[]} array, we can specify {@link ValueLayout#JAVA_INT}
287 * as the target layout for the address layouts of both parameters. This will allow the comparator method to access
288 * the contents of the array elements to be compared. We then {@linkplain FunctionDescriptor#toMethodType() turn}
289 * that function descriptor into a suitable {@linkplain java.lang.invoke.MethodType method type} which we then use to look up
290 * the comparator method handle. We can now create an upcall stub which points to that method, and pass it, as a function
291 * pointer, to the {@code qsort} downcall handle, as follows:
292 *
293 * {@snippet lang = java:
294 * try (Arena arena = Arena.ofConfined()) {
295 * MemorySegment comparFunc = linker.upcallStub(comparHandle, comparDesc, arena);
296 * MemorySegment array = arena.allocateArray(JAVA_INT, 0, 9, 3, 4, 6, 5, 1, 8, 2, 7);
297 * qsort.invokeExact(array, 10L, 4L, comparFunc);
298 * int[] sorted = array.toArray(JAVA_INT); // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
299 * }
300 * }
301 *
302 * This code creates an off-heap array, copies the contents of a Java array into it, and then passes the array to the
303 * {@code qsort} method handle along with the comparator function we obtained from the native linker. After the invocation, the contents
304 * of the off-heap array will be sorted according to our comparator function, written in Java. We then extract a
305 * new Java array from the segment, which contains the sorted elements.
306 *
307 * <h3 id="by-ref">Functions returning pointers</h3>
308 *
309 * When interacting with native functions, it is common for those functions to allocate a region of memory and return
310 * a pointer to that region. Let's consider the following function from the C standard library:
311 *
312 * {@snippet lang = c:
313 * void *malloc(size_t size);
314 * }
315 *
316 * The {@code malloc} function allocates a region of memory of given size,
334 * MethodHandle malloc = linker.downcallHandle(
335 * linker.defaultLookup().find("malloc").orElseThrow(),
336 * FunctionDescriptor.of(ADDRESS, JAVA_LONG)
337 * );
338 *
339 * MethodHandle free = linker.downcallHandle(
340 * linker.defaultLookup().find("free").orElseThrow(),
341 * FunctionDescriptor.ofVoid(ADDRESS)
342 * );
343 * }
344 *
345 * When a native function returning a pointer (such as {@code malloc}) is invoked using a downcall method handle,
346 * the Java runtime has no insight into the size or the lifetime of the returned pointer. Consider the following code:
347 *
348 * {@snippet lang = java:
349 * MemorySegment segment = (MemorySegment)malloc.invokeExact(100);
350 * }
351 *
352 * The size of the segment returned by the {@code malloc} downcall method handle is
353 * <a href="MemorySegment.html#wrapping-addresses">zero</a>. Moreover, the scope of the
354 * returned segment is a fresh scope that is always alive. To provide safe access to the segment, we must,
355 * unsafely, resize the segment to the desired size (100, in this case). It might also be desirable to
356 * attach the segment to some existing {@linkplain Arena arena}, so that the lifetime of the region of memory
357 * backing the segment can be managed automatically, as for any other native segment created directly from Java code.
358 * Both of these operations are accomplished using the restricted method {@link MemorySegment#reinterpret(long, Arena, Consumer)},
359 * as follows:
360 *
361 * {@snippet lang = java:
362 * MemorySegment allocateMemory(long byteSize, Arena arena) throws Throwable {
363 * MemorySegment segment = (MemorySegment) malloc.invokeExact(byteSize); // size = 0, scope = always alive
364 * return segment.reinterpret(byteSize, arena, s -> {
365 * try {
366 * free.invokeExact(s);
367 * } catch (Throwable e) {
368 * throw new RuntimeException(e);
369 * }
370 * }); // size = byteSize, scope = arena.scope()
371 * }
372 * }
373 *
374 * The {@code allocateMemory} method defined above accepts two parameters: a size and an arena. The method calls the
375 * {@code malloc} downcall method handle, and unsafely reinterprets the returned segment, by giving it a new size
376 * (the size passed to the {@code allocateMemory} method) and a new scope (the scope of the provided arena).
377 * The method also specifies a <em>cleanup action</em> to be executed when the provided arena is closed. Unsurprisingly,
378 * the cleanup action passes the segment to the {@code free} downcall method handle, to deallocate the underlying
379 * region of memory. We can use the {@code allocateMemory} method as follows:
380 *
381 * {@snippet lang = java:
382 * try (Arena arena = Arena.ofConfined()) {
383 * MemorySegment segment = allocateMemory(100, arena);
384 * } // 'free' called here
385 * }
386 *
387 * Note how the segment obtained from {@code allocateMemory} acts as any other segment managed by the confined arena. More
388 * specifically, the obtained segment has the desired size, can only be accessed by a single thread (the thread which created
389 * the confined arena), and its lifetime is tied to the surrounding <em>try-with-resources</em> block.
390 *
391 * <h3 id="variadic-funcs">Variadic functions</h3>
392 *
393 * Variadic functions are C functions which can accept a variable number and type of arguments. They are declared:
394 * <ol>
395 * <li>With a trailing ellipsis ({@code ...}) at the end of the formal parameter list, such as: {@code void foo(int x, ...);}</li>
396 * <li>With an empty formal parameter list, called a prototype-less function, such as: {@code void foo();}</li>
397 * </ol>
398 * The arguments passed in place of the ellipsis, or the arguments passed to a prototype-less function are called
399 * <em>variadic arguments</em>. Variadic functions are, essentially, templates that can be <em>specialized</em> into multiple
400 * non-variadic functions by replacing the {@code ...} or empty formal parameter list with a list of <em>variadic parameters</em>
401 * of a fixed number and type.
402 * <p>
403 * It should be noted that values passed as variadic arguments undergo default argument promotion in C. For instance, the
404 * following argument promotions are applied:
405 * <ul>
406 * <li>{@code _Bool} -> {@code unsigned int}</li>
407 * <li>{@code [signed] char} -> {@code [signed] int}</li>
408 * <li>{@code [signed] short} -> {@code [signed] int}</li>
409 * <li>{@code float} -> {@code double}</li>
410 * </ul>
411 * whereby the signed-ness of the source type corresponds to the signed-ness of the promoted type. The complete process
412 * of default argument promotion is described in the C specification. In effect these promotions place limits on the
413 * specialized form of a variadic function, as the variadic parameters of the specialized form will always have a promoted
414 * type.
415 * <p>
416 * The native linker only supports linking the specialized form of a variadic function. A variadic function in its specialized
417 * form can be linked using a function descriptor describing the specialized form. Additionally, the
418 * {@link Linker.Option#firstVariadicArg(int)} linker option must be provided to indicate the first variadic parameter in
419 * the parameter list. The corresponding argument layout (if any), and all following argument layouts in the specialized
420 * function descriptor, are called <em>variadic argument layouts</em>. For a prototype-less function, the index passed to
421 * {@link Linker.Option#firstVariadicArg(int)} should always be {@code 0}.
422 * <p>
423 * The native linker will reject an attempt to link a specialized function descriptor with any variadic argument layouts
424 * corresponding to a C type that would be subject to default argument promotion (as described above). Exactly which layouts
425 * will be rejected is platform specific, but as an example: on Linux/x64 the layouts {@link ValueLayout#JAVA_BOOLEAN},
426 * {@link ValueLayout#JAVA_BYTE}, {@link ValueLayout#JAVA_CHAR}, {@link ValueLayout#JAVA_SHORT}, and
427 * {@link ValueLayout#JAVA_FLOAT} will be rejected.
428 * <p>
429 * A well-known variadic function is the {@code printf} function, defined in the C standard library:
430 *
431 * {@snippet lang = c:
432 * int printf(const char *format, ...);
433 * }
434 *
435 * This function takes a format string, and a number of additional arguments (the number of such arguments is
436 * dictated by the format string). Consider the following variadic call:
437 *
438 * {@snippet lang = c:
439 * printf("%d plus %d equals %d", 2, 2, 4);
440 * }
441 *
442 * To perform an equivalent call using a downcall method handle we must create a function descriptor which
443 * describes the specialized signature of the C function we want to call. This descriptor must include an additional layout
444 * for each variadic argument we intend to provide. In this case, the specialized signature of the C
445 * function is {@code (char*, int, int, int)} as the format string accepts three integer parameters. We then need to use
446 * a {@linkplain Linker.Option#firstVariadicArg(int) linker option} to specify the position of the first variadic layout
447 * in the provided function descriptor (starting from 0). In this case, since the first parameter is the format string
448 * (a non-variadic argument), the first variadic index needs to be set to 1, as follows:
449 *
450 * {@snippet lang = java:
451 * Linker linker = Linker.nativeLinker();
452 * MethodHandle printf = linker.downcallHandle(
453 * linker.defaultLookup().find("printf").orElseThrow(),
454 * FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_INT, JAVA_INT, JAVA_INT),
455 * Linker.Option.firstVariadicArg(1) // first int is variadic
456 * );
457 * }
458 *
459 * We can then call the specialized downcall handle as usual:
460 *
461 * {@snippet lang = java:
462 * try (Arena arena = Arena.ofConfined()) {
463 * int res = (int)printf.invokeExact(arena.allocateUtf8String("%d plus %d equals %d"), 2, 2, 4); //prints "2 plus 2 equals 4"
464 * }
465 * }
466 *
467 * <h2 id="safety">Safety considerations</h2>
468 *
469 * Creating a downcall method handle is intrinsically unsafe. A symbol in a foreign library does not, in general,
470 * contain enough signature information (e.g. arity and types of foreign function parameters). As a consequence,
471 * the linker runtime cannot validate linkage requests. When a client interacts with a downcall method handle obtained
472 * through an invalid linkage request (e.g. by specifying a function descriptor featuring too many argument layouts),
473 * the result of such interaction is unspecified and can lead to JVM crashes.
474 * <p>
475 * When an upcall stub is passed to a foreign function, a JVM crash might occur, if the foreign code casts the function pointer
476 * associated with the upcall stub to a type that is incompatible with the type of the upcall stub, and then attempts to
477 * invoke the function through the resulting function pointer. Moreover, if the method
478 * handle associated with an upcall stub returns a {@linkplain MemorySegment memory segment}, clients must ensure
479 * that this address cannot become invalid after the upcall completes. This can lead to unspecified behavior,
480 * and even JVM crashes, since an upcall is typically executed in the context of a downcall method handle invocation.
481 *
482 * @implSpec
483 * Implementations of this interface are immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
484 *
485 * @since 19
486 */
487 @PreviewFeature(feature=PreviewFeature.Feature.FOREIGN)
488 public sealed interface Linker permits AbstractLinker {
489
490 /**
491 * {@return a linker for the ABI associated with the underlying native platform} The underlying native platform
492 * is the combination of OS and processor where the Java runtime is currently executing.
493 *
494 * @apiNote It is not currently possible to obtain a linker for a different combination of OS and processor.
495 * @implNote The libraries exposed by the {@linkplain #defaultLookup() default lookup} associated with the returned
496 * linker are the native libraries loaded in the process where the Java runtime is currently executing. For example,
497 * on Linux, these libraries typically include {@code libc}, {@code libm} and {@code libdl}.
498 *
499 * @throws UnsupportedOperationException if the underlying native platform is not supported.
500 */
501 static Linker nativeLinker() {
502 return SharedUtils.getSystemLinker();
503 }
504
505 /**
506 * Creates a method handle which is used to call a foreign function with the given signature and address.
507 * <p>
508 * Calling this method is equivalent to the following code:
509 * {@snippet lang=java :
510 * linker.downcallHandle(function).bindTo(symbol);
511 * }
512 * <p>
513 * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
514 * Restricted methods are unsafe, and, if used incorrectly, their use might crash
515 * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
516 * restricted methods, and use safe and supported functionalities, where possible.
517 *
518 * @param address the native memory segment whose {@linkplain MemorySegment#address() base address} is the
519 * address of the target foreign function.
520 * @param function the function descriptor of the target foreign function.
521 * @param options the linker options associated with this linkage request.
522 * @return a downcall method handle.
523 * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
524 * @throws IllegalArgumentException if {@code !address.isNative()}, or if {@code address.equals(MemorySegment.NULL)}.
525 * @throws IllegalArgumentException if an invalid combination of linker options is given.
526 * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
527 *
528 * @see SymbolLookup
529 */
530 @CallerSensitive
531 MethodHandle downcallHandle(MemorySegment address, FunctionDescriptor function, Option... options);
532
533 /**
534 * Creates a method handle which is used to call a foreign function with the given signature.
535 * <p>
536 * The Java {@linkplain java.lang.invoke.MethodType method type} associated with the returned method handle is
541 * the linker runtime to allocate the memory region associated with the struct returned by the downcall method handle.
542 * <p>
543 * Upon invoking a downcall method handle, the linker provides the following guarantees for any argument
544 * {@code A} of type {@link MemorySegment} whose corresponding layout is an {@linkplain AddressLayout address layout}:
545 * <ul>
546 * <li>{@code A.scope().isAlive() == true}. Otherwise, the invocation throws {@link IllegalStateException};</li>
547 * <li>The invocation occurs in a thread {@code T} such that {@code A.isAccessibleBy(T) == true}.
548 * Otherwise, the invocation throws {@link WrongThreadException}; and</li>
549 * <li>{@code A} is kept alive during the invocation. For instance, if {@code A} has been obtained using a
550 * {@linkplain Arena#ofShared() shared arena}, any attempt to {@linkplain Arena#close() close}
551 * the arena while the downcall method handle is still executing will result in an {@link IllegalStateException}.</li>
552 *</ul>
553 * <p>
554 * Moreover, if the provided function descriptor's return layout is an {@linkplain AddressLayout address layout},
555 * invoking the returned method handle will return a native segment associated with
556 * a fresh scope that is always alive. Under normal conditions, the size of the returned segment is {@code 0}.
557 * However, if the function descriptor's return layout has a {@linkplain AddressLayout#targetLayout() target layout}
558 * {@code T}, then the size of the returned segment is set to {@code T.byteSize()}.
559 * <p>
560 * The returned method handle will throw an {@link IllegalArgumentException} if the {@link MemorySegment}
561 * representing the target address of the foreign function is the {@link MemorySegment#NULL} address.
562 * The returned method handle will additionally throw {@link NullPointerException} if any argument passed to it is {@code null}.
563 * <p>
564 * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
565 * Restricted methods are unsafe, and, if used incorrectly, their use might crash
566 * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
567 * restricted methods, and use safe and supported functionalities, where possible.
568 *
569 * @param function the function descriptor of the target foreign function.
570 * @param options the linker options associated with this linkage request.
571 * @return a downcall method handle.
572 * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
573 * @throws IllegalArgumentException if an invalid combination of linker options is given.
574 * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
575 */
576 @CallerSensitive
577 MethodHandle downcallHandle(FunctionDescriptor function, Option... options);
578
579 /**
580 * Creates an upcall stub which can be passed to other foreign functions as a function pointer, associated with the given
581 * arena. Calling such a function pointer from foreign code will result in the execution of the provided
582 * method handle.
583 * <p>
584 * The returned memory segment's address points to the newly allocated upcall stub, and is associated with
585 * the provided arena. As such, the lifetime of the returned upcall stub segment is controlled by the
586 * provided arena. For instance, if the provided arena is a confined arena, the returned
587 * upcall stub segment will be deallocated when the provided confined arena is {@linkplain Arena#close() closed}.
588 * <p>
589 * An upcall stub argument whose corresponding layout is an {@linkplain AddressLayout address layout}
590 * is a native segment associated with a fresh scope that is always alive.
591 * Under normal conditions, the size of this segment argument is {@code 0}.
592 * However, if the address layout has a {@linkplain AddressLayout#targetLayout() target layout} {@code T}, then the size of the
593 * segment argument is set to {@code T.byteSize()}.
594 * <p>
595 * The target method handle should not throw any exceptions. If the target method handle does throw an exception,
596 * the JVM will terminate abruptly. To avoid this, clients should wrap the code in the target method handle in a
597 * try/catch block to catch any unexpected exceptions. This can be done using the
598 * {@link java.lang.invoke.MethodHandles#catchException(MethodHandle, Class, MethodHandle)} method handle combinator,
599 * and handle exceptions as desired in the corresponding catch block.
600 * <p>
601 * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
602 * Restricted methods are unsafe, and, if used incorrectly, their use might crash
603 * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
604 * restricted methods, and use safe and supported functionalities, where possible.
605 *
606 * @param target the target method handle.
607 * @param function the upcall stub function descriptor.
608 * @param arena the arena associated with the returned upcall stub segment.
609 * @param options the linker options associated with this linkage request.
610 * @return a zero-length segment whose address is the address of the upcall stub.
611 * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
612 * @throws IllegalArgumentException if the type of {@code target} is incompatible with the
613 * type {@linkplain FunctionDescriptor#toMethodType() derived} from {@code function}.
614 * @throws IllegalArgumentException if it is determined that the target method handle can throw an exception.
615 * @throws IllegalStateException if {@code arena.scope().isAlive() == false}
616 * @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a
617 * thread {@code T}, other than the arena's owner thread.
618 * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
619 */
620 @CallerSensitive
621 MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function, Arena arena, Linker.Option... options);
622
623 /**
624 * Returns a symbol lookup for symbols in a set of commonly used libraries.
625 * <p>
626 * Each {@link Linker} is responsible for choosing libraries that are widely recognized as useful on the OS
627 * and processor combination supported by the {@link Linker}. Accordingly, the precise set of symbols exposed by the
628 * symbol lookup is unspecified; it varies from one {@link Linker} to another.
629 * @implNote It is strongly recommended that the result of {@link #defaultLookup} exposes a set of symbols that is stable over time.
630 * Clients of {@link #defaultLookup()} are likely to fail if a symbol that was previously exposed by the symbol lookup is no longer exposed.
631 * <p>If an implementer provides {@link Linker} implementations for multiple OS and processor combinations, then it is strongly
632 * recommended that the result of {@link #defaultLookup()} exposes, as much as possible, a consistent set of symbols
633 * across all the OS and processor combinations.
634 * @return a symbol lookup for symbols in a set of commonly used libraries.
635 */
636 SymbolLookup defaultLookup();
637
638 /**
639 * A linker option is used to provide additional parameters to a linkage request.
640 * @since 20
641 */
642 @PreviewFeature(feature=PreviewFeature.Feature.FOREIGN)
643 sealed interface Option
644 permits LinkerOptions.LinkerOptionImpl {
645
646 /**
647 * {@return a linker option used to denote the index indicating the start of the variadic arguments passed to the
648 * function described by the function descriptor associated with a downcall linkage request}
649 * <p>
650 * The {@code index} value must conform to {@code 0 <= index <= N}, where {@code N} is the number of argument
651 * layouts of the function descriptor used in conjunction with this linker option. When the {@code index} is:
652 * <ul>
653 * <li>{@code 0}, all arguments passed to the function are passed as variadic arguments</li>
654 * <li>{@code N}, none of the arguments passed to the function are passed as variadic arguments</li>
655 * <li>{@code n}, where {@code 0 < m < N}, the arguments {@code m..N} are passed as variadic arguments</li>
656 * </ul>
657 * It is important to always use this linker option when linking a <a href=Linker.html#variadic-funcs>variadic
658 * function</a>, even if no variadic argument is passed (the second case in the list
659 * above), as this might still affect the calling convention on certain platforms.
660 *
661 * @implNote The index value is validated when making a linkage request, which is when the function descriptor
662 * against which the index is validated is available.
687 * <p>
688 * Captured state can be retrieved from the capture state segment by constructing var handles
689 * from the {@linkplain #captureStateLayout capture state layout}.
690 * <p>
691 * The following example demonstrates the use of this linker option:
692 * {@snippet lang = "java":
693 * MemorySegment targetAddress = ...
694 * Linker.Option ccs = Linker.Option.captureCallState("errno");
695 * MethodHandle handle = Linker.nativeLinker().downcallHandle(targetAddress, FunctionDescriptor.ofVoid(), ccs);
696 *
697 * StructLayout capturedStateLayout = Linker.Option.captureStateLayout();
698 * VarHandle errnoHandle = capturedStateLayout.varHandle(PathElement.groupElement("errno"));
699 * try (Arena arena = Arena.ofConfined()) {
700 * MemorySegment capturedState = arena.allocate(capturedStateLayout);
701 * handle.invoke(capturedState);
702 * int errno = (int) errnoHandle.get(capturedState);
703 * // use errno
704 * }
705 * }
706 *
707 * @param capturedState the names of the values to save.
708 * @throws IllegalArgumentException if at least one of the provided {@code capturedState} names
709 * is unsupported on the current platform.
710 * @see #captureStateLayout()
711 */
712 static Option captureCallState(String... capturedState) {
713 Set<CapturableState> set = Stream.of(Objects.requireNonNull(capturedState))
714 .map(Objects::requireNonNull)
715 .map(CapturableState::forName)
716 .collect(Collectors.toSet());
717 return new LinkerOptions.CaptureCallState(set);
718 }
719
720 /**
721 * {@return a struct layout that represents the layout of the capture state segment that is passed
722 * to a downcall handle linked with {@link #captureCallState(String...)}}
723 * <p>
724 * The capture state layout is <em>platform-dependent</em> but is guaranteed to be
725 * a {@linkplain StructLayout struct layout} containing only {@linkplain ValueLayout value layouts}
726 * and possibly {@linkplain PaddingLayout padding layouts}.
729 * <li>GetLastError</li>
730 * <li>WSAGetLastError</li>
731 * <li>errno</li>
732 * </ul>
733 * <p>
734 * Clients can obtain the names of the supported captured value layouts as follows:
735 * {@snippet lang = java:
736 * List<String> capturedNames = Linker.Option.captureStateLayout().memberLayouts().stream()
737 * .map(MemoryLayout::name)
738 * .flatMap(Optional::stream)
739 * .toList();
740 * }
741 *
742 * @see #captureCallState(String...)
743 */
744 static StructLayout captureStateLayout() {
745 return CapturableState.LAYOUT;
746 }
747
748 /**
749 * {@return a linker option used to mark a foreign function as <em>trivial</em>}
750 * <p>
751 * A trivial function is a function that has an extremely short running time
752 * in all cases (similar to calling an empty function), and does not call back into Java (e.g. using an upcall stub).
753 * <p>
754 * Using this linker option is a hint which some implementations may use to apply
755 * optimizations that are only valid for trivial functions.
756 * <p>
757 * Using this linker option when linking non trivial functions is likely to have adverse effects,
758 * such as loss of performance, or JVM crashes.
759 */
760 static Option isTrivial() {
761 return LinkerOptions.IsTrivial.INSTANCE;
762 }
763 }
764 }
|
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.abi.AbstractLinker;
29 import jdk.internal.foreign.abi.LinkerOptions;
30 import jdk.internal.foreign.abi.CapturableState;
31 import jdk.internal.foreign.abi.SharedUtils;
32 import jdk.internal.reflect.CallerSensitive;
33
34 import java.lang.invoke.MethodHandle;
35 import java.nio.ByteOrder;
36 import java.util.Map;
37 import java.util.Objects;
38 import java.util.Set;
39 import java.util.function.Consumer;
40 import java.util.stream.Collectors;
41 import java.util.stream.Stream;
42
43 /**
44 * A linker provides access to foreign functions from Java code, and access to Java code from foreign functions.
45 * <p>
46 * Foreign functions typically reside in libraries that can be loaded on-demand. Each library conforms to
47 * a specific ABI (Application Binary Interface). An ABI is a set of calling conventions and data types associated with
48 * the compiler, OS, and processor where the library was built. For example, a C compiler on Linux/x64 usually
49 * builds libraries that conform to the SystemV ABI.
50 * <p>
51 * A linker has detailed knowledge of the calling conventions and data types used by a specific ABI.
52 * For any library which conforms to that ABI, the linker can mediate between Java code running
53 * in the JVM and foreign functions in the library. In particular:
54 * <ul>
55 * <li>A linker allows Java code to link against foreign functions, via
56 * {@linkplain #downcallHandle(MemorySegment, FunctionDescriptor, Option...) downcall method handles}; and</li>
57 * <li>A linker allows foreign functions to call Java method handles,
58 * via the generation of {@linkplain #upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...) upcall stubs}.</li>
59 * </ul>
60 * A linker provides a way to look up the <em>canonical layouts</em> associated with the data types used by the ABI.
61 * For example, a linker implementing the C ABI might choose to provide a canonical layout for the C {@code size_t}
62 * type. On 64-bit platforms, this canonical layout might be equal to {@link ValueLayout#JAVA_LONG}. The canonical
63 * layouts supported by a linker are exposed via the {@link #canonicalLayouts()} method, which returns a map from
64 * type names to canonical layouts.
65 * <p>
66 * In addition, a linker provides a way to look up foreign functions in libraries that conform to the ABI. Each linker
67 * chooses a set of libraries that are commonly used on the OS and processor combination associated with the ABI.
68 * For example, a linker for Linux/x64 might choose two libraries: {@code libc} and {@code libm}. The functions in these
69 * libraries are exposed via a {@linkplain #defaultLookup() symbol lookup}.
70 *
71 * <h2 id="native-linker">Calling native functions</h2>
72 *
73 * The {@linkplain #nativeLinker() native linker} can be used to link against functions
74 * defined in C libraries (native functions). Suppose we wish to downcall from Java to the {@code strlen} function
75 * defined in the standard C library:
76 * {@snippet lang = c:
77 * size_t strlen(const char *s);
78 * }
79 * A downcall method handle that exposes {@code strlen} is obtained, using the native linker, as follows:
80 *
81 * {@snippet lang = java:
82 * Linker linker = Linker.nativeLinker();
83 * MethodHandle strlen = linker.downcallHandle(
84 * linker.defaultLookup().find("strlen").orElseThrow(),
85 * FunctionDescriptor.of(JAVA_LONG, ADDRESS)
86 * );
87 * }
88 *
89 * Note how the native linker also provides access, via its {@linkplain #defaultLookup() default lookup},
90 * to the native functions defined by the C libraries loaded with the Java runtime. Above, the default lookup
91 * is used to search the address of the {@code strlen} native function. That address is then passed, along with
92 * a <em>platform-dependent description</em> of the signature of the function expressed as a
93 * {@link FunctionDescriptor} (more on that below) to the native linker's
94 * {@link #downcallHandle(MemorySegment, FunctionDescriptor, Option...)} method.
95 * The obtained downcall method handle is then invoked as follows:
96 *
97 * {@snippet lang = java:
98 * try (Arena arena = Arena.ofConfined()) {
99 * MemorySegment str = arena.allocateFrom("Hello");
100 * long len = (long) strlen.invokeExact(str); // 5
101 * }
102 *}
103 * <h3 id="describing-c-sigs">Describing C signatures</h3>
104 *
105 * When interacting with the native linker, clients must provide a platform-dependent description of the signature
106 * of the C function they wish to link against. This description, a {@link FunctionDescriptor function descriptor},
107 * defines the layouts associated with the parameter types and return type (if any) of the C function.
108 * <p>
109 * Scalar C types such as {@code bool}, {@code int} are modelled as {@linkplain ValueLayout value layouts}
110 * of a suitable carrier. The {@linkplain #canonicalLayouts() mapping} between a scalar type and its corresponding
111 * canonical layout is dependent on the ABI implemented by the native linker (see below).
112 * <p>
113 * Composite types are modelled as {@linkplain GroupLayout group layouts}. More specifically, a C {@code struct} type
114 * maps to a {@linkplain StructLayout struct layout}, whereas a C {@code union} type maps to a {@link UnionLayout union
115 * layout}. When defining a struct or union layout, clients must pay attention to the size and alignment constraint
116 * of the corresponding composite type definition in C. For instance, padding between two struct fields
117 * must be modelled explicitly, by adding an adequately sized {@linkplain PaddingLayout padding layout} member
118 * to the resulting struct layout.
119 * <p>
120 * Finally, pointer types such as {@code int**} and {@code int(*)(size_t*, size_t*)} are modelled as
121 * {@linkplain AddressLayout address layouts}. When the spatial bounds of the pointer type are known statically,
122 * the address layout can be associated with a {@linkplain AddressLayout#targetLayout() target layout}. For instance,
123 * a pointer that is known to point to a C {@code int[2]} array can be modelled as an address layout whose
124 * target layout is a sequence layout whose element count is 2, and whose element type is {@link ValueLayout#JAVA_INT}.
125 * <p>
126 * All native linker implementations are guaranteed to provide canonical layouts for the following set of types:
127 * <ul>
128 * <li>{@code bool}</li>
129 * <li>{@code char}</li>
130 * <li>{@code short}</li>
131 * <li>{@code int}</li>
132 * <li>{@code long}</li>
133 * <li>{@code long long}</li>
134 * <li>{@code float}</li>
135 * <li>{@code double}</li>
136 * <li>{@code size_t}</li>
137 * <li>{@code wchar_t}</li>
138 * <li>{@code void*}</li>
139 * </ul>
140 * As noted above, the specific canonical layout associated with each type can vary, depending on the data model
141 * supported by a given ABI. For instance, the C type {@code long} maps to the layout constant {@link ValueLayout#JAVA_LONG}
142 * on Linux/x64, but maps to the layout constant {@link ValueLayout#JAVA_INT} on Windows/x64. Similarly, the C type
143 * {@code size_t} maps to the layout constant {@link ValueLayout#JAVA_LONG} on 64-bit platforms, but maps to the layout
144 * constant {@link ValueLayout#JAVA_INT} on 32-bit platforms.
145 * <p>
146 * A native linker typically does not provide canonical layouts for C's unsigned integral types. Instead, they are
147 * modelled using the canonical layouts associated with their corresponding signed integral types. For instance,
148 * the C type {@code unsigned long} maps to the layout constant {@link ValueLayout#JAVA_LONG} on Linux/x64, but maps to
149 * the layout constant {@link ValueLayout#JAVA_INT} on Windows/x64.
150 * <p>
151 * The following table shows some examples of how C types are modelled in Linux/x64 (all the examples provided
152 * here will assume these platform-dependent mappings):
153 *
154 * <blockquote><table class="plain">
155 * <caption style="display:none">Mapping C types</caption>
156 * <thead>
157 * <tr>
158 * <th scope="col">C type</th>
159 * <th scope="col">Layout</th>
160 * <th scope="col">Java type</th>
161 * </tr>
162 * </thead>
163 * <tbody>
164 * <tr><th scope="row" style="font-weight:normal">{@code bool}</th>
165 * <td style="text-align:center;">{@link ValueLayout#JAVA_BOOLEAN}</td>
166 * <td style="text-align:center;">{@code boolean}</td>
167 * <tr><th scope="row" style="font-weight:normal">{@code char} <br> {@code unsigned char}</th>
168 * <td style="text-align:center;">{@link ValueLayout#JAVA_BYTE}</td>
169 * <td style="text-align:center;">{@code byte}</td>
170 * <tr><th scope="row" style="font-weight:normal">{@code short} <br> {@code unsigned short}</th>
171 * <td style="text-align:center;">{@link ValueLayout#JAVA_SHORT}</td>
172 * <td style="text-align:center;">{@code short}</td>
173 * <tr><th scope="row" style="font-weight:normal">{@code int} <br> {@code unsigned int}</th>
174 * <td style="text-align:center;">{@link ValueLayout#JAVA_INT}</td>
175 * <td style="text-align:center;">{@code int}</td>
176 * <tr><th scope="row" style="font-weight:normal">{@code long} <br> {@code unsigned long}</th>
177 * <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
178 * <td style="text-align:center;">{@code long}</td>
179 * <tr><th scope="row" style="font-weight:normal">{@code long long} <br> {@code unsigned long long}</th>
180 * <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
181 * <td style="text-align:center;">{@code long}</td>
182 * <tr><th scope="row" style="font-weight:normal">{@code float}</th>
183 * <td style="text-align:center;">{@link ValueLayout#JAVA_FLOAT}</td>
184 * <td style="text-align:center;">{@code float}</td>
185 * <tr><th scope="row" style="font-weight:normal">{@code double}</th>
186 * <td style="text-align:center;">{@link ValueLayout#JAVA_DOUBLE}</td>
187 * <td style="text-align:center;">{@code double}</td>
188 <tr><th scope="row" style="font-weight:normal">{@code size_t}</th>
189 * <td style="text-align:center;">{@link ValueLayout#JAVA_LONG}</td>
190 * <td style="text-align:center;">{@code long}</td>
191 * <tr><th scope="row" style="font-weight:normal">{@code char*}, {@code int**}, {@code struct Point*}</th>
192 * <td style="text-align:center;">{@link ValueLayout#ADDRESS}</td>
193 * <td style="text-align:center;">{@link MemorySegment}</td>
194 * <tr><th scope="row" style="font-weight:normal">{@code int (*ptr)[10]}</th>
195 * <td style="text-align:left;">
196 * <pre>
197 * ValueLayout.ADDRESS.withTargetLayout(
198 * MemoryLayout.sequenceLayout(10,
199 * ValueLayout.JAVA_INT)
210 * );
211 * </pre>
212 * </td>
213 * <td style="text-align:center;">{@link MemorySegment}</td>
214 * <tr><th scope="row" style="font-weight:normal"><code>union Choice { float a; int b; }</code></th>
215 * <td style="text-align:left;">
216 * <pre>
217 * MemoryLayout.unionLayout(
218 * ValueLayout.JAVA_FLOAT.withName("a"),
219 * ValueLayout.JAVA_INT.withName("b")
220 * );
221 * </pre>
222 * </td>
223 * <td style="text-align:center;">{@link MemorySegment}</td>
224 * </tbody>
225 * </table></blockquote>
226 * <p>
227 * All native linker implementations operate on a subset of memory layouts. More formally, a layout {@code L}
228 * is supported by a native linker {@code NL} if:
229 * <ul>
230 * <li>{@code L} is a value layout {@code V} and {@code V.withoutName()} is a canonical layout</li>
231 * <li>{@code L} is a sequence layout {@code S} and all the following conditions hold:
232 * <ol>
233 * <li>the alignment constraint of {@code S} is set to its <a href="MemoryLayout.html#layout-align">natural alignment</a>, and</li>
234 * <li>{@code S.elementLayout()} is a layout supported by {@code NL}.</li>
235 * </ol>
236 * </li>
237 * <li>{@code L} is a group layout {@code G} and all the following conditions hold:
238 * <ol>
239 * <li>the alignment constraint of {@code G} is set to its <a href="MemoryLayout.html#layout-align">natural alignment</a>;</li>
240 * <li>the size of {@code G} is a multiple of its alignment constraint;</li>
241 * <li>each member layout in {@code G.memberLayouts()} is either a padding layout or a layout supported by {@code NL}, and</li>
242 * <li>{@code G} does not contain padding other than what is strictly required to align its non-padding layout elements, or to satisfy (2).</li>
243 * </ol>
244 * </li>
245 * </ul>
246 *
247 * A native linker only supports function descriptors whose argument/return layouts are layouts supported by that linker
248 * and are not sequence layouts.
249 *
250 * <h3 id="function-pointers">Function pointers</h3>
290 * {@snippet lang = java:
291 * FunctionDescriptor comparDesc = FunctionDescriptor.of(JAVA_INT,
292 * ADDRESS.withTargetLayout(JAVA_INT),
293 * ADDRESS.withTargetLayout(JAVA_INT));
294 * MethodHandle comparHandle = MethodHandles.lookup()
295 * .findStatic(Qsort.class, "qsortCompare",
296 * comparDesc.toMethodType());
297 * }
298 *
299 * First, we create a function descriptor for the function pointer type. Since we know that the parameters passed to
300 * the comparator method will be pointers to elements of a C {@code int[]} array, we can specify {@link ValueLayout#JAVA_INT}
301 * as the target layout for the address layouts of both parameters. This will allow the comparator method to access
302 * the contents of the array elements to be compared. We then {@linkplain FunctionDescriptor#toMethodType() turn}
303 * that function descriptor into a suitable {@linkplain java.lang.invoke.MethodType method type} which we then use to look up
304 * the comparator method handle. We can now create an upcall stub which points to that method, and pass it, as a function
305 * pointer, to the {@code qsort} downcall handle, as follows:
306 *
307 * {@snippet lang = java:
308 * try (Arena arena = Arena.ofConfined()) {
309 * MemorySegment comparFunc = linker.upcallStub(comparHandle, comparDesc, arena);
310 * MemorySegment array = arena.allocateFrom(JAVA_INT, 0, 9, 3, 4, 6, 5, 1, 8, 2, 7);
311 * qsort.invokeExact(array, 10L, 4L, comparFunc);
312 * int[] sorted = array.toArray(JAVA_INT); // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
313 * }
314 * }
315 *
316 * This code creates an off-heap array, copies the contents of a Java array into it, and then passes the array to the
317 * {@code qsort} method handle along with the comparator function we obtained from the native linker. After the invocation, the contents
318 * of the off-heap array will be sorted according to our comparator function, written in Java. We then extract a
319 * new Java array from the segment, which contains the sorted elements.
320 *
321 * <h3 id="by-ref">Functions returning pointers</h3>
322 *
323 * When interacting with native functions, it is common for those functions to allocate a region of memory and return
324 * a pointer to that region. Let's consider the following function from the C standard library:
325 *
326 * {@snippet lang = c:
327 * void *malloc(size_t size);
328 * }
329 *
330 * The {@code malloc} function allocates a region of memory of given size,
348 * MethodHandle malloc = linker.downcallHandle(
349 * linker.defaultLookup().find("malloc").orElseThrow(),
350 * FunctionDescriptor.of(ADDRESS, JAVA_LONG)
351 * );
352 *
353 * MethodHandle free = linker.downcallHandle(
354 * linker.defaultLookup().find("free").orElseThrow(),
355 * FunctionDescriptor.ofVoid(ADDRESS)
356 * );
357 * }
358 *
359 * When a native function returning a pointer (such as {@code malloc}) is invoked using a downcall method handle,
360 * the Java runtime has no insight into the size or the lifetime of the returned pointer. Consider the following code:
361 *
362 * {@snippet lang = java:
363 * MemorySegment segment = (MemorySegment)malloc.invokeExact(100);
364 * }
365 *
366 * The size of the segment returned by the {@code malloc} downcall method handle is
367 * <a href="MemorySegment.html#wrapping-addresses">zero</a>. Moreover, the scope of the
368 * returned segment is a scope that is always alive. To provide safe access to the segment, we must,
369 * unsafely, resize the segment to the desired size (100, in this case). It might also be desirable to
370 * attach the segment to some existing {@linkplain Arena arena}, so that the lifetime of the region of memory
371 * backing the segment can be managed automatically, as for any other native segment created directly from Java code.
372 * Both of these operations are accomplished using the restricted method {@link MemorySegment#reinterpret(long, Arena, Consumer)},
373 * as follows:
374 *
375 * {@snippet lang = java:
376 * MemorySegment allocateMemory(long byteSize, Arena arena) throws Throwable {
377 * MemorySegment segment = (MemorySegment) malloc.invokeExact(byteSize); // size = 0, scope = always alive
378 * return segment.reinterpret(byteSize, arena, s -> {
379 * try {
380 * free.invokeExact(s);
381 * } catch (Throwable e) {
382 * throw new RuntimeException(e);
383 * }
384 * }); // size = byteSize, scope = arena.scope()
385 * }
386 * }
387 *
388 * The {@code allocateMemory} method defined above accepts two parameters: a size and an arena. The method calls the
389 * {@code malloc} downcall method handle, and unsafely reinterprets the returned segment, by giving it a new size
390 * (the size passed to the {@code allocateMemory} method) and a new scope (the scope of the provided arena).
391 * The method also specifies a <em>cleanup action</em> to be executed when the provided arena is closed. Unsurprisingly,
392 * the cleanup action passes the segment to the {@code free} downcall method handle, to deallocate the underlying
393 * region of memory. We can use the {@code allocateMemory} method as follows:
394 *
395 * {@snippet lang = java:
396 * try (Arena arena = Arena.ofConfined()) {
397 * MemorySegment segment = allocateMemory(100, arena);
398 * } // 'free' called here
399 * }
400 *
401 * Note how the segment obtained from {@code allocateMemory} acts as any other segment managed by the confined arena. More
402 * specifically, the obtained segment has the desired size, can only be accessed by a single thread (the thread which created
403 * the confined arena), and its lifetime is tied to the surrounding <em>try-with-resources</em> block.
404 *
405 * <h3 id="variadic-funcs">Variadic functions</h3>
406 *
407 * Variadic functions are C functions which can accept a variable number and type of arguments. They are declared with a
408 * trailing ellipsis ({@code ...}) at the end of the formal parameter list, such as: {@code void foo(int x, ...);}.
409 * The arguments passed in place of the ellipsis are called <em>variadic arguments</em>. Variadic functions are,
410 * essentially, templates that can be <em>specialized</em> into multiple non-variadic functions by replacing the
411 * {@code ...} with a list of <em>variadic parameters</em> of a fixed number and type.
412 * <p>
413 * It should be noted that values passed as variadic arguments undergo default argument promotion in C. For instance, the
414 * following argument promotions are applied:
415 * <ul>
416 * <li>{@code _Bool} -> {@code unsigned int}</li>
417 * <li>{@code [signed] char} -> {@code [signed] int}</li>
418 * <li>{@code [signed] short} -> {@code [signed] int}</li>
419 * <li>{@code float} -> {@code double}</li>
420 * </ul>
421 * whereby the signed-ness of the source type corresponds to the signed-ness of the promoted type. The complete process
422 * of default argument promotion is described in the C specification. In effect these promotions place limits on the
423 * types that can be used to replace the {@code ...}, as the variadic parameters of the specialized form of a variadic
424 * function will always have a promoted type.
425 * <p>
426 * The native linker only supports linking the specialized form of a variadic function. A variadic function in its specialized
427 * form can be linked using a function descriptor describing the specialized form. Additionally, the
428 * {@link Linker.Option#firstVariadicArg(int)} linker option must be provided to indicate the first variadic parameter in
429 * the parameter list. The corresponding argument layout (if any), and all following argument layouts in the specialized
430 * function descriptor, are called <em>variadic argument layouts</em>.
431 * <p>
432 * The native linker does not automatically perform default argument promotions. However, since passing an argument of a
433 * non-promoted type as a variadic argument is not supported in C, the native linker will reject an attempt to link a
434 * specialized function descriptor with any variadic argument value layouts corresponding to a non-promoted C type.
435 * Since the size of the C {@code int} type is platform-specific, exactly which layouts will be rejected is
436 * platform-specific as well. As an example: on Linux/x64 the layouts corresponding to the C types {@code _Bool},
437 * {@code (unsigned) char}, {@code (unsigned) short}, and {@code float} (among others), will be rejected by the linker.
438 * The {@link #canonicalLayouts()} method can be used to find which layout corresponds to a particular C type.
439 * <p>
440 * A well-known variadic function is the {@code printf} function, defined in the C standard library:
441 *
442 * {@snippet lang = c:
443 * int printf(const char *format, ...);
444 * }
445 *
446 * This function takes a format string, and a number of additional arguments (the number of such arguments is
447 * dictated by the format string). Consider the following variadic call:
448 *
449 * {@snippet lang = c:
450 * printf("%d plus %d equals %d", 2, 2, 4);
451 * }
452 *
453 * To perform an equivalent call using a downcall method handle we must create a function descriptor which
454 * describes the specialized signature of the C function we want to call. This descriptor must include an additional layout
455 * for each variadic argument we intend to provide. In this case, the specialized signature of the C
456 * function is {@code (char*, int, int, int)} as the format string accepts three integer parameters. We then need to use
457 * a {@linkplain Linker.Option#firstVariadicArg(int) linker option} to specify the position of the first variadic layout
458 * in the provided function descriptor (starting from 0). In this case, since the first parameter is the format string
459 * (a non-variadic argument), the first variadic index needs to be set to 1, as follows:
460 *
461 * {@snippet lang = java:
462 * Linker linker = Linker.nativeLinker();
463 * MethodHandle printf = linker.downcallHandle(
464 * linker.defaultLookup().find("printf").orElseThrow(),
465 * FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_INT, JAVA_INT, JAVA_INT),
466 * Linker.Option.firstVariadicArg(1) // first int is variadic
467 * );
468 * }
469 *
470 * We can then call the specialized downcall handle as usual:
471 *
472 * {@snippet lang = java:
473 * try (Arena arena = Arena.ofConfined()) {
474 * int res = (int)printf.invokeExact(arena.allocateFrom("%d plus %d equals %d"), 2, 2, 4); //prints "2 plus 2 equals 4"
475 * }
476 *}
477 *
478 * <h2 id="safety">Safety considerations</h2>
479 *
480 * Creating a downcall method handle is intrinsically unsafe. A symbol in a foreign library does not, in general,
481 * contain enough signature information (e.g. arity and types of foreign function parameters). As a consequence,
482 * the linker runtime cannot validate linkage requests. When a client interacts with a downcall method handle obtained
483 * through an invalid linkage request (e.g. by specifying a function descriptor featuring too many argument layouts),
484 * the result of such interaction is unspecified and can lead to JVM crashes.
485 * <p>
486 * When an upcall stub is passed to a foreign function, a JVM crash might occur, if the foreign code casts the function pointer
487 * associated with the upcall stub to a type that is incompatible with the type of the upcall stub, and then attempts to
488 * invoke the function through the resulting function pointer. Moreover, if the method
489 * handle associated with an upcall stub returns a {@linkplain MemorySegment memory segment}, clients must ensure
490 * that this address cannot become invalid after the upcall completes. This can lead to unspecified behavior,
491 * and even JVM crashes, since an upcall is typically executed in the context of a downcall method handle invocation.
492 *
493 * @implSpec
494 * Implementations of this interface are immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
495 *
496 * @since 22
497 */
498 public sealed interface Linker permits AbstractLinker {
499
500 /**
501 * {@return a linker for the ABI associated with the underlying native platform} The underlying native platform
502 * is the combination of OS and processor where the Java runtime is currently executing.
503 *
504 * @apiNote It is not currently possible to obtain a linker for a different combination of OS and processor.
505 * @implSpec A native linker implementation is guaranteed to provide canonical layouts for
506 * <a href="#describing-c-sigs">basic C types</a>.
507 * @implNote The libraries exposed by the {@linkplain #defaultLookup() default lookup} associated with the returned
508 * linker are the native libraries loaded in the process where the Java runtime is currently executing. For example,
509 * on Linux, these libraries typically include {@code libc}, {@code libm} and {@code libdl}.
510 */
511 static Linker nativeLinker() {
512 return SharedUtils.getSystemLinker();
513 }
514
515 /**
516 * Creates a method handle which is used to call a foreign function with the given signature and address.
517 * <p>
518 * Calling this method is equivalent to the following code:
519 * {@snippet lang=java :
520 * linker.downcallHandle(function).bindTo(symbol);
521 * }
522 * <p>
523 * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
524 * Restricted methods are unsafe, and, if used incorrectly, their use might crash
525 * the JVM or, worse, silently result in memory corruption.
526 *
527 * @param address the native memory segment whose {@linkplain MemorySegment#address() base address} is the
528 * address of the target foreign function.
529 * @param function the function descriptor of the target foreign function.
530 * @param options the linker options associated with this linkage request.
531 * @return a downcall method handle.
532 * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
533 * @throws IllegalArgumentException if {@code !address.isNative()}, or if {@code address.equals(MemorySegment.NULL)}.
534 * @throws IllegalArgumentException if an invalid combination of linker options is given.
535 * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
536 *
537 * @see SymbolLookup
538 */
539 @CallerSensitive
540 MethodHandle downcallHandle(MemorySegment address, FunctionDescriptor function, Option... options);
541
542 /**
543 * Creates a method handle which is used to call a foreign function with the given signature.
544 * <p>
545 * The Java {@linkplain java.lang.invoke.MethodType method type} associated with the returned method handle is
550 * the linker runtime to allocate the memory region associated with the struct returned by the downcall method handle.
551 * <p>
552 * Upon invoking a downcall method handle, the linker provides the following guarantees for any argument
553 * {@code A} of type {@link MemorySegment} whose corresponding layout is an {@linkplain AddressLayout address layout}:
554 * <ul>
555 * <li>{@code A.scope().isAlive() == true}. Otherwise, the invocation throws {@link IllegalStateException};</li>
556 * <li>The invocation occurs in a thread {@code T} such that {@code A.isAccessibleBy(T) == true}.
557 * Otherwise, the invocation throws {@link WrongThreadException}; and</li>
558 * <li>{@code A} is kept alive during the invocation. For instance, if {@code A} has been obtained using a
559 * {@linkplain Arena#ofShared() shared arena}, any attempt to {@linkplain Arena#close() close}
560 * the arena while the downcall method handle is still executing will result in an {@link IllegalStateException}.</li>
561 *</ul>
562 * <p>
563 * Moreover, if the provided function descriptor's return layout is an {@linkplain AddressLayout address layout},
564 * invoking the returned method handle will return a native segment associated with
565 * a fresh scope that is always alive. Under normal conditions, the size of the returned segment is {@code 0}.
566 * However, if the function descriptor's return layout has a {@linkplain AddressLayout#targetLayout() target layout}
567 * {@code T}, then the size of the returned segment is set to {@code T.byteSize()}.
568 * <p>
569 * The returned method handle will throw an {@link IllegalArgumentException} if the {@link MemorySegment}
570 * representing the target address of the foreign function is the {@link MemorySegment#NULL} address. If an argument
571 * is a {@link MemorySegment},whose corresponding layout is an {@linkplain GroupLayout group layout}, the linker might attempt to access the contents of the segment. As such, one of the exceptions specified by the
572 * {@link MemorySegment#get(ValueLayout.OfByte, long)} or the
573 * {@link MemorySegment#copy(MemorySegment, long, MemorySegment, long, long)} methods may be thrown.
574 * The returned method handle will additionally throw {@link NullPointerException} if any argument
575 * passed to it is {@code null}.
576 * <p>
577 * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
578 * Restricted methods are unsafe, and, if used incorrectly, their use might crash
579 * the JVM or, worse, silently result in memory corruption.
580 *
581 * @param function the function descriptor of the target foreign function.
582 * @param options the linker options associated with this linkage request.
583 * @return a downcall method handle.
584 * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
585 * @throws IllegalArgumentException if an invalid combination of linker options is given.
586 * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
587 */
588 @CallerSensitive
589 MethodHandle downcallHandle(FunctionDescriptor function, Option... options);
590
591 /**
592 * Creates an upcall stub which can be passed to other foreign functions as a function pointer, associated with the given
593 * arena. Calling such a function pointer from foreign code will result in the execution of the provided
594 * method handle.
595 * <p>
596 * The returned memory segment's address points to the newly allocated upcall stub, and is associated with
597 * the provided arena. As such, the lifetime of the returned upcall stub segment is controlled by the
598 * provided arena. For instance, if the provided arena is a confined arena, the returned
599 * upcall stub segment will be deallocated when the provided confined arena is {@linkplain Arena#close() closed}.
600 * <p>
601 * An upcall stub argument whose corresponding layout is an {@linkplain AddressLayout address layout}
602 * is a native segment associated with a scope that is always alive.
603 * Under normal conditions, the size of this segment argument is {@code 0}.
604 * However, if the address layout has a {@linkplain AddressLayout#targetLayout() target layout} {@code T}, then the size of the
605 * segment argument is set to {@code T.byteSize()}.
606 * <p>
607 * The target method handle should not throw any exceptions. If the target method handle does throw an exception,
608 * the JVM will terminate abruptly. To avoid this, clients should wrap the code in the target method handle in a
609 * try/catch block to catch any unexpected exceptions. This can be done using the
610 * {@link java.lang.invoke.MethodHandles#catchException(MethodHandle, Class, MethodHandle)} method handle combinator,
611 * and handle exceptions as desired in the corresponding catch block.
612 * <p>
613 * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
614 * Restricted methods are unsafe, and, if used incorrectly, their use might crash
615 * the JVM or, worse, silently result in memory corruption.
616 *
617 * @param target the target method handle.
618 * @param function the upcall stub function descriptor.
619 * @param arena the arena associated with the returned upcall stub segment.
620 * @param options the linker options associated with this linkage request.
621 * @return a zero-length segment whose address is the address of the upcall stub.
622 * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
623 * @throws IllegalArgumentException if the type of {@code target} is incompatible with the
624 * type {@linkplain FunctionDescriptor#toMethodType() derived} from {@code function}.
625 * @throws IllegalArgumentException if it is determined that the target method handle can throw an exception.
626 * @throws IllegalStateException if {@code arena.scope().isAlive() == false}
627 * @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a
628 * thread {@code T}, other than the arena's owner thread.
629 * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
630 */
631 @CallerSensitive
632 MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function, Arena arena, Linker.Option... options);
633
634 /**
635 * Returns a symbol lookup for symbols in a set of commonly used libraries.
636 * <p>
637 * Each {@link Linker} is responsible for choosing libraries that are widely recognized as useful on the OS
638 * and processor combination supported by the {@link Linker}. Accordingly, the precise set of symbols exposed by the
639 * symbol lookup is unspecified; it varies from one {@link Linker} to another.
640 * @implNote It is strongly recommended that the result of {@link #defaultLookup} exposes a set of symbols that is stable over time.
641 * Clients of {@link #defaultLookup()} are likely to fail if a symbol that was previously exposed by the symbol lookup is no longer exposed.
642 * <p>If an implementer provides {@link Linker} implementations for multiple OS and processor combinations, then it is strongly
643 * recommended that the result of {@link #defaultLookup()} exposes, as much as possible, a consistent set of symbols
644 * across all the OS and processor combinations.
645 * @return a symbol lookup for symbols in a set of commonly used libraries.
646 */
647 SymbolLookup defaultLookup();
648
649 /**
650 * {@return an unmodifiable mapping between the names of data types used by the ABI implemented by this linker and their
651 * <em>canonical layouts</em>}
652 * <p>
653 * Each {@link Linker} is responsible for choosing the data types that are widely recognized as useful on the OS
654 * and processor combination supported by the {@link Linker}. Accordingly, the precise set of data type names
655 * and canonical layouts exposed by the linker is unspecified; it varies from one {@link Linker} to another.
656 * @implNote It is strongly recommended that the result of {@link #canonicalLayouts()} exposes a set of symbols that is stable over time.
657 * Clients of {@link #canonicalLayouts()} are likely to fail if a data type that was previously exposed by the linker
658 * is no longer exposed, or if its canonical layout is updated.
659 * <p>If an implementer provides {@link Linker} implementations for multiple OS and processor combinations, then it is strongly
660 * recommended that the result of {@link #canonicalLayouts()} exposes, as much as possible, a consistent set of symbols
661 * across all the OS and processor combinations.
662 */
663 Map<String, MemoryLayout> canonicalLayouts();
664
665 /**
666 * A linker option is used to provide additional parameters to a linkage request.
667 * @since 22
668 */
669 sealed interface Option
670 permits LinkerOptions.LinkerOptionImpl {
671
672 /**
673 * {@return a linker option used to denote the index indicating the start of the variadic arguments passed to the
674 * function described by the function descriptor associated with a downcall linkage request}
675 * <p>
676 * The {@code index} value must conform to {@code 0 <= index <= N}, where {@code N} is the number of argument
677 * layouts of the function descriptor used in conjunction with this linker option. When the {@code index} is:
678 * <ul>
679 * <li>{@code 0}, all arguments passed to the function are passed as variadic arguments</li>
680 * <li>{@code N}, none of the arguments passed to the function are passed as variadic arguments</li>
681 * <li>{@code n}, where {@code 0 < m < N}, the arguments {@code m..N} are passed as variadic arguments</li>
682 * </ul>
683 * It is important to always use this linker option when linking a <a href=Linker.html#variadic-funcs>variadic
684 * function</a>, even if no variadic argument is passed (the second case in the list
685 * above), as this might still affect the calling convention on certain platforms.
686 *
687 * @implNote The index value is validated when making a linkage request, which is when the function descriptor
688 * against which the index is validated is available.
713 * <p>
714 * Captured state can be retrieved from the capture state segment by constructing var handles
715 * from the {@linkplain #captureStateLayout capture state layout}.
716 * <p>
717 * The following example demonstrates the use of this linker option:
718 * {@snippet lang = "java":
719 * MemorySegment targetAddress = ...
720 * Linker.Option ccs = Linker.Option.captureCallState("errno");
721 * MethodHandle handle = Linker.nativeLinker().downcallHandle(targetAddress, FunctionDescriptor.ofVoid(), ccs);
722 *
723 * StructLayout capturedStateLayout = Linker.Option.captureStateLayout();
724 * VarHandle errnoHandle = capturedStateLayout.varHandle(PathElement.groupElement("errno"));
725 * try (Arena arena = Arena.ofConfined()) {
726 * MemorySegment capturedState = arena.allocate(capturedStateLayout);
727 * handle.invoke(capturedState);
728 * int errno = (int) errnoHandle.get(capturedState);
729 * // use errno
730 * }
731 * }
732 *
733 * @apiNote This linker option can not be combined with {@link #critical}.
734 *
735 * @param capturedState the names of the values to save.
736 * @throws IllegalArgumentException if at least one of the provided {@code capturedState} names
737 * is unsupported on the current platform.
738 * @see #captureStateLayout()
739 */
740 static Option captureCallState(String... capturedState) {
741 Set<CapturableState> set = Stream.of(Objects.requireNonNull(capturedState))
742 .map(Objects::requireNonNull)
743 .map(CapturableState::forName)
744 .collect(Collectors.toSet());
745 return new LinkerOptions.CaptureCallState(set);
746 }
747
748 /**
749 * {@return a struct layout that represents the layout of the capture state segment that is passed
750 * to a downcall handle linked with {@link #captureCallState(String...)}}
751 * <p>
752 * The capture state layout is <em>platform-dependent</em> but is guaranteed to be
753 * a {@linkplain StructLayout struct layout} containing only {@linkplain ValueLayout value layouts}
754 * and possibly {@linkplain PaddingLayout padding layouts}.
757 * <li>GetLastError</li>
758 * <li>WSAGetLastError</li>
759 * <li>errno</li>
760 * </ul>
761 * <p>
762 * Clients can obtain the names of the supported captured value layouts as follows:
763 * {@snippet lang = java:
764 * List<String> capturedNames = Linker.Option.captureStateLayout().memberLayouts().stream()
765 * .map(MemoryLayout::name)
766 * .flatMap(Optional::stream)
767 * .toList();
768 * }
769 *
770 * @see #captureCallState(String...)
771 */
772 static StructLayout captureStateLayout() {
773 return CapturableState.LAYOUT;
774 }
775
776 /**
777 * {@return a linker option used to mark a foreign function as <em>critical</em>}
778 * <p>
779 * A critical function is a function that has an extremely short running time in all cases
780 * (similar to calling an empty function), and does not call back into Java (e.g. using an upcall stub).
781 * <p>
782 * Using this linker option is a hint which some implementations may use to apply
783 * optimizations that are only valid for critical functions.
784 * <p>
785 * Using this linker option when linking non-critical functions is likely to have adverse effects,
786 * such as loss of performance, or JVM crashes.
787 */
788 static Option critical() {
789 return LinkerOptions.Critical.INSTANCE;
790 }
791 }
792 }
|