1 ## State of foreign function support
2
3 **January 2022**
4
5 **Maurizio Cimadamore**
6
7 Panama supports foreign functions through the Foreign Linker API, which has been available as an [incubating](https://openjdk.java.net/jeps/11) API since Java [16](https://openjdk.java.net/jeps/389). The central abstraction in the Foreign Linker API is the *foreign linker*, which allows clients to construct *downcall* method handles — that is, method handles whose invocation targets a native function defined in some native library. In other words, Panama foreign function support is completely expressed in terms of Java code and no intermediate native code is required.
8
9 ### Native addresses
10
11 Before we dive into the specifics of the foreign function support, it would be useful to briefly recap some of the main concepts we have learned when exploring the [foreign memory access support](panama_memaccess.md). The Foreign Memory Access API allows client to create and manipulate *memory segments*. A memory segment is a view over a memory source (either on- or off-heap) which is spatially bounded, temporally bounded and thread-confined. The guarantees ensure that dereferencing a segment that has been created by Java code is always *safe*, and can never result in a VM crash, or, worse, in silent memory corruption.
12
13 Now, in the case of memory segments, the above properties (spatial bounds, temporal bounds and confinement) can be known *in full* when the segment is created. But when we interact with native libraries we often receive *raw* pointers; such pointers have no spatial bounds (does a `char*` in C refer to one `char`, or a `char` array of a given size?), no notion of temporal bounds, nor thread-confinement. Raw addresses in our interop support are modeled using the `MemoryAddress` abstraction.
14
15 If clients want to dereference `MemoryAddress`, they can do so *unsafely* in two ways. First, they can use one of the *unsafe* dereference methods provided by `MemoryAddress` (these methods closely mirror those offered by `MemorySegment`); these methods are *restricted* and can only be called if the caller module has been listed in the `--enable-native-access` command-line flag:
16
17 ```java
18 ...
19 MemoryAddress addr = ... //obtain address from native code
20 int x = addr.get(JAVA_INT, 0);
21 ```
22
23 Alternatively, the client can create a memory segment from an address *unsafely*, using the `MemorySegment::ofAddress` factory (which is also a *restricted* method); this can also be useful to inject extra knowledge about spatial bounds which might be available in the native library the client is interacting with:
24
25 ```java
26 MemoryAddress addr = ... //obtain address from native code
27 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
28 MemorySegment segment = MemorySegment.ofAddress(100, scope);
29 int x = segment.get(JAVA_INT, 0);
30 }
31 ```
32
33 Both `MemoryAddress` and `MemorySegment` implement the `Addressable` interface, which is an interface modelling entities that can be passed *by reference* — that is, which can be projected to a `MemoryAddress` instance. In the case of `MemoryAddress` such a projection is the identity function; in the case of a memory segment, the projection returns the `MemoryAddress` instance for the segment's base address. This abstraction allows to pass either memory address or memory segments where an address is expected (this is especially useful when generating native bindings).
34
35 ### Segment allocators
36
37 Idiomatic C code implicitly relies on stack allocation to allow for concise variable declarations; consider this example:
38
39 ```c
40 int arr[] = { 0, 1, 2, 3, 4 };
41 ```
42
43 A variable initializer such as the one above can be implemented as follows, using the Foreign Memory Access API:
44
45 ```java
46 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
47 MemorySegment arr = MemorySegment.allocateNative(MemoryLayout.sequenceLayout(5, JAVA_INT), scope);
48 for (int i = 0 ; i < 5 ; i++) {
49 arr.setAtIndex(JAVA_INT, i, i);
50 }
51 }
52 ```
53
54 There are a number of issues with the above code snippet:
55
56 * compared to the C code, it is more verbose — the native array has to be initialized *element by element*
57 * allocation is very slow compared to C; allocating the `arr` variable now takes a full `malloc`, while in C the variable was simply stack-allocated
58 * when having multiple declarations like the one above, it might become increasingly harder to manage the lifecycle of the various segments
59
60 To address these problems, Panama provides a `SegmentAllocator` abstraction, a functional interface which provides methods to allocate commonly used values. Conveniently, the above code can be rewritten as follows:
61
62 ```java
63 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
64 SegmentAllocator allocator = SegmentAllocator.nativeAllocator(scope);
65 MemorySegment arr = allocator.allocateArray(JAVA_INT, new int[] { 0, 1, 2, 3, 4 });
66 } // 'arr' is released here
67 ```
68
69 In the above code, the resource scope is used to build a *native* allocator (that is, an allocator built on top of `MemorySegment::allocateNative`). The segment allocator is then used to create a native array, initialized to the values `{ 0, 1, 2, 3, 4 }`. The array initialization is more efficient, compared to the previous snippet, as the Java array is copied *in bulk* into the memory region associated with the newly allocated memory segment. The returned segment is associated with the scope which performed the allocation, meaning that the segment will no longer be accessible after the try-with-resource construct.
70
71 Custom segment allocators are also critical to achieve optimal allocation performance; for this reason, a number of predefined allocators are available via factories in the `SegmentAllocator` interface. For instance, it is possible to create an arena-based allocator, as follows:
72
73 ```java
74 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
75 SegmentAllocator allocator = SegmentAllocator.newNativeArena(scope);
76 for (int i = 0 ; i < 100 ; i++) {
77 allocator.allocateArray(JAVA_INT, new int[] { 0, 1, 2, 3, 4 });
78 }
79 ...
80 } // all memory allocated is released here
81 ```
82
83 The above code creates a confined scope; inside the *try-with-resources*, a new unbounded arena allocation is created, associated with the existing scope. The allocator will pre-allocate a native segment, of a specific size, and respond to allocation requests by returning different slices of the pre-allocated segment. If the pre-allocated segment does not have sufficient space to accommodate a new allocation request, a new segment will be allocated. If the scope associated with the arena allocator is closed, all memory segments created by the allocator (see the body of the `for` loop) will be deallocated at once. This idiom combines the advantages of deterministic deallocation (provided by the Memory Access API) with a more flexible and scalable allocation scheme, and can be very useful when writing large applications.
84
85 For these reasons, all the methods in the Foreign Linker API which *produce* memory segments (see `VaList::nextVarg`), allow an optional allocator to be provided by user code — this is key in ensuring that an application using the Foreign Linker API achieves optimal allocation performances, especially in non-trivial use cases.
86
87 ### Symbol lookups
88
89 The first ingredient of any foreign function support is a mechanism to lookup symbols in native libraries. In traditional Java/JNI, this is done via the `System::loadLibrary` and `System::load` methods. Unfortunately, these methods do not provide a way for clients to obtain the *address* associated with a given library symbol. For this reason, the Foreign Linker API introduces a new abstraction, namely `SymbolLookup` (similar in spirit to a method handle lookup), which provides capabilities to lookup named symbols; we can obtain a symbol lookup in 2 different ways <a href="#1"><sup>1</sup></a>:
90
91 * `SymbolLookup::loaderLookup` — creates a symbol lookup which can be used to search symbols in all the libraries loaded by the caller's classloader (e.g. using `System::loadLibrary` or `System::load`)
92 * By obtaining a `CLinker` instance. In fact, `CLinker` implements the `SymbolLookup` interface, and can be used to look up platform-specific symbols in the standard C library.
93
94 Once a lookup has been obtained, a client can use it to retrieve handles to library symbols (either global variables or functions) using the `lookup(String)` method, which returns an `Optional<NativeSymbol>`. `NativeSymbol` is a class used to model references to library symbols, which implements the `Addressable` interface.
95
96 For instance, the following code can be used to look up the `clang_getClangVersion` function provided by the `clang` library:
97
98 ```java
99 System.loadLibrary("clang");
100 NativeSymbol clangVersion = SymbolLookup.loaderLookup().lookup("clang_getClangVersion").get();
101 ```
102
103 ### C Linker
104
105 At the core of Panama foreign function support we find the `CLinker` abstraction. This abstraction plays a dual role: first, for downcalls, it allows modelling native function calls as plain `MethodHandle` calls (see `CLinker::downcallHandle`); second, for upcalls, it allows to convert an existing `MethodHandle` (which might point to some Java method) into a `NativeSymbol` which could then be passed to native functions as a function pointer (see `CLinker::upcallStub`):
106
107 ```java
108 interface CLinker {
109 MethodHandle downcallHandle(NativeSymbol func, FunctionDescriptor function);
110 NativeSymbol upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope);
111 ... // some overloads omitted here
112
113 static CLinker systemCLinker() { ... }
114 }
115 ```
116
117 Both functions take a `FunctionDescriptor` instance — essentially an aggregate of memory layouts which is used to describe the argument and return types of a foreign function in full. Supported layouts are *value layouts* (for scalars and pointers) and *group layouts* (for structs/unions). Each layout in a function descriptor is associated with a carrier Java type (see table below); together, all the carrier types associated with layouts in a function descriptor will determine a unique Java `MethodType` — that is, the Java signature that clients will be using when interacting with said downcall handles, or upcall stubs.
118
119 The following table shows the mapping between C types, layouts and Java carriers under the Linux/macOS foreign linker implementation; note that the mappings can be platform dependent: on Windows/x64, the C type `long` is 32-bit, so the `JAVA_INT` layout (and the Java carrier `int.class`) would have to be used instead:
120
121 | C type | Layout | Java carrier |
122 | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------------------------------- |
123 | `bool` | `JAVA_BOOLEAN` | `byte` |
124 | `char` | `JAVA_BYTE` | `byte` |
125 | `short` | `JAVA_SHORT` | `short`, `char` |
126 | `int` | `JAVA_INT` | `int` |
127 | `long` | `JAVA_LONG` | `long` |
128 | `long long` | `JAVA_LONG` | `long` |
129 | `float` | `JAVA_FLOAT` | `float` |
130 | `double` | `JAVA_DOUBLE` | `double` |
131 | `char*`<br />`int**`<br /> ... | `ADDRESS` | `Addressable`<br />`MemoryAddress` |
132 | `struct Point { int x; int y; };`<br />`union Choice { float a; int b; };`<br />... | `MemoryLayout.structLayout(...)`<br />`MemoryLayout.unionLayout(...)`<br /> | `MemorySegment` |
133
134 Note that all C pointer types are modelled using the `ADDRESS` layout constant; the Java carrier type associated with this layout is either `Addressable` or `MemoryAddress` depending on where the layout occurs in the function descriptor. For downcall method handles, for instance, the `Addressable` carrier is used when the `ADDRESS` layout occurs in a parameter position of the corresponding function descriptor. This maximizes applicability of a downcall method handles, ensuring that any implementation of `Addressable` (e.g. memory segments, memory address, upcall stubs, va lists) can be passed where a pointer is expected.
135
136 A tool, such as `jextract`, will generate all the required C layouts (for scalars and structs/unions) *automatically*, so that clients do not have to worry about platform-dependent details such as sizes, alignment constraints and padding.
137
138 ### Downcalls
139
140 We will now look at how foreign functions can be called from Java using the foreign linker abstraction. Assume we wanted to call the following function from the standard C library:
141
142 ```c
143 size_t strlen(const char *s);
144 ```
145
146 In order to do that, we have to:
147
148 * lookup the `strlen` symbol
149 * describe the signature of the C function using a function descriptor
150
151 * create a *downcall* native method handle with the above information, using the standard C foreign linker
152
153 Here's an example of how we might want to do that (a full listing of all the examples in this and subsequent sections will be provided in the [appendix](#appendix-full-source-code)):
154
155 ```java
156 CLinker linker = CLinker.systemCLinker();
157 MethodHandle strlen = linker.downcallHandle(
158 linker.lookup("strlen").get(),
159 FunctionDescriptor.of(JAVA_LONG, ADDRESS)
160 );
161 ```
162
163 Note that, since the function `strlen` is part of the standard C library, which is loaded with the VM, we can just use the system lookup to look it up. The rest is pretty straightforward — the only tricky detail is how to model `size_t`: typically this type has the size of a pointer, so we can use `JAVA_LONG` both Linux and Windows. On the Java side, we model the `size_t` using a `long` and the pointer is modelled using an `Addressable` parameter.
164
165 Once we have obtained the downcall method handle, we can just use it as any other method handle<a href="#2"><sup>2</sup></a>:
166
167 ```java
168 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
169 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
170 long len = strlen.invoke(malloc.allocateUtf8String("Hello")); // 5
171 }
172 ```
173
174 Here we are using a native segment allocator to convert a Java string into an off-heap memory segment which contains a `NULL` terminated C string. We then pass that segment to the method handle and retrieve our result in a Java `long`. Note how all this is possible *without* any piece of intervening native code — all the interop code can be expressed in (low level) Java. Note also how we use an explicit resource scope to control the lifecycle of the allocated C string, which ensures timely deallocation of the memory segment holding the native string.
175
176 The `CLinker` interface also supports linking of native functions without an address known at link time; when that happens, an address (of type `Addressable`) must be provided when the method handle returned by the linker is invoked — this is very useful to support *virtual calls*. For instance, the above code can be rewritten as follows:
177
178 ```java
179 MethodHandle strlen_virtual = linker.downcallHandle( // address parameter missing!
180 FunctionDescriptor.of(JAVA_LONG, ADDRESS)
181 );
182
183 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
184 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
185 long len = strlen_virtual.invoke(
186 linker.lookup("strlen").get() // address provided here!
187 malloc.allocateUtf8String("Hello")
188 ); // 5
189 }
190 ```
191
192 It is important to note that, albeit the interop code is written in Java, the above code can *not* be considered 100% safe. There are many arbitrary decisions to be made when setting up downcall method handles such as the one above, some of which might be obvious to us (e.g. how many parameters does the function take), but which cannot ultimately be verified by the Panama runtime. After all, a symbol in a dynamic library is nothing but a numeric offset and, unless we are using a shared library with debugging information, no type information is attached to a given library symbol. This means that the Panama runtime has to *trust* the function descriptor passed in<a href="#3"><sup>3</sup></a>; for this reason, access to the foreign linker is a restricted operation, which can only be performed if the requesting module is listed in the `--enable-native-access` command-line flag.
193
194 If a native function returns a raw pointer (of type `MemoryAddress`), it is then up to the client to make sure that the address is being accessed and disposed of correctly, compatibly with the requirements of the underlying native library. If a native function returns a struct by value, a *fresh*, memory segment is allocated off-heap and returned to the caller. In such cases, the downcall method handle will feature an additional prefix `SegmentAllocator` (see above) parameter which will be used by the downcall method handle to allocate the returned segment. The allocation will likely associate the segment with a *resource scope* that is known to the caller and which can then be used to release the memory associated with that segment.
195
196 Performance-wise, the reader might ask how efficient calling a foreign function using a native method handle is; the answer is *very*. The JVM comes with some special support for native method handles, so that, if a give method handle is invoked many times (e.g, inside a *hot* loop), the JIT compiler might decide to generate a snippet of assembly code required to call the native function, and execute that directly. In most cases, invoking native function this way is as efficient as doing so through JNI.
197
198 ### Upcalls
199
200 Sometimes, it is useful to pass Java code as a function pointer to some native function; we can achieve that by using foreign linker support for upcalls. To demonstrate this, let's consider the following function from the C standard library:
201
202 ```c
203 void qsort(void *base, size_t nmemb, size_t size,
204 int (*compar)(const void *, const void *));
205 ```
206
207 The `qsort` function can be used to sort the contents of an array, using a custom comparator function — `compar` — which is passed as a function pointer. To be able to call the `qsort` function from Java we have first to create a downcall method handle for it:
208
209 ```java
210 CLinker linker = CLinker.systemCLinker();
211 MethodHandle qsort = linker.downcallHandle(
212 CLinker.systemLookup().lookup("qsort").get(),
213 FunctionDescriptor.ofVoid(ADDRESS, JAVA_LONG, JAVA_LONG, ADDRESS)
214 );
215 ```
216
217 As before, we use `JAVA_LONG` and `long.class` to map the C `size_t` type, and `ADDRESS` for both the first pointer parameter (the array pointer) and the last parameter (the function pointer).
218
219 This time, in order to invoke the `qsort` downcall handle, we need a *function pointer* to be passed as the last parameter; this is where the upcall support in foreign linker comes in handy, as it allows us to create a function pointer out of an existing method handle. First, let's write a function that can compare two int elements (passed as pointers):
220
221 ```java
222 class Qsort {
223 static int qsortCompare(MemoryAddress addr1, MemoryAddress addr2) {
224 return addr1.get(JAVA_INT, 0) - addr2.get(JAVA_INT, 0);
225 }
226 }
227 ```
228
229 Here we can see that the function is performing some *unsafe* dereference of the pointer contents.
230
231 Now let's create a method handle pointing to the comparator function above:
232
233 ```java
234 FunctionDescriptor comparDesc = FunctionDescriptor.of(JAVA_INT, ADDRESS, ADDRESS);
235 MethodHandle comparHandle = MethodHandles.lookup()
236 .findStatic(Qsort.class, "qsortCompare",
237 CLinker.upcallType(comparDesc));
238 ```
239
240 To do that, we first create a function descriptor for the function pointer type, and then we use the `CLinker::upcallType` to turn that function descriptor into a suitable `MethodType` instance to be used in a method handle lookup. Now that we have a method handle for our Java comparator function, we finally have all the ingredients to create an upcall stub, and pass it to the `qsort` downcall handle:
241
242 ```java
243 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
244 NativeSymbol comparFunc = linker.upcallStub(
245 comparHandle, comparDesc, scope);
246 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
247 MemorySegment array = malloc.allocateArray(new int[] { 0, 9, 3, 4, 6, 5, 1, 8, 2, 7 }));
248 qsort.invoke(array, 10L, 4L, comparFunc);
249 int[] sorted = array.toArray(JAVA_INT); // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
250 }
251 ```
252
253 The above code creates an upcall stub — `comparFunc` — a function pointer that can be used to invoke our Java comparator function, of type `NativeSymbol`. The upcall stub is associated with the provided resource scope instance; this means that the stub will be uninstalled when the resource scope is closed.
254
255 The snippet then creates an off-heap array from a Java array (using a `SegmentAllocator`), which is then passed to the `qsort` handle, along with the comparator function we obtained from the foreign linker. As a side effect, after the call, the contents of the off-heap array will be sorted (as instructed by our comparator function, written in Java). We can than extract a new Java array from the segment, which contains the sorted elements. This is a more advanced example, but one that shows how powerful the native interop support provided by the foreign linker abstraction is, allowing full bidirectional interop support between Java and native.
256
257 ### Varargs
258
259 Some C functions are *variadic* and can take an arbitrary number of arguments. Perhaps the most common example of this is the `printf` function, defined in the C standard library:
260
261 ```c
262 int printf(const char *format, ...);
263 ```
264
265 This function takes a format string, which features zero or more *holes*, and then can take a number of additional arguments that is identical to the number of holes in the format string.
266
267 The foreign function support can support variadic calls, but with a caveat: the client must provide a specialized Java signature, and a specialized description of the C signature. For instance, let's say we wanted to model the following C call:
268
269 ```C
270 printf("%d plus %d equals %d", 2, 2, 4);
271 ```
272
273 To do this using the foreign function support provided by Panama we would have to build a *specialized* downcall handle for that call shape, using the `FunctionDescriptor::asVariadic` to inject additional variadic layouts, as follows:
274
275 ```java
276 CLinker linker = CLinker.systemCLinker();
277 MethodHandle printf = linker.downcallHandle(
278 linker.lookup("printf").get(),
279 FunctionDescriptor.of(JAVA_INT, ADDRESS).asVariadic(JAVA_INT, JAVA_INT, JAVA_INT)
280 );
281 ```
282
283 Then we can call the specialized downcall handle as usual:
284
285 ```java
286 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
287 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
288 printf.invoke(malloc.allocateUtf8String("%d plus %d equals %d"), 2, 2, 4); //prints "2 plus 2 equals 4"
289 }
290 ```
291
292 While this works, and provides optimal performance, there are some drawbacks:
293
294 * If the variadic function needs to be called with many shapes, we have to create many downcall handles
295 * while this approach works for downcalls (since the Java code is in charge of determining which and how many arguments should be passed) it fails to scale to upcalls; in that case, the call comes from native code, so we have no way to guarantee that the shape of the upcall stub we have created will match that required by the native function.
296
297 To add flexibility, the standard C foreign linker comes equipped with support for C variable argument lists — or `va_list`. When a variadic function is called, C code has to unpack the variadic arguments by creating a `va_list` structure, and then accessing the variadic arguments through the `va_list` one by one (using the `va_arg` macro). To facilitate interop between standard variadic functions and `va_list` many C library functions in fact define *two* flavors of the same function, one using standard variadic signature, one using an extra `va_list` parameter. For instance, in the case of `printf` we can find that a `va_list`-accepting function performing the same task is also defined:
298
299 ```c
300 int vprintf(const char *format, va_list ap);
301 ```
302
303 The behavior of this function is the same as before — the only difference is that the ellipsis notation `...` has been replaced with a single `va_list` parameter; in other words, the function is no longer variadic.
304
305 It is indeed fairly easy to create a downcall for `vprintf`:
306
307 ```java
308 CLinker linker = CLinker.systemCLinker();
309 MethodHandle vprintf = linker.downcallHandle(
310 linker.lookup("vprintf").get(),
311 FunctionDescriptor.of(JAVA_INT, ADDRESS, ADDRESS));
312 ```
313
314 Here, the layout of a `va_list` parameter is simply `ADDRESS` (as va lists are passed by reference). To call the `vprintf` handle we need to create an instance of `VaList` which contains the arguments we want to pass to the `vprintf` function — we can do so, as follows:
315
316 ```java
317 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
318 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
319 vprintf.invoke(
320 malloc.allocateUtf8String("%d plus %d equals %d", scope),
321 VaList.make(builder ->
322 builder.addVarg(JAVA_INT, 2)
323 .addVarg(JAVA_INT, 2)
324 .addVarg(JAVA_INT, 4), scope)
325 ); //prints "2 plus 2 equals 4"
326 ```
327
328 While the callee has to do more work to call the `vprintf` handle, note that that now we're back in a place where the downcall handle `vprintf` can be shared across multiple callees. Note that both the format string and the `VaList` are associated with the given resource scope — this means that both will remain valid throughout the native function call.
329
330 Using `VaList` also scales to upcall stubs — it is therefore possible for clients to create upcalls stubs which take a `VaList` and then, from the Java upcall, read the arguments packed inside the `VaList` one by one using the methods provided by the `VaList` API (e.g. `VaList::nextVarg(ValueLayout.OfInt)`), which mimics the behavior of the C `va_arg` macro.
331
332 ### Appendix: full source code
333
334 The full source code containing most of the code shown throughout this document can be seen below:
335
336 ```java
337 import jdk.incubator.foreign.Addressable;
338 import jdk.incubator.foreign.CLinker;
339 import jdk.incubator.foreign.FunctionDescriptor;
340 import jdk.incubator.foreign.SymbolLookup;
341 import jdk.incubator.foreign.MemoryAddress;
342 import jdk.incubator.foreign.MemorySegment;
343 import jdk.incubator.foreign.NativeSymbol;
344 import jdk.incubator.foreign.ResourceScope;
345 import jdk.incubator.foreign.SegmentAllocator;
346 import jdk.incubator.foreign.VaList;
347
348 import java.lang.invoke.MethodHandle;
349 import java.lang.invoke.MethodHandles;
350 import java.lang.invoke.MethodType;
351 import java.util.Arrays;
352
353 import static jdk.incubator.foreign.ValueLayout.*;
354
355 public class Examples {
356
357 static CLinker LINKER = CLinker.systemCLinker();
358
359 public static void main(String[] args) throws Throwable {
360 strlen();
361 strlen_virtual();
362 qsort();
363 printf();
364 vprintf();
365 }
366
367 public static void strlen() throws Throwable {
368 MethodHandle strlen = LINKER.downcallHandle(
369 LINKER.lookup("strlen").get(),
370 FunctionDescriptor.of(JAVA_LONG, ADDRESS)
371 );
372
373 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
374 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
375 MemorySegment hello = malloc.allocateUtf8String("Hello");
376 long len = (long) strlen.invoke(hello); // 5
377 System.out.println(len);
378 }
379 }
380
381 public static void strlen_virtual() throws Throwable {
382 MethodHandle strlen_virtual = LINKER.downcallHandle(
383 FunctionDescriptor.of(JAVA_LONG, ADDRESS)
384 );
385
386 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
387 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
388 MemorySegment hello = malloc.allocateUtf8String("Hello");
389 long len = (long) strlen_virtual.invoke(
390 LINKER.lookup("strlen").get(),
391 hello); // 5
392 System.out.println(len);
393 }
394 }
395
396 static class Qsort {
397 static int qsortCompare(MemoryAddress addr1, MemoryAddress addr2) {
398 return addr1.get(JAVA_INT, 0) - addr2.get(JAVA_INT, 0);
399 }
400 }
401
402 public static void qsort() throws Throwable {
403 MethodHandle qsort = LINKER.downcallHandle(
404 LINKER.lookup("qsort").get(),
405 FunctionDescriptor.ofVoid(ADDRESS, JAVA_LONG, JAVA_LONG, ADDRESS)
406 );
407 FunctionDescriptor comparDesc = FunctionDescriptor.of(JAVA_INT, ADDRESS, ADDRESS);
408 MethodHandle comparHandle = MethodHandles.lookup()
409 .findStatic(Qsort.class, "qsortCompare",
410 CLinker.upcallType(comparDesc));
411
412 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
413 NativeSymbol comparFunc = LINKER.upcallStub(
414 comparHandle, comparDesc, scope);
415
416 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
417 MemorySegment array = malloc.allocateArray(JAVA_INT, new int[] { 0, 9, 3, 4, 6, 5, 1, 8, 2, 7 });
418 qsort.invoke(array, 10L, 4L, comparFunc);
419 int[] sorted = array.toArray(JAVA_INT); // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
420 System.out.println(Arrays.toString(sorted));
421 }
422 }
423
424 public static void printf() throws Throwable {
425 MethodHandle printf = LINKER.downcallHandle(
426 LINKER.lookup("printf").get(),
427 FunctionDescriptor.of(JAVA_INT, ADDRESS).asVariadic(JAVA_INT, JAVA_INT, JAVA_INT)
428 );
429 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
430 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
431 MemorySegment s = malloc.allocateUtf8String("%d plus %d equals %d\n");
432 printf.invoke(s, 2, 2, 4);
433 }
434 }
435
436 public static void vprintf() throws Throwable {
437
438 MethodHandle vprintf = LINKER.downcallHandle(
439 LINKER.lookup("vprintf").get(),
440 FunctionDescriptor.of(JAVA_INT, ADDRESS, ADDRESS));
441
442 try (ResourceScope scope = ResourceScope.newConfinedScope()) {
443 SegmentAllocator malloc = SegmentAllocator.nativeAllocator(scope);
444 MemorySegment s = malloc.allocateUtf8String("%d plus %d equals %d\n");
445 VaList vlist = VaList.make(builder ->
446 builder.addVarg(JAVA_INT, 2)
447 .addVarg(JAVA_INT, 2)
448 .addVarg(JAVA_INT, 4), scope);
449 vprintf.invoke(s, vlist);
450 }
451 }
452 }
453 ```
454
455
456
457 * <a id="1"/>(<sup>1</sup>):<small> Users might add more ways to obtain a symbol lookup — for instance: `SymbolLookup libraryLookup(String libName, ResourceScope scope)`. This would allow developers to load a library and associate its lifecycle with a `ResourceScope` (rather than a classloader). That is, when the scope is closed, the library will be unloaded. This is possible, as `CLinker` guarantees that memory addresses used by a downcall method handle cannot be released while the downcall method handle is being invoked.</small>
458 * <a id="2"/>(<sup>2</sup>):<small> For simplicity, the examples shown in this document use `MethodHandle::invoke` rather than `MethodHandle::invokeExact`; by doing so we avoid having to cast by-reference arguments back to `Addressable`. With `invokeExact` the method handle invocation should be rewritten as `strlen.invokeExact((Addressable)malloc.allocateUtf8String("Hello"));`</small>
459 * <a id="3"/>(<sup>3</sup>):<small> In reality this is not entirely new; even in JNI, when you call a `native` method the VM trusts that the corresponding implementing function in C will feature compatible parameter types and return values; if not a crash might occur.</small>