Summary

Replace the LibraryLookup abstraction in the Foreign Linker API with a more robust abstraction, which works reliably across different platforms and operating systems.

Problem

The LibraryLookup abstraction in the Foreign Linker API exposes a so called default lookup object, which can be used to find symbols in the standard C library. Unfortunately, this functionality is broken in few ways:

• In most platforms, the default lookup will expose symbols defined in libjvm.so
• On Windows, the default lookup doesn't return symbols defined in the "newer" universal C runtime (ucrtbase.dll). Also, on Windows, this functionality is implemented using a debugging function, to list all the libraries loaded by the current process.
• On MacOS, the default lookup leaks symbols from libraries loaded independently, e.g. via calls to LibraryLookup.ofPath.

Solution

To create a downcall method handle, the Foreign Linker API requires the address of the symbol to be linked. LibraryLookup obviously satisfies this requirement, but it does so by reinventing a new library loading mechanism almost from scratch. This new mechanism suffers from some of the platform-related issues described above, as well as other problems (e.g. library unloading is controlled by reachability, and can sometimes be triggered unexpectedly).

A more robust solution would be to simply expose a way to lookup symbols in already loaded libraries (e.g. libraries loaded via System::load or System::loadLibrary). This is done, in our proposed solution, by allowing clients to obtain a so called loader lookup object - that is, a lookup object that can search symbols in all libraries associated with the current class loader.

To allow searching symbols in the standard C library, we also define an additional lookup factory, namely CLinker::systemLookup. The API does not make any promise on which set of symbols will be provided by such lookup: not all operating systems expose the same symbols, even when it comes to the standard C library: for instance printf on Windows is defined as a macro.

Both lookup factories are restricted meaning that they can only be called with the --enable-native-access flag set.

Since we realized that this library lookup abstraction is simpler than the one it replaces (as it doesn't concern with library loading), we decided to rename LibraryLookup as SymbolLookup. Clients are encouraged to create custom symbol lookups obtained by combining different lookup objects.

Specification

Javadoc link (as of June 2nd): http://cr.openjdk.java.net/~mcimadamore/8268129_v1/javadoc/jdk/incubator/foreign/package-summary.html

Specdiff link (as of June 2nd): http://cr.openjdk.java.net/~mcimadamore/8268129_v1/specdiff/overview-summary.html

A zipped version of the latest specdiff (v1) has been attached to this CSR.