Class NativeEngineBindings

java.lang.Object
ai.tegmentum.wasmtime4j.panama.NativeEngineBindings
public final class NativeEngineBindings extends Object
Native function bindings for Engine and Module operations.

Provides type-safe wrappers for all Wasmtime engine lifecycle and module compilation and introspection native functions. Hot-path methods use eagerly initialized volatile MethodHandle fields for invokeExact optimization.

Store-related bindings are in NativeStoreBindings.

This class follows the singleton pattern with initialization-on-demand holder.

  • Method Details

    • getInstance

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

    • engineCreateWithConfig

      public MemorySegment engineCreateWithConfig(ai.tegmentum.wasmtime4j.config.EngineConfig config)
      Creates a new Wasmtime engine with extended configuration.
      Parameters:
      config - the engine configuration
      Returns:
      memory segment pointer to the engine, or null on failure

    • engineCreateWithExtensions

      public MemorySegment engineCreateWithExtensions(ai.tegmentum.wasmtime4j.config.EngineConfig config)
      Creates a new engine with JSON configuration and all optional extension traits.
      Parameters:
      config - the engine configuration (may have cache store, memory creator, stack creator, and/or custom code memory set)
      Returns:
      memory segment pointer to the engine, or null on failure

    • engineDestroy

      public void engineDestroy(MemorySegment enginePtr)
      Destroys a Wasmtime engine.
      Parameters:
      enginePtr - pointer to the engine to destroy

    • engineSupportsFeature

      public boolean engineSupportsFeature(MemorySegment enginePtr, String featureName)
      Checks if engine supports a feature by name.
      Parameters:
      enginePtr - pointer to the engine
      featureName - feature name string
      Returns:
      true if supported, false otherwise

    • engineStackSizeLimit

      public long engineStackSizeLimit(MemorySegment enginePtr)
      Gets the stack size limit.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      stack size limit in bytes, or -1 if not set

    • engineFuelEnabled

      public boolean engineFuelEnabled(MemorySegment enginePtr)
      Checks if fuel is enabled.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      true if fuel is enabled, false otherwise

    • engineEpochInterruptionEnabled

      public boolean engineEpochInterruptionEnabled(MemorySegment enginePtr)
      Checks if epoch interruption is enabled.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      true if epoch interruption is enabled, false otherwise

    • engineCoredumpOnTrapEnabled

      public boolean engineCoredumpOnTrapEnabled(MemorySegment enginePtr)
      Checks if coredump generation on trap is enabled.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      true if coredump generation is enabled, false otherwise

    • engineSame

      public boolean engineSame(MemorySegment enginePtr1, MemorySegment enginePtr2)
      Checks if two engines are the same (share the same underlying Wasmtime engine).
      Parameters:
      enginePtr1 - pointer to the first engine
      enginePtr2 - pointer to the second engine
      Returns:
      true if both engines share the same underlying engine

    • engineIsAsync

      public boolean engineIsAsync(MemorySegment enginePtr)
      Checks if async support is enabled for the engine.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      true if async support is enabled, false otherwise

    • engineIsRecording

      public boolean engineIsRecording(MemorySegment enginePtr)
      Checks if the engine is configured for execution recording.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      true if recording is enabled, false otherwise

    • engineIsReplaying

      public boolean engineIsReplaying(MemorySegment enginePtr)
      Checks if the engine is configured for execution replaying.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      true if replaying is enabled, false otherwise

    • engineIncrementEpoch

      public void engineIncrementEpoch(MemorySegment enginePtr)
      Increments the epoch counter.

      This method is signal-safe and performs only an atomic increment. The epoch counter is used for epoch-based interruption of WebAssembly execution.

      Parameters:
      enginePtr - pointer to the engine

    • engineDetectHostFeature

      public int engineDetectHostFeature(String featureName)
      Detects whether a host CPU feature is available.
      Parameters:
      featureName - the feature name (e.g., "sse4.2", "avx2")
      Returns:
      1 if available, 0 if not

    • tlsEagerInitialize

      public void tlsEagerInitialize()
      Eagerly initializes Wasmtime's thread-local state for the current thread.

    • engineUnloadProcessHandlers

      public int engineUnloadProcessHandlers(MemorySegment enginePtr)
      Unloads process-level signal handlers installed by Wasmtime.
      Parameters:
      enginePtr - pointer to the engine (consumed by this call)
      Returns:
      0 on success, -1 on failure

    • engineIsPulley

      public boolean engineIsPulley(MemorySegment enginePtr)
      Checks if the Pulley interpreter is being used.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      true if Pulley interpreter is being used, false if using Cranelift JIT

    • enginePrecompileCompatibilityHash

      public byte[] enginePrecompileCompatibilityHash(MemorySegment enginePtr)
      Gets the precompilation compatibility hash for this engine.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      the compatibility hash as a byte array, or null if not available

    • enginePrecompileModule

      public byte[] enginePrecompileModule(MemorySegment enginePtr, byte[] wasmBytes) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Precompiles WebAssembly bytecode into a serialized form for ahead-of-time (AOT) usage.

      This method compiles the WebAssembly binary into a serialized form that can be later loaded via Module.deserialize() without needing to recompile.

      Parameters:
      enginePtr - pointer to the engine
      wasmBytes - the WebAssembly bytecode to precompile
      Returns:
      the precompiled serialized module bytes
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if precompilation fails

    • serializerFreeBuffer

      public void serializerFreeBuffer(MemorySegment buffer, long size)
      Frees a buffer allocated by serialization functions.
      Parameters:
      buffer - pointer to the buffer to free
      size - size of the buffer

    • engineDetectPrecompiled

      public int engineDetectPrecompiled(MemorySegment enginePtr, MemorySegment bytesPtr, long bytesLen)
      Detects whether bytes are a precompiled artifact.
      Parameters:
      enginePtr - the engine pointer
      bytesPtr - pointer to the bytes to inspect
      bytesLen - length of the bytes
      Returns:
      -1 if not precompiled, 0 for MODULE, 1 for COMPONENT

    • enginePrecompileComponent

      public byte[] enginePrecompileComponent(MemorySegment enginePtr, byte[] wasmBytes) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Precompiles a WebAssembly component for AOT usage.
      Parameters:
      enginePtr - pointer to the engine
      wasmBytes - the WebAssembly component bytecode to precompile
      Returns:
      the precompiled serialized component bytes
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if precompilation fails

    • enginePoolingAllocatorMetrics

      public long[] enginePoolingAllocatorMetrics(MemorySegment enginePtr)
      Gets pooling allocator metrics from the engine.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      a 12-element long array with metrics, or null if pooling is not enabled

    • engineCreateSharedMemory

      public MemorySegment engineCreateSharedMemory(MemorySegment enginePtr, int initialPages, int maxPages)
      Creates a standalone shared memory from an engine.
      Parameters:
      enginePtr - pointer to the engine
      initialPages - initial number of 64KB pages
      maxPages - maximum number of 64KB pages
      Returns:
      pointer to the created shared memory, or NULL on failure

    • engineCreateWeak

      public MemorySegment engineCreateWeak(MemorySegment enginePtr)
      Creates a weak reference to an engine.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      pointer to the weak engine, or NULL if creation failed

    • weakEngineUpgrade

      public MemorySegment weakEngineUpgrade(MemorySegment weakPtr)
      Upgrades a weak engine reference to a strong engine.
      Parameters:
      weakPtr - pointer to the weak engine
      Returns:
      pointer to the engine, or NULL if the engine has been dropped

    • weakEngineDestroy

      public void weakEngineDestroy(MemorySegment weakPtr)
      Destroys a weak engine reference.
      Parameters:
      weakPtr - pointer to the weak engine to destroy

    • moduleCompileWithDwarf

      public int moduleCompileWithDwarf(MemorySegment enginePtr, MemorySegment wasmBytes, long wasmSize, MemorySegment dwarfBytes, long dwarfSize, MemorySegment modulePtr)
      Compiles a WebAssembly module with DWARF debug package.
      Parameters:
      enginePtr - pointer to the engine
      wasmBytes - pointer to the WASM bytes
      wasmSize - size of the WASM bytes
      dwarfBytes - pointer to the DWARF package bytes
      dwarfSize - size of the DWARF package bytes
      modulePtr - pointer to store the compiled module
      Returns:
      0 on success, negative error code on failure

    • moduleCompileWat

      public int moduleCompileWat(MemorySegment enginePtr, MemorySegment watText, MemorySegment modulePtr)
      Compiles a WebAssembly module from WAT (WebAssembly Text format).
      Parameters:
      enginePtr - pointer to the engine
      watText - pointer to the WAT text string
      modulePtr - pointer to store the compiled module
      Returns:
      0 on success, negative error code on failure

    • moduleSerialize

      public int moduleSerialize(MemorySegment modulePtr, MemorySegment dataPtrPtr, MemorySegment lenPtr)
      Serializes a WebAssembly module.
      Parameters:
      modulePtr - pointer to the module to serialize
      dataPtrPtr - pointer to receive the serialized data pointer
      lenPtr - pointer to receive the data length
      Returns:
      0 on success, non-zero on error

    • moduleDeserialize

      public int moduleDeserialize(MemorySegment enginePtr, MemorySegment dataPtr, long len, MemorySegment modulePtrPtr)
      Deserializes a WebAssembly module from serialized bytes.
      Parameters:
      enginePtr - pointer to the engine
      dataPtr - pointer to the serialized module data
      len - length of the serialized data
      modulePtrPtr - pointer to store the deserialized module pointer
      Returns:
      0 on success, negative error code on failure

    • moduleDestroy

      public void moduleDestroy(MemorySegment modulePtr)
      Destroys a WebAssembly module.
      Parameters:
      modulePtr - pointer to the module to destroy

    • moduleCompileFromFile

      public int moduleCompileFromFile(MemorySegment enginePtr, MemorySegment pathPtr, MemorySegment modulePtrPtr)
      Compiles a WebAssembly module from a file path.
      Parameters:
      enginePtr - pointer to the engine
      pathPtr - pointer to the file path (null-terminated string)
      modulePtrPtr - pointer to store the compiled module pointer
      Returns:
      0 on success, negative error code on failure

    • moduleSame

      public boolean moduleSame(MemorySegment modulePtr1, MemorySegment modulePtr2)
      Checks if two modules share the same underlying compiled code.
      Parameters:
      modulePtr1 - pointer to the first module
      modulePtr2 - pointer to the second module
      Returns:
      1 if the modules are the same, 0 if not

    • moduleGetExportIndex

      public int moduleGetExportIndex(MemorySegment modulePtr, MemorySegment namePtr)
      Gets the index of an export by name.
      Parameters:
      modulePtr - pointer to the module
      namePtr - pointer to the export name (null-terminated string)
      Returns:
      the zero-based index, or -1 if not found

    • moduleInitializeCowImage

      public int moduleInitializeCowImage(MemorySegment modulePtr)
      Pre-initializes a module's copy-on-write image for faster instantiation.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      0 on success, negative error code on failure

    • moduleImageRange

      public int moduleImageRange(MemorySegment modulePtr, MemorySegment startPtr, MemorySegment endPtr)
      Gets the image range of a compiled module.
      Parameters:
      modulePtr - pointer to the module
      startPtr - output pointer for the start address (u64)
      endPtr - output pointer for the end address (u64)
      Returns:
      0 on success, negative error code on failure

    • moduleResourcesRequired

      public int moduleResourcesRequired(MemorySegment modulePtr, MemorySegment minMemoryBytesOut, MemorySegment maxMemoryBytesOut, MemorySegment minTableElementsOut, MemorySegment maxTableElementsOut, MemorySegment numMemoriesOut, MemorySegment numTablesOut, MemorySegment numGlobalsOut, MemorySegment numFunctionsOut)
      Gets the resources required to instantiate a module.
      Parameters:
      modulePtr - pointer to the module
      minMemoryBytesOut - output pointer for minimum memory bytes (i64)
      maxMemoryBytesOut - output pointer for maximum memory bytes (i64, -1 if unbounded)
      minTableElementsOut - output pointer for minimum table elements (i64)
      maxTableElementsOut - output pointer for maximum table elements (i64, -1 if unbounded)
      numMemoriesOut - output pointer for number of memories (i32)
      numTablesOut - output pointer for number of tables (i32)
      numGlobalsOut - output pointer for number of globals (i32)
      numFunctionsOut - output pointer for number of functions (i32)
      Returns:
      0 on success, negative error code on failure

    • moduleCreate

      public MemorySegment moduleCreate(MemorySegment enginePtr, MemorySegment wasmBytes, long wasmSize)
      Creates a WebAssembly module from bytecode (Panama FFI).
      Parameters:
      enginePtr - pointer to the engine
      wasmBytes - pointer to the WASM bytecode
      wasmSize - size of the WASM bytecode
      Returns:
      memory segment pointer to the module, or null on failure

    • moduleValidate

      public int moduleValidate(MemorySegment wasmBytes, long wasmSize)
      Validates WebAssembly bytecode using full Wasmtime structural and semantic validation.
      Parameters:
      wasmBytes - pointer to the WASM bytecode
      wasmSize - size of the WASM bytecode in bytes
      Returns:
      0 on success (valid), non-zero on failure (invalid)

    • moduleImportsLen

      public long moduleImportsLen(MemorySegment modulePtr)
      Gets the number of imports in a module.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      the number of imports

    • moduleExportsLen

      public long moduleExportsLen(MemorySegment modulePtr)
      Gets the number of exports in a module.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      the number of exports

    • moduleGetExportsJson

      public MemorySegment moduleGetExportsJson(MemorySegment modulePtr)
      Gets module exports as JSON string.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      MemorySegment pointing to JSON string, or NULL on error

    • moduleGetImportsJson

      public MemorySegment moduleGetImportsJson(MemorySegment modulePtr)
      Gets module imports as JSON string.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      MemorySegment pointing to JSON string, or NULL on error

    • moduleGetAllFunctions

      public MemorySegment moduleGetAllFunctions(MemorySegment modulePtr)
      Gets all module functions (imports, exports, and internal) as JSON string.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      MemorySegment pointing to JSON string, or NULL on error

    • moduleFreeString

      public void moduleFreeString(MemorySegment strPtr)
      Frees a C string returned by module functions.
      Parameters:
      strPtr - pointer to the string to free

    • moduleText

      public int moduleText(MemorySegment modulePtr, MemorySegment dataPtrPtr, MemorySegment lenPtr)
      Gets compiled machine code text from a module.
      Parameters:
      modulePtr - pointer to the module
      dataPtrPtr - output pointer for the data pointer
      lenPtr - output pointer for the data length
      Returns:
      0 on success, negative error code on failure

    • moduleAddressMap

      public int moduleAddressMap(MemorySegment modulePtr, MemorySegment codeOffsetsOut, MemorySegment wasmOffsetsOut, MemorySegment countOut)
      Gets address map from a module.
      Parameters:
      modulePtr - pointer to the module
      codeOffsetsOut - output pointer for code offsets array
      wasmOffsetsOut - output pointer for wasm offsets array
      countOut - output pointer for the number of entries
      Returns:
      0 on success, 1 if address map not available, -1 on error

    • moduleFromTrustedFile

      public int moduleFromTrustedFile(MemorySegment enginePtr, MemorySegment pathPtr, MemorySegment modulePtrPtr)
      Loads a module from a trusted file, skipping code integrity validation.
      Parameters:
      enginePtr - pointer to the engine
      pathPtr - pointer to the file path (null-terminated string)
      modulePtrPtr - pointer to store the loaded module pointer
      Returns:
      0 on success, negative error code on failure

    • moduleDeserializeRaw

      public int moduleDeserializeRaw(MemorySegment enginePtr, MemorySegment dataPtr, long len, MemorySegment modulePtrPtr)
      Deserializes a module from raw bytes (no file format wrapper).
      Parameters:
      enginePtr - pointer to the engine
      dataPtr - pointer to the raw module bytes
      len - length of the raw data
      modulePtrPtr - pointer to store the deserialized module pointer
      Returns:
      0 on success, negative error code on failure

    • moduleDeserializeOpenFile

      public int moduleDeserializeOpenFile(MemorySegment enginePtr, int fd, MemorySegment modulePtrPtr)
      Deserializes a module from an open file descriptor (Unix only).
      Parameters:
      enginePtr - pointer to the engine
      fd - the file descriptor
      modulePtrPtr - pointer to store the deserialized module pointer
      Returns:
      0 on success, negative error code on failure

    • freeByteArray

      public void freeByteArray(MemorySegment dataPtr, long len)
      Frees a byte array allocated by native code.
      Parameters:
      dataPtr - pointer to the data
      len - length of the data

    • freeAddressMap

      public void freeAddressMap(MemorySegment codeOffsetsPtr, MemorySegment wasmOffsetsPtr, long count)
      Frees address map arrays allocated by native code.
      Parameters:
      codeOffsetsPtr - pointer to the code offsets array
      wasmOffsetsPtr - pointer to the wasm offsets array
      count - number of entries

    • moduleGetName

      public MemorySegment moduleGetName(MemorySegment modulePtr)
      Gets the name of a module.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      pointer to the module name string, or null if unnamed

    • moduleExportCount

      public long moduleExportCount(MemorySegment modulePtr)
      Gets the number of exports in a module.
      Parameters:
      modulePtr - pointer to the module
      Returns:
      the number of exports

    • moduleGetExportNames

      public long moduleGetExportNames(MemorySegment modulePtr, MemorySegment namesOut, long maxCount)
      Gets export names from a module.
      Parameters:
      modulePtr - pointer to the module
      namesOut - pointer to array that will hold char* pointers
      maxCount - maximum number of names to retrieve
      Returns:
      actual number of exports retrieved

    • moduleGetExportKind

      public int moduleGetExportKind(MemorySegment modulePtr, MemorySegment name)
      Gets the kind of a specific export by name.
      Parameters:
      modulePtr - pointer to the module
      name - pointer to null-terminated C string name
      Returns:
      0=not found, 1=function, 2=global, 3=memory, 4=table

    • guestProfilerNew

      public MemorySegment guestProfilerNew(MemorySegment enginePtr, MemorySegment moduleNamePtr, long intervalNanos, MemorySegment modulePtrs, MemorySegment moduleNamePtrs, int moduleCount)
      Creates a new guest profiler.
      Parameters:
      enginePtr - pointer to the engine
      moduleNamePtr - pointer to module name C string
      intervalNanos - sampling interval in nanoseconds
      modulePtrs - pointer to array of module pointers
      moduleNamePtrs - pointer to array of module name C strings
      moduleCount - number of modules
      Returns:
      pointer to the profiler, or NULL on failure

    • guestProfilerNewComponent

      public MemorySegment guestProfilerNewComponent(MemorySegment enginePtr, MemorySegment componentNamePtr, long intervalNanos, MemorySegment componentPtr, MemorySegment extraModulePtrs, MemorySegment extraModuleNamePtrs, int extraModuleCount)
      Creates a new guest profiler for a component.
      Parameters:
      enginePtr - pointer to the engine
      componentNamePtr - pointer to component name C string
      intervalNanos - sampling interval in nanoseconds
      componentPtr - pointer to the component
      extraModulePtrs - pointer to array of extra module pointers
      extraModuleNamePtrs - pointer to array of extra module name C strings
      extraModuleCount - number of extra modules
      Returns:
      pointer to the profiler, or NULL on failure

    • guestProfilerSample

      public int guestProfilerSample(MemorySegment profilerPtr, MemorySegment storePtr, long deltaNanos)
      Collects a stack sample.
      Parameters:
      profilerPtr - pointer to the profiler
      storePtr - pointer to the store
      deltaNanos - CPU time since previous sample in nanoseconds
      Returns:
      0 on success, -1 on error, -2 if already finished

    • guestProfilerCallHook

      public int guestProfilerCallHook(MemorySegment profilerPtr, MemorySegment storePtr, int hookKind)
      Records a call hook transition.
      Parameters:
      profilerPtr - pointer to the profiler
      storePtr - pointer to the store
      hookKind - 0=CallingWasm, 1=ReturningFromWasm, 2=CallingHost, 3=ReturningFromHost
      Returns:
      0 on success, -1 on error, -2 if already finished

    • guestProfilerFinish

      public int guestProfilerFinish(MemorySegment profilerPtr, MemorySegment dataOut, MemorySegment lenOut)
      Finishes profiling and returns the profile data.
      Parameters:
      profilerPtr - pointer to the profiler
      dataOut - pointer to receive the data pointer
      lenOut - pointer to receive the data length
      Returns:
      0 on success, -1 on error, -2 if already finished

    • guestProfilerFreeData

      public void guestProfilerFreeData(MemorySegment dataPtr, long len)
      Frees profile data returned by finish.
      Parameters:
      dataPtr - pointer to the data
      len - length of the data

    • guestProfilerDestroy

      public void guestProfilerDestroy(MemorySegment profilerPtr)
      Destroys a guest profiler.
      Parameters:
      profilerPtr - pointer to the profiler to destroy

    • codeBuilderCreate

      public MemorySegment codeBuilderCreate(MemorySegment enginePtr) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Creates a new CodeBuilder for the given engine.
      Parameters:
      enginePtr - pointer to the engine
      Returns:
      pointer to the new CodeBuilder
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if creation fails

    • codeBuilderWasmBinary

      public void codeBuilderWasmBinary(MemorySegment builderPtr, byte[] wasmBytes) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Sets wasm binary bytes on the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      wasmBytes - the wasm bytes
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if setting bytes fails

    • codeBuilderWasmBinaryOrText

      public void codeBuilderWasmBinaryOrText(MemorySegment builderPtr, byte[] wasmBytes) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Sets wasm binary or text bytes on the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      wasmBytes - the wasm or WAT bytes
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if setting bytes fails

    • codeBuilderDwarfPackage

      public void codeBuilderDwarfPackage(MemorySegment builderPtr, byte[] dwarfBytes) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Sets DWARF package bytes on the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      dwarfBytes - the DWARF package bytes
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if setting bytes fails

    • codeBuilderHint

      public void codeBuilderHint(MemorySegment builderPtr, int hintOrdinal)
      Sets hint on the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      hintOrdinal - the hint ordinal (0=MODULE, 1=COMPONENT)

    • codeBuilderCompileModule

      public MemorySegment codeBuilderCompileModule(MemorySegment builderPtr) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Compiles a module from the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      Returns:
      pointer to the compiled module
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if compilation fails

    • codeBuilderCompileModuleSerialized

      public byte[] codeBuilderCompileModuleSerialized(MemorySegment builderPtr) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Compiles a module to serialized bytes from the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      Returns:
      the serialized module bytes
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if compilation fails

    • codeBuilderCompileComponent

      public MemorySegment codeBuilderCompileComponent(MemorySegment builderPtr) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Compiles a component from the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      Returns:
      pointer to the compiled component
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if compilation fails

    • codeBuilderCompileComponentSerialized

      public byte[] codeBuilderCompileComponentSerialized(MemorySegment builderPtr) throws ai.tegmentum.wasmtime4j.exception.WasmException
      Compiles a component to serialized bytes from the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      Returns:
      the serialized component bytes
      Throws:
      ai.tegmentum.wasmtime4j.exception.WasmException - if compilation fails

    • codeBuilderCompileTimeBuiltinsBinary

      public void codeBuilderCompileTimeBuiltinsBinary(MemorySegment builderPtr, String name, byte[] wasmBytes)
      Adds compile-time builtins from binary bytes to the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      name - the name of the builtin component
      wasmBytes - the wasm binary bytes

    • codeBuilderCompileTimeBuiltinsBinaryOrText

      public void codeBuilderCompileTimeBuiltinsBinaryOrText(MemorySegment builderPtr, String name, byte[] wasmBytes)
      Adds compile-time builtins from binary or text bytes to the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      name - the name of the builtin component
      wasmBytes - the wasm binary or WAT text bytes

    • codeBuilderExposeUnsafeIntrinsics

      public void codeBuilderExposeUnsafeIntrinsics(MemorySegment builderPtr, String importName)
      Exposes unsafe intrinsics at the given import name on the code builder.
      Parameters:
      builderPtr - pointer to the code builder
      importName - the import name for unsafe intrinsics

    • codeBuilderDestroy

      public void codeBuilderDestroy(MemorySegment builderPtr)
      Destroys a code builder.
      Parameters:
      builderPtr - pointer to the code builder to destroy

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