Class PanamaFunctionReference

java.lang.Object
ai.tegmentum.wasmtime4j.panama.PanamaFunctionReference
All Implemented Interfaces:
ai.tegmentum.wasmtime4j.func.FunctionReference
public final class PanamaFunctionReference extends Object implements ai.tegmentum.wasmtime4j.func.FunctionReference
Panama FFI implementation for WebAssembly function references.

Function references enable dynamic function dispatch and callback mechanisms in WebAssembly programs. They can be passed as parameters, stored in tables, and called indirectly through call_indirect instructions.

This implementation provides thread-safe management of function references with comprehensive defensive programming practices to prevent JVM crashes and resource leaks.

Key Features:

  • Thread-safe function reference creation and management
  • Support for both host functions and WebAssembly functions
  • Automatic resource cleanup and lifecycle management
  • Parameter and return value marshalling via Panama FFI
  • Error handling and exception propagation
Since:
1.0.0

  • Constructor Details

    • PanamaFunctionReference

      public PanamaFunctionReference(ai.tegmentum.wasmtime4j.func.HostFunction hostFunction, ai.tegmentum.wasmtime4j.type.FunctionType functionType, PanamaStore store, ArenaResourceManager arenaManager) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Creates a new function reference from a host function.
      Parameters:
      hostFunction - the host function implementation
      functionType - the WebAssembly function type signature
      store - the store this function reference belongs to
      arenaManager - the arena resource manager for memory lifecycle
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if function reference creation fails
      IllegalArgumentException - if any required parameter is null

    • PanamaFunctionReference

      public PanamaFunctionReference(ai.tegmentum.wasmtime4j.WasmFunction wasmFunction, PanamaStore store, ArenaResourceManager arenaManager) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Creates a new function reference from a WebAssembly function.
      Parameters:
      wasmFunction - the WebAssembly function
      store - the store this function reference belongs to
      arenaManager - the arena resource manager for memory lifecycle
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if function reference creation fails
      IllegalArgumentException - if any required parameter is null

  • Method Details

    • getFunctionType

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

    • 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.func.FunctionReference
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException

    • getName

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

    • isValid

      public boolean isValid()
      Specified by:
      isValid in interface ai.tegmentum.wasmtime4j.func.FunctionReference

    • getId

      public long getId()
      Specified by:
      getId in interface ai.tegmentum.wasmtime4j.func.FunctionReference

    • isHostFunction

      public boolean isHostFunction()
      Checks if this function reference is a host function.
      Returns:
      true if this is a host function reference

    • isWasmFunction

      public boolean isWasmFunction()
      Checks if this function reference is a WebAssembly function.
      Returns:
      true if this is a WebAssembly function reference

    • getUpcallStub

      public MemorySegment getUpcallStub()
      Gets the upcall stub for this function reference.

      This is used when passing the function reference to native code.

      Returns:
      the upcall stub memory segment, or null for WebAssembly functions

    • longValue

      public long longValue()
      Returns the registry ID as a long value for storage in globals or tables.
      Returns:
      the registry ID

    • close

      public void close() throws ai.tegmentum.wasmtime4j.exception.WasmException
      Closes this function reference and releases its resources.
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if closing fails

    • getNativeRegistryId

      public long getNativeRegistryId()
      Gets the native registry ID for this function reference.

      This ID is used when setting funcref globals or storing in tables.

      Returns:
      the native registry ID, or -1 if not registered

    • getFunctionReferenceById

      public static ai.tegmentum.wasmtime4j.func.FunctionReference getFunctionReferenceById(long functionReferenceId)
      Retrieves a function reference from the registry by ID.

      This is the public accessor for looking up function references during value unmarshalling.

      Parameters:
      functionReferenceId - the function reference ID
      Returns:
      the function reference, or null if not found

    • getGlobalCallbackStub

      public static MemorySegment getGlobalCallbackStub()
      Gets the global callback stub address for use with native function reference creation.

      This method returns a memory segment pointing to a static callback function that can be passed to native code. When the native code calls this callback, it dispatches to the appropriate Java function reference based on the callback ID.

      Returns:
      the global callback stub memory segment

    • invokeNativeCallback

      public static int invokeNativeCallback(long callbackId, MemorySegment paramsPtr, int paramsLen, MemorySegment resultsPtr, int resultsLen, MemorySegment errorMsgPtr, int errorMsgLen)
      Native callback entry point for function reference invocation.

      This static method is called by native code through the global callback stub. It unmarshals parameters, invokes the function reference, and marshals results back.

      Parameters:
      callbackId - the function reference ID
      paramsPtr - pointer to the parameter array
      paramsLen - number of parameters
      resultsPtr - pointer to the result buffer
      resultsLen - expected number of results
      errorMsgPtr - pointer to error message buffer (for writing on failure)
      errorMsgLen - size of error message buffer
      Returns:
      0 on success, non-zero on error

    • toString

      public String toString()
      Overrides:
      toString in class Object