Module jdk.incubator.foreign
Package jdk.incubator.foreign

Interface LibraryLookup

public interface LibraryLookup
A native library lookup. Exposes a lookup operation for searching symbols, see lookup(String). A given native library remains loaded as long as there is at least one live library lookup instance referring to it. All symbol instances (see LibraryLookup.Symbol) generated by a given library lookup object contain a strong reference to said lookup object, therefore preventing library unloading; in turn method handle instances obtained from CLinker.downcallHandle(Addressable, MethodType, FunctionDescriptor)) also maintain a strong reference to the addressable parameter used for their construction. This means that there is always a strong reachability chain from a native method handle to a lookup object (the one that was used to lookup the native library symbol the method handle refers to); this is useful to prevent situations where a native library is unloaded in the middle of a native call.

In cases where a client wants to create a memory segment out of a lookup symbol, the client might want to attach the lookup symbol to the newly created segment, so that the symbol will be kept reachable as long as the memory segment is reachable; this can be achieved by creating the segment using the MemoryAddress.asSegmentRestricted(long, Runnable, Object) restricted segment factory, as follows: 

LibraryLookup defaultLookup = LibraryLookup.defaultLookup();
LibraryLookup.Symbol errno = defaultLookup.lookup("errno");
MemorySegment errnoSegment = errno.address().asRestrictedSegment(4, errno);

To allow for a library to be unloaded, a client will have to discard any strong references it maintains, directly, or indirectly to a lookup object associated with given library.

Unless otherwise specified, passing a null argument, or an array argument containing one or more null elements to a method in this class causes a NullPointerException to be thrown.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    LibraryLookup.Symbol
    A symbol retrieved during a library lookup.

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<LibraryLookup.Symbol>
    lookup​(String name)
    Looks up a symbol with given name in this library.
    static LibraryLookup
    ofDefault()
    Obtain a default library lookup object.
    static LibraryLookup
    ofLibrary​(String libName)
    Obtain a library lookup object corresponding to a library identified by given library name.
    static LibraryLookup
    ofPath​(Path path)
    Obtain a library lookup object corresponding to a library identified by given path.

  • Method Details

    • lookup

      Optional<LibraryLookup.Symbol> lookup​(String name)
      Looks up a symbol with given name in this library. The returned symbol maintains a strong reference to this lookup object.
      Parameters:
      name - the symbol name.
      Returns:
      the library symbol (if any).

    • ofDefault

      static LibraryLookup ofDefault()
      Obtain a default library lookup object.
      Returns:
      the default library lookup object.

    • ofPath

      static LibraryLookup ofPath​(Path path)
      Obtain a library lookup object corresponding to a library identified by given path.
      Parameters:
      path - the library absolute path.
      Returns:
      a library lookup object for given path.
      Throws:
      IllegalArgumentException - if the specified path does not correspond to an absolute path, e.g. if !path.isAbsolute().

    • ofLibrary

      static LibraryLookup ofLibrary​(String libName)
      Obtain a library lookup object corresponding to a library identified by given library name. The library name is decorated according to the platform conventions (e.g. on Linux, the lib prefix is added, as well as the .so extension); the resulting name is then looked up in the standard native library path (which can be overriden, by setting the java.library.path property).
      Parameters:
      libName - the library name.
      Returns:
      a library lookup object for given library name.