Package ej.lang

Class WasmModule

  • All Implemented Interfaces:
    Cloneable
    public abstract class WasmModule
extends Object
implements Cloneable
    Abstract superclass for all Wasm modules.

    To declare a custom Wasm module, create a concrete class that extends WasmModule. The class must be marked as final.

    A WasmModule can be instantiated in two ways:

    • Using WasmModule() to create a module instance with its own dedicated linear memory.
    • Using clone() to create an instance that shares the linear memory of another module (typically for multi-threaded or reentrant scenarios).

    The module's linear memory is accessible via the getMemory() method.

    An Alias annotation applied to a type that extends WasmModule specifies the name of the associated WASM module resource to be loaded from the classpath. If no Alias name is provided, the simple class name is used to identify the WASM module resource. The WASM resource file must have a .wasm extension, which must not be included in the alias name. For example @Alias("my_module") will resolve to /my_module.wasm on the classpath.

    Example: Declaring a simple Wasm module 

     @Alias("my_module") // Loads '/my_module.wasm' from the classpath
 public final class MyModule extends WasmModule {
        MyModule() {
                // Implicit call to super() constructor (sets up the module with a new
                // dedicated linear memory)
                // Additional custom initialization can be performed here
                // ...
        }
 }
    See Also:
    Alias

    • Constructor Detail

      • WasmModule

        protected WasmModule()
        Creates a new Wasm module instance with its own linear memory.

        This constructor performs the following:

        • Initializes Wasm globals
        • Allocates a new linear memory
        • Initializes data segments
        • Invokes the Wasm start function, if defined

    • Method Detail

      • getMemory

        public byte[] getMemory()
        Gets the linear memory associated with this module.
        Returns:
        the memory buffer

      • setHostInfo

        public void setHostInfo​(Object hostInfo)
        Associates the given host-provided object with this module instance.

        Host info is a single arbitrary object that the host environment can bind to a specific module instance to associate host-side runtime state with it.

        Each module instance maintains its own independent host info, which makes this mechanism well suited to per-instance sandboxing. For example, when using WASI (WebAssembly System Interface), each module instance can be initialized with its own WASI context — holding its own open file descriptors, environment variables, pre-opened directories, and other I/O state — by storing it here. The WASI implementation then retrieves it via getHostInfo() whenever it handles a system call from this module instance, ensuring full isolation between instances.

        Host info can only be set once per module instance. Calling this method a second time throws an IllegalStateException.

        Parameters:
        hostInfo - the object to associate with this module instance.
        Throws:
        IllegalArgumentException - if the given hostInfo is null.
        IllegalStateException - if host info has already been set on this module instance.
        See Also:
        getHostInfo()

      • getHostInfo

        @Nullable
public Object getHostInfo()
        Returns the host-provided object associated with this module instance.

        Returns the value previously set by setHostInfo(Object), or null if no object has been set yet.

        Returns:
        the host info object, or null if none has been set.
        See Also:
        setHostInfo(Object)

      • clone

        public WasmModule clone()
                 throws CloneNotSupportedException
        Creates and returns a copy of this Wasm module instance using the same shared elements (particularly the shared linear memory). All fields bound to Wasm globals are re-initialized. Other custom fields are left unchanged. Implementations may override this method to extend the new Wasm module initialization behavior.

        This operation is only supported for modules that uses shared memory. Modules with non-shared memory cannot be cloned and will cause this method to throw a CloneNotSupportedException.

        Overrides:
        clone in class Object
        Returns:
        a new Wasm module instance using the same linear memory with x.clone().getClass() == x.getClass()
        Throws:
        CloneNotSupportedException - if the module does not use shared memory
        See Also:
        Cloneable