public sealed interface Linker
Linker
is a preview API of the Java platform. Foreign functions typically reside in libraries that can be loaded on-demand. Each library conforms to a specific ABI (Application Binary Interface). An ABI is a set of calling conventions and data types associated with the compiler, OS, and processor where the library was built. For example, a C compiler on Linux/x64 usually builds libraries that conform to the SystemV ABI.
A linker has detailed knowledge of the calling conventions and data types used by a specific ABI. For any library which conforms to that ABI, the linker can mediate between Java code running in the JVM and foreign functions in the library. In particular:
libc
and libm
. The functions in these libraries are exposed via a symbol lookup. strlen
function defined in the standard C library: size_t strlen(const char *s);
strlen
is obtained, using the native linker, as follows: Linker linker = Linker.nativeLinker();
MethodHandle strlen = linker.downcallHandle(
linker.defaultLookup().find("strlen").orElseThrow(),
FunctionDescriptor.of(JAVA_LONG, ADDRESS)
);
strlen
native function. That address is then passed, along with a platform-dependent description of the signature of the function expressed as a FunctionDescriptor
PREVIEW (more on that below) to the native linker's downcallHandle(MemorySegment, FunctionDescriptor, Option...)
method. The obtained downcall method handle is then invoked as follows: try (Arena arena = Arena.ofConfined()) {
MemorySegment str = arena.allocateUtf8String("Hello");
long len = (long) strlen.invokeExact(str); // 5
}
function descriptor
PREVIEW, defines the layouts associated with the parameter types and return type (if any) of the C function. Scalar C types such as bool
, int
are modelled as value layoutsPREVIEW of a suitable carrier. The mapping between a scalar type and its corresponding layout is dependent on the ABI implemented by the native linker. For instance, the C type long
maps to the layout constant ValueLayout.JAVA_LONG
PREVIEW on Linux/x64, but maps to the layout constant ValueLayout.JAVA_INT
PREVIEW on Windows/x64. Similarly, the C type size_t
maps to the layout constant ValueLayout.JAVA_LONG
PREVIEW on 64-bit platforms, but maps to the layout constant ValueLayout.JAVA_INT
PREVIEW on 32-bit platforms.
Composite types are modelled as group layoutsPREVIEW. More specifically, a C struct
type maps to a struct layoutPREVIEW, whereas a C union
type maps to a union
layout
PREVIEW. When defining a struct or union layout, clients must pay attention to the size and alignment constraint of the corresponding composite type definition in C. For instance, padding between two struct fields must be modelled explicitly, by adding an adequately sized padding layoutPREVIEW member to the resulting struct layout.
Finally, pointer types such as int**
and int(*)(size_t*, size_t*)
are modelled as address layoutsPREVIEW. When the spatial bounds of the pointer type are known statically, the address layout can be associated with a target layoutPREVIEW. For instance, a pointer that is known to point to a C int[2]
array can be modelled as an address layout whose target layout is a sequence layout whose element count is 2, and whose element type is ValueLayout.JAVA_INT
PREVIEW.
The following table shows some examples of how C types are modelled in Linux/x64:
C type Layout Java type bool
ValueLayout.JAVA_BOOLEAN
PREVIEWboolean
char
ValueLayout.JAVA_BYTE
PREVIEWbyte
short
ValueLayout.JAVA_SHORT
PREVIEWshort
int
ValueLayout.JAVA_INT
PREVIEWint
long
ValueLayout.JAVA_LONG
PREVIEWlong
long long
ValueLayout.JAVA_LONG
PREVIEWlong
float
ValueLayout.JAVA_FLOAT
PREVIEWfloat
double
ValueLayout.JAVA_DOUBLE
PREVIEWdouble
size_t
ValueLayout.JAVA_LONG
PREVIEWlong
char*
,int**
,struct Point*
ValueLayout.ADDRESS
PREVIEWMemorySegment
PREVIEWint (*ptr)[10]
ValueLayout.ADDRESS.withTargetLayout( MemoryLayout.sequenceLayout(10, ValueLayout.JAVA_INT) );MemorySegment
PREVIEWstruct Point { int x; long y; };
MemoryLayout.structLayout( ValueLayout.JAVA_INT.withName("x"), MemoryLayout.paddingLayout(32), ValueLayout.JAVA_LONG.withName("y") );MemorySegment
PREVIEWunion Choice { float a; int b; }
MemoryLayout.unionLayout( ValueLayout.JAVA_FLOAT.withName("a"), ValueLayout.JAVA_INT.withName("b") );MemorySegment
PREVIEW
All native linker implementations operate on a subset of memory layouts. More formally, a layout L
is supported by a native linker NL
if:
L
is a value layout V
and V.withoutName()
is equalPREVIEW to one of the following layout constants:
L
is an address layout A
and A.withoutTargetLayout().withoutName()
is equalPREVIEW to ValueLayout.ADDRESS
PREVIEW
L
is a sequence layout S
and all the following conditions hold: S
is set to its natural alignment, andS.elementLayout()
is a layout supported by NL
.L
is a group layout G
and all the following conditions hold: G
is set to its natural alignment;G
is a multiple of its alignment constraint;G.memberLayouts()
is either a padding layout or a layout supported by NL
, andG
does not contain padding other than what is strictly required to align its non-padding layout elements, or to satisfy (2).void qsort(void *base, size_t nmemb, size_t size,
int (*compar)(const void *, const void *));
qsort
function can be used to sort the contents of an array, using a custom comparator function which is passed as a function pointer (the compar
parameter). To be able to call the qsort
function from Java, we must first create a downcall method handle for it, as follows: Linker linker = Linker.nativeLinker();
MethodHandle qsort = linker.downcallHandle(
linker.defaultLookup().find("qsort").orElseThrow(),
FunctionDescriptor.ofVoid(ADDRESS, JAVA_LONG, JAVA_LONG, ADDRESS)
);
ValueLayout.JAVA_LONG
PREVIEW to map the C type size_t
type, and ValueLayout.ADDRESS
PREVIEW for both the first pointer parameter (the array pointer) and the last parameter (the function pointer). To invoke the qsort
downcall handle obtained above, we need a function pointer to be passed as the last parameter. That is, we need to create a function pointer out of an existing method handle. First, let's write a Java method that can compare two int elements passed as pointers (i.e. as memory segmentsPREVIEW):
class Qsort {
static int qsortCompare(MemorySegment elem1, MemorySegment elem2) {
return Integer.compare(elem1.get(JAVA_INT, 0), elem2.get(JAVA_INT, 0));
}
}
FunctionDescriptor comparDesc = FunctionDescriptor.of(JAVA_INT,
ADDRESS.withTargetLayout(JAVA_INT),
ADDRESS.withTargetLayout(JAVA_INT));
MethodHandle comparHandle = MethodHandles.lookup()
.findStatic(Qsort.class, "qsortCompare",
comparDesc.toMethodType());
int[]
array, we can specify ValueLayout.JAVA_INT
PREVIEW as the target layout for the address layouts of both parameters. This will allow the comparator method to access the contents of the array elements to be compared. We then turnPREVIEW that function descriptor into a suitable method type which we then use to look up the comparator method handle. We can now create an upcall stub which points to that method, and pass it, as a function pointer, to the qsort
downcall handle, as follows: try (Arena arena = Arena.ofConfined()) {
MemorySegment comparFunc = linker.upcallStub(comparHandle, comparDesc, arena);
MemorySegment array = arena.allocateArray(JAVA_INT, 0, 9, 3, 4, 6, 5, 1, 8, 2, 7);
qsort.invokeExact(array, 10L, 4L, comparFunc);
int[] sorted = array.toArray(JAVA_INT); // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
}
qsort
method handle along with the comparator function we obtained from the native linker. After the invocation, the contents of the off-heap array will be sorted according to our comparator function, written in Java. We then extract a new Java array from the segment, which contains the sorted elements. void *malloc(size_t size);
malloc
function allocates a region of memory of given size, and returns a pointer to that region of memory, which is later deallocated using another function from the C standard library: void free(void *ptr);
free
function takes a pointer to a region of memory and deallocates that region. In this section we will show how to interact with these native functions, with the aim of providing a safe allocation API (the approach outlined below can of course be generalized to allocation functions other than malloc
and free
). First, we need to create the downcall method handles for malloc
and free
, as follows:
Linker linker = Linker.nativeLinker();
MethodHandle malloc = linker.downcallHandle(
linker.defaultLookup().find("malloc").orElseThrow(),
FunctionDescriptor.of(ADDRESS, JAVA_LONG)
);
MethodHandle free = linker.downcallHandle(
linker.defaultLookup().find("free").orElseThrow(),
FunctionDescriptor.ofVoid(ADDRESS)
);
malloc
) is invoked using a downcall method handle, the Java runtime has no insight into the size or the lifetime of the returned pointer. Consider the following code: MemorySegment segment = (MemorySegment)malloc.invokeExact(100);
malloc
downcall method handle is zero. Moreover, the scope of the returned segment is a fresh scope that is always alive. To provide safe access to the segment, we must, unsafely, resize the segment to the desired size (100, in this case). It might also be desirable to attach the segment to some existing arenaPREVIEW, so that the lifetime of the region of memory backing the segment can be managed automatically, as for any other native segment created directly from Java code. Both of these operations are accomplished using the restricted method MemorySegment.reinterpret(long, Arena, Consumer)
PREVIEW, as follows: MemorySegment allocateMemory(long byteSize, Arena arena) throws Throwable {
MemorySegment segment = (MemorySegment) malloc.invokeExact(byteSize); // size = 0, scope = always alive
return segment.reinterpret(byteSize, arena, s -> {
try {
free.invokeExact(s);
} catch (Throwable e) {
throw new RuntimeException(e);
}
}); // size = byteSize, scope = arena.scope()
}
allocateMemory
method defined above accepts two parameters: a size and an arena. The method calls the malloc
downcall method handle, and unsafely reinterprets the returned segment, by giving it a new size (the size passed to the allocateMemory
method) and a new scope (the scope of the provided arena). The method also specifies a cleanup action to be executed when the provided arena is closed. Unsurprisingly, the cleanup action passes the segment to the free
downcall method handle, to deallocate the underlying region of memory. We can use the allocateMemory
method as follows: try (Arena arena = Arena.ofConfined()) {
MemorySegment segment = allocateMemory(100, arena);
} // 'free' called here
allocateMemory
acts as any other segment managed by the confined arena. More specifically, the obtained segment has the desired size, can only be accessed by a single thread (the thread which created the confined arena), and its lifetime is tied to the surrounding try-with-resources block. ...
) at the end of the formal parameter list, such as: void foo(int x, ...);
void foo();
...
or empty formal parameter list with a list of variadic parameters of a fixed number and type. It should be noted that values passed as variadic arguments undergo default argument promotion in C. For instance, the following argument promotions are applied:
_Bool
-> unsigned int
[signed] char
-> [signed] int
[signed] short
-> [signed] int
float
-> double
The native linker only supports linking the specialized form of a variadic function. A variadic function in its specialized form can be linked using a function descriptor describing the specialized form. Additionally, the Linker.Option.firstVariadicArg(int)
PREVIEW linker option must be provided to indicate the first variadic parameter in the parameter list. The corresponding argument layout (if any), and all following argument layouts in the specialized function descriptor, are called variadic argument layouts. For a prototype-less function, the index passed to Linker.Option.firstVariadicArg(int)
PREVIEW should always be 0
.
The native linker will reject an attempt to link a specialized function descriptor with any variadic argument layouts corresponding to a C type that would be subject to default argument promotion (as described above). Exactly which layouts will be rejected is platform specific, but as an example: on Linux/x64 the layouts ValueLayout.JAVA_BOOLEAN
PREVIEW, ValueLayout.JAVA_BYTE
PREVIEW, ValueLayout.JAVA_CHAR
PREVIEW, ValueLayout.JAVA_SHORT
PREVIEW, and ValueLayout.JAVA_FLOAT
PREVIEW will be rejected.
A well-known variadic function is the printf
function, defined in the C standard library:
int printf(const char *format, ...);
printf("%d plus %d equals %d", 2, 2, 4);
(char*, int, int, int)
as the format string accepts three integer parameters. We then need to use a linker optionPREVIEW to specify the position of the first variadic layout in the provided function descriptor (starting from 0). In this case, since the first parameter is the format string (a non-variadic argument), the first variadic index needs to be set to 1, as follows: Linker linker = Linker.nativeLinker();
MethodHandle printf = linker.downcallHandle(
linker.defaultLookup().find("printf").orElseThrow(),
FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_INT, JAVA_INT, JAVA_INT),
Linker.Option.firstVariadicArg(1) // first int is variadic
);
try (Arena arena = Arena.ofConfined()) {
int res = (int)printf.invokeExact(arena.allocateUtf8String("%d plus %d equals %d"), 2, 2, 4); //prints "2 plus 2 equals 4"
}
When an upcall stub is passed to a foreign function, a JVM crash might occur, if the foreign code casts the function pointer associated with the upcall stub to a type that is incompatible with the type of the upcall stub, and then attempts to invoke the function through the resulting function pointer. Moreover, if the method handle associated with an upcall stub returns a memory segmentPREVIEW, clients must ensure that this address cannot become invalid after the upcall completes. This can lead to unspecified behavior, and even JVM crashes, since an upcall is typically executed in the context of a downcall method handle invocation.
Modifier and Type | Interface | Description |
---|---|---|
static interface |
Linker.OptionPREVIEW |
Preview. A linker option is used to provide additional parameters to a linkage request. |
Modifier and Type | Method | Description |
---|---|---|
SymbolLookupPREVIEW |
defaultLookup() |
Returns a symbol lookup for symbols in a set of commonly used libraries. |
MethodHandle |
downcallHandle |
Creates a method handle which is used to call a foreign function with the given signature. |
MethodHandle |
downcallHandle |
Creates a method handle which is used to call a foreign function with the given signature and address. |
static LinkerPREVIEW |
nativeLinker() |
Returns a linker for the ABI associated with the underlying native platform. |
MemorySegmentPREVIEW |
upcallStub |
Creates an upcall stub which can be passed to other foreign functions as a function pointer, associated with the given arena. |
static LinkerPREVIEW nativeLinker()
libc
, libm
and libdl
.UnsupportedOperationException
- if the underlying native platform is not supported.MethodHandle downcallHandle(MemorySegmentPREVIEW address, FunctionDescriptorPREVIEW function, Linker.OptionPREVIEW... options)
Calling this method is equivalent to the following code:
linker.downcallHandle(function).bindTo(symbol);
This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
address
- the native memory segment whose base addressPREVIEW is the address of the target foreign function.function
- the function descriptor of the target foreign function.options
- the linker options associated with this linkage request.IllegalArgumentException
- if the provided function descriptor is not supported by this linker.IllegalArgumentException
- if !address.isNative()
, or if address.equals(MemorySegment.NULL)
.IllegalArgumentException
- if an invalid combination of linker options is given.IllegalCallerException
- If the caller is in a module that does not have native access enabled.MethodHandle downcallHandle(FunctionDescriptorPREVIEW function, Linker.OptionPREVIEW... options)
The Java method type associated with the returned method handle is derivedPREVIEW from the argument and return layouts in the function descriptor, but features an additional leading parameter of type MemorySegment
PREVIEW, from which the address of the target foreign function is derived. Moreover, if the function descriptor's return layout is a group layout, the resulting downcall method handle accepts an additional leading parameter of type SegmentAllocator
PREVIEW, which is used by the linker runtime to allocate the memory region associated with the struct returned by the downcall method handle.
Upon invoking a downcall method handle, the linker provides the following guarantees for any argument A
of type MemorySegment
PREVIEW whose corresponding layout is an address layoutPREVIEW:
A.scope().isAlive() == true
. Otherwise, the invocation throws IllegalStateException
;T
such that A.isAccessibleBy(T) == true
. Otherwise, the invocation throws WrongThreadException
; andA
is kept alive during the invocation. For instance, if A
has been obtained using a shared arenaPREVIEW, any attempt to closePREVIEW the arena while the downcall method handle is still executing will result in an IllegalStateException
. Moreover, if the provided function descriptor's return layout is an address layoutPREVIEW, invoking the returned method handle will return a native segment associated with a fresh scope that is always alive. Under normal conditions, the size of the returned segment is 0
. However, if the function descriptor's return layout has a target layoutPREVIEW T
, then the size of the returned segment is set to T.byteSize()
.
The returned method handle will throw an IllegalArgumentException
if the MemorySegment
PREVIEW representing the target address of the foreign function is the MemorySegment.NULL
PREVIEW address. The returned method handle will additionally throw NullPointerException
if any argument passed to it is null
.
This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
function
- the function descriptor of the target foreign function.options
- the linker options associated with this linkage request.IllegalArgumentException
- if the provided function descriptor is not supported by this linker.IllegalArgumentException
- if an invalid combination of linker options is given.IllegalCallerException
- If the caller is in a module that does not have native access enabled.MemorySegmentPREVIEW upcallStub(MethodHandle target, FunctionDescriptorPREVIEW function, ArenaPREVIEW arena, Linker.OptionPREVIEW... options)
The returned memory segment's address points to the newly allocated upcall stub, and is associated with the provided arena. As such, the lifetime of the returned upcall stub segment is controlled by the provided arena. For instance, if the provided arena is a confined arena, the returned upcall stub segment will be deallocated when the provided confined arena is closedPREVIEW.
An upcall stub argument whose corresponding layout is an address layoutPREVIEW is a native segment associated with a fresh scope that is always alive. Under normal conditions, the size of this segment argument is 0
. However, if the address layout has a target layoutPREVIEW T
, then the size of the segment argument is set to T.byteSize()
.
The target method handle should not throw any exceptions. If the target method handle does throw an exception, the JVM will terminate abruptly. To avoid this, clients should wrap the code in the target method handle in a try/catch block to catch any unexpected exceptions. This can be done using the MethodHandles.catchException(MethodHandle, Class, MethodHandle)
method handle combinator, and handle exceptions as desired in the corresponding catch block.
This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
target
- the target method handle.function
- the upcall stub function descriptor.arena
- the arena associated with the returned upcall stub segment.options
- the linker options associated with this linkage request.IllegalArgumentException
- if the provided function descriptor is not supported by this linker.IllegalArgumentException
- if the type of target
is incompatible with the type derivedPREVIEW from function
.IllegalArgumentException
- if it is determined that the target method handle can throw an exception.IllegalStateException
- if arena.scope().isAlive() == false
WrongThreadException
- if arena
is a confined arena, and this method is called from a thread T
, other than the arena's owner thread.IllegalCallerException
- If the caller is in a module that does not have native access enabled.SymbolLookupPREVIEW defaultLookup()
Each Linker
PREVIEW is responsible for choosing libraries that are widely recognized as useful on the OS and processor combination supported by the Linker
PREVIEW. Accordingly, the precise set of symbols exposed by the symbol lookup is unspecified; it varies from one Linker
PREVIEW to another.
defaultLookup()
exposes a set of symbols that is stable over time. Clients of defaultLookup()
are likely to fail if a symbol that was previously exposed by the symbol lookup is no longer exposed. If an implementer provides Linker
PREVIEW implementations for multiple OS and processor combinations, then it is strongly recommended that the result of defaultLookup()
exposes, as much as possible, a consistent set of symbols across all the OS and processor combinations.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/Linker.html
Linker
when preview features are enabled.