Class NativeExecutionBindings

java.lang.Object
ai.tegmentum.wasmtime4j.panama.NativeExecutionBindings
public final class NativeExecutionBindings extends Object
Native function bindings for execution-related operations.

Provides type-safe wrappers for pooling allocator native functions.

  • Method Details

    • getInstance

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

    • poolingAllocatorCreateWithConfig

      public MemorySegment poolingAllocatorCreateWithConfig(int instancePoolSize, long maxMemoryPerInstance, int stackSize, int maxStacks, int maxTablesPerInstance, int maxTables, boolean memoryDecommitEnabled, boolean poolWarmingEnabled, float poolWarmingPercentage)
      Creates a new pooling allocator with custom configuration.
      Parameters:
      instancePoolSize - the number of instances in the pool
      maxMemoryPerInstance - maximum memory per instance in bytes
      stackSize - stack size for WebAssembly execution
      maxStacks - maximum number of stacks
      maxTablesPerInstance - maximum tables per instance
      maxTables - maximum total tables
      memoryDecommitEnabled - whether memory decommit is enabled
      poolWarmingEnabled - whether pool warming is enabled
      poolWarmingPercentage - pool warming percentage (0.0 to 1.0)
      Returns:
      pointer to the allocator, or null on failure

    • poolingAllocatorCreateFromJson

      public MemorySegment poolingAllocatorCreateFromJson(byte[] jsonBytes)
      Creates a pooling allocator from JSON configuration bytes.

      All fields in the JSON map directly to wasmtime's PoolingAllocationConfig API. This is the preferred creation path as it wires all configuration options.

      Parameters:
      jsonBytes - UTF-8 JSON configuration bytes
      Returns:
      pointer to the allocator, or null on failure

    • poolingAllocatorAllocateInstance

      public boolean poolingAllocatorAllocateInstance(MemorySegment allocatorPtr, MemorySegment instanceIdOut)
      Allocates an instance from the pool.
      Parameters:
      allocatorPtr - pointer to the allocator
      instanceIdOut - pointer to store the instance ID
      Returns:
      true on success, false on failure

    • poolingAllocatorReuseInstance

      public boolean poolingAllocatorReuseInstance(MemorySegment allocatorPtr, long instanceId)
      Reuses an existing instance from the pool.
      Parameters:
      allocatorPtr - pointer to the allocator
      instanceId - the instance ID to reuse
      Returns:
      true on success, false on failure

    • poolingAllocatorReleaseInstance

      public boolean poolingAllocatorReleaseInstance(MemorySegment allocatorPtr, long instanceId)
      Releases an instance back to the pool.
      Parameters:
      allocatorPtr - pointer to the allocator
      instanceId - the instance ID to release
      Returns:
      true on success, false on failure

    • poolingAllocatorGetStatistics

      public boolean poolingAllocatorGetStatistics(MemorySegment allocatorPtr, MemorySegment statsOut)
      Gets pool statistics.
      Parameters:
      allocatorPtr - pointer to the allocator
      statsOut - pointer to store the statistics
      Returns:
      true on success, false on failure

    • poolingAllocatorResetStatistics

      public boolean poolingAllocatorResetStatistics(MemorySegment allocatorPtr)
      Resets pool statistics.
      Parameters:
      allocatorPtr - pointer to the allocator
      Returns:
      true on success, false on failure

    • poolingAllocatorWarmPools

      public boolean poolingAllocatorWarmPools(MemorySegment allocatorPtr)
      Warms up the pools by pre-allocating resources.
      Parameters:
      allocatorPtr - pointer to the allocator
      Returns:
      true on success, false on failure

    • poolingAllocatorPerformMaintenance

      public boolean poolingAllocatorPerformMaintenance(MemorySegment allocatorPtr)
      Performs maintenance operations on the pools.
      Parameters:
      allocatorPtr - pointer to the allocator
      Returns:
      true on success, false on failure

    • poolingAllocatorDestroy

      public void poolingAllocatorDestroy(MemorySegment allocatorPtr)
      Destroys a pooling allocator.
      Parameters:
      allocatorPtr - pointer to the allocator

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