Summary

Add a method to compose two symbol lookups.

Problem

Often clients needs to perform symbol lookups in multiple libraries. For instance, it is common, when working with OpenGL applications, to use both "libGL" and "libGLUT" at the same time. Since SymbolLookup is a functional interface, clients could define a custom lookup which searches both libraries. However, given how common this use case is, it would be better for the SymbolLookup API to support this idiom directly.

Solution

A new instance method, namely SymbolLookup::or is added. This method returns a new composite lookup, which has a find method whose implementation will search for matching symbol in the original lookup, and, should that fail, then will also search for matching symbol in the provided, "fallback" lookup.

Specification

The javadoc for SymbolLookup::or is provided below:

   /**
     * {@return a composed symbol lookup that returns 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:
     * {@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 not found in neither "foo" nor "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.
     */
    default SymbolLookup or(SymbolLookup other) {
        Objects.requireNonNull(other);
        return name -> find(name).or(() -> other.find(name));
    }