Interface SymbolLookup
- Functional Interface:
- This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
A symbol lookup is created with respect to a particular library (or libraries).
Subsequently, the find(String)
method takes the name of a symbol
and returns the address of the symbol in that library.
The address of a symbol is modeled as a zero-length memory segment. The segment can be used in different ways:
- It can be passed to a
Linker
to create a downcall method handle, which can then be used to call the foreign function at the segment's address. - It can be passed to an existing downcall method handleRESTRICTED, as an argument to the underlying foreign function.
- It can be stored inside another memory segment.
- It can be used to access the region of memory backing a global variable (this requires resizingRESTRICTED the segment first).
Obtaining a symbol lookup
The factory methodslibraryLookup(String, Arena)
RESTRICTED and
libraryLookup(Path, Arena)
RESTRICTED create a symbol lookup for a library known to
the operating system. The library is specified by either its name or a path.
The library is loaded if not already loaded. The symbol lookup, which is known as a
library lookup, and its lifetime is controlled by an arena.
For instance, if the provided arena is a confined arena, the library associated with
the symbol lookup is unloaded when the confined arena is closed:
try (Arena arena = Arena.ofConfined()) {
SymbolLookup libGL = SymbolLookup.libraryLookup("libGL.so", arena); // libGL.so loaded here
MemorySegment glGetString = libGL.findOrThrow("glGetString");
...
} // libGL.so unloaded here
If a library was previously loaded through JNI, i.e., by System.load(String)
or System.loadLibrary(String)
, then the library was also associated with
a particular class loader. The factory method loaderLookup()
creates
a symbol lookup for all the libraries associated with the caller's class loader:
System.loadLibrary("GL"); // libGL.so loaded here
...
SymbolLookup libGL = SymbolLookup.loaderLookup();
MemorySegment glGetString = libGL.findOrThrow("glGetString");
Note that a loader lookup only exposes symbols in libraries that were previously
loaded through JNI, i.e., by System.load(String)
or System.loadLibrary(String)
.
A loader lookup does not expose symbols in libraries that were loaded in the course
of creating a library lookup:
libraryLookup("libGL.so", arena).find("glGetString").isPresent(); // true
loaderLookup().find("glGetString").isPresent(); // false
L
exposes symbols in L
even if L
was previously loaded through JNI (the association with
a class loader is immaterial to the library lookup):
System.loadLibrary("GL"); // libGL.so loaded here
libraryLookup("libGL.so", arena).find("glGetString").isPresent(); // true
Finally, each Linker
provides a symbol lookup for libraries that are commonly
used on the OS and processor combination supported by that Linker
. This
symbol lookup, which is known as a default lookup, helps clients to quickly
find addresses of well-known symbols. For example, a Linker
for Linux/x64
might choose to expose symbols in libc
through the default lookup:
Linker nativeLinker = Linker.nativeLinker();
SymbolLookup stdlib = nativeLinker.defaultLookup();
MemorySegment malloc = stdlib.findOrThrow("malloc");
- Since:
- 22
-
Method Summary
Modifier and TypeMethodDescriptionReturns the address of the symbol with the given name.default MemorySegment
findOrThrow
(String name) Returns the address of the symbol with the given name or throws an exception.static SymbolLookup
libraryLookup
(String name, Arena arena) Restricted.Loads a library with the given name (if not already loaded) and creates a symbol lookup for symbols in that library.static SymbolLookup
libraryLookup
(Path path, Arena arena) Restricted.Loads a library from the given path (if not already loaded) and creates a symbol lookup for symbols in that library.static SymbolLookup
Returns a symbol lookup for symbols in the libraries associated with the caller's class loader.default SymbolLookup
or
(SymbolLookup other) Returns a composed symbol lookup that returns the result of finding the symbol with this lookup if found, otherwise returns the result of finding the symbol with the other lookup.
-
Method Details
-
find
Returns the address of the symbol with the given name.- Parameters:
name
- the symbol name- Returns:
- a zero-length memory segment whose address indicates the address of the symbol, if found
- See Also:
-
findOrThrow
Returns the address of the symbol with the given name or throws an exception.This is equivalent to the following code, but is more efficient: to:
String name = ... MemorySegment address = lookup.find(name) .orElseThrow(() -> new NoSuchElementException("Symbol not found: " + name));
- Parameters:
name
- the symbol name- Returns:
- a zero-length memory segment whose address indicates the address of the symbol
- Throws:
NoSuchElementException
- if no symbol address can be found for the given name- Since:
- 23
- See Also:
-
or
Returns a composed symbol lookup that returns the result of finding the symbol with this lookup if found, otherwise returns the result of finding the symbol with the other lookup.- API Note:
- This method could be used to chain multiple symbol lookups together,
e.g. so that symbols could be retrieved, in order, from multiple
libraries:
var lookup = SymbolLookup.libraryLookup("foo", arena) .or(SymbolLookup.libraryLookup("bar", arena)) .or(SymbolLookup.loaderLookup());
- Parameters:
other
- the symbol lookup that should be used to look for symbols not found in this lookup- Returns:
- a composed symbol lookup that returns the result of finding the symbol with this lookup if found, otherwise returns the result of finding the symbol with the other lookup
-
loaderLookup
Returns a symbol lookup for symbols in the libraries associated with the caller's class loader.A library is associated with a class loader
CL
when the library is loaded via an invocation ofSystem.load(String)
orSystem.loadLibrary(String)
from code in a class defined byCL
. If that code makes further invocations ofSystem.load(String)
orSystem.loadLibrary(String)
then more libraries are loaded and associated withCL
. The symbol lookup returned by this method is always current: it reflects all the libraries associated with the relevant class loader, even if they were loaded after this method returned.Libraries associated with a class loader are unloaded when the class loader becomes unreachable. The symbol lookup returned by this method is associated with an automatic scope which keeps the caller's class loader reachable. Therefore, libraries associated with the caller's class loader are kept loaded (and their symbols available) as long as a loader lookup for that class loader, or any of the segments obtained by it, is reachable.
In cases where this method is called from a context where there is no caller frame on the stack (e.g. when called directly from a JNI attached thread), the caller's class loader defaults to the system class loader.
- Returns:
- a symbol lookup for symbols in the libraries associated with the caller's class loader
- See Also:
-
libraryLookup
libraryLookup
is a restricted method of the Java platform.Restricted methods are unsafe, and, if used incorrectly, might crash the JVM or result in memory corruption.Loads a library with the given name (if not already loaded) and creates a symbol lookup for symbols in that library. The lifetime of the returned library lookup is controlled by the provided arena. For instance, if the provided arena is a confined arena, the library associated with the returned lookup will be unloaded when the provided confined arena is closed.- Implementation Note:
- The process of resolving a library name is OS-specific. For instance,
in a POSIX-compliant OS, the library name is resolved according to the
specification of the
dlopen
function for that OS. In Windows, the library name is resolved according to the specification of theLoadLibrary
function. - Parameters:
name
- the name of the library in which symbols should be looked uparena
- the arena associated with symbols obtained from the returned lookup- Returns:
- a new symbol lookup suitable to find symbols in a library with the given name
- Throws:
IllegalStateException
- ifarena.scope().isAlive() == false
WrongThreadException
- ifarena
is a confined arena, and this method is called from a threadT
, other than the arena's owner threadIllegalArgumentException
- ifname
does not identify a valid libraryIllegalCallerException
- If the caller is in a module that does not have native access enabled
-
libraryLookup
libraryLookup
is a restricted method of the Java platform.Programs can only uselibraryLookup
when access to restricted methods is enabled.Restricted methods are unsafe, and, if used incorrectly, might crash the JVM or result in memory corruption.Loads a library from the given path (if not already loaded) and creates a symbol lookup for symbols in that library. The lifetime of the returned library lookup is controlled by the provided arena. For instance, if the provided arena is a confined arena, the library associated with the returned lookup will be unloaded when the provided confined arena is closed.- Implementation Note:
- On Linux, the functionalities provided by this factory method and the
returned symbol lookup are implemented using the
dlopen
,dlsym
anddlclose
functions. - Parameters:
path
- the path of the library in which symbols should be looked uparena
- the arena associated with symbols obtained from the returned lookup- Returns:
- a new symbol lookup suitable to find symbols in a library with the given path
- Throws:
IllegalStateException
- ifarena.scope().isAlive() == false
WrongThreadException
- ifarena
is a confined arena, and this method is called from a threadT
, other than the arena's owner threadIllegalArgumentException
- ifpath
does not point to a valid library in the default file systemIllegalCallerException
- If the caller is in a module that does not have native access enabled
-
libraryLookup
when access to restricted methods is enabled.