Class NativeComponentBindings

java.lang.Object
ai.tegmentum.wasmtime4j.panama.NativeComponentBindings
public final class NativeComponentBindings extends Object
Native function bindings for the WebAssembly Component Model.

Provides type-safe wrappers for all component model native functions including component engine lifecycle, component loading and instantiation, component linker operations, enhanced component engine with instance IDs, component metrics, and WIT value marshalling.

This class covers the following functional areas:

  • Component engine creation and destruction
  • Component loading from bytes and validation
  • Component instantiation and instance management
  • Component export/import introspection
  • Component linker with WASI Preview 2 and HTTP support
  • Enhanced component engine with instance ID tracking
  • Component metrics collection and querying
  • WIT value serialization and deserialization
  • Component orchestrator and resource management

  • Method Details

    • getInstance

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

    • destroyComponent

      public void destroyComponent(MemorySegment componentPtr)
      Destroys a component.
      Parameters:
      componentPtr - pointer to the component to destroy

    • componentGetSize

      public long componentGetSize(MemorySegment componentHandle)
      Gets the size of a component.
      Parameters:
      componentHandle - the component handle
      Returns:
      the component size in bytes

    • componentExportsInterface

      public int componentExportsInterface(MemorySegment componentHandle, MemorySegment interfaceName)
      Checks if a component exports an interface.
      Parameters:
      componentHandle - the component handle
      interfaceName - the interface name (C string)
      Returns:
      1 if exports the interface, 0 otherwise

    • componentImportsInterface

      public int componentImportsInterface(MemorySegment componentHandle, MemorySegment interfaceName)
      Checks if a component imports an interface.
      Parameters:
      componentHandle - the component handle
      interfaceName - the interface name (C string)
      Returns:
      1 if imports the interface, 0 otherwise

    • componentExportCount

      public long componentExportCount(MemorySegment componentHandle)
      Gets the count of exports in a component.
      Parameters:
      componentHandle - the component handle
      Returns:
      number of exports

    • componentImportCount

      public long componentImportCount(MemorySegment componentHandle)
      Gets the count of imports in a component.
      Parameters:
      componentHandle - the component handle
      Returns:
      number of imports

    • componentGetExportName

      public int componentGetExportName(MemorySegment componentHandle, long index, MemorySegment nameOut)
      Gets an export interface name by index.
      Parameters:
      componentHandle - the component handle
      index - the export index
      nameOut - pointer to receive the name string
      Returns:
      0 on success, non-zero on error

    • componentGetImportName

      public int componentGetImportName(MemorySegment componentHandle, long index, MemorySegment nameOut)
      Gets an import interface name by index.
      Parameters:
      componentHandle - the component handle
      index - the import index
      nameOut - pointer to receive the name string
      Returns:
      0 on success, non-zero on error

    • componentFreeString

      public void componentFreeString(MemorySegment stringPtr)
      Frees a string returned by component functions.
      Parameters:
      stringPtr - the string pointer to free

    • componentGetFullTypeJson

      public int componentGetFullTypeJson(MemorySegment componentHandle, MemorySegment engineHandle, MemorySegment jsonOut)
      Gets the full component type as a JSON string with complete type information.
      Parameters:
      componentHandle - the component handle
      engineHandle - the engine handle
      jsonOut - pointer to receive the JSON string
      Returns:
      0 on success, non-zero on error

    • componentLinkerSubstitutedTypeJson

      public int componentLinkerSubstitutedTypeJson(MemorySegment linkerHandle, MemorySegment componentHandle, MemorySegment jsonOut)
      Gets the substituted component type as a JSON string.
      Parameters:
      linkerHandle - the linker handle
      componentHandle - the component handle
      jsonOut - pointer to receive the JSON string
      Returns:
      0 on success, non-zero on error

    • componentFreeStringArray

      public void componentFreeStringArray(MemorySegment stringsPtr, int count)
      Frees an array of C strings returned by component functions.
      Parameters:
      stringsPtr - pointer to array of string pointers
      count - number of strings in the array

    • enhancedComponentEngineCreate

      public MemorySegment enhancedComponentEngineCreate()
      Creates an enhanced component engine for managing component instances.
      Returns:
      pointer to the enhanced component engine, or NULL on failure

    • enhancedComponentLoadFromBytes

      public int enhancedComponentLoadFromBytes(MemorySegment engineHandle, MemorySegment wasmBytes, long wasmSize, MemorySegment componentOut)
      Loads (compiles) a component from WebAssembly bytes.
      Parameters:
      engineHandle - the enhanced component engine handle
      wasmBytes - the WebAssembly component bytes
      wasmSize - the size of the WebAssembly bytes
      componentOut - output parameter for the component handle
      Returns:
      error code (0 for success)

    • componentCompileWat

      public int componentCompileWat(MemorySegment engineHandle, MemorySegment watBytes, long watLen, MemorySegment componentOut)
      Compiles a component from WAT text.
      Parameters:
      engineHandle - the enhanced component engine handle
      watBytes - pointer to WAT text bytes
      watLen - length of WAT text bytes
      componentOut - output parameter for the component pointer
      Returns:
      0 on success, non-zero error code on failure

    • componentValidate

      public int componentValidate(MemorySegment componentPtr, MemorySegment witInterface)
      Validates a component against a WIT interface.
      Parameters:
      componentPtr - pointer to the component
      witInterface - C string pointer to the WIT interface text
      Returns:
      1 if valid, 0 if invalid, negative on error

    • enhancedComponentInstantiate

      public int enhancedComponentInstantiate(MemorySegment engineHandle, MemorySegment componentHandle, MemorySegment instanceIdOut)
      Instantiates a component and returns an instance ID.
      Parameters:
      engineHandle - the enhanced component engine handle
      componentHandle - the component handle
      instanceIdOut - output parameter for the instance ID (u64)
      Returns:
      0 on success, non-zero error code on failure

    • enhancedComponentInvoke

      public int enhancedComponentInvoke(MemorySegment engineHandle, long instanceId, MemorySegment functionName, MemorySegment paramsPtr, int paramsCount, MemorySegment resultsOut, MemorySegment resultsCountOut)
      Invokes a component function using instance ID.
      Parameters:
      engineHandle - the enhanced component engine handle
      instanceId - the instance ID returned from instantiation
      functionName - the function name to invoke
      paramsPtr - pointer to the parameters array
      paramsCount - number of parameters
      resultsOut - output parameter for results array
      resultsCountOut - output parameter for results count
      Returns:
      0 on success, non-zero error code on failure

    • enhancedComponentGetExports

      public int enhancedComponentGetExports(MemorySegment engineHandle, long instanceId, MemorySegment functionsOut, MemorySegment countOut)
      Gets the list of exported function names using instance ID.
      Parameters:
      engineHandle - the enhanced component engine handle
      instanceId - the instance ID
      functionsOut - output parameter for array of function name pointers
      countOut - output parameter for count of functions
      Returns:
      0 on success, non-zero error code on failure

    • enhancedComponentEngineIsAsync

      public boolean enhancedComponentEngineIsAsync(MemorySegment enginePtr)
      Checks if async support is enabled for an enhanced component engine.
      Parameters:
      enginePtr - pointer to the enhanced component engine
      Returns:
      true if async support is enabled

    • enhancedComponentInstanceHasFunc

      public int enhancedComponentInstanceHasFunc(MemorySegment enginePtr, long instanceId, MemorySegment functionName)
      Checks if a component instance has a specific function export.
      Parameters:
      enginePtr - pointer to the enhanced component engine
      instanceId - the component instance ID
      functionName - C string with the function name
      Returns:
      1 if found, 0 if not found, -1 on error

    • enhancedComponentInstanceGetModule

      public int enhancedComponentInstanceGetModule(MemorySegment enginePtr, long instanceId, MemorySegment moduleName, MemorySegment moduleOut)
      Looks up a core module exported by a component instance.
      Parameters:
      enginePtr - pointer to the enhanced component engine
      instanceId - the component instance ID
      moduleName - C string with the module name
      moduleOut - output pointer for the module handle
      Returns:
      0 on success, non-zero on error

    • enhancedComponentInstanceHasResource

      public int enhancedComponentInstanceHasResource(MemorySegment enginePtr, long instanceId, MemorySegment resourceName)
      Checks if a resource type is exported by a component instance.
      Parameters:
      enginePtr - pointer to the enhanced component engine
      instanceId - the component instance ID
      resourceName - C string with the resource name
      Returns:
      1 if found, 0 if not found, -1 on error

    • enhancedComponentEngineDestroy

      public void enhancedComponentEngineDestroy(MemorySegment engineHandle)
      Destroys an enhanced component engine and all its instances.
      Parameters:
      engineHandle - the enhanced component engine handle

    • witValueSerialize

      public int witValueSerialize(int typeDiscriminator, MemorySegment valuePtr, long valueLen, MemorySegment outData, MemorySegment outLen)
      Serializes a WIT value to binary format.
      Parameters:
      typeDiscriminator - the type discriminator (1-6)
      valuePtr - pointer to the value data
      valueLen - length of the value data
      outData - output buffer for serialized data
      outLen - output parameter for data length
      Returns:
      0 on success, non-zero on error

    • witValueDeserialize

      public int witValueDeserialize(int typeDiscriminator, MemorySegment dataPtr, long dataLen, MemorySegment outValue, MemorySegment outLen)
      Deserializes a WIT value from binary format.
      Parameters:
      typeDiscriminator - the type discriminator (1-6)
      dataPtr - pointer to the serialized data
      dataLen - length of the data
      outValue - output buffer for deserialized value
      outLen - output parameter for value length
      Returns:
      0 on success, non-zero on error

    • witValueValidateDiscriminator

      public boolean witValueValidateDiscriminator(int typeDiscriminator)
      Validates a type discriminator.
      Parameters:
      typeDiscriminator - the type discriminator to validate
      Returns:
      true if valid (1), false otherwise (0)

    • witValueFreeBuffer

      public void witValueFreeBuffer(MemorySegment ptr, long len)
      Frees a buffer allocated by WIT value marshalling functions.
      Parameters:
      ptr - pointer to the buffer to free
      len - length of the buffer

    • componentLinkerCreateWithEngine

      public MemorySegment componentLinkerCreateWithEngine(MemorySegment enginePtr)
      Creates a new component linker from a Wasmtime engine.
      Parameters:
      enginePtr - pointer to the Wasmtime engine
      Returns:
      pointer to the new component linker, or null on failure

    • componentLinkerDestroy

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

    • componentLinkerIsValid

      public int componentLinkerIsValid(MemorySegment linkerPtr)
      Checks if a component linker is valid.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      1 if valid, 0 if invalid

    • componentLinkerEnableWasiP2

      public int componentLinkerEnableWasiP2(MemorySegment linkerPtr)
      Enables WASI Preview 2 in the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      0 on success, non-zero on error

    • componentLinkerEnableWasiHttp

      public int componentLinkerEnableWasiHttp(MemorySegment linkerPtr)
      Enables WASI HTTP in the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      0 on success, non-zero on error

    • componentLinkerEnableWasiHttpWithConfig

      public int componentLinkerEnableWasiHttpWithConfig(MemorySegment linkerPtr, long fieldSizeLimit)
      Enables WASI HTTP with configuration in the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      fieldSizeLimit - maximum HTTP header field size (0 for default)
      Returns:
      0 on success, non-zero on error

    • componentLinkerEnableWasiConfig

      public int componentLinkerEnableWasiConfig(MemorySegment linkerPtr)
      Enables WASI Config in the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetConfigVariables

      public int componentLinkerSetConfigVariables(MemorySegment linkerPtr, Map<String,String> variables)
      Sets configuration variables for WASI Config.

      Allocates native memory for the key-value string arrays, calls the native function, and releases memory when done.

      Parameters:
      linkerPtr - pointer to the component linker
      variables - the configuration variables as key-value pairs
      Returns:
      0 on success, non-zero on error

    • componentLinkerGetInterfaces

      public int componentLinkerGetInterfaces(MemorySegment linkerPtr, MemorySegment jsonOut)
      Gets all defined interfaces from the native linker as a JSON array string.
      Parameters:
      linkerPtr - pointer to the component linker
      jsonOut - pointer to receive the JSON string (must be freed with componentFreeString)
      Returns:
      0 on success, non-zero on error

    • componentLinkerGetFunctions

      public int componentLinkerGetFunctions(MemorySegment linkerPtr, MemorySegment namespace, MemorySegment interfaceName, MemorySegment jsonOut)
      Gets all defined functions for a specific interface as a JSON array string.
      Parameters:
      linkerPtr - pointer to the component linker
      namespace - pointer to the interface namespace C string
      interfaceName - pointer to the interface name C string
      jsonOut - pointer to receive the JSON string (must be freed with componentFreeString)
      Returns:
      0 on success, non-zero on error

    • componentLinkerHostFunctionCount

      public long componentLinkerHostFunctionCount(MemorySegment linkerPtr)
      Gets the number of host functions defined in the linker.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      the host function count

    • componentLinkerInterfaceCount

      public long componentLinkerInterfaceCount(MemorySegment linkerPtr)
      Gets the number of interfaces defined in the linker.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      the interface count

    • componentLinkerWasiP2Enabled

      public int componentLinkerWasiP2Enabled(MemorySegment linkerPtr)
      Checks if WASI Preview 2 is enabled in the linker.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      1 if enabled, 0 if not, FFI_ERROR on error

    • componentLinkerWasiHttpEnabled

      public int componentLinkerWasiHttpEnabled(MemorySegment linkerPtr)
      Checks if WASI HTTP is enabled in the linker.
      Parameters:
      linkerPtr - pointer to the component linker
      Returns:
      1 if enabled, 0 if not, FFI_ERROR on error

    • componentLinkerSetAsyncSupport

      public int componentLinkerSetAsyncSupport(MemorySegment linkerPtr, int enabled)
      Sets async support on the linker.
      Parameters:
      linkerPtr - pointer to the component linker
      enabled - 1 to enable, 0 to disable
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiMaxRandomSize

      public int componentLinkerSetWasiMaxRandomSize(MemorySegment linkerPtr, long maxSize)
      Sets the maximum random buffer size for WASI random operations.
      Parameters:
      linkerPtr - pointer to the component linker
      maxSize - the maximum size in bytes
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiArgs

      public int componentLinkerSetWasiArgs(MemorySegment linkerPtr, MemorySegment argsJsonPtr)
      Sets WASI Preview 2 arguments for the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      argsJsonPtr - pointer to JSON array of argument strings
      Returns:
      0 on success, non-zero on error

    • componentLinkerAddWasiEnv

      public int componentLinkerAddWasiEnv(MemorySegment linkerPtr, MemorySegment keyPtr, MemorySegment valuePtr)
      Adds a WASI Preview 2 environment variable to the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      keyPtr - pointer to environment variable key string
      valuePtr - pointer to environment variable value string
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInheritEnv

      public int componentLinkerSetWasiInheritEnv(MemorySegment linkerPtr, int inherit)
      Sets whether to inherit environment from host in WASI Preview 2.
      Parameters:
      linkerPtr - pointer to the component linker
      inherit - 1 to inherit, 0 to not inherit
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInheritArgs

      public int componentLinkerSetWasiInheritArgs(MemorySegment linkerPtr, int inherit)
      Sets whether to inherit arguments from host in WASI Preview 2.
      Parameters:
      linkerPtr - pointer to the component linker
      inherit - 1 to inherit, 0 to not inherit
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInheritStdio

      public int componentLinkerSetWasiInheritStdio(MemorySegment linkerPtr, int inherit)
      Sets whether to inherit stdio from host in WASI Preview 2.
      Parameters:
      linkerPtr - pointer to the component linker
      inherit - 1 to inherit, 0 to not inherit
      Returns:
      0 on success, non-zero on error

    • componentLinkerAddWasiPreopenDir

      public int componentLinkerAddWasiPreopenDir(MemorySegment linkerPtr, MemorySegment hostPathPtr, MemorySegment guestPathPtr, int dirPermsBits, int filePermsBits)
      Adds a preopened directory for WASI Preview 2 with granular permissions.
      Parameters:
      linkerPtr - pointer to the component linker
      hostPathPtr - pointer to host path string
      guestPathPtr - pointer to guest path string
      dirPermsBits - directory permission bits (DirPerms)
      filePermsBits - file permission bits (FilePerms)
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiAllowNetwork

      public int componentLinkerSetWasiAllowNetwork(MemorySegment linkerPtr, int allow)
      Sets whether network access is allowed in WASI Preview 2.
      Parameters:
      linkerPtr - pointer to the component linker
      allow - 1 to allow, 0 to disallow
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInheritStdin

      public int componentLinkerSetWasiInheritStdin(MemorySegment linkerPtr, int inherit)
      Sets whether to inherit stdin individually.
      Parameters:
      linkerPtr - pointer to the component linker
      inherit - 1 to inherit, 0 to not inherit
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInheritStdout

      public int componentLinkerSetWasiInheritStdout(MemorySegment linkerPtr, int inherit)
      Sets whether to inherit stdout individually.
      Parameters:
      linkerPtr - pointer to the component linker
      inherit - 1 to inherit, 0 to not inherit
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInheritStderr

      public int componentLinkerSetWasiInheritStderr(MemorySegment linkerPtr, int inherit)
      Sets whether to inherit stderr individually.
      Parameters:
      linkerPtr - pointer to the component linker
      inherit - 1 to inherit, 0 to not inherit
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiStdinBytes

      public int componentLinkerSetWasiStdinBytes(MemorySegment linkerPtr, MemorySegment data, long dataLen)
      Sets stdin bytes for the WASI context.
      Parameters:
      linkerPtr - pointer to the component linker
      data - pointer to the byte data
      dataLen - length of the byte data
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiAllowTcp

      public int componentLinkerSetWasiAllowTcp(MemorySegment linkerPtr, int allow)
      Sets whether TCP sockets are allowed.
      Parameters:
      linkerPtr - pointer to the component linker
      allow - 1 to allow, 0 to disallow
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiAllowUdp

      public int componentLinkerSetWasiAllowUdp(MemorySegment linkerPtr, int allow)
      Sets whether UDP sockets are allowed.
      Parameters:
      linkerPtr - pointer to the component linker
      allow - 1 to allow, 0 to disallow
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiAllowIpNameLookup

      public int componentLinkerSetWasiAllowIpNameLookup(MemorySegment linkerPtr, int allow)
      Sets whether IP name lookup (DNS) is allowed.
      Parameters:
      linkerPtr - pointer to the component linker
      allow - 1 to allow, 0 to disallow
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiAllowBlockingCurrentThread

      public int componentLinkerSetWasiAllowBlockingCurrentThread(MemorySegment linkerPtr, int allow)
      Sets whether blocking the current thread is allowed.
      Parameters:
      linkerPtr - pointer to the component linker
      allow - 1 to allow, 0 to disallow
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInsecureRandomSeed

      public int componentLinkerSetWasiInsecureRandomSeed(MemorySegment linkerPtr, long seed)
      Sets the insecure random seed.
      Parameters:
      linkerPtr - pointer to the component linker
      seed - the seed value
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiWallClock

      public int componentLinkerSetWasiWallClock(MemorySegment linkerPtr, MemorySegment nowFn, MemorySegment resolutionFn, long callbackId)
      Sets a custom wall clock callback.
      Parameters:
      linkerPtr - pointer to the component linker
      nowFn - function pointer for now() callback
      resolutionFn - function pointer for resolution() callback
      callbackId - identifier for the Java-side clock
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiMonotonicClock

      public int componentLinkerSetWasiMonotonicClock(MemorySegment linkerPtr, MemorySegment nowFn, MemorySegment resolutionFn, long callbackId)
      Sets a custom monotonic clock callback.
      Parameters:
      linkerPtr - pointer to the component linker
      nowFn - function pointer for now() callback
      resolutionFn - function pointer for resolution() callback
      callbackId - identifier for the Java-side clock
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiSecureRandom

      public int componentLinkerSetWasiSecureRandom(MemorySegment linkerPtr, MemorySegment fillBytesFn, long callbackId)
      Sets a custom secure random callback.
      Parameters:
      linkerPtr - pointer to the component linker
      fillBytesFn - function pointer for fillBytes() callback
      callbackId - identifier for the Java-side random source
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiInsecureRandom

      public int componentLinkerSetWasiInsecureRandom(MemorySegment linkerPtr, MemorySegment fillBytesFn, long callbackId)
      Sets a custom insecure random callback.
      Parameters:
      linkerPtr - pointer to the component linker
      fillBytesFn - function pointer for fillBytes() callback
      callbackId - identifier for the Java-side random source
      Returns:
      0 on success, non-zero on error

    • componentLinkerSetWasiSocketAddrCheck

      public int componentLinkerSetWasiSocketAddrCheck(MemorySegment linkerPtr, MemorySegment checkFn, long callbackId)
      Sets a socket address check callback.
      Parameters:
      linkerPtr - pointer to the component linker
      checkFn - function pointer for check() callback
      callbackId - identifier for the Java-side check
      Returns:
      0 on success, non-zero on error

    • componentLinkerInstantiate

      public int componentLinkerInstantiate(MemorySegment linkerPtr, MemorySegment componentPtr, MemorySegment instanceOutPtr)
      Instantiates a component using the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      componentPtr - pointer to the component
      instanceOutPtr - pointer to store the instance pointer
      Returns:
      0 on success, non-zero on error

    • componentSerialize

      public int componentSerialize(MemorySegment componentPtr, MemorySegment dataPtrOut, MemorySegment lenOut)
      Serializes a component to bytes.

      The caller must free the returned data using componentFreeSerializedData(java.lang.foreign.MemorySegment, long).

      Parameters:
      componentPtr - the component pointer
      dataPtrOut - output pointer to receive the serialized data pointer
      lenOut - output pointer to receive the data length
      Returns:
      0 on success, non-zero on error

    • componentFreeSerializedData

      public void componentFreeSerializedData(MemorySegment dataPtr, long len)
      Frees serialized component data previously returned by componentSerialize(java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment, java.lang.foreign.MemorySegment).
      Parameters:
      dataPtr - the data pointer to free
      len - the length of the data

    • panamaComponentDeserialize

      public int panamaComponentDeserialize(MemorySegment enginePtr, MemorySegment dataPtr, long len, MemorySegment componentPtrOut)
      Deserializes a component from bytes using the enhanced component engine.
      Parameters:
      enginePtr - pointer to the enhanced component engine
      dataPtr - pointer to the serialized data
      len - length of the serialized data
      componentPtrOut - output pointer to receive the new component pointer
      Returns:
      0 on success, non-zero on error

    • panamaComponentDeserializeFile

      public int panamaComponentDeserializeFile(MemorySegment enginePtr, MemorySegment pathPtr, long pathLen, MemorySegment componentPtrOut)
      Deserializes a component from a file using the enhanced component engine.
      Parameters:
      enginePtr - pointer to the enhanced component engine
      pathPtr - pointer to the file path bytes (UTF-8)
      pathLen - length of the file path
      componentPtrOut - output pointer to receive the new component pointer
      Returns:
      0 on success, non-zero on error

    • panamaComponentResourcesRequired

      public int panamaComponentResourcesRequired(MemorySegment componentPtr, MemorySegment numMemoriesOut, MemorySegment maxMemoryOut, MemorySegment numTablesOut, MemorySegment maxTableOut)
      Gets the resources required by a component.
      Parameters:
      componentPtr - pointer to the component
      numMemoriesOut - output pointer for number of memories (i32)
      maxMemoryOut - output pointer for max initial memory size (i64, -1 if unbounded)
      numTablesOut - output pointer for number of tables (i32)
      maxTableOut - output pointer for max initial table size (i64, -1 if unbounded)
      Returns:
      0 on success, non-zero on error. numMemories=-2 means resources_required() returned None

    • componentImageRange

      public int componentImageRange(MemorySegment componentPtr, MemorySegment startPtr, MemorySegment endPtr)
      Gets the image range of a compiled component.
      Parameters:
      componentPtr - pointer to the component
      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

    • componentInitializeCowImage

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

    • componentLinkerInstantiatePre

      public MemorySegment componentLinkerInstantiatePre(MemorySegment linkerPtr, MemorySegment componentPtr)
      Pre-instantiates a component using the linker.
      Parameters:
      linkerPtr - pointer to the component linker
      componentPtr - pointer to the component
      Returns:
      pointer to the pre-instantiated handle, or null on failure

    • componentLinkerAllowShadowing

      public void componentLinkerAllowShadowing(MemorySegment linkerPtr, int allow)
      Allow or disallow shadowing of previously defined names.
      Parameters:
      linkerPtr - pointer to the component linker
      allow - 1 to allow, 0 to disallow

    • componentLinkerDefineUnknownImportsAsTraps

      public int componentLinkerDefineUnknownImportsAsTraps(MemorySegment linkerPtr, MemorySegment componentPtr)
      Define all unknown imports as traps.
      Parameters:
      linkerPtr - pointer to the component linker
      componentPtr - pointer to the component
      Returns:
      0 on success, -1 on error

    • componentLinkerDefineResource

      public int componentLinkerDefineResource(MemorySegment linkerPtr, MemorySegment interfacePathPtr, long interfacePathLen, MemorySegment resourceNamePtr, long resourceNameLen, int resourceId, MemorySegment destructorFn, long destructorCallbackId)
      Defines a host resource type on the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      interfacePathPtr - UTF-8 encoded interface path (e.g., "wasi:io/streams")
      interfacePathLen - length of the interface path
      resourceNamePtr - UTF-8 encoded resource name
      resourceNameLen - length of the resource name
      resourceId - unique resource ID
      destructorFn - function pointer for the destructor callback (nullable)
      destructorCallbackId - callback ID passed to the destructor function
      Returns:
      0 on success, non-zero on error

    • componentLinkerDefineModule

      public int componentLinkerDefineModule(MemorySegment linkerPtr, MemorySegment instancePathPtr, long instancePathLen, MemorySegment namePtr, long nameLen, MemorySegment modulePtr)
      Defines a core module on the component linker.
      Parameters:
      linkerPtr - pointer to the component linker
      instancePathPtr - UTF-8 encoded instance path
      instancePathLen - length of the instance path
      namePtr - UTF-8 encoded module name
      nameLen - length of the module name
      modulePtr - pointer to the native module
      Returns:
      0 on success, non-zero on error

    • componentLinkerDefineHostFunction

      public int componentLinkerDefineHostFunction(MemorySegment linkerPtr, MemorySegment witPathPtr, long witPathLen, MemorySegment callbackFn, long callbackId)
      Defines a host function on the component linker using a WIT path.
      Parameters:
      linkerPtr - pointer to the component linker
      witPathPtr - UTF-8 encoded WIT path (e.g., "wasi:cli/stdout#print")
      witPathLen - length of the WIT path
      callbackFn - function pointer for the host function callback
      callbackId - callback ID passed to the function pointer
      Returns:
      0 on success, non-zero on error

    • componentLinkerDefineHostFunctionAsync

      public int componentLinkerDefineHostFunctionAsync(MemorySegment linkerPtr, MemorySegment witPathPtr, long witPathLen, MemorySegment callbackFn, long callbackId)
      Defines an async host function on the component linker using a WIT path.
      Parameters:
      linkerPtr - pointer to the component linker
      witPathPtr - UTF-8 encoded WIT path (e.g., "wasi:cli/stdout#print")
      witPathLen - length of the WIT path
      callbackFn - function pointer for the host function callback
      callbackId - callback ID passed to the function pointer
      Returns:
      0 on success, non-zero on error

    • componentHostCallbackAllocResult

      public MemorySegment componentHostCallbackAllocResult(long len)
      Allocates a result buffer for host function callback results.
      Parameters:
      len - length of the buffer to allocate
      Returns:
      pointer to the allocated buffer

    • componentInstancePreInstantiate

      public int componentInstancePreInstantiate(MemorySegment prePtr, MemorySegment instanceOutPtr)
      Instantiates from a pre-instantiated component.
      Parameters:
      prePtr - pointer to the pre-instantiated handle
      instanceOutPtr - pointer to store the instance pointer
      Returns:
      0 on success, non-zero on error

    • componentInstancePreInstantiateWithConfig

      public int componentInstancePreInstantiateWithConfig(MemorySegment prePtr, long fuelLimit, long epochDeadline, long maxMemoryBytes, long maxTableElements, long maxInstances, long maxTables, long maxMemories, byte trapOnGrowFailure, MemorySegment instanceOutPtr)
      Instantiates from a pre-instantiated component with store configuration.
      Parameters:
      prePtr - pointer to the pre-instantiated handle
      fuelLimit - fuel limit for the store (0 for no limit)
      epochDeadline - epoch deadline for the store (0 for no deadline)
      maxMemoryBytes - maximum memory in bytes (0 for unlimited)
      maxTableElements - maximum elements per table (0 for unlimited)
      maxInstances - maximum wasm instances (0 for unlimited)
      maxTables - maximum tables (0 for unlimited)
      maxMemories - maximum memories (0 for unlimited)
      trapOnGrowFailure - whether to trap on grow failure (1) or return -1 (0)
      instanceOutPtr - pointer to store the instance pointer
      Returns:
      0 on success, non-zero on error

    • componentInstancePreIsValid

      public int componentInstancePreIsValid(MemorySegment prePtr)
      Checks if a pre-instantiated component handle is valid.
      Parameters:
      prePtr - pointer to the pre-instantiated handle
      Returns:
      1 if valid, 0 if not

    • componentInstancePreInstanceCount

      public long componentInstancePreInstanceCount(MemorySegment prePtr)
      Gets the instance count from a pre-instantiated component.
      Parameters:
      prePtr - pointer to the pre-instantiated handle
      Returns:
      the number of instances created

    • componentInstancePrePreparationTimeNs

      public long componentInstancePrePreparationTimeNs(MemorySegment prePtr)
      Gets the preparation time in nanoseconds from a pre-instantiated component.
      Parameters:
      prePtr - pointer to the pre-instantiated handle
      Returns:
      preparation time in nanoseconds

    • componentInstancePreAvgInstantiationTimeNs

      public long componentInstancePreAvgInstantiationTimeNs(MemorySegment prePtr)
      Gets the average instantiation time in nanoseconds from a pre-instantiated component.
      Parameters:
      prePtr - pointer to the pre-instantiated handle
      Returns:
      average instantiation time in nanoseconds

    • componentInstancePreDestroy

      public void componentInstancePreDestroy(MemorySegment prePtr)
      Destroys a pre-instantiated component handle.
      Parameters:
      prePtr - pointer to the pre-instantiated handle to destroy

    • componentGetExportIndex

      public int componentGetExportIndex(MemorySegment componentPtr, MemorySegment instanceIndexPtr, MemorySegment name, MemorySegment indexOut)
      Looks up a component export index by name.
      Parameters:
      componentPtr - pointer to the component
      instanceIndexPtr - optional parent instance index (may be NULL)
      name - C string with the export name
      indexOut - output pointer for the export index handle
      Returns:
      0 if found, 1 if not found, -1 on error

    • componentExportIndexDestroy

      public void componentExportIndexDestroy(MemorySegment indexPtr)
      Destroys a component export index handle.
      Parameters:
      indexPtr - pointer to the export index to destroy

    • enhancedComponentInstanceHasFuncByIndex

      public int enhancedComponentInstanceHasFuncByIndex(MemorySegment enginePtr, long instanceId, MemorySegment indexPtr)
      Checks if a component instance has a function at the given export index.
      Parameters:
      enginePtr - pointer to the enhanced component engine
      instanceId - the component instance ID
      indexPtr - pointer to the export index
      Returns:
      1 if found, 0 if not found, -1 on error

    • enhancedComponentInstanceGetExport

      public int enhancedComponentInstanceGetExport(MemorySegment enginePtr, long instanceId, MemorySegment parentIndexPtr, MemorySegment namePtr, long nameLen, MemorySegment outIndexPtr)
      Looks up a general export by name on a component instance.

      Returns the export kind code (0-6) on success, -1 if not found, -2 on error. On success, writes the boxed ComponentExportIndex pointer to outIndexPtr.

      Parameters:
      enginePtr - pointer to the enhanced component engine
      instanceId - the component instance ID
      parentIndexPtr - pointer to parent export index (NULL for root)
      namePtr - pointer to the export name bytes
      nameLen - length of the export name
      outIndexPtr - pointer to output export index pointer (caller-allocated)
      Returns:
      kind code (0-6), -1 if not found, -2 on error

    • enhancedComponentRunConcurrent

      public int enhancedComponentRunConcurrent(MemorySegment enginePtr, long instanceId, MemorySegment jsonPtr, long jsonLen, MemorySegment resultPtr, MemorySegment resultLen)
      Executes concurrent component function calls via the enhanced component engine.
      Parameters:
      enginePtr - the enhanced engine pointer
      instanceId - the component instance ID
      jsonPtr - pointer to the JSON input bytes
      jsonLen - length of the JSON input bytes
      resultPtr - pointer to output result pointer (caller-allocated)
      resultLen - pointer to output result length (caller-allocated)
      Returns:
      0 on success, -1 on error

    • freeConcurrentResult

      public void freeConcurrentResult(MemorySegment ptr, long len)
      Frees a result buffer allocated by the concurrent call function.
      Parameters:
      ptr - the pointer to the result buffer
      len - the length of the result buffer

    • asyncValClose

      public int asyncValClose(long handle)
      Closes an async val handle (Future/Stream/ErrorContext) in the native AsyncValRegistry.

      This removes the handle from the global registry, dropping the stored Val. Safe to call with handles that have already been consumed or closed (no-op).

      Parameters:
      handle - the async val handle to close
      Returns:
      0 on success (handle found and removed), -1 if handle was not found

    • createAsyncValCloseAction

      public Runnable createAsyncValCloseAction(long handle)
      Creates a Runnable close action that invokes asyncValClose(long) for the given handle. Suitable for use with StreamAny.create(long, Runnable), FutureAny.create(long, Runnable), and ErrorContext.create(long, Runnable).
      Parameters:
      handle - the async val handle
      Returns:
      a Runnable that will close the handle when invoked

    • resourceAnyDrop

      public int resourceAnyDrop(MemorySegment enginePtr, long instanceId, long resourceHandle)
      Drops a ResourceAny held in the global resource registry.

      Takes the resource from the registry and calls resource_drop on it using the store associated with the given component instance.

      Parameters:
      enginePtr - the enhanced component engine pointer
      instanceId - the component instance ID that owns the store
      resourceHandle - the resource handle ID from the global registry
      Returns:
      0 on success, non-zero on error

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