mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-27 23:04:50 +02:00
8319324: FFM: Reformat javadocs
Reviewed-by: mcimadamore
This commit is contained in:
Per Minborg
parent
a3f1b33b9b
commit
f939542104
16 changed files with 3001 additions and 2166 deletions
|
|
@ -46,26 +46,34 @@ import java.util.function.BiFunction;
|
|||
* A <em>symbol lookup</em> retrieves the address of a symbol in one or more libraries.
|
||||
* A symbol is a named entity, such as a function or a global variable.
|
||||
* <p>
|
||||
* A symbol lookup is created with respect to a particular library (or libraries). Subsequently, the {@link SymbolLookup#find(String)}
|
||||
* method takes the name of a symbol and returns the address of the symbol in that library.
|
||||
* A symbol lookup is created with respect to a particular library (or libraries).
|
||||
* Subsequently, the {@link SymbolLookup#find(String)} method takes the name of a symbol
|
||||
* and returns the address of the symbol in that library.
|
||||
* <p>
|
||||
* The address of a symbol is modeled as a zero-length {@linkplain MemorySegment memory segment}. The segment can be used in different ways:
|
||||
* The address of a symbol is modeled as a zero-length
|
||||
* {@linkplain MemorySegment memory segment}. The segment can be used in different ways:
|
||||
* <ul>
|
||||
* <li>It can be passed to a {@link Linker} to create a downcall method handle, which can then be used to call the foreign function at the segment's address.</li>
|
||||
* <li>It can be passed to an existing {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle}, as an argument to the underlying foreign function.</li>
|
||||
* <li>It can be {@linkplain MemorySegment#set(AddressLayout, long, MemorySegment) stored} inside another memory segment.</li>
|
||||
* <li>It can be used to access the region of memory backing a global variable (this requires
|
||||
* {@linkplain MemorySegment#reinterpret(long) resizing} the segment first).</li>
|
||||
* <li>It can be passed to a {@link Linker} to create a downcall method handle, which
|
||||
* can then be used to call the foreign function at the segment's address.</li>
|
||||
* <li>It can be passed to an existing
|
||||
* {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle},
|
||||
* as an argument to the underlying foreign function.</li>
|
||||
* <li>It can be {@linkplain MemorySegment#set(AddressLayout, long, MemorySegment) stored}
|
||||
* inside another memory segment.</li>
|
||||
* <li>It can be used to access the region of memory backing a global variable
|
||||
* (this requires {@linkplain MemorySegment#reinterpret(long) resizing}
|
||||
* the segment first).</li>
|
||||
* </ul>
|
||||
*
|
||||
* <h2 id="obtaining">Obtaining a symbol lookup</h2>
|
||||
*
|
||||
* The factory methods {@link #libraryLookup(String, Arena)} and {@link #libraryLookup(Path, Arena)}
|
||||
* 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 <em>library lookup</em>, and its
|
||||
* lifetime is controlled by an {@linkplain Arena 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 {@linkplain Arena#close() closed}:
|
||||
* The factory methods {@link #libraryLookup(String, Arena)} and
|
||||
* {@link #libraryLookup(Path, Arena)} 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
|
||||
* <em>library lookup</em>, and its lifetime is controlled by an {@linkplain Arena 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 {@linkplain Arena#close() closed}:
|
||||
*
|
||||
* {@snippet lang = java:
|
||||
* try (Arena arena = Arena.ofConfined()) {
|
||||
|
|
@ -76,8 +84,9 @@ import java.util.function.BiFunction;
|
|||
*}
|
||||
* <p>
|
||||
* If a library was previously loaded through JNI, i.e., by {@link System#load(String)}
|
||||
* or {@link System#loadLibrary(String)}, then the library was also associated with a particular class loader. The factory
|
||||
* method {@link #loaderLookup()} creates a symbol lookup for all the libraries associated with the caller's class loader:
|
||||
* or {@link System#loadLibrary(String)}, then the library was also associated with
|
||||
* a particular class loader. The factory method {@link #loaderLookup()} creates
|
||||
* a symbol lookup for all the libraries associated with the caller's class loader:
|
||||
*
|
||||
* {@snippet lang=java :
|
||||
* System.loadLibrary("GL"); // libGL.so loaded here
|
||||
|
|
@ -86,21 +95,24 @@ import java.util.function.BiFunction;
|
|||
* MemorySegment glGetString = libGL.find("glGetString").orElseThrow();
|
||||
* }
|
||||
*
|
||||
* This symbol lookup, which is known as a <em>loader lookup</em>, is dynamic with respect to the libraries associated
|
||||
* with the class loader. If other libraries are subsequently loaded through JNI and associated with the class loader,
|
||||
* then the loader lookup will expose their symbols automatically.
|
||||
* This symbol lookup, which is known as a <em>loader lookup</em>, is dynamic with
|
||||
* respect to the libraries associated with the class loader. If other libraries are
|
||||
* subsequently loaded through JNI and associated with the class loader, then the loader
|
||||
* lookup will expose their symbols automatically.
|
||||
* <p>
|
||||
* Note that a loader lookup only exposes symbols in libraries that were previously loaded through JNI, i.e.,
|
||||
* by {@link System#load(String)} or {@link System#loadLibrary(String)}. A loader lookup does not expose symbols in libraries
|
||||
* that were loaded in the course of creating a library lookup:
|
||||
* Note that a loader lookup only exposes symbols in libraries that were previously
|
||||
* loaded through JNI, i.e., by {@link System#load(String)} or {@link System#loadLibrary(String)}.
|
||||
* A loader lookup does not expose symbols in libraries that were loaded in the course
|
||||
* of creating a library lookup:
|
||||
*
|
||||
* {@snippet lang = java:
|
||||
* libraryLookup("libGL.so", arena).find("glGetString").isPresent(); // true
|
||||
* loaderLookup().find("glGetString").isPresent(); // false
|
||||
*}
|
||||
*
|
||||
* Note also that a library lookup for library {@code L} exposes symbols in {@code L} even if {@code L} was previously loaded
|
||||
* through JNI (the association with a class loader is immaterial to the library lookup):
|
||||
* Note also that a library lookup for library {@code L} exposes symbols in {@code L}
|
||||
* even if {@code L} was previously loaded through JNI (the association with
|
||||
* a class loader is immaterial to the library lookup):
|
||||
*
|
||||
* {@snippet lang = java:
|
||||
* System.loadLibrary("GL"); // libGL.so loaded here
|
||||
|
|
@ -108,10 +120,11 @@ import java.util.function.BiFunction;
|
|||
*}
|
||||
*
|
||||
* <p>
|
||||
* Finally, each {@link Linker} provides a symbol lookup for libraries that are commonly used on the OS and processor
|
||||
* combination supported by that {@link Linker}. This symbol lookup, which is known as a <em>default lookup</em>,
|
||||
* helps clients to quickly find addresses of well-known symbols. For example, a {@link Linker} for Linux/x64 might choose to
|
||||
* expose symbols in {@code libc} through the default lookup:
|
||||
* Finally, each {@link Linker} provides a symbol lookup for libraries that are commonly
|
||||
* used on the OS and processor combination supported by that {@link Linker}. This
|
||||
* symbol lookup, which is known as a <em>default lookup</em>, helps clients to quickly
|
||||
* find addresses of well-known symbols. For example, a {@link Linker} for Linux/x64
|
||||
* might choose to expose symbols in {@code libc} through the default lookup:
|
||||
*
|
||||
* {@snippet lang = java:
|
||||
* Linker nativeLinker = Linker.nativeLinker();
|
||||
|
|
@ -126,27 +139,33 @@ public interface SymbolLookup {
|
|||
|
||||
/**
|
||||
* Returns the address of the symbol with the given name.
|
||||
* @param name the symbol name.
|
||||
* @return a zero-length memory segment whose address indicates the address of the symbol, if found.
|
||||
*
|
||||
* @param name the symbol name
|
||||
* @return a zero-length memory segment whose address indicates the address of
|
||||
* the symbol, if found
|
||||
*/
|
||||
Optional<MemorySegment> find(String name);
|
||||
|
||||
/**
|
||||
* {@return 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}
|
||||
* {@return 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}
|
||||
*
|
||||
* @apiNote This method could be used to chain multiple symbol lookups together, e.g. so that symbols could
|
||||
* be retrieved, in order, from multiple libraries:
|
||||
* @apiNote This method could be used to chain multiple symbol lookups together,
|
||||
* e.g. so that symbols could be retrieved, in order, from multiple
|
||||
* libraries:
|
||||
* {@snippet lang = java:
|
||||
* var lookup = SymbolLookup.libraryLookup("foo", arena)
|
||||
* .or(SymbolLookup.libraryLookup("bar", arena))
|
||||
* .or(SymbolLookup.loaderLookup());
|
||||
*}
|
||||
* The above code creates a symbol lookup that first searches for symbols in the "foo" library. If no symbol is found
|
||||
* in "foo" then "bar" is searched. Finally, if a symbol is neither found in "foo" nor in "bar", the {@linkplain
|
||||
* SymbolLookup#loaderLookup() loader lookup} is used.
|
||||
* The above code creates a symbol lookup that first searches for symbols in
|
||||
* the "foo" library. If no symbol is found in "foo" then "bar" is searched.
|
||||
* Finally, if a symbol is neither found in "foo" nor in "bar", the
|
||||
* {@linkplain SymbolLookup#loaderLookup() loader lookup} is used.
|
||||
*
|
||||
* @param other the symbol lookup that should be used to look for symbols not found in this lookup.
|
||||
* @param other the symbol lookup that should be used to look for symbols not found
|
||||
* in this lookup
|
||||
*/
|
||||
default SymbolLookup or(SymbolLookup other) {
|
||||
Objects.requireNonNull(other);
|
||||
|
|
@ -154,27 +173,33 @@ public interface SymbolLookup {
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns a symbol lookup for symbols in the libraries associated with the caller's class loader.
|
||||
* Returns a symbol lookup for symbols in the libraries associated with the caller's
|
||||
* class loader.
|
||||
* <p>
|
||||
* A library is associated with a class loader {@code CL} when the library is loaded via an invocation of
|
||||
* {@link System#load(String)} or {@link System#loadLibrary(String)} from code in a class defined by {@code CL}.
|
||||
* If that code makes further invocations of {@link System#load(String)} or {@link System#loadLibrary(String)},
|
||||
* then more libraries are loaded and associated with {@code CL}. 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.
|
||||
* A library is associated with a class loader {@code CL} when the library is loaded
|
||||
* via an invocation of {@link System#load(String)} or
|
||||
* {@link System#loadLibrary(String)} from code in a class defined by {@code CL}.
|
||||
* If that code makes further invocations of {@link System#load(String)} or
|
||||
* {@link System#loadLibrary(String)} then more libraries are loaded and associated
|
||||
* with {@code CL}. 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.
|
||||
* <p>
|
||||
* Libraries associated with a class loader are unloaded when the class loader becomes
|
||||
* <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>. The symbol lookup
|
||||
* returned by this method is associated with an automatic {@linkplain MemorySegment.Scope 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.
|
||||
* <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>. The
|
||||
* symbol lookup returned by this method is associated with an automatic
|
||||
* {@linkplain MemorySegment.Scope 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.
|
||||
* <p>
|
||||
* 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
|
||||
* 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
|
||||
* {@linkplain ClassLoader#getSystemClassLoader system class loader}.
|
||||
*
|
||||
* @return a symbol lookup for symbols in the libraries associated with the caller's class loader.
|
||||
* @return a symbol lookup for symbols in the libraries associated with
|
||||
* the caller's class loader
|
||||
* @see System#load(String)
|
||||
* @see System#loadLibrary(String)
|
||||
*/
|
||||
|
|
@ -206,24 +231,28 @@ public interface SymbolLookup {
|
|||
}
|
||||
|
||||
/**
|
||||
* 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
|
||||
* {@linkplain Arena#close() closed}.
|
||||
* 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 {@linkplain Arena#close() closed}.
|
||||
*
|
||||
* @implNote 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 {@code dlopen} function for that OS.
|
||||
* In Windows, the library name is resolved according to the specification of the {@code LoadLibrary} function.
|
||||
* @implNote 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 {@code dlopen} function for that OS. In Windows,
|
||||
* the library name is resolved according to the specification of the
|
||||
* {@code LoadLibrary} function.
|
||||
*
|
||||
* @param name the name of the library in which symbols should be looked up.
|
||||
* @param arena the arena associated with symbols obtained from the returned lookup.
|
||||
* @return a new symbol lookup suitable to find symbols in a library with the given name.
|
||||
* @param name the name of the library in which symbols should be looked up
|
||||
* @param arena the arena associated with symbols obtained from the returned lookup
|
||||
* @return a new symbol lookup suitable to find symbols in a library with the
|
||||
* given name
|
||||
* @throws IllegalStateException if {@code arena.scope().isAlive() == false}
|
||||
* @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a
|
||||
* thread {@code T}, other than the arena's owner thread
|
||||
* @throws WrongThreadException if {@code arena} is a confined arena, and this method
|
||||
* is called from a thread {@code T}, other than the arena's owner thread
|
||||
* @throws IllegalArgumentException if {@code name} does not identify a valid library
|
||||
* @throws IllegalCallerException If the caller is in a module that does not have native access enabled
|
||||
* @throws IllegalCallerException If the caller is in a module that does not have
|
||||
* native access enabled
|
||||
*/
|
||||
@CallerSensitive
|
||||
@Restricted
|
||||
|
|
@ -237,22 +266,26 @@ public interface SymbolLookup {
|
|||
}
|
||||
|
||||
/**
|
||||
* 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
|
||||
* {@linkplain Arena#close() closed}.
|
||||
* 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 {@linkplain Arena#close() closed}.
|
||||
*
|
||||
* @implNote On Linux, the functionalities provided by this factory method and the returned symbol lookup are
|
||||
* implemented using the {@code dlopen}, {@code dlsym} and {@code dlclose} functions.
|
||||
* @param path the path of the library in which symbols should be looked up.
|
||||
* @param arena the arena associated with symbols obtained from the returned lookup.
|
||||
* @return a new symbol lookup suitable to find symbols in a library with the given path.
|
||||
* @implNote On Linux, the functionalities provided by this factory method and the
|
||||
* returned symbol lookup are implemented using the {@code dlopen},
|
||||
* {@code dlsym} and {@code dlclose} functions.
|
||||
*
|
||||
* @param path the path of the library in which symbols should be looked up
|
||||
* @param arena the arena associated with symbols obtained from the returned lookup
|
||||
* @return a new symbol lookup suitable to find symbols in a library with the given
|
||||
* path
|
||||
* @throws IllegalStateException if {@code arena.scope().isAlive() == false}
|
||||
* @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a
|
||||
* thread {@code T}, other than the arena's owner thread
|
||||
* @throws WrongThreadException if {@code arena} is a confined arena, and this method
|
||||
* is called from a thread {@code T}, other than the arena's owner thread
|
||||
* @throws IllegalArgumentException if {@code path} does not point to a valid library
|
||||
* @throws IllegalCallerException If the caller is in a module that does not have native access enabled
|
||||
* @throws IllegalCallerException If the caller is in a module that does not have
|
||||
* native access enabled
|
||||
*/
|
||||
@CallerSensitive
|
||||
@Restricted
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue