Class PanamaHostFunction

java.lang.Object
ai.tegmentum.wasmtime4j.panama.PanamaHostFunction
All Implemented Interfaces:
ai.tegmentum.wasmtime4j.WasmFunction
public final class PanamaHostFunction extends Object implements ai.tegmentum.wasmtime4j.WasmFunction
Panama FFI implementation for host functions that can be called from WebAssembly.

This class provides the foundation for callback upcall handles, allowing Java code to expose functions that can be imported and called by WebAssembly modules. It uses Panama's upcall stub mechanism for optimal performance while maintaining type safety and error handling.

The implementation uses a registry pattern to track active host functions and prevent premature garbage collection of callback stubs, ensuring memory safety across the FFI boundary.

Since:
1.0.0

  • Constructor Details

    • PanamaHostFunction

      public PanamaHostFunction(String functionName, ai.tegmentum.wasmtime4j.type.FunctionType functionType, PanamaHostFunction.HostFunctionCallback callback, ai.tegmentum.wasmtime4j.func.HostFunction implementation, PanamaStore store, ArenaResourceManager arenaManager) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Creates a new host function with the specified signature and implementation.
      Parameters:
      functionName - the name of the function (for debugging/logging)
      functionType - the WebAssembly function type signature
      callback - the Java implementation of the function
      implementation - the original HostFunction implementation (may be null for direct callbacks)
      store - the store this host function belongs to (may be null for direct callbacks)
      arenaManager - the arena resource manager for memory lifecycle
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if host function creation fails
      IllegalArgumentException - if any parameter is null

    • PanamaHostFunction

      public PanamaHostFunction(String functionName, ai.tegmentum.wasmtime4j.type.FunctionType functionType, PanamaHostFunction.HostFunctionCallback callback, ai.tegmentum.wasmtime4j.func.HostFunction implementation, PanamaStore store, ArenaResourceManager arenaManager, boolean unchecked) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Creates a new host function with the specified signature and implementation.
      Parameters:
      functionName - the name of the function (for debugging/logging)
      functionType - the WebAssembly function type signature
      callback - the Java implementation of the function
      implementation - the original HostFunction implementation (may be null for direct callbacks)
      store - the store this host function belongs to (may be null for direct callbacks)
      arenaManager - the arena resource manager for memory lifecycle
      unchecked - if true, uses Func::new_unchecked for better performance
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if host function creation fails
      IllegalArgumentException - if any parameter is null

  • Method Details

    • call

      public ai.tegmentum.wasmtime4j.WasmValue[] call(ai.tegmentum.wasmtime4j.WasmValue... params) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Specified by:
      call in interface ai.tegmentum.wasmtime4j.WasmFunction
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException

    • getFunctionType

      public ai.tegmentum.wasmtime4j.type.FunctionType getFunctionType()
      Specified by:
      getFunctionType in interface ai.tegmentum.wasmtime4j.WasmFunction

    • getName

      public String getName()
      Specified by:
      getName in interface ai.tegmentum.wasmtime4j.WasmFunction

    • toRawFuncRef

      public long toRawFuncRef() throws ai.tegmentum.wasmtime4j.exception.WasmException
      Specified by:
      toRawFuncRef in interface ai.tegmentum.wasmtime4j.WasmFunction
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException

    • callAsync

      public CompletableFuture<ai.tegmentum.wasmtime4j.WasmValue[]> callAsync(ai.tegmentum.wasmtime4j.WasmValue... params)
      Specified by:
      callAsync in interface ai.tegmentum.wasmtime4j.WasmFunction

    • getFunctionHandle

      public MemorySegment getFunctionHandle()
      Gets the native function handle for use in WebAssembly import operations.

      This handle can be passed to WebAssembly runtime functions to create function imports that reference this host function.

      Returns:
      the native function handle
      Throws:
      IllegalStateException - if the host function has been closed

    • getFuncRefId

      public long getFuncRefId()
      Gets the native function reference registry ID for table operations.

      This ID is used to look up the function in the native reference registry when setting table elements.

      Returns:
      the function reference ID, or 0 if not registered

    • getUpcallStub

      public MemorySegment getUpcallStub()
      Gets the upcall stub for direct FFI integration.

      This method is intended for internal use by Panama FFI components and should not be used by application code.

      Returns:
      the upcall stub memory segment
      Throws:
      IllegalStateException - if the host function has been closed

    • isClosed

      public boolean isClosed()
      Checks if this host function has been closed.
      Returns:
      true if the host function has been closed

    • close

      public void close() throws ai.tegmentum.wasmtime4j.exception.WasmException
      Closes this host function and releases its resources.
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException

    • toString

      public String toString()
      Overrides:
      toString in class Object