Class DowncallFactory

java.lang.Object
express.mvp.roray.utils.functions.DowncallFactory
public final class DowncallFactory extends Object
Factory for creating downcall handles with common patterns. All operations are setup-time only - produces raw MethodHandles that should be stored in static final fields for optimal JIT performance.

Example usage: 

private static final DowncallFactory FACTORY = DowncallFactory.forNativeLinker();

private static final MethodHandle getpid = FACTORY.downcall(
    "getpid",
    FunctionDescriptorBuilder.returnsInt().build()
);

  • Method Details

    • forNativeLinker

      public static DowncallFactory forNativeLinker()
      Create a factory using the native linker and its default lookup. Suitable for standard C library functions.

    • withLookup

      public static DowncallFactory withLookup(SymbolLookup libraryLookup)
      Create a factory with a custom symbol lookup (e.g., for a loaded library).

    • withLibrary

      public static DowncallFactory withLibrary(Arena arena, String libraryPath)
      Create a factory for a library loaded from the specified path.
      Parameters:
      arena - Arena controlling the library's lifetime
      libraryPath - Path to the shared library

    • downcall

      public MethodHandle downcall(String functionName, FunctionDescriptor descriptor)
      Creates a downcall handle. The returned MethodHandle should be stored in a static final field for optimal JIT performance.
      Parameters:
      functionName - Name of the native function
      descriptor - Function signature
      Returns:
      MethodHandle for calling the native function
      Throws:
      UnsatisfiedLinkError - if the symbol is not found

    • downcall

      public MethodHandle downcall(String functionName, FunctionDescriptor descriptor, Linker.Option... options)
      Creates a downcall handle with linker options.
      Parameters:
      functionName - Name of the native function
      descriptor - Function signature
      options - Linker options (e.g., critical, captureCallState)
      Returns:
      MethodHandle for calling the native function
      Throws:
      UnsatisfiedLinkError - if the symbol is not found

    • downcallVirtual

      public MethodHandle downcallVirtual(FunctionDescriptor descriptor)
      Creates a "virtual" downcall handle that takes a function pointer as its first argument. Useful when function addresses are resolved dynamically (e.g., io_uring ops).

      The returned MethodHandle should be stored in a static final field for optimal JIT performance.

      Parameters:
      descriptor - Function signature (first arg will be the function pointer)
      Returns:
      MethodHandle that expects function pointer as first argument

    • downcallVirtual

      public MethodHandle downcallVirtual(FunctionDescriptor descriptor, Linker.Option... options)
      Creates a virtual downcall handle with linker options.

      The returned MethodHandle should be stored in a static final field for optimal JIT performance.

      Parameters:
      descriptor - Function signature (first arg will be the function pointer)
      options - Linker options (e.g., critical, captureCallState)
      Returns:
      MethodHandle that expects function pointer as first argument

    • findSymbol

      public MemorySegment findSymbol(String symbolName)
      Look up a symbol address without creating a downcall handle.
      Parameters:
      symbolName - Name of the symbol
      Returns:
      MemorySegment representing the symbol address
      Throws:
      UnsatisfiedLinkError - if the symbol is not found

    • linker

      public Linker linker()
      Get the underlying linker.

    • lookup

      public SymbolLookup lookup()
      Get the underlying symbol lookup.