Module preinit 

Available on crate feature preinit only.

Pre-initialization support for capturing Python memory state. Pre-initialization support for linked Python components.

This module provides functionality to pre-initialize Python components after linking. Pre-initialization runs the Python interpreter’s startup code and captures the initialized memory state into the component, avoiding the initialization cost at runtime.

How It Works

1. We link the component with real WASI imports
2. We use wasmtime-wizer to instrument the component (adding state accessors)
3. We instantiate the instrumented component - Python initializes
4. Optionally run imports (e.g., import numpy) to capture more state
5. Call finalize-preinit to reset WASI file handle state
6. The memory state is captured and embedded into the original component
7. The resulting component starts with Python already initialized

Performance Impact

• First build with pre-init: ~3-4 seconds (one-time cost)
• Per-execution after pre-init: ~1-5ms (vs ~450-500ms without)

Example

use eryx_runtime::preinit::{PreInitOptions, pre_initialize_with_options};

// Pre-initialize with native extensions
let preinit_component = pre_initialize_with_options(
    PreInitOptions::new(&python_stdlib_path)
        .site_packages(&site_packages_path)
        .imports(["numpy", "pandas"])  // Modules to import during pre-init
        .extensions(native_extensions)
        .setup_code("import numpy as np; arr = np.zeros(10)"),  // Optional setup code
).await?;

Structs

CallbackDeclaration

A callback the sandbox will offer at runtime, as the guest sees it.

PreInitOptions

Everything pre_initialize_with_options needs.

Enums

PreInitError

Errors that can occur during pre-initialization.

Functions

pre_initialize

Pre-initialize a Python component with native extensions.

pre_initialize_with_options

Pre-initialize a Python component according to options.