Class NativeMemoryBindings

java.lang.Object
ai.tegmentum.wasmtime4j.panama.NativeMemoryBindings
public final class NativeMemoryBindings extends Object
Native function bindings for memory, global, and table operations.

Provides type-safe wrappers for Panama FFI memory operations (read, write, grow, size), atomic memory operations (compare-and-swap, load, store, fence, notify, wait), global variable operations (get, set, create, destroy, metadata), table operations (size, get, set, grow, fill, copy, init, destroy), data/element segment operations, and error handling functions.

Hot-path operations (panamaMemoryReadBytes(java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, long, long, java.lang.foreign.MemorySegment) and panamaMemoryWriteBytes(java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, long, long, java.lang.foreign.MemorySegment)) use eagerly-initialized volatile MethodHandle fields for invokeExact optimization.

  • Method Details

    • getInstance

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

    • panamaMemoryInit

      public int panamaMemoryInit(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment instancePtr, int destOffset, int dataSegmentIndex, int srcOffset, int length)
      Initializes memory from a data segment (memory.init instruction).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      instancePtr - pointer to the instance
      destOffset - destination offset in memory
      dataSegmentIndex - data segment index
      srcOffset - source offset in segment
      length - number of bytes to copy
      Returns:
      0 on success, non-zero on error

    • dataSegmentDrop

      public int dataSegmentDrop(MemorySegment instancePtr, int dataSegmentIndex)
      Drops a data segment from memory (data.drop instruction).
      Parameters:
      instancePtr - pointer to the instance
      dataSegmentIndex - data segment index to drop
      Returns:
      0 on success, non-zero on error

    • panamaMemorySizePages

      public int panamaMemorySizePages(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment sizeOutPtr)
      Gets memory size in pages (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      sizeOutPtr - pointer to store the size in pages
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryGrow

      public int panamaMemoryGrow(MemorySegment memoryPtr, MemorySegment storePtr, long additionalPages, MemorySegment previousPagesOutPtr)
      Grows memory by additional pages (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      additionalPages - number of pages to grow
      previousPagesOutPtr - pointer to store the previous size in pages
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryGrow64

      public int panamaMemoryGrow64(MemorySegment memoryPtr, MemorySegment storePtr, long additionalPages, MemorySegment previousPagesOutPtr)
      Grows memory by additional pages using 64-bit addressing (Panama FFI version).

      This supports Memory64 proposal for memories larger than 4GB.

      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      additionalPages - number of pages to grow (64-bit)
      previousPagesOutPtr - pointer to store the previous size in pages (64-bit)
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryGrowAsync

      public int panamaMemoryGrowAsync(MemorySegment memoryPtr, MemorySegment storePtr, long additionalPages, MemorySegment previousPagesOutPtr)
      Grows memory asynchronously through the async resource limiter (Panama FFI version).

      Requires engine with asyncSupport(true).

      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      additionalPages - number of pages to grow
      previousPagesOutPtr - pointer to store the previous size in pages
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryIs64Bit

      public int panamaMemoryIs64Bit(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment is64BitOutPtr)
      Checks if memory uses 64-bit addressing (Memory64 proposal).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      is64BitOutPtr - pointer to store the result (1 if 64-bit, 0 if 32-bit)
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryIsShared

      public int panamaMemoryIsShared(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment isSharedOutPtr)
      Checks if memory is shared between threads (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      isSharedOutPtr - pointer to store the result (1 if shared, 0 if not shared)
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryGetMinimum

      public int panamaMemoryGetMinimum(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment minimumOutPtr)
      Gets memory type minimum pages (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      minimumOutPtr - pointer to store the minimum pages (64-bit unsigned)
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryGetMaximum

      public int panamaMemoryGetMaximum(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment maximumOutPtr)
      Gets memory type maximum pages (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      maximumOutPtr - pointer to store the maximum pages (64-bit signed, -1 if unlimited)
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryGetPageSizeLog2

      public int panamaMemoryGetPageSizeLog2(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment pageSizeLog2OutPtr)
      Gets memory type page size log2 (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      pageSizeLog2OutPtr - pointer to store the page size log2 (32-bit unsigned)
      Returns:
      0 on success, negative error code on failure

    • panamaMemorySizePages64

      public int panamaMemorySizePages64(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment sizeOutPtr)
      Gets memory size in pages using 64-bit return value (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      sizeOutPtr - pointer to store the size in pages (64-bit)
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryReadBytes

      public int panamaMemoryReadBytes(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long length, MemorySegment bufferPtr)
      Reads bytes from memory (Panama FFI version).

      This method uses an eagerly-initialized MethodHandle for invokeExact optimization on the hot path, falling back to the generic callNativeFunction path if the handle is unavailable.

      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - offset in memory to read from
      length - number of bytes to read
      bufferPtr - pointer to buffer to read into
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryWriteBytes

      public int panamaMemoryWriteBytes(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long length, MemorySegment bufferPtr)
      Writes bytes to memory (Panama FFI version).

      This method uses an eagerly-initialized MethodHandle for invokeExact optimization on the hot path, falling back to the generic callNativeFunction path if the handle is unavailable.

      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - offset in memory to write to
      length - number of bytes to write
      bufferPtr - pointer to buffer to write from
      Returns:
      0 on success, negative error code on failure

    • panamaMemorySizeBytes

      public int panamaMemorySizeBytes(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment sizeOutPtr)
      Gets memory size in bytes (Panama FFI version).
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      sizeOutPtr - pointer to store the size in bytes
      Returns:
      0 on success, negative error code on failure

    • panamaMemoryGetData

      public int panamaMemoryGetData(MemorySegment memoryPtr, MemorySegment storePtr, MemorySegment dataPtrOutPtr, MemorySegment sizeOutPtr)
      Gets raw pointer to WASM linear memory for zero-copy access.

      This provides direct access to the WebAssembly linear memory without copying, enabling high-performance memory operations.

      WARNING: The returned pointer is only valid while:

      • The memory instance is alive
      • The store is alive
      • No memory.grow() operations are performed

      After memory.grow(), the pointer may be invalidated and must be re-obtained.

      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      dataPtrOutPtr - pointer to store the raw memory data pointer
      sizeOutPtr - pointer to store the memory size in bytes
      Returns:
      0 on success, negative error code on failure

    • getPanamaMemoryCreate

      public MethodHandle getPanamaMemoryCreate()
      Gets the method handle for Panama FFI memory creation (simple version).
      Returns:
      the method handle, or null if not available

    • getPanamaMemoryCreateWithConfig

      public MethodHandle getPanamaMemoryCreateWithConfig()
      Gets the method handle for Panama FFI memory creation (with configuration).
      Returns:
      the method handle, or null if not available

    • getPanamaMemoryCreateAsync

      public MethodHandle getPanamaMemoryCreateAsync()
      Gets the method handle for async memory creation with config (async resource limiter path).
      Returns:
      the method handle, or null if not available

    • memoryDestroy

      public void memoryDestroy(MemorySegment memoryPtr)
      Destroys a validated memory instance and unregisters it from the handle registry.

      This must be called to properly free native memory pointers obtained from memory creation or instance export lookup.

      Parameters:
      memoryPtr - pointer to the validated memory to destroy

    • memoryClearHandleRegistries

      public int memoryClearHandleRegistries()
      Clears all memory and store handle registries (for testing purposes).

      This function clears both memory and store handle registries to prevent stale handles from interfering with subsequent tests. Should only be called in test teardown after all handles have been properly destroyed.

      Returns:
      0 on success, negative error code on failure

    • memoryAtomicCompareAndSwapI32

      public int memoryAtomicCompareAndSwapI32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int expected, int newValue, MemorySegment resultOut)
      Atomic compare-and-swap on 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      expected - expected value
      newValue - new value to swap in
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicCompareAndSwapI64

      public int memoryAtomicCompareAndSwapI64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long expected, long newValue, MemorySegment resultOut)
      Atomic compare-and-swap on 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      expected - expected value
      newValue - new value to swap in
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicLoadI32

      public int memoryAtomicLoadI32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, MemorySegment resultOut)
      Atomic load of 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      resultOut - pointer to store the value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicLoadI64

      public int memoryAtomicLoadI64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, MemorySegment resultOut)
      Atomic load of 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      resultOut - pointer to store the value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicStoreI32

      public int memoryAtomicStoreI32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int value)
      Atomic store of 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to store
      Returns:
      0 on success, error code otherwise

    • memoryAtomicStoreI64

      public int memoryAtomicStoreI64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long value)
      Atomic store of 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to store
      Returns:
      0 on success, error code otherwise

    • memoryAtomicAddI32

      public int memoryAtomicAddI32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int value, MemorySegment resultOut)
      Atomic add on 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to add
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicAddI64

      public int memoryAtomicAddI64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long value, MemorySegment resultOut)
      Atomic add on 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to add
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicAndI32

      public int memoryAtomicAndI32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int value, MemorySegment resultOut)
      Atomic AND on 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to AND
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicOrI32

      public int memoryAtomicOrI32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int value, MemorySegment resultOut)
      Atomic OR on 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to OR
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicXorI32

      public int memoryAtomicXorI32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int value, MemorySegment resultOut)
      Atomic XOR on 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to XOR
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicAndI64

      public int memoryAtomicAndI64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long value, MemorySegment resultOut)
      Atomic AND on 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to AND
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicOrI64

      public int memoryAtomicOrI64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long value, MemorySegment resultOut)
      Atomic OR on 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to OR
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicXorI64

      public int memoryAtomicXorI64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long value, MemorySegment resultOut)
      Atomic XOR on 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      value - value to XOR
      resultOut - pointer to store the old value
      Returns:
      0 on success, error code otherwise

    • memoryAtomicFence

      public int memoryAtomicFence(MemorySegment memoryPtr, MemorySegment storePtr)
      Atomic memory fence.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      Returns:
      0 on success, error code otherwise

    • memoryAtomicNotify

      public int memoryAtomicNotify(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int count, MemorySegment resultOut)
      Atomic notify/wake.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      count - number of waiters to wake
      resultOut - pointer to store number of waiters woken
      Returns:
      0 on success, error code otherwise

    • memoryAtomicWait32

      public int memoryAtomicWait32(MemorySegment memoryPtr, MemorySegment storePtr, long offset, int expected, long timeoutNanos, MemorySegment resultOut)
      Atomic wait on 32-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      expected - expected value
      timeoutNanos - timeout in nanoseconds (-1 for infinite)
      resultOut - pointer to store the wait result (0=ok, 1=not-equal, 2=timed-out)
      Returns:
      0 on success, error code otherwise

    • memoryAtomicWait64

      public int memoryAtomicWait64(MemorySegment memoryPtr, MemorySegment storePtr, long offset, long expected, long timeoutNanos, MemorySegment resultOut)
      Atomic wait on 64-bit value.
      Parameters:
      memoryPtr - pointer to the memory
      storePtr - pointer to the store
      offset - byte offset in memory
      expected - expected value
      timeoutNanos - timeout in nanoseconds (-1 for infinite)
      resultOut - pointer to store the wait result (0=ok, 1=not-equal, 2=timed-out)
      Returns:
      0 on success, error code otherwise

    • globalCreate

      public MemorySegment globalCreate(MemorySegment storePtr, int valueType, int isMutable, ai.tegmentum.wasmtime4j.WasmValue initialValue)
      Creates a new WebAssembly global variable.
      Parameters:
      storePtr - pointer to the store
      valueType - the WebAssembly value type code
      isMutable - 1 if mutable, 0 if immutable
      initialValue - the initial value for the global
      Returns:
      pointer to the created global, or null on failure

    • globalGet

      public void globalGet(MemorySegment globalPtr, MemorySegment valueOutPtr)
      Gets the value of a WebAssembly global.
      Parameters:
      globalPtr - pointer to the global
      valueOutPtr - pointer to store the global value

    • globalSet

      public void globalSet(MemorySegment globalPtr, MemorySegment valuePtr)
      Sets the value of a WebAssembly global.
      Parameters:
      globalPtr - pointer to the global
      valuePtr - pointer to the new value

    • globalType

      public MemorySegment globalType(MemorySegment globalPtr)
      Gets the type of a WebAssembly global.
      Parameters:
      globalPtr - pointer to the global
      Returns:
      pointer to the global type

    • globalCreateMutable

      public int globalCreateMutable(MemorySegment storePtr, int valueType, MemorySegment initialValuePtr, MemorySegment globalOutPtr)
      Creates a mutable WebAssembly global.
      Parameters:
      storePtr - pointer to the store
      valueType - the WebAssembly value type
      initialValuePtr - pointer to the initial value
      globalOutPtr - pointer to store the created global
      Returns:
      0 on success, negative error code on failure

    • globalCreateImmutable

      public int globalCreateImmutable(MemorySegment storePtr, int valueType, MemorySegment initialValuePtr, MemorySegment globalOutPtr)
      Creates an immutable WebAssembly global.
      Parameters:
      storePtr - pointer to the store
      valueType - the WebAssembly value type
      initialValuePtr - pointer to the initial value
      globalOutPtr - pointer to store the created global
      Returns:
      0 on success, negative error code on failure

    • globalDestroy

      public void globalDestroy(MemorySegment globalPtr)
      Destroys a WebAssembly global.
      Parameters:
      globalPtr - pointer to the global to destroy

    • panamaGlobalGet

      public int panamaGlobalGet(MemorySegment globalPtr, MemorySegment storePtr, MemorySegment i32ValueOutPtr, MemorySegment i64ValueOutPtr, MemorySegment f32ValueOutPtr, MemorySegment f64ValueOutPtr, MemorySegment refIdPresentOutPtr, MemorySegment refIdOutPtr, MemorySegment v128BytesOutPtr)
      Gets the value of a WebAssembly global (Panama FFI version).
      Parameters:
      globalPtr - pointer to the global
      storePtr - pointer to the store
      i32ValueOutPtr - pointer to store i32 value
      i64ValueOutPtr - pointer to store i64 value
      f32ValueOutPtr - pointer to store f32 value
      f64ValueOutPtr - pointer to store f64 value
      refIdPresentOutPtr - pointer to store reference presence flag
      refIdOutPtr - pointer to store reference ID
      v128BytesOutPtr - pointer to store V128 bytes (16 bytes, can be null)
      Returns:
      0 on success, negative error code on failure

    • panamaGlobalSet

      public int panamaGlobalSet(MemorySegment globalPtr, MemorySegment storePtr, int valueType, int i32Value, long i64Value, double f32Value, double f64Value, int refIdPresent, long refId, MemorySegment v128BytesPtr)
      Sets the value of a WebAssembly global (Panama FFI version).
      Parameters:
      globalPtr - pointer to the global
      storePtr - pointer to the store
      valueType - the value type (0=I32, 1=I64, 2=F32, 3=F64, 4=V128, 5=FuncRef, 6=ExternRef)
      i32Value - i32 value
      i64Value - i64 value
      f32Value - f32 value
      f64Value - f64 value
      refIdPresent - reference presence flag
      refId - reference ID
      v128BytesPtr - pointer to V128 bytes (16 bytes, can be null)
      Returns:
      0 on success, negative error code on failure

    • panamaGlobalSet

      public int panamaGlobalSet(MemorySegment globalPtr, MemorySegment storePtr, ai.tegmentum.wasmtime4j.WasmValue value)
      Sets a WebAssembly global value using WasmValue (Panama FFI version).
      Parameters:
      globalPtr - pointer to the global
      storePtr - pointer to the store
      value - the value to set
      Returns:
      0 on success, negative error code on failure

    • globalGetTypeInfo

      public int globalGetTypeInfo(MemorySegment globalPtr, MemorySegment typeInfoOutPtr, MemorySegment mutabilityOutPtr)
      Gets type information for a WebAssembly global.
      Parameters:
      globalPtr - pointer to the global
      typeInfoOutPtr - pointer to store the type information
      mutabilityOutPtr - pointer to store the mutability flag
      Returns:
      0 on success, negative error code on failure

    • panamaGlobalCreate

      public int panamaGlobalCreate(MemorySegment storePtr, int valueType, int mutability, ai.tegmentum.wasmtime4j.WasmValue value, MemorySegment namePtr, MemorySegment globalPtrPtr)
      Creates a new WebAssembly global with a WasmValue (Panama FFI version).
      Parameters:
      storePtr - pointer to the store
      valueType - the value type (0=I32, 1=I64, 2=F32, 3=F64, 4=V128, 5=FuncRef, 6=ExternRef)
      mutability - mutability flag (0=const, 1=var)
      value - the initial value
      namePtr - optional name pointer (can be null)
      globalPtrPtr - pointer to store the created global pointer
      Returns:
      0 on success, negative error code on failure

    • panamaGlobalMetadata

      public int panamaGlobalMetadata(MemorySegment globalPtr, MemorySegment valueTypePtr, MemorySegment mutabilityPtr)
      Gets metadata for a WebAssembly global (Panama FFI version).
      Parameters:
      globalPtr - pointer to the global
      valueTypePtr - pointer to store the value type code
      mutabilityPtr - pointer to store the mutability flag
      Returns:
      0 on success, negative error code on failure

    • panamaGlobalDestroy

      public void panamaGlobalDestroy(MemorySegment globalPtr)
      Destroys a WebAssembly global (Panama FFI version).
      Parameters:
      globalPtr - pointer to the global

    • globalRegisterShared

      public int globalRegisterShared(MemorySegment globalPtr, MemorySegment namePtr, MemorySegment registryPtr)
      Registers a global for cross-module sharing.
      Parameters:
      globalPtr - pointer to the global
      namePtr - pointer to the global name string
      registryPtr - pointer to the global registry
      Returns:
      0 on success, negative error code on failure

    • globalLookupShared

      public MemorySegment globalLookupShared(MemorySegment namePtr, MemorySegment registryPtr)
      Looks up a shared global by name.
      Parameters:
      namePtr - pointer to the global name string
      registryPtr - pointer to the global registry
      Returns:
      pointer to the global, or null if not found

    • globalGetDirectAccess

      public MemorySegment globalGetDirectAccess(MemorySegment globalPtr)
      Gets direct access to a global's value for zero-copy operations.
      Parameters:
      globalPtr - pointer to the global
      Returns:
      pointer to direct value access, or null if not supported

    • globalReleaseDirectAccess

      public void globalReleaseDirectAccess(MemorySegment globalPtr, MemorySegment directPtr)
      Releases direct access to a global's value.
      Parameters:
      globalPtr - pointer to the global
      directPtr - pointer to the direct access handle

    • getPanamaGlobalCreate

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

    • getTableSize

      public MethodHandle getTableSize()
      Gets the method handle for table size query.
      Returns:
      the method handle, or null if not available

    • getTableGet

      public MethodHandle getTableGet()
      Gets the method handle for table element get.
      Returns:
      the method handle, or null if not available

    • getTableSet

      public MethodHandle getTableSet()
      Gets the method handle for table element set.
      Returns:
      the method handle, or null if not available

    • getTableGrow

      public MethodHandle getTableGrow()
      Gets the method handle for table grow.
      Returns:
      the method handle, or null if not available

    • getTableDelete

      public MethodHandle getTableDelete()
      Gets the method handle for table deletion.
      Returns:
      the method handle, or null if not available

    • getTableMetadata

      public MethodHandle getTableMetadata()
      Gets the method handle for table metadata retrieval.
      Returns:
      the method handle, or null if not available

    • getPanamaTableSize

      public MethodHandle getPanamaTableSize()
      Gets the method handle for Panama FFI table size retrieval.
      Returns:
      the method handle, or null if not available

    • getPanamaTableGet

      public MethodHandle getPanamaTableGet()
      Gets the method handle for Panama FFI table element get.
      Returns:
      the method handle, or null if not available

    • getPanamaTableSet

      public MethodHandle getPanamaTableSet()
      Gets the method handle for Panama FFI table element set.
      Returns:
      the method handle, or null if not available

    • getPanamaTableGrow

      public MethodHandle getPanamaTableGrow()
      Gets the method handle for Panama FFI table grow.
      Returns:
      the method handle, or null if not available

    • panamaTableGrowAsync

      public int panamaTableGrowAsync(MemorySegment tablePtr, MemorySegment storePtr, int delta, int elementType, int refIdPresent, long refId, MemorySegment oldSizeOut)
      Grows a table asynchronously through the async resource limiter (Panama FFI version).

      Requires engine with asyncSupport(true).

      Parameters:
      tablePtr - pointer to the table
      storePtr - pointer to the store
      delta - number of elements to add
      elementType - element type code (5=FUNCREF, 6=EXTERNREF)
      refIdPresent - whether a reference ID is provided (0=no, 1=yes)
      refId - the reference ID for the init value
      oldSizeOut - pointer to store the previous size
      Returns:
      0 on success, non-zero on failure

    • getPanamaTableMetadata

      public MethodHandle getPanamaTableMetadata()
      Gets the method handle for Panama FFI table metadata retrieval.
      Returns:
      the method handle, or null if not available

    • getPanamaTableFill

      public MethodHandle getPanamaTableFill()
      Gets the method handle for Panama FFI table fill.
      Returns:
      the method handle, or null if not available

    • panamaTableCopy

      public int panamaTableCopy(MemorySegment tablePtr, MemorySegment storePtr, int dst, int src, int count)
      Copies elements within a table (same table).

      This is equivalent to the WebAssembly table.copy instruction when copying within the same table.

      Parameters:
      tablePtr - pointer to the table
      storePtr - pointer to the store
      dst - destination index in the table
      src - source index in the table
      count - number of elements to copy
      Returns:
      0 on success, non-zero on error

    • panamaTableCopyFrom

      public int panamaTableCopyFrom(MemorySegment dstTablePtr, MemorySegment storePtr, int dst, MemorySegment srcTablePtr, int src, int count)
      Copies elements from one table to another.

      This is equivalent to the WebAssembly table.copy instruction when copying between different tables.

      Parameters:
      dstTablePtr - pointer to the destination table
      storePtr - pointer to the store
      dst - destination index in the destination table
      srcTablePtr - pointer to the source table
      src - source index in the source table
      count - number of elements to copy
      Returns:
      0 on success, non-zero on error

    • getPanamaTableDelete

      public MethodHandle getPanamaTableDelete()
      Gets the method handle for Panama FFI table deletion.
      Returns:
      the method handle, or null if not available

    • getPanamaTableCreate

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

    • getPanamaTableCreateWithInit

      public MethodHandle getPanamaTableCreateWithInit()
      Gets the method handle for Panama FFI table creation with initial value.
      Returns:
      the method handle, or null if not available

    • getPanamaTableCreate64

      public MethodHandle getPanamaTableCreate64()
      Gets the method handle for Panama FFI 64-bit table creation.
      Returns:
      the method handle, or null if not available

    • getPanamaTableCreateAsync

      public MethodHandle getPanamaTableCreateAsync()
      Gets the method handle for async table creation (async resource limiter path).
      Returns:
      the method handle, or null if not available

    • panamaTableInit

      public int panamaTableInit(MemorySegment tablePtr, MemorySegment storePtr, MemorySegment instancePtr, int destIndex, int srcIndex, int count, int segmentIndex)
      Initializes a table from an element segment (table.init instruction).
      Parameters:
      tablePtr - pointer to the table
      storePtr - pointer to the store
      instancePtr - pointer to the instance
      destIndex - destination index in the table
      srcIndex - source index in the element segment
      count - number of elements to copy
      segmentIndex - element segment index
      Returns:
      0 on success, non-zero on error

    • elemDrop

      public int elemDrop(MemorySegment instancePtr, int segmentIndex)
      Drops an element segment (elem.drop instruction).
      Parameters:
      instancePtr - pointer to the instance
      segmentIndex - element segment index to drop
      Returns:
      0 on success, non-zero on error

    • tableSupports64BitAddressing

      public boolean tableSupports64BitAddressing(MemorySegment tablePtr, MemorySegment storePtr)
      Checks if a table supports 64-bit addressing (Table64).
      Parameters:
      tablePtr - pointer to the table
      storePtr - pointer to the store
      Returns:
      true if the table supports 64-bit addressing

    • getLastErrorMessage

      public MemorySegment getLastErrorMessage()
      Gets the last error message from the native library.
      Returns:
      pointer to error message string, or null if no error

    • freeErrorMessage

      public void freeErrorMessage(MemorySegment messagePtr)
      Frees an error message returned by getLastErrorMessage.
      Parameters:
      messagePtr - pointer to the error message to free

    • freeString

      public void freeString(MemorySegment stringPtr)
      Frees a C string allocated by Rust.
      Parameters:
      stringPtr - pointer to the C string to free

    • clearErrorState

      public void clearErrorState()
      Clears any stored error state in the native library.

    • 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]