Class NativeWasiBindings

java.lang.Object
ai.tegmentum.wasmtime4j.panama.NativeWasiBindings
public final class NativeWasiBindings extends Object
Native function bindings for WASI context operations.

Provides type-safe wrappers for all WASI context native functions including context lifecycle management, environment and argument configuration, stdio redirection, directory pre-opening, output capture, and linker integration.

  • Method Details

    • getInstance

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

    • wasiContextCreate

      public MemorySegment wasiContextCreate()
      Creates a new WASI context.
      Returns:
      pointer to the WASI context, or null on failure

    • wasiContextDestroy

      public void wasiContextDestroy(MemorySegment contextHandle)
      Destroys a WASI context.
      Parameters:
      contextHandle - the WASI context handle

    • wasiContextSetArgv

      public int wasiContextSetArgv(MemorySegment contextHandle, MemorySegment args, long argCount)
      Sets command line arguments for the WASI context.
      Parameters:
      contextHandle - the WASI context handle
      args - pointer to array of C strings
      argCount - number of arguments
      Returns:
      0 on success, non-zero on error

    • wasiContextSetEnv

      public int wasiContextSetEnv(MemorySegment contextHandle, MemorySegment key, MemorySegment value)
      Sets an environment variable in the WASI context.
      Parameters:
      contextHandle - the WASI context handle
      key - the environment variable name (C string)
      value - the environment variable value (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextInheritEnv

      public int wasiContextInheritEnv(MemorySegment contextHandle)
      Inherits all host environment variables.
      Parameters:
      contextHandle - the WASI context handle
      Returns:
      0 on success, non-zero on error

    • wasiContextInheritArgs

      public int wasiContextInheritArgs(MemorySegment contextHandle)
      Inherits host command-line arguments.
      Parameters:
      contextHandle - the WASI context handle
      Returns:
      0 on success, non-zero on error

    • wasiContextGetEnvironment

      public int wasiContextGetEnvironment(MemorySegment contextHandle, MemorySegment outPtr, MemorySegment outLen)
      Gets the environment variables from the WASI context.

      Returns environment as "key=value\n" pairs in the output buffer. The caller must free the buffer using wasiFreeCaptureBuffer(MemorySegment, long).

      Parameters:
      contextHandle - the WASI context handle
      outPtr - output pointer for the data buffer
      outLen - output pointer for the data length
      Returns:
      0 on success, non-zero on error

    • wasiContextGetArguments

      public int wasiContextGetArguments(MemorySegment contextHandle, MemorySegment outPtr, MemorySegment outLen)
      Gets the arguments from the WASI context.

      Returns arguments as "arg1\narg2\n..." in the output buffer. The caller must free the buffer using wasiFreeCaptureBuffer(MemorySegment, long).

      Parameters:
      contextHandle - the WASI context handle
      outPtr - output pointer for the data buffer
      outLen - output pointer for the data length
      Returns:
      0 on success, non-zero on error

    • wasiContextInheritStdio

      public int wasiContextInheritStdio(MemorySegment contextHandle)
      Inherits host stdio streams.
      Parameters:
      contextHandle - the WASI context handle
      Returns:
      0 on success, non-zero on error

    • wasiContextSetStdin

      public int wasiContextSetStdin(MemorySegment contextHandle, MemorySegment path)
      Sets stdin to read from a file.
      Parameters:
      contextHandle - the WASI context handle
      path - the file path (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextSetStdinBytes

      public int wasiContextSetStdinBytes(MemorySegment contextHandle, MemorySegment dataPtr, long dataLen)
      Sets stdin from binary data buffer (supports binary data with null bytes).
      Parameters:
      contextHandle - the WASI context handle
      dataPtr - pointer to the binary data
      dataLen - length of the data in bytes
      Returns:
      0 on success, non-zero on error

    • wasiContextSetStdout

      public int wasiContextSetStdout(MemorySegment contextHandle, MemorySegment path)
      Sets stdout to write to a file.
      Parameters:
      contextHandle - the WASI context handle
      path - the file path (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextSetStderr

      public int wasiContextSetStderr(MemorySegment contextHandle, MemorySegment path)
      Sets stderr to write to a file.
      Parameters:
      contextHandle - the WASI context handle
      path - the file path (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextSetStdoutAppend

      public int wasiContextSetStdoutAppend(MemorySegment contextHandle, MemorySegment path)
      Sets stdout to append to a file.
      Parameters:
      contextHandle - the WASI context handle
      path - the file path (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextSetStderrAppend

      public int wasiContextSetStderrAppend(MemorySegment contextHandle, MemorySegment path)
      Sets stderr to append to a file.
      Parameters:
      contextHandle - the WASI context handle
      path - the file path (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextPreopenDir

      public int wasiContextPreopenDir(MemorySegment contextHandle, MemorySegment hostPath, MemorySegment guestPath)
      Adds a pre-opened directory with full permissions.
      Parameters:
      contextHandle - the WASI context handle
      hostPath - the host filesystem path (C string)
      guestPath - the guest path visible to WASI module (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextPreopenDirReadonly

      public int wasiContextPreopenDirReadonly(MemorySegment contextHandle, MemorySegment hostPath, MemorySegment guestPath)
      Adds a pre-opened directory with read-only permissions.
      Parameters:
      contextHandle - the WASI context handle
      hostPath - the host filesystem path (C string)
      guestPath - the guest path visible to WASI module (C string)
      Returns:
      0 on success, non-zero on error

    • wasiContextPreopenDirWithPerms

      public int wasiContextPreopenDirWithPerms(MemorySegment contextHandle, MemorySegment hostPath, MemorySegment guestPath, int canRead, int canWrite, int canCreate)
      Adds a pre-opened directory with custom permissions.
      Parameters:
      contextHandle - the WASI context handle
      hostPath - the host filesystem path (C string)
      guestPath - the guest path visible to WASI module (C string)
      canRead - whether reading is allowed
      canWrite - whether writing is allowed
      canCreate - whether file creation is allowed
      Returns:
      0 on success, non-zero on error

    • wasiContextEnableOutputCapture

      public int wasiContextEnableOutputCapture(MemorySegment contextHandle)
      Enables output capture for stdout and stderr.

      This configures the WASI context to capture stdout and stderr to internal buffers instead of inheriting from the host process.

      Parameters:
      contextHandle - the WASI context handle
      Returns:
      0 on success, non-zero on error

    • wasiContextGetStdoutCapture

      public MemorySegment wasiContextGetStdoutCapture(MemorySegment contextHandle, MemorySegment lengthOut)
      Gets captured stdout data.

      Returns a pointer to the captured stdout data and sets the length in the output parameter. The caller must free the returned buffer using wasiFreeCaptureBuffer(MemorySegment, long).

      Parameters:
      contextHandle - the WASI context handle
      lengthOut - output parameter for the data length
      Returns:
      pointer to captured data, or NULL if capture is not enabled or empty

    • wasiContextGetStderrCapture

      public MemorySegment wasiContextGetStderrCapture(MemorySegment contextHandle, MemorySegment lengthOut)
      Gets captured stderr data.

      Returns a pointer to the captured stderr data and sets the length in the output parameter. The caller must free the returned buffer using wasiFreeCaptureBuffer(MemorySegment, long).

      Parameters:
      contextHandle - the WASI context handle
      lengthOut - output parameter for the data length
      Returns:
      pointer to captured data, or NULL if capture is not enabled or empty

    • wasiFreeCaptureBuffer

      public void wasiFreeCaptureBuffer(MemorySegment buffer, long length)
      Frees a capture buffer allocated by wasiContextGetStdoutCapture(MemorySegment, MemorySegment) or wasiContextGetStderrCapture(MemorySegment, MemorySegment).
      Parameters:
      buffer - pointer to the buffer to free (can be NULL)
      length - the length of the buffer in bytes (must match the length returned at allocation)

    • wasiContextHasStdoutCapture

      public int wasiContextHasStdoutCapture(MemorySegment contextHandle)
      Checks if stdout capture is enabled.
      Parameters:
      contextHandle - the WASI context handle
      Returns:
      1 if capture is enabled, 0 if not, -1 on error

    • wasiContextHasStderrCapture

      public int wasiContextHasStderrCapture(MemorySegment contextHandle)
      Checks if stderr capture is enabled.
      Parameters:
      contextHandle - the WASI context handle
      Returns:
      1 if capture is enabled, 0 if not, -1 on error

    • wasiCtxAddToStore

      public int wasiCtxAddToStore(MemorySegment contextHandle, MemorySegment storeHandle)
      Adds a WASI context to a Store.

      This must be called before instantiating WASI-enabled modules. The context will be used by WASI imports when they are called.

      Parameters:
      contextHandle - the WASI context handle
      storeHandle - the Store handle
      Returns:
      0 on success, non-zero on error

    • linkerAddWasi

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

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

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

    • wasiContextSetNetworkConfig

      public int wasiContextSetNetworkConfig(MemorySegment contextHandle, int allowNetwork, int allowTcp, int allowUdp, int allowIpNameLookup)
      Sets network configuration on a WASI context.
      Parameters:
      contextHandle - the WASI context handle
      allowNetwork - 1 to allow network access (inherit_network), 0 to deny
      allowTcp - 1 to allow TCP socket creation, 0 to deny
      allowUdp - 1 to allow UDP socket creation, 0 to deny
      allowIpNameLookup - 1 to allow IP name lookups (DNS), 0 to deny
      Returns:
      0 on success, non-zero on failure

    • wasiContextSetAllowBlocking

      public int wasiContextSetAllowBlocking(MemorySegment contextHandle, int allow)
      Sets whether blocking the current thread is allowed.
      Parameters:
      contextHandle - the WASI context handle
      allow - 1 to allow blocking, 0 to deny
      Returns:
      0 on success, non-zero on failure

    • wasiContextSetInsecureRandomSeed

      public int wasiContextSetInsecureRandomSeed(MemorySegment contextHandle, long seedLo, long seedHi)
      Sets the insecure random seed for deterministic testing.
      Parameters:
      contextHandle - the WASI context handle
      seedLo - low 64 bits of the u128 seed
      seedHi - high 64 bits of the u128 seed
      Returns:
      0 on success, non-zero on failure

    • wasiContextRebuild

      public int wasiContextRebuild(MemorySegment contextHandle)
      Rebuilds the WASI context after configuration changes.

      Must be called after setting network config, blocking, or random seed to apply the changes. This avoids redundant rebuilds when multiple settings are configured at once.

      Parameters:
      contextHandle - the WASI context handle
      Returns:
      0 on success, non-zero on failure

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