DynLoad API Reference

Dynamic module loading, WASM sandboxing, and hot reload support

Import

U std/dynload

Overview

The dynload module provides comprehensive support for:

• Runtime loading and unloading of dynamic libraries
• WASM plugin sandboxing with resource limits and capabilities
• Hot reload for development workflows
• Plugin discovery from standard paths

Constants

Loading Flags

Plugin Capabilities

Structs

ModuleHandle

Represents a loaded dynamic module.

S ModuleHandle {
    handle: i64,      # dlopen handle
    path: i64,        # Path to the module (string pointer)
    version: i64,     # Module version (incremented on reload)
    loaded: i64       # 1 if loaded, 0 if not
}

Functions:

ResourceLimits

Resource limits for sandboxed execution.

S ResourceLimits {
    max_memory_bytes: i64,     # Maximum memory in bytes
    max_time_ms: i64,          # Maximum execution time in milliseconds
    max_stack_bytes: i64,      # Maximum stack size
    max_call_depth: i64        # Maximum function call depth
}

Functions:

WasmSandbox

WASM sandbox handle for plugin execution.

S WasmSandbox {
    handle: i64,
    capabilities: i64
}

Functions:

WasmInstance

WASM instance handle for calling functions.

S WasmInstance {
    handle: i64,
    sandbox: i64
}

Functions:

HotReloadConfig

Configuration for hot reload.

S HotReloadConfig {
    source_path: i64,      # Path to source file
    output_dir: i64,       # Output directory for compiled modules
    debounce_ms: i64,      # Debounce time for file changes
    verbose: i64           # Enable verbose logging
}

Functions:

HotReloader

Hot reloader handle.

S HotReloader {
    handle: i64,
    version: i64,
    running: i64
}

Functions:

Module Loading Functions

Capability System Functions

Utility Functions

External C Functions

Examples

Basic Dynamic Loading

U std/dynload

F main() -> i64 {
    # Load a dynamic library
    module := load_module("/path/to/plugin.dylib")

    I module_is_loaded(module) == 1 {
        # Get function pointer
        init_fn := get_function(module, "plugin_init")

        # Call the function (would need to cast and call)
        # ...

        # Unload when done
        unload_module(module)
    } E {
        # Error loading
        err := get_load_error()
        # Handle error
    }

    0
}

WASM Sandbox with Capabilities

U std/dynload

F main() -> i64 {
    # Create restrictive sandbox
    sandbox := sandbox_restrictive()

    # Grant specific capabilities
    sandbox = sandbox_grant(sandbox, CAP_CONSOLE)
    sandbox = sandbox_grant(sandbox, CAP_TIME)

    # Load WASM plugin
    wasm_bytes := load_wasm_file("plugin.wasm")
    wasm_len := get_wasm_size(wasm_bytes)

    instance := sandbox_load(sandbox, wasm_bytes, wasm_len)

    I wasm_is_valid(instance) == 1 {
        # Call plugin function
        result := wasm_call1(instance, "process", 42)
    }

    # Cleanup
    sandbox_destroy(sandbox)
    0
}

Hot Reload

U std/dynload

F main() -> i64 {
    # Create hot reloader for a source file
    reloader := hot_reloader_new("./src/plugin.vais")
    reloader = hot_reloader_start(reloader)

    # Main loop
    L 1 {
        # Check for changes
        changed := hot_reloader_check(reloader)

        I changed == 1 {
            version := hot_reloader_version(reloader)
            # Plugin was reloaded, update references
        }

        # Do work
        # ...
    }

    reloader = hot_reloader_stop(reloader)
    0
}

Capability Checking

U std/dynload

F verify_plugin_safety(plugin_caps: i64) -> i64 {
    # Check if plugin has dangerous capabilities
    I has_dangerous_capabilities(plugin_caps) == 1 {
        # Warn user or reject plugin
        0
    } E {
        # Safe to load
        1
    }
}

F main() -> i64 {
    # Build capability set for a plugin
    caps := CAP_CONSOLE
    caps = add_capability(caps, CAP_TIME)
    caps = add_capability(caps, CAP_RANDOM)

    # Check specific capability
    I has_capability(caps, CAP_NETWORK) == 1 {
        # Has network access
    }

    verify_plugin_safety(caps)
    0
}