Class NativeInstanceBindings

java.lang.Object
ai.tegmentum.wasmtime4j.panama.NativeInstanceBindings
public final class NativeInstanceBindings extends Object
Native function bindings for Instance, Linker, InstancePre, Caller, Function, Function Reference, extern type, and call hook operations.

Provides type-safe wrappers for all Wasmtime instance lifecycle, linker configuration and instantiation, caller context access, function invocation, function reference management, and call hook native functions. Hot-path methods use eagerly initialized volatile MethodHandle fields for invokeExact optimization.

This class follows the singleton pattern with double-checked locking.

  • Method Details

    • getInstance

      public static NativeInstanceBindings getInstance()
      Gets the singleton instance.
      Returns:
      the singleton instance
      Throws:
      RuntimeException - if initialization fails

    • getPanamaInstanceCreate

      public MethodHandle getPanamaInstanceCreate()
      Gets the method handle for Panama FFI instance creation.
      Returns:
      the method handle, or null if not available

    • instanceCreate

      public MemorySegment instanceCreate(MemorySegment storePtr, MemorySegment modulePtr)
      Creates a WebAssembly instance (Panama FFI).
      Parameters:
      storePtr - pointer to the store
      modulePtr - pointer to the module
      Returns:
      memory segment pointer to the instance, or null on failure

    • panamaInstanceCreateWithImports

      public int panamaInstanceCreateWithImports(MemorySegment storePtr, MemorySegment modulePtr, MemorySegment externPtrs, MemorySegment externTypes, int count, MemorySegment instanceOut)
      Creates a WebAssembly instance with explicit imports (Panama FFI).
      Parameters:
      storePtr - pointer to the store
      modulePtr - pointer to the module
      externPtrs - pointer to array of extern handle pointers
      externTypes - pointer to array of extern type codes
      count - number of imports
      instanceOut - output pointer for the created instance
      Returns:
      0 on success, negative error code on failure

    • panamaInstanceGetModuleExport

      public int panamaInstanceGetModuleExport(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment moduleExportPtr, MemorySegment outHandle, MemorySegment outType)
      Gets an export from an instance using a pre-resolved ModuleExport handle (Panama FFI).
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      moduleExportPtr - pointer to the ModuleExport handle
      outHandle - output pointer for the extern handle
      outType - output pointer for the extern type code
      Returns:
      0 on success, negative error code on failure

    • panamaModuleGetModuleExport

      public int panamaModuleGetModuleExport(MemorySegment modulePtr, MemorySegment namePtr, MemorySegment outPtr)
      Gets a ModuleExport handle for O(1) export lookups (Panama FFI).
      Parameters:
      modulePtr - pointer to the module
      namePtr - pointer to the export name string
      outPtr - output pointer for the ModuleExport handle
      Returns:
      0 on success, negative error code on failure

    • instanceCallFunctionFast

      public long instanceCallFunctionFast(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment functionName, MemorySegment paramsPtr, long paramCount, MemorySegment resultsPtr, long maxResults)
      Fast path for instance function calls using invokeExact.

      This method is optimized for performance by using invokeExact instead of invokeWithArguments, which avoids varargs array creation, primitive boxing, and runtime type checking.

      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionName - name of the function to call
      paramsPtr - pointer to array of WasmValue parameters
      paramCount - number of parameters
      resultsPtr - pointer to buffer for WasmValue results
      maxResults - maximum number of results to return
      Returns:
      number of actual results (0 on error)

    • instanceCallVoid

      public int instanceCallVoid(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment functionName)
      Typed fast-path: call a function with signature () -> void.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionName - null-terminated function name
      Returns:
      0 on success, -1 on error

    • instanceCallI32ToI32

      public int instanceCallI32ToI32(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment functionName, int arg, MemorySegment resultPtr)
      Typed fast-path: call a function with signature (i32) -> i32.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionName - null-terminated function name
      arg - the i32 argument
      resultPtr - pointer to write the i32 result
      Returns:
      0 on success, -1 on error

    • instanceCallI32I32ToI32

      public int instanceCallI32I32ToI32(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment functionName, int arg1, int arg2, MemorySegment resultPtr)
      Typed fast-path: call a function with signature (i32, i32) -> i32.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionName - null-terminated function name
      arg1 - first i32 argument
      arg2 - second i32 argument
      resultPtr - pointer to write the i32 result
      Returns:
      0 on success, -1 on error

    • instanceCallI64ToI64

      public int instanceCallI64ToI64(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment functionName, long arg, MemorySegment resultPtr)
      Typed fast-path: call a function with signature (i64) -> i64.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionName - null-terminated function name
      arg - the i64 argument
      resultPtr - pointer to write the i64 result
      Returns:
      0 on success, -1 on error

    • instanceCallF64ToF64

      public int instanceCallF64ToF64(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment functionName, double arg, MemorySegment resultPtr)
      Typed fast-path: call a function with signature (f64) -> f64.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionName - null-terminated function name
      arg - the f64 argument
      resultPtr - pointer to write the f64 result
      Returns:
      0 on success, -1 on error

    • instanceCallToI32

      public int instanceCallToI32(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment functionName, MemorySegment resultPtr)
      Typed fast-path: call a function with signature () -> i32.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionName - null-terminated function name
      resultPtr - pointer to write the i32 result
      Returns:
      0 on success, -1 on error

    • instanceGetMemoryByName

      public MemorySegment instanceGetMemoryByName(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name)
      Gets a memory export by name from an instance.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the memory export
      Returns:
      memory segment pointer or null if not found

    • instanceGetSharedMemoryByName

      public MemorySegment instanceGetSharedMemoryByName(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name)
      Gets a shared memory export by name from an instance (only shared memories).
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the shared memory export
      Returns:
      memory segment pointer or null if not found

    • instanceGetMemorySizePages

      public int instanceGetMemorySizePages(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name, MemorySegment sizeOut)
      Gets memory size in pages by looking up the memory fresh.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the memory export
      sizeOut - pointer to store the size
      Returns:
      0 on success, negative error code on failure

    • instanceGrowMemory

      public int instanceGrowMemory(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name, long pages, MemorySegment previousPagesOut)
      Grows memory by looking up the memory fresh.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the memory export
      pages - number of pages to grow
      previousPagesOut - pointer to store previous size
      Returns:
      0 on success, negative error code on failure

    • instanceGetGlobalType

      public int instanceGetGlobalType(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name, MemorySegment valueTypeOut, MemorySegment isMutableOut)
      Gets the type and mutability of a global export.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the global export
      valueTypeOut - output for value type code
      isMutableOut - output for mutability flag
      Returns:
      0 on success, negative error code on failure

    • instanceHasGlobalExport

      public int instanceHasGlobalExport(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name)
      Checks if a global export exists in an instance.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the global export
      Returns:
      0 if global exists, non-zero if not found or error

    • instanceGetGlobalValue

      public int instanceGetGlobalValue(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name, MemorySegment i32Out, MemorySegment i64Out, MemorySegment f32Out, MemorySegment f64Out, MemorySegment refIdPresentOut, MemorySegment refIdOut)
      Gets the value of a global by looking it up fresh from the instance.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the global export
      i32Out - output for i32 value
      i64Out - output for i64 value
      f32Out - output for f32 value (as double)
      f64Out - output for f64 value
      refIdPresentOut - output for reference presence flag
      refIdOut - output for reference ID
      Returns:
      0 on success, negative error code on failure

    • instanceSetGlobalValue

      public int instanceSetGlobalValue(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name, int valueTypeCode, int i32Value, long i64Value, double f32Value, double f64Value, int refIdPresent, long refId)
      Sets the value of a global by looking it up fresh from the instance.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the global export
      valueTypeCode - type code (0=I32, 1=I64, 2=F32, 3=F64, 5=FuncRef, 6=ExternRef)
      i32Value - i32 value
      i64Value - i64 value
      f32Value - f32 value (as double)
      f64Value - f64 value
      refIdPresent - reference presence flag
      refId - reference ID
      Returns:
      0 on success, negative error code on failure

    • instanceGetTableByName

      public MemorySegment instanceGetTableByName(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name)
      Gets a table export by name from an instance.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the table export
      Returns:
      table segment pointer or null if not found

    • instanceGetTagByName

      public MemorySegment instanceGetTagByName(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name)
      Gets a tag export by name from an instance.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the tag export
      Returns:
      tag segment pointer or null if not found

    • instanceGetGlobalWrapped

      public MemorySegment instanceGetGlobalWrapped(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name)
      Gets a global export by name from an instance, wrapped for linker use.

      Returns a properly wrapped Global struct that can be used with panamaLinkerDefineGlobal(java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment).

      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - name of the global export
      Returns:
      wrapped global segment pointer or null if not found

    • instanceDebugFunction

      public MemorySegment instanceDebugFunction(MemorySegment instancePtr, MemorySegment storePtr, int functionIndex)
      Debug: gets a function by its internal module index.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      functionIndex - the internal function index
      Returns:
      function handle or null if not found

    • instanceDebugGlobal

      public MemorySegment instanceDebugGlobal(MemorySegment instancePtr, MemorySegment storePtr, int globalIndex)
      Debug: gets a global by its internal module index.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      globalIndex - the internal global index
      Returns:
      global handle or null if not found

    • instanceDebugMemory

      public MemorySegment instanceDebugMemory(MemorySegment instancePtr, MemorySegment storePtr, int memoryIndex)
      Debug: gets a memory by its internal module index.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      memoryIndex - the internal memory index
      Returns:
      memory handle or null if not found

    • instanceDebugSharedMemory

      public MemorySegment instanceDebugSharedMemory(MemorySegment instancePtr, MemorySegment storePtr, int memoryIndex)
      Debug: gets a shared memory by its internal module index.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      memoryIndex - the internal memory index
      Returns:
      shared memory handle or null if not found

    • instanceDebugTable

      public MemorySegment instanceDebugTable(MemorySegment instancePtr, MemorySegment storePtr, int tableIndex)
      Debug: gets a table by its internal module index.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      tableIndex - the internal table index
      Returns:
      table handle or null if not found

    • instanceDebugTag

      public MemorySegment instanceDebugTag(MemorySegment instancePtr, MemorySegment storePtr, int tagIndex)
      Debug: gets a tag by its internal module index.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      tagIndex - the internal tag index
      Returns:
      tag handle or null if not found

    • callerGetFuelRemaining

      public int callerGetFuelRemaining(MemorySegment callerPtr, MemorySegment fuelOut)
      Gets the fuel remaining in the caller if fuel metering is enabled.
      Parameters:
      callerPtr - pointer to the caller context
      fuelOut - pointer to store the fuel value
      Returns:
      0 on success, negative error code on failure

    • callerAddFuel

      public int callerAddFuel(MemorySegment callerPtr, long fuel)
      Adds fuel to the caller.
      Parameters:
      callerPtr - pointer to the caller context
      fuel - amount of fuel to add
      Returns:
      0 on success, negative error code on failure

    • callerSetFuel

      public int callerSetFuel(MemorySegment callerPtr, long fuel)
      Sets the fuel level to a specific value for the caller.
      Parameters:
      callerPtr - pointer to the caller context
      fuel - the fuel level to set
      Returns:
      0 on success, negative error code on failure

    • callerHasExport

      public int callerHasExport(MemorySegment callerPtr, MemorySegment name)
      Checks if caller has an export with the given name.
      Parameters:
      callerPtr - pointer to the caller context
      name - name of the export to check
      Returns:
      1 if export exists, 0 if not found, negative error code on failure

    • callerGetMemory

      public int callerGetMemory(MemorySegment callerPtr, MemorySegment name, MemorySegment memoryOut)
      Gets memory export from caller by name.
      Parameters:
      callerPtr - pointer to the caller context
      name - name of the memory export
      memoryOut - pointer to store the memory pointer
      Returns:
      1 if memory found, 0 if not found, negative error code on failure

    • callerGetFunction

      public int callerGetFunction(MemorySegment callerPtr, MemorySegment name, MemorySegment functionOut)
      Gets function export from caller by name.
      Parameters:
      callerPtr - pointer to the caller context
      name - name of the function export
      functionOut - pointer to store the function pointer
      Returns:
      1 if function found, 0 if not found, negative error code on failure

    • callerGetGlobal

      public int callerGetGlobal(MemorySegment callerPtr, MemorySegment name, MemorySegment globalOut)
      Gets global export from caller by name.
      Parameters:
      callerPtr - pointer to the caller context
      name - name of the global export
      globalOut - pointer to store the global pointer
      Returns:
      1 if global found, 0 if not found, negative error code on failure

    • callerGetTable

      public int callerGetTable(MemorySegment callerPtr, MemorySegment name, MemorySegment tableOut)
      Gets table export from caller by name.
      Parameters:
      callerPtr - pointer to the caller context
      name - name of the table export
      tableOut - pointer to store the table pointer
      Returns:
      1 if table found, 0 if not found, negative error code on failure

    • callerSetFuelAsyncYieldInterval

      public int callerSetFuelAsyncYieldInterval(MemorySegment callerPtr, long interval)
      Sets the fuel async yield interval for the caller's store.
      Parameters:
      callerPtr - pointer to the caller
      interval - the yield interval, or 0 to disable
      Returns:
      0 on success, non-zero on error

    • callerDebugExitFrames

      public int callerDebugExitFrames(MemorySegment callerPtr, MemorySegment countOut, MemorySegment outData)
      Gets debug exit frames from the caller.

      Two-phase protocol: first call with outData=NULL to get count, second call with allocated buffer to get data.

      Parameters:
      callerPtr - pointer to the caller context
      countOut - pointer to store the frame count
      outData - pointer to frame data buffer (NULL for phase 1)
      Returns:
      0 on success, -1 if debugging not enabled, -2 on error
      Since:
      1.1.0

    • funcCall

      public int funcCall(MemorySegment funcPtr, MemorySegment storePtr, MemorySegment paramsPtr, long paramCount, MemorySegment resultsPtr, long resultCount)
      Calls a WebAssembly function directly using a function handle.
      Parameters:
      funcPtr - pointer to the function
      storePtr - pointer to the store
      paramsPtr - pointer to parameters array (WasmValue format)
      paramCount - number of parameters
      resultsPtr - pointer to results buffer (WasmValue format)
      resultCount - maximum number of results
      Returns:
      0 on success, negative error code on failure

    • funcGetType

      public MemorySegment funcGetType(MemorySegment funcPtr, MemorySegment storePtr)
      Gets the function type for a function handle.
      Parameters:
      funcPtr - pointer to the function
      storePtr - pointer to the store
      Returns:
      pointer to the function type, or null on failure

    • funcMatchesTy

      public int funcMatchesTy(MemorySegment funcPtr, MemorySegment storePtr, MemorySegment paramTypesPtr, int paramCount, MemorySegment resultTypesPtr, int resultCount)
      Checks if a function matches a function type using subtype-aware checking.
      Parameters:
      funcPtr - the function pointer
      storePtr - the store pointer
      paramTypesPtr - pointer to array of param type codes
      paramCount - number of param types
      resultTypesPtr - pointer to array of result type codes
      resultCount - number of result types
      Returns:
      1 if matches, 0 if not, negative on error

    • funcDestroy

      public void funcDestroy(MemorySegment funcPtr)
      Destroys a function handle.
      Parameters:
      funcPtr - pointer to the function to destroy

    • funcTypeDestroy

      public void funcTypeDestroy(MemorySegment funcTypePtr)
      Destroys a function type handle.
      Parameters:
      funcTypePtr - pointer to the function type to destroy

    • funcGet

      public int funcGet(MemorySegment instancePtr, MemorySegment storePtr, MemorySegment name, MemorySegment funcPtrOut)
      Gets a function export from an instance by name.
      Parameters:
      instancePtr - pointer to the instance
      storePtr - pointer to the store
      name - function name (native string)
      funcPtrOut - output pointer for the function handle
      Returns:
      0 on success, non-zero on failure

    • funcToRaw

      public long funcToRaw(MemorySegment funcPtr, MemorySegment storePtr)
      Converts a function to its raw funcref pointer value.
      Parameters:
      funcPtr - pointer to the function
      storePtr - pointer to the store
      Returns:
      the raw funcref value (i64)

    • funcFromRaw

      public MemorySegment funcFromRaw(MemorySegment storePtr, long raw)
      Reconstructs a function from a raw funcref pointer.
      Parameters:
      storePtr - pointer to the store
      raw - the raw funcref value
      Returns:
      pointer to the reconstructed function, or NULL if invalid

    • funcCallNativeAsync

      public long funcCallNativeAsync(MemorySegment funcPtr, MemorySegment storePtr, MemorySegment paramsPtr, long paramCount, MemorySegment resultsPtr, long maxResults)
      Calls a WebAssembly function using Wasmtime's native async call path.

      Uses Func::call_async via the async runtime, blocking the current thread but enabling proper async host function interleaving.

      Parameters:
      funcPtr - pointer to the function
      storePtr - pointer to the store
      paramsPtr - pointer to parameters array (WasmValue format)
      paramCount - number of parameters
      resultsPtr - pointer to results buffer (WasmValue format)
      maxResults - maximum number of results
      Returns:
      actual result count on success, negative value on failure

    • panamaLinkerCreate

      public MemorySegment panamaLinkerCreate(MemorySegment enginePtr)
      Creates a new Panama linker.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      pointer to the linker, or null on failure

    • panamaLinkerDefineHostFunction

      public int panamaLinkerDefineHostFunction(MemorySegment linkerPtr, MemorySegment moduleName, MemorySegment name, MemorySegment paramTypes, int paramCount, MemorySegment returnTypes, int returnCount, MemorySegment callbackFn, long callbackId)
      Defines a host function in the Panama linker.
      Parameters:
      linkerPtr - pointer to the linker
      moduleName - module name (C string)
      name - function name (C string)
      paramTypes - parameter types array
      paramCount - number of parameters
      returnTypes - return types array
      returnCount - number of returns
      callbackFn - callback function pointer
      callbackId - callback ID
      Returns:
      0 on success, non-zero on error

    • panamaLinkerDefineHostFunctionUnchecked

      public int panamaLinkerDefineHostFunctionUnchecked(MemorySegment linkerPtr, MemorySegment moduleName, MemorySegment name, MemorySegment paramTypes, int paramCount, MemorySegment returnTypes, int returnCount, MemorySegment callbackFn, long callbackId)
      Defines an unchecked host function in the linker (Panama FFI version).

      This uses Func::new_unchecked internally, which skips type-checking at call time for better performance. The caller is responsible for ensuring correct types.

      Parameters:
      linkerPtr - pointer to the linker
      moduleName - pointer to the module name string
      name - pointer to the function name string
      paramTypes - pointer to array of parameter type codes
      paramCount - number of parameters
      returnTypes - pointer to array of return type codes
      returnCount - number of returns
      callbackFn - callback function pointer
      callbackId - callback ID
      Returns:
      0 on success, non-zero on error

    • panamaLinkerDefineGlobal

      public int panamaLinkerDefineGlobal(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr, MemorySegment namePtr, MemorySegment globalPtr)
      Defines a global in the linker (Panama FFI version).
      Parameters:
      linkerPtr - pointer to the linker
      storePtr - pointer to the store
      moduleNamePtr - pointer to the module name string
      namePtr - pointer to the global name string
      globalPtr - pointer to the global
      Returns:
      0 on success, negative error code on failure

    • panamaLinkerDefineMemory

      public int panamaLinkerDefineMemory(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr, MemorySegment namePtr, MemorySegment memoryPtr)
      Defines a memory in the linker (Panama FFI version).
      Parameters:
      linkerPtr - pointer to the linker
      storePtr - pointer to the store
      moduleNamePtr - pointer to the module name string
      namePtr - pointer to the memory name string
      memoryPtr - pointer to the memory
      Returns:
      0 on success, negative error code on failure

    • panamaLinkerDefineMemoryFromInstance

      public int panamaLinkerDefineMemoryFromInstance(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr, MemorySegment memoryNamePtr, MemorySegment instancePtr, MemorySegment exportNamePtr)
      Defines a memory from an instance in the linker (Panama FFI version).

      This variant extracts the memory from the instance and defines it in the linker all within the same store context to avoid store mismatch issues.

      Parameters:
      linkerPtr - pointer to the linker
      storePtr - pointer to the store
      moduleNamePtr - pointer to the module name string
      memoryNamePtr - pointer to the memory name string
      instancePtr - pointer to the instance containing the memory
      exportNamePtr - pointer to the export name of the memory in the instance
      Returns:
      0 on success, negative error code on failure

    • panamaLinkerDefineTable

      public int panamaLinkerDefineTable(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr, MemorySegment namePtr, MemorySegment tablePtr)
      Defines a table in the linker (Panama FFI version).
      Parameters:
      linkerPtr - pointer to the linker
      storePtr - pointer to the store
      moduleNamePtr - pointer to the module name string
      namePtr - pointer to the table name string
      tablePtr - pointer to the table
      Returns:
      0 on success, negative error code on failure

    • panamaLinkerDefineInstance

      public int panamaLinkerDefineInstance(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr, MemorySegment instancePtr)
      Defines an instance in the linker (Panama FFI version).
      Parameters:
      linkerPtr - pointer to the linker
      storePtr - pointer to the store
      moduleNamePtr - pointer to the module name string
      instancePtr - pointer to the instance
      Returns:
      0 on success, negative error code on failure

    • panamaLinkerModule

      public int panamaLinkerModule(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr, MemorySegment modulePtr)
      Defines a module in the linker, instantiating it and registering all exports (Panama FFI version). This corresponds to Wasmtime's Linker::module() which handles WASI commands specially.
      Parameters:
      linkerPtr - pointer to the linker
      storePtr - pointer to the store
      moduleNamePtr - pointer to the module name string
      modulePtr - pointer to the module
      Returns:
      0 on success, negative error code on failure

    • panamaLinkerInstantiate

      public MemorySegment panamaLinkerInstantiate(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment modulePtr)
      Instantiates a module using the linker (Panama FFI version).
      Parameters:
      linkerPtr - pointer to the linker
      storePtr - pointer to the store
      modulePtr - pointer to the module
      Returns:
      pointer to the instance, or null on failure

    • panamaLinkerAlias

      public int panamaLinkerAlias(MemorySegment linkerPtr, MemorySegment fromModulePtr, MemorySegment fromNamePtr, MemorySegment toModulePtr, MemorySegment toNamePtr)
      Creates an alias for an export in the linker.
      Parameters:
      linkerPtr - pointer to the linker
      fromModulePtr - pointer to the source module name
      fromNamePtr - pointer to the source export name
      toModulePtr - pointer to the destination module name
      toNamePtr - pointer to the destination export name
      Returns:
      0 on success, negative error code on failure

    • panamaLinkerAliasModule

      public int panamaLinkerAliasModule(MemorySegment linkerPtr, MemorySegment modulePtr, MemorySegment asModulePtr)
      Aliases all definitions from one module name to another.
      Parameters:
      linkerPtr - pointer to the linker
      modulePtr - source module name (C string)
      asModulePtr - destination module name (C string)
      Returns:
      0 on success, non-zero error code on failure

    • panamaLinkerDestroy

      public void panamaLinkerDestroy(MemorySegment linkerPtr)
      Destroys a Panama linker.
      Parameters:
      linkerPtr - pointer to the linker to destroy

    • linkerAddWasi

      public int linkerAddWasi(MemorySegment linkerHandle)
      Adds WASI Preview 1 imports to a linker.

      Configures the linker to extract WASI context from store data when instantiating modules. The store must have a WASI context attached before instantiating WASI-enabled modules.

      Parameters:
      linkerHandle - pointer to the linker
      Returns:
      0 on success, non-zero on failure

    • linkerAllowShadowing

      public int linkerAllowShadowing(MemorySegment linkerPtr, int allow)
      Allows subsequent definitions to shadow prior definitions.
      Parameters:
      linkerPtr - the linker pointer
      allow - 1 to allow, 0 to disallow
      Returns:
      0 on success, -1 on error

    • linkerAllowUnknownExports

      public int linkerAllowUnknownExports(MemorySegment linkerPtr, int allow)
      Allows unknown exports from modules.
      Parameters:
      linkerPtr - the linker pointer
      allow - 1 to allow, 0 to disallow
      Returns:
      0 on success, -1 on error

    • linkerDefineUnknownImportsAsTraps

      public int linkerDefineUnknownImportsAsTraps(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment modulePtr)
      Defines all undefined imports as trapping functions.
      Parameters:
      linkerPtr - the linker pointer
      storePtr - the store pointer
      modulePtr - the module pointer
      Returns:
      0 on success, -1 on error

    • linkerDefineUnknownImportsAsDefaultValues

      public int linkerDefineUnknownImportsAsDefaultValues(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment modulePtr)
      Defines all undefined imports with default values.
      Parameters:
      linkerPtr - the linker pointer
      storePtr - the store pointer
      modulePtr - the module pointer
      Returns:
      0 on success, -1 on error

    • linkerGetByImport

      public MemorySegment linkerGetByImport(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr, MemorySegment namePtr)
      Gets a definition by its import specifier.
      Parameters:
      linkerPtr - the linker pointer
      storePtr - the store pointer
      moduleNamePtr - the module name string
      namePtr - the item name string
      Returns:
      the extern pointer, or NULL if not found

    • linkerGetDefault

      public MemorySegment linkerGetDefault(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment moduleNamePtr)
      Gets the default function for a module.
      Parameters:
      linkerPtr - the linker pointer
      storePtr - the store pointer
      moduleNamePtr - the module name string
      Returns:
      the function pointer, or NULL if not found

    • linkerIter

      public int linkerIter(MemorySegment linkerPtr, MemorySegment storePtr, MemorySegment outCountPtr)
      Iterates over all definitions in the linker.

      Stores the results in thread-local storage for retrieval with linkerIterGet(int, java.lang.foreign.MemorySegment, int, java.lang.foreign.MemorySegment, int, java.lang.foreign.MemorySegment).

      Parameters:
      linkerPtr - the linker pointer
      storePtr - the store pointer
      outCountPtr - pointer to write the definition count
      Returns:
      0 on success, -1 on error

    • linkerIterGet

      public int linkerIterGet(int index, MemorySegment outModuleNamePtr, int moduleNameCapacity, MemorySegment outItemNamePtr, int itemNameCapacity, MemorySegment outTypeCodePtr)
      Gets a specific definition from the last iter() call.
      Parameters:
      index - the definition index
      outModuleNamePtr - buffer for the module name
      moduleNameCapacity - capacity of the module name buffer
      outItemNamePtr - buffer for the item name
      itemNameCapacity - capacity of the item name buffer
      outTypeCodePtr - pointer for the type code
      Returns:
      0 on success, -1 on error

    • linkerInstantiatePre

      public MemorySegment linkerInstantiatePre(MemorySegment linkerPtr, MemorySegment modulePtr)
      Creates an InstancePre from a linker and module for fast repeated instantiation.
      Parameters:
      linkerPtr - pointer to the linker
      modulePtr - pointer to the module
      Returns:
      pointer to the InstancePre, or null on failure

    • instancePreInstantiate

      public MemorySegment instancePreInstantiate(MemorySegment instancePrePtr, MemorySegment storePtr)
      Instantiates from an InstancePre with a store.
      Parameters:
      instancePrePtr - pointer to the InstancePre
      storePtr - pointer to the store
      Returns:
      pointer to the new instance, or null on failure

    • instancePreInstantiateAsync

      public MemorySegment instancePreInstantiateAsync(MemorySegment instancePrePtr, MemorySegment storePtr)
      Asynchronously instantiates from an InstancePre.

      Requires async support enabled in the engine.

      Parameters:
      instancePrePtr - pointer to the InstancePre
      storePtr - pointer to the store
      Returns:
      pointer to the created instance, or NULL on failure

    • instancePreIsValid

      public int instancePreIsValid(MemorySegment instancePrePtr)

    • instancePreGetInstanceCount

      public long instancePreGetInstanceCount(MemorySegment instancePrePtr)
      Gets the instance count for an InstancePre.
      Parameters:
      instancePrePtr - pointer to the InstancePre
      Returns:
      the number of instances created from this InstancePre

    • instancePreGetPreparationTimeNs

      public long instancePreGetPreparationTimeNs(MemorySegment instancePrePtr)
      Gets the preparation time in nanoseconds for an InstancePre.
      Parameters:
      instancePrePtr - pointer to the InstancePre
      Returns:
      the preparation time in nanoseconds

    • instancePreGetAvgInstantiationTimeNs

      public long instancePreGetAvgInstantiationTimeNs(MemorySegment instancePrePtr)
      Gets the average instantiation time in nanoseconds for an InstancePre.
      Parameters:
      instancePrePtr - pointer to the InstancePre
      Returns:
      the average instantiation time in nanoseconds

    • instancePreDestroy

      public void instancePreDestroy(MemorySegment instancePrePtr)
      Destroys an InstancePre.
      Parameters:
      instancePrePtr - pointer to the InstancePre to destroy

    • functionReferenceCreate

      public int functionReferenceCreate(MemorySegment storePtr, MemorySegment paramTypes, int paramCount, MemorySegment returnTypes, int returnCount, MemorySegment callbackFn, long callbackId, MemorySegment resultOut)
      Creates a new function reference.
      Parameters:
      storePtr - pointer to the store
      paramTypes - parameter types array
      paramCount - number of parameters
      returnTypes - return types array
      returnCount - number of return values
      callbackFn - callback function pointer
      callbackId - callback ID for identifying the Java callback
      resultOut - pointer to store the registry ID
      Returns:
      0 on success, non-zero on error

    • externGetType

      public int externGetType(MemorySegment externPtr)
      Gets the type of an extern value.
      Parameters:
      externPtr - the extern pointer
      Returns:
      the extern type code (0=FUNC, 1=TABLE, 2=MEMORY, 3=GLOBAL), or -1 on error

    • storeSetCallHookFn

      public int storeSetCallHookFn(MemorySegment storePtr, MemorySegment callbackFn, long callbackId)
      Sets a call hook with a function pointer callback on the store.

      The callback is invoked on every transition between host and WebAssembly code. The callback receives the callback ID and hook type (0=CallingWasm, 1=ReturningFromWasm, 2=CallingHost, 3=ReturningFromHost) and returns 0 to continue or non-zero to trap.

      Parameters:
      storePtr - the store pointer
      callbackFn - the upcall stub function pointer
      callbackId - the callback identifier for dispatch
      Returns:
      0 on success, non-zero on error

    • tagCreate

      public MemorySegment tagCreate(MemorySegment storePtr, int[] paramTypes, int[] returnTypes)
      Creates a new WebAssembly tag for exception handling.
      Parameters:
      storePtr - the store pointer
      paramTypes - the parameter type codes
      returnTypes - the return type codes
      Returns:
      the tag pointer, or NULL on error

    • tagGetParamTypes

      public int[] tagGetParamTypes(MemorySegment tagPtr, MemorySegment storePtr)
      Gets the parameter types of a tag.
      Parameters:
      tagPtr - the tag pointer
      storePtr - the store pointer
      Returns:
      the parameter type codes

    • tagGetReturnTypes

      public int[] tagGetReturnTypes(MemorySegment tagPtr, MemorySegment storePtr)
      Gets the return types of a tag.
      Parameters:
      tagPtr - the tag pointer
      storePtr - the store pointer
      Returns:
      the return type codes

    • tagEquals

      public int tagEquals(MemorySegment tag1Ptr, MemorySegment tag2Ptr, MemorySegment storePtr)
      Checks if two tags are equal.
      Parameters:
      tag1Ptr - the first tag pointer
      tag2Ptr - the second tag pointer
      storePtr - the store pointer
      Returns:
      1 if equal, 0 if not equal, -1 on error

    • tagDestroy

      public void tagDestroy(MemorySegment tagPtr)
      Destroys a tag and frees its native resources.
      Parameters:
      tagPtr - the tag pointer

    • exnRefGetTag

      public MemorySegment exnRefGetTag(MemorySegment exnRefPtr, MemorySegment storePtr)
      Gets the tag from an exception reference.
      Parameters:
      exnRefPtr - the exception reference pointer
      storePtr - the store pointer
      Returns:
      the tag pointer, or NULL on error

    • exnRefIsValid

      public int exnRefIsValid(MemorySegment exnRefPtr, MemorySegment storePtr)
      Checks if an exception reference is valid.
      Parameters:
      exnRefPtr - the exception reference pointer
      storePtr - the store pointer
      Returns:
      1 if valid, 0 if not valid, -1 on error

    • exnRefDestroy

      public void exnRefDestroy(MemorySegment exnRefPtr)
      Destroys an exception reference and frees its native resources.
      Parameters:
      exnRefPtr - the exception reference pointer

    • exnRefGetField

      public int exnRefGetField(MemorySegment exnRefPtr, MemorySegment storePtr, int index, MemorySegment outType, MemorySegment outValueI64, MemorySegment outValueF64, MemorySegment outValueV128)
      Gets a single field value from an exception reference by index.
      Parameters:
      exnRefPtr - the exception reference pointer
      storePtr - the store pointer
      index - the zero-based field index
      outType - output pointer for the type code
      outValueI64 - output pointer for integer/long values
      outValueF64 - output pointer for float/double values
      Returns:
      0 on success, non-zero on failure

    • exnRefFieldCount

      public int exnRefFieldCount(MemorySegment exnRefPtr, MemorySegment storePtr)
      Gets the number of fields in an exception reference.
      Parameters:
      exnRefPtr - the exception reference pointer
      storePtr - the store pointer
      Returns:
      the field count, or -1 on error

    • exnRefCreate

      public MemorySegment exnRefCreate(MemorySegment storePtr, MemorySegment tagPtr, int fieldCount, MemorySegment fieldTypesPtr, MemorySegment fieldI64ValuesPtr, MemorySegment fieldF64ValuesPtr, MemorySegment fieldV128ValuesPtr)
      Creates a new ExnRef from a tag and field values.
      Parameters:
      storePtr - the store pointer
      tagPtr - the tag pointer
      fieldCount - the number of fields
      fieldTypesPtr - pointer to int array of field type codes
      fieldI64ValuesPtr - pointer to long array of integer field values
      fieldF64ValuesPtr - pointer to double array of float field values
      Returns:
      the new ExnRef pointer, or NULL on failure

    • exnRefToRaw

      public long exnRefToRaw(MemorySegment exnRefPtr, MemorySegment storePtr)
      Converts an ExnRef to its raw u32 representation.
      Parameters:
      exnRefPtr - the exception reference pointer
      storePtr - the store pointer
      Returns:
      the raw value as a long, or -1 on failure

    • exnRefFromRaw

      public MemorySegment exnRefFromRaw(MemorySegment storePtr, int raw)
      Creates an ExnRef from a raw u32 representation.
      Parameters:
      storePtr - the store pointer
      raw - the raw u32 value
      Returns:
      the ExnRef pointer, or NULL if raw is 0 or invalid

    • exnRefMatchesTy

      public int exnRefMatchesTy(MemorySegment exnRefPtr, MemorySegment storePtr, int heapTypeCode)
      Checks if an ExnRef matches a given heap type.
      Parameters:
      exnRefPtr - the exception reference pointer
      storePtr - the store pointer
      heapTypeCode - the heap type code (matching Java HeapType enum ordinal)
      Returns:
      1 if matches, 0 if not, -1 on error

    • externRefToRaw

      public long externRefToRaw(MemorySegment storePtr, long externRefData)
      Converts an ExternRef (identified by its i64 data) to a raw u32 GC heap index.
      Parameters:
      storePtr - the store pointer
      externRefData - the i64 data stored in the ExternRef
      Returns:
      the raw value as a long, or -1 on failure

    • externRefFromRaw

      public long externRefFromRaw(MemorySegment storePtr, int raw)
      Creates an ExternRef from a raw u32 GC heap index.
      Parameters:
      storePtr - the store pointer
      raw - the raw u32 value
      Returns:
      the i64 data from the ExternRef, or -1 on failure

    • getPanamaStoreCreateHostFunction

      public MethodHandle getPanamaStoreCreateHostFunction()
      Gets the method handle for creating a host function in a store.
      Returns:
      the method handle, or null if not available

    • getPanamaStoreCreateHostFunctionUnchecked

      public MethodHandle getPanamaStoreCreateHostFunctionUnchecked()
      Gets the method handle for creating an unchecked host function in a store.
      Returns:
      the method handle, or null if not available

    • getPanamaDestroyHostFunction

      public MethodHandle getPanamaDestroyHostFunction()
      Gets the method handle for destroying a host function.
      Returns:
      the method handle, or null if not available

    • markInitialized

      protected void markInitialized()
      Marks this binding set as initialized. Subclasses should call this after registering all function bindings and initializing hot-path MethodHandles.

    • isInitialized

      public boolean isInitialized()
      Checks if the bindings are initialized and available.
      Returns:
      true if initialized, false otherwise

    • addFunctionBinding

      protected void addFunctionBinding(String functionName, FunctionDescriptor descriptor)
      Registers a native function binding with a given descriptor.
      Parameters:
      functionName - the native function symbol name
      descriptor - the Panama FunctionDescriptor for the native function

    • getFunctionBinding

      protected ai.tegmentum.wasmtime4j.panama.NativeBindingsBase.FunctionBinding getFunctionBinding(String functionName)
      Gets a registered function binding by name.
      Parameters:
      functionName - the native function symbol name
      Returns:
      the function binding, or null if not registered

    • callNativeFunction

      public <T> T callNativeFunction(String functionName, Class<T> returnType, Object... args)
      Calls a native function with type safety.
      Parameters:
      functionName - the name of the function
      returnType - the expected return type
      args - the function arguments
      Returns:
      the function result
      Throws:
      IllegalStateException - if the function call fails

    • validatePointer

      protected void validatePointer(MemorySegment pointer, String name)
      Validates that a pointer is not null.
      Parameters:
      pointer - the pointer to validate
      name - the name of the parameter for error messages
      Throws:
      IllegalArgumentException - if the pointer is null

    • validateSize

      protected void validateSize(long size, String name)
      Validates that a size is positive.
      Parameters:
      size - the size to validate
      name - the name of the parameter for error messages
      Throws:
      IllegalArgumentException - if the size is not positive

    • extractValueForNative

      protected Object[] extractValueForNative(ai.tegmentum.wasmtime4j.WasmValue value)
      Extracts value components from WasmValue for passing to native code.
      Parameters:
      value - the WasmValue to extract components from
      Returns:
      array containing [i32Value, i64Value, f32Value, f64Value, refValue]