- GraalVM for JDK 23 (Latest)
- GraalVM for JDK 24 (Early Access)
- GraalVM for JDK 21
- GraalVM for JDK 17
- Archives
- Dev Build
- Truffle Language Implementation Framework
- Truffle Branches Instrumentation
- Dynamic Object Model
- Static Object Model
- Host Optimization for Interpreter Code
- Truffle Approach to Function Inlining
- Profiling Truffle Interpreters
- Truffle Interop 2.0
- Language Implementations
- Implementing a New Language with Truffle
- Truffle Language Safepoint Tutorial
- Truffle Native Function Interface
- Optimizing Truffle Interpreters
- Options
- On-Stack Replacement
- Truffle Strings Guide
- Specialization Histogram
- Testing DSL Specializations
- Polyglot API Based TCK
- Truffle Approach to the Compilation Queue
- Truffle Library Guide
- Truffle AOT Overview
- Truffle AOT Compilation
- Auxiliary Engine Caching
- Truffle Language Safepoint Tutorial
- Monomorphization
- Splitting Algorithm
- Monomorphization Use Cases
- Reporting Polymorphic Specializations to Runtime
This documentation is for the unreleased GraalVM version.Download Early Access Builds from GitHub.
Truffle Native Function Interface
Truffle includes a way to call native functions, called the Native Function Interface (NFI). It is implemented as an internal language on top of Truffle that language implementors can access via the standard polyglot eval interface and Truffle interoperability. NFI is intended to be used, for example, to implement a language’s FFI, or to call native runtime routines that are not available in Java.
NFI uses libffi
.
On a standard JVM it calls it using JNI, and on GraalVM Native Image it uses system Java.
In the future it may be optimised by the Graal Compiler in native executables so that native calls are made directly from the compiled code.
Stability #
The NFI is an internal language designed for language implementors. It is not considered stable and the interface and behavior may change without warning. It is not intended to be used directly by end-users.
Basic Concepts #
The NFI is accessed via the polyglot interface of whatever language you are using. This could be Java, or it could be a Truffle language. This lets you use the NFI from both your Java language implementation code, or from your guest language to reduce the amount of Java that you need to write.
The entry point is the polyglot eval
interface.
This runs a special DSL, and returns Truffle interoperability objects which can then expose more methods.
Below are some examples using Ruby’s polyglot interface, but any other JVM or a language implementation could be used instead.
Basic Example #
Here is a basic working example, before going into the details:
library = Polyglot.eval('nfi', 'load "libSDL2.dylib"') # load a library
symbol = library['SDL_GetRevisionNumber'] # load a symbol from the library
signature = Polyglot.eval('nfi', '():UINT32') # prepare a signature
function = signature.bind(symbol) # bind the symbol to the signature to create a function
puts function.call # => 12373 # call the function
Loading libaries #
To load a library, a script written in the ‘nfi
’ language DSL is evaluated.
It returns an object that represents the loaded library.
library = Polyglot.eval('nfi', '...load command...')
The load command can be any of these forms:
default
load "filename"
load (flag | flag | ...) "filename"
The default
command returns a pseudo-library that contains all symbols already loaded in
the process, equivalent to RTLD_DEFAULT
in the Posix interface.
The load "filename"
command loads a library from a file.
You are responsible for any cross-platform concerns about library naming conventions and load paths.
The load (flag | flag | ...) "filename"
command allows you to specify flags to load the library.
For the default backend (backends will be described later), and when running on a Posix platform, the flags available are RTLD_GLOBAL
, RTLD_LOCAL
, RTLD_LAZY
, and RTLD_NOW
, which have the conventional Posix semantics.
The default is RTLD_NOW
if neither RTLD_LAZY
nor RTLD_NOW
were specified.
Loading Symbols from Libraries #
To load a symbol from a library, read the symbol as a property from the library object that was previously loaded.
symbol = library['symbol_name']
Producing Native Function Objects from Symbols #
To get an executable object that you can call in order to invoke the native function, bind the symbol object that was previously loaded, by creating a signature object and calling the bind
method on it.
The signature object needs to match the native function’s actual type signature.
signature = Polyglot.eval('nfi', '...signature...')
function = signature.bind(symbol)
The format of the signature is (arg, arg, ...) : return
, where arg
and return
are types.
Types can be one of the simple types:
VOID
UINT8
SINT8
UINT16
SINT16
UINT32
SINT32
UINT64
SINT64
FLOAT
DOUBLE
POINTER
STRING
OBJECT
ENV
Array types are formed by placing another type in square brackets.
For example [UINT8]
. These are C-style arrays.
Function pointer types are formed by writing a nested signature.
For example the signature of qsort
would be (POINTER, UINT64, UINT64, (POINTER, POINTER) : SINT32) : VOID
.
For a function with a signature with variadic arguments, you specify ...
where the variadic arguments start, but then you must specify the actual types that you will be calling the function with.
You may therefore need to bind the same symbol multiple times in order to call it with different types or a different number of arguments.
For example, to call printf
with %d %f
you would use the type signature (STRING, ...SINT32, DOUBLE) : SINT32
.
Type expressions can be nested arbitrarily deep.
Two additional special types, ENV
and OBJECT
, are described in the section on the native API, later in this document.
Types can be written in any case.
You are responsible for any mapping of types from a foreign language such as C into NFI types.
Calling Native Function Objects #
To call a native function, execute it.
return_value = function.call(...arguments...)
Calling back from Native Code to Managed Functions #
Using nested signatures, a function call can get function pointers as arguments.
The managed caller needs to pass a Polyglot executable object, that will be converted to a native function pointer.
When calling this function pointer from the native side, the execute
message is sent to the Polyglot object.
void native_function(int32_t (*fn)(int32_t)) {
printf("%d\n", fn(15));
}
signature = Polyglot.eval('nfi', '((SINT32):SINT32):VOID')
native_function = signature.bind(library['native_function'])
native_function.call(->(x) { x + 1 })
The arguments and return values of callback functions are converted the same as for regular function calls, with the conversion in the other direction, i.e., arguments are converted from native to managed, and return values are converted from managed to native.
Callback function pointers can themselves have function pointer arguments.
That works as you would expect: the function accepts a native function pointer as argument, and it is converted to a Truffle executable object.
Sending the execute
message to that object calls the native function pointer, same as calling a regular NFI function.
Function pointer types are also supported as return types.
Combined Loading and Binding #
You can optionally combine loading a library with loading symbols and binding them.
This is achieved with an extended load
command, which then returns an object with the already bound functions as methods.
These two examples are equivalent:
library = Polyglot.eval('nfi', 'load libSDL2.dylib')
symbol = library['SDL_GetRevisionNumber']
signature = Polyglot.eval('nfi', '():UINT32')
function = signature.bind(symbol)
puts function.call # => 12373
library = Polyglot.eval('nfi', 'load libSDL2.dylib { SDL_GetRevisionNumber():UINT32; }')
puts library.SDL_GetRevisionNumber # => 12373
The definitions in the curly braces {}
can contain multiple function bindings, so that many functions can be loaded from a library at once.
Backends #
The load command can be prefixed by with
in order to select a specific NFI backend.
Multiple NFI backends are available.
The default is called native
, and will be used if there is no with
prefix, or the selected backend is not available.
Depending on the configuration of components you are running, available backends may include:
native
llvm
, which uses the GraalVM LLVM runtime to run the native codepanama
Panama backend #
The Panama backend uses the Foreign Function and Memory APIs introduced by project Panama.
This backend only supports a subset of all the types. Specifically, it does not support STRING
, OBJECT
, ENV
, FP80
or array types.
Although less feature-complete, the backend is typically more performant.
It is available starting from JDK 22.
Truffle NFI on Native Image #
To build a native image that contains the Truffle NFI, it is sufficient to use the --language:nfi
argument, or specify Requires = language:nfi
in native-image.properties
.
It is possible to select what implementation to use for the native
backend using --language:nfi=<backend>
.
Note that the --language:nfi=<backend>
argument must come before any other arguments that might pull in the NFI as dependency via Requires = language:nfi
.
The first instance of language:nfi
wins and determines what backend will be built into the native image.
Available arguments for --language:nfi=<backend>
are:
libffi
(the default)none
Selecting the none
native backend will effectively disable access to native functions using the Truffle NFI.
This will break users of the NFI that rely on native access (e.g. the GraalVM LLVM Runtime, unless used with --llvm.managed
on EE).
Native API #
The NFI can be used with unmodified, already compiled native code, but it can also be used with a Truffle-specific API being used by the native code.
The special type ENV
adds an additional parameter TruffleEnv *env
to the signature.
An additional simple type OBJECT
translates to an opaque TruffleObject
type.
The trufflenfi.h
header file provides declarations for working with these types, that can then be used by the native code called through the NFI.
See trufflenfi.h
for more documentation on this API.
Type Marshalling #
This section describes in detail how argument values and return values are converted for all types in the function signature.
The following table shows the possible types in NFI signatures with their corresponding C language types on the native side, and what polyglot values these arguments map to on the managed side:
NFI type | C language type | Polyglot value |
---|---|---|
VOID |
void |
Polyglot object with isNull == true (only valid as return type). |
SINT8/16/32/64 |
int8/16/32/64_t |
Polyglot isNumber that fitsIn... the corresponding integer type. |
UINT8/16/32/64 |
uint8/16/32/64_t |
Polyglot isNumber that fitsIn... the corresponding integer type. |
FLOAT |
float |
Polyglot isNumber that fitsInFloat . |
DOUBLE |
double |
Polyglot isNumber that fitsInDouble . |
POINTER |
void * |
Polyglot object with isPointer == true or isNull == true . |
STRING |
char * (zero-terminated UTF-8 string) |
Polyglot isString . |
OBJECT |
TruffleObject |
Arbitrary object. |
[type] |
type * (array of primitive) |
Java host primitive array. |
(args):ret |
ret (*)(args) (function pointer type) |
Polyglot function with isExecutable == true . |
ENV |
TruffleEnv * |
nothing (injected argument) |
The following sections describe the type conversions in detail.
The type conversion behavior with function pointers can be slightly confusing, because the direction of the arguments is reversed. When in doubt, always try to figure out in which direction arguments or return values flow, from managed to native or from native to managed.
VOID
#
This type is only allowed as return type, and is used to denote functions that do not return a value.
Since in the Polyglot API, all executable objects have to return a value, a Polyglot object with isNull == true
will be returned from native functions that have a VOID
return type.
The return value of managed callback functions with return type VOID
will be ignored.
Primitive Numbers #
The primitive number types are converted as you might expect. The argument needs to be a Polyglot number, and its value needs to fit in the value range of the specified numeric type.
One thing to note is the handling of the unsigned integer types.
Even though the Polyglot API does not specify separate messages for values fitting in unsigned types, the conversion is still using the unsigned value ranges.
For example, the value 0xFF
passed from native to managed through a return value of type SINT8
will result in a Polyglot number -1
, which fitsInByte
.
But the same value returned as UINT8
results in a Polyglot number 255
, which does not fitsInByte
.
When passing numbers from managed code to native code, the signedness of the number is ignored, only the bits of the number are relevant.
So for example, passing -1
to an argument of type UINT8
is allowed, and the result on the native side is 255
, since it has the same bits as -1
.
The other way round, passing 255
to an argument of type SINT8
is also allowed, and the result on the native side is -1
.
Since in the current Polyglot API it is not possible to represent numbers outside of the signed 64-bit range, the UINT64
type is currently handled with signed semantics.
This is a known bug in the API, and will change in a future release.
POINTER
#
This type is a generic pointer argument. On the native side, it does not matter what exact pointer type the argument is.
A polyglot object passed to POINTER
arguments will be converted to a native pointer if possible (using the isPointer
, asPointer
and toNative
messages as necessary).
An object with isNull == true
will be passed as a native NULL
.
POINTER
return values will produce a polyglot object with isPointer == true
.
The native NULL
pointer will additionally have isNull == true
.
STRING
#
This is a pointer type with special conversion semantics for strings.
Polyglot strings passed from managed to native using the STRING
type will be converted to a zero-terminated UTF-8 encoded string.
For STRING
arguments, the pointer is owned by the caller, and is guaranteed to stay alive for the duration of the call only.
The STRING
values returned from managed function pointers to a native caller are also owned by the caller.
They have to be freed with free
after use.
Polyglot pointer values or null values can also be passed to STRING
arguments.
The semantics is the same as for POINTER
arguments.
The user is responsible for ensuring that the pointer is a valid UTF-8 string.
The STRING
values passed from native functions to managed code behave like POINTER
return values, but in addition they have isString == true
.
The user is responsible for the ownership of the pointer and it might be necessary to free
the return value, depending on the semantics of the called native function.
After freeing the returned pointer, the returned polyglot string is invalid and reading it results in undefined behavior.
In that sense, the returned polyglot string is not a safe object, similar to a raw pointer.
It is recommented that the user of the NFI copies the returned string before passing it along to untrusted managed code.
OBJECT
#
This argument corresponds to the C type TruffleObject
.
This type is defined in trufflenfi.h
, and is an opaque pointer type.
A value of type TruffleObject
represents a reference to an arbitrary managed object.
Native code can do nothing with values of type TruffleObject
except pass them back to managed code, either through return values or passing them to callback function pointers.
The lifetime of TruffleObject
references needs to be managed manually.
See the documentation in trufflenfi.h
for API functions to manage the lifetime of TruffleObject
references.
A TruffleObject
passed as an argument is owned by the caller, and guaranteed to stay alive for the duration of the call.
A TruffleObject
reference returned from a callback function pointer is owned by the caller, and needs to be freed after use.
Returning a TruffleObject
from a native function does not transfer ownership (but there is an API function in trufflenfi.h
to do that).
[...]
(Native Primitive Arrays) #
This type is only allowed as an argument from managed code to a native function, and only arrays of primitive numeric types are supported.
On the managed side, only Java host objects containing a Java primitive array are supported. On the native side, the type is a pointer to the contents of the array. It is the user’s responsibility to pass along the array length as a separate argument.
The pointer is valid for the duration of the native call only.
Modifications to the contents are propagated back to the Java array after returning from the call. The effects of concurrent access to the Java array during the native call are unspecified.
(...):...
(Function Pointer) #
On the native side, a nested signature type corresponds to a function pointer with the given signature, calling back to managed code.
Polyglot executable objects passed from managed to native using a function pointer type are converted to a function pointer that can be called by the native code.
For function pointer arguments, the function pointer is owned by the caller, and is guaranteed to stay alive for the duration of the call only.
Function pointer return values are owned by the caller, and have to be freed manually.
See polyglot.h
for API functions to manage the lifetime of function pointer values.
Polyglot pointer values or null values can also be passed to function pointer arguments.
The semantics is the same as for POINTER
arguments.
The user is responsible for ensuring that the pointer is a valid function pointer.
Function pointer return types are the same as regular POINTER
return types, but in addition they are already bound to the given signature type.
They support the execute
message, and behave the same as regular NFI functions.
ENV
#
This type is a special argument of type TruffleEnv *
.
It is only valid as argument type, not as a return type.
It is an injected argument on the native side, there is no corresponding argument on the managed side.
When used as argument type of a native function, the native function will get an environment pointer on this position.
That environment pointer can be used to call API functions (see trufflenfi.h
).
The argument is injected, for example, if the signature is (SINT32, ENV, SINT32):VOID
.
This function object is expected to be called with two integer arguments, and the corresponding native function will be called with three arguments: first the first real argument, then the injected ENV
argument, and then the second real argument.
When the ENV
type is used as an argument type for a function pointer parameter, that function pointer must be called with a valid NFI environment as an argument.
If the caller already has an environment, threading it through to callback function pointers is more efficient than calling them without an ENV
argument.
Calling Convention #
Native functions must use the system’s standard ABI. There is currently no support for alternative ABIs.