Class UpcallFactory

java.lang.Object
express.mvp.roray.utils.functions.UpcallFactory
public final class UpcallFactory extends Object
Factory for creating upcall stubs (Java callbacks callable from native code). All setup costs are paid at stub creation time.

Upcall stubs allow native code to call back into Java methods. The stub's lifetime is tied to the Arena used during creation.

Usage Example

// Define a callback interface
@FunctionalInterface
interface SignalHandler {
    void handle(int signum);
}

// Create an upcall stub
try (Arena arena = Arena.ofConfined()) {
    UpcallFactory factory = UpcallFactory.create();

    MemorySegment stub = factory.upcallStub(
        arena,
        (int signum) -> System.out.println("Signal: " + signum),
        SignalHandler.class,
        FunctionDescriptor.ofVoid(ValueLayout.JAVA_INT)
    );

    // Pass 'stub' to native code as a function pointer
}

Warning: The upcall stub is only valid while the Arena is alive. Using the stub after the Arena is closed results in undefined behavior.

  • Method Details

    • create

      public static UpcallFactory create()
      Create an UpcallFactory using the native linker.

    • upcallStub

      public MemorySegment upcallStub(Arena arena, MethodHandle target, FunctionDescriptor descriptor)
      Creates an upcall stub from a MethodHandle.

      The returned MemorySegment can be passed to native code as a function pointer. The stub remains valid for the lifetime of the arena.

      Parameters:
      arena - Arena controlling the stub's lifetime
      target - MethodHandle to the Java method to invoke
      descriptor - Native function signature matching the MethodHandle
      Returns:
      MemorySegment representing a native function pointer
      Throws:
      IllegalArgumentException - if the descriptor doesn't match the handle

    • upcallStub

      public <T> MemorySegment upcallStub(Arena arena, MethodHandles.Lookup lookup, T callback, Class<T> functionalInterface, FunctionDescriptor descriptor)
      Creates an upcall stub from a functional interface instance.

      This is a convenience method that looks up the single abstract method (SAM) of the functional interface and creates an upcall stub for it.

      Type Parameters:
      T - The functional interface type
      Parameters:
      arena - Arena controlling the stub's lifetime
      lookup - MethodHandles.Lookup with access to the interface
      callback - The callback instance (lambda or method reference)
      functionalInterface - The functional interface class
      descriptor - Native function signature
      Returns:
      MemorySegment representing a native function pointer
      Throws:
      IllegalArgumentException - if the interface is not a functional interface
      RuntimeException - if the method cannot be found or accessed

    • upcallStub

      public <T> MemorySegment upcallStub(Arena arena, T callback, Class<T> functionalInterface, FunctionDescriptor descriptor)
      Creates an upcall stub using the caller's lookup context.
      Type Parameters:
      T - The functional interface type
      Parameters:
      arena - Arena controlling the stub's lifetime
      callback - The callback instance
      functionalInterface - The functional interface class
      descriptor - Native function signature
      Returns:
      MemorySegment representing a native function pointer

    • linker

      public Linker linker()
      Get the underlying linker.