Memlink Runtime

Dynamic module loading and execution framework for Rust

Overview

Memlink Runtime is a high-performance dynamic module loading system that enables plugin architectures, hot-reloadable code, and safe FFI execution. Load shared libraries at runtime, call methods on them, and unload them without restarting your application.

Key Features

• 🔌 Dynamic Loading - Load .so, .dll, .dylib files at runtime
• 🛡️ Panic Isolation - Module panics don't crash your application
• 🔥 Hot Reload - Replace modules with zero downtime
• 📊 Prometheus Metrics - Built-in observability
• 🧵 Thread-Safe - Concurrent module calls from multiple threads
• 📦 Multi-Module - Load and manage multiple modules simultaneously

Quick Start

Installation

[dependencies]

memlink-runtime = "0.1.0"

Basic Example

use memlink_runtime::runtime::{Runtime, ModuleRuntime};
use memlink_runtime::resolver::ModuleRef;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create runtime
    let runtime = Runtime::with_local_resolver();
    
    // Load a module
    let handle = runtime.load(
        ModuleRef::parse("./my_module.so")?
    )?;
    
    // Call a method
    let result = runtime.call(handle, "process", b"input data")?;
    println!("Result: {:?}", String::from_utf8_lossy(&result));
    
    // Unload when done
    runtime.unload(handle)?;
    
    Ok(())
}

Creating Modules

Modules are shared libraries that export three required functions:

Minimal Module (C)

#include <stdint.h>
#include <string.h>

__attribute__((visibility("default")))
int memlink_init(const unsigned char* config, unsigned long config_len) {
    (void)config;
    (void)config_len;
    return 0;
}

__attribute__((visibility("default")))
int memlink_call(unsigned int method_id, const unsigned char* args,
                unsigned long args_len, unsigned char* output) {
    (void)method_id;
    // Echo input back
    if (args_len > 0 && args != NULL) {
        memcpy(output, args, args_len);
    }
    return 0;
}

__attribute__((visibility("default")))
int memlink_shutdown(void) {
    return 0;
}

Build Commands

See ABI Documentation for full specification.

Advanced Usage

Loading Multiple Modules

use memlink_runtime::runtime::{Runtime, ModuleRuntime};
use memlink_runtime::resolver::ModuleRef;
use std::sync::Arc;
use std::thread;

let runtime = Arc::new(Runtime::with_local_resolver());

// Load multiple modules
let math = runtime.load(ModuleRef::parse("./math.so")?)?;
let string = runtime.load(ModuleRef::parse("./string.so")?)?;
let crypto = runtime.load(ModuleRef::parse("./crypto.so")?)?;

// Call concurrently from different threads
let mut handles = vec![];

for (name, module) in [("math", math), ("string", string), ("crypto", crypto)] {
    let rt = Arc::clone(&runtime);
    let h = thread::spawn(move || {
        for i in 0..100 {
            rt.call(module, "process", format!("{}_{}", name, i).as_bytes()).unwrap();
        }
    });
    handles.push(h);
}

for h in handles {
    h.join().unwrap();
}

Hot Reload

use memlink_runtime::reload::ReloadConfig;
use std::time::Duration;

// Reload a module with new version
let config = ReloadConfig::default()
    .with_drain_timeout(Duration::from_secs(30))
    .with_state_preservation();

let reload_state = runtime.reload_with_config(
    old_handle,
    ModuleRef::parse("./my_module_v2.so")?,
    config
)?;

// Old module drains in-flight calls before unloading

Metrics and Monitoring

// Get usage statistics
let usage = runtime.get_usage(handle).unwrap();
println!("Calls: {}", usage.call_count);
println!("Arena: {} bytes ({:.2}%)", 
    usage.arena_bytes, 
    usage.arena_usage * 100.0
);

// Export Prometheus metrics
let metrics = RuntimeMetrics::new();
// ... after operations ...
println!("{}", metrics.prometheus_export());

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
│                     (Memlink Runtime)                    │
├─────────────────────────────────────────────────────────┤
│  Runtime                                                │
│  ├─ Resolver (locate modules)                           │
│  ├─ Loader (load shared libs)                           │
│  ├─ Instance Manager (track loaded modules)             │
│  ├─ Panic Handler (catch module panics)                 │
│  └─ Metrics (Prometheus-compatible)                     │
└─────────────────────────────────────────────────────────┘
         │
         ├─→ [module_a.so] ── memlink_init/call/shutdown
         ├─→ [module_b.dll] ── memlink_init/call/shutdown
         └─→ [module_c.dylib] ── memlink_init/call/shutdown

Components

Performance

Key Highlights:

• ✅ Sub-microsecond call latency
• ✅ Linear scalability up to 8 threads
• ✅ Fast hot reload with zero downtime
• ✅ Low memory footprint

See Performance Benchmarks for detailed methodology, full results, and optimization recommendations.

Use Cases

Plugin Systems

Load user-created plugins without recompiling your application:

// Load all plugins from a directory
for entry in std::fs::read_dir("./plugins")? {
    let path = entry?.path();
    if path.extension() == Some("so".as_ref()) {
        runtime.load(ModuleRef::parse(path.to_str().unwrap())?)?;
    }
}

Hot-Reloadable Business Logic

Update logic in production without downtime:

// Watch for file changes
notify::Watcher::new(move |event| {
    if event.path.ends_with("business_logic.so") {
        runtime.reload(handle, ModuleRef::parse("./business_logic.so")?)?;
    }
})?;

Sandboxed Execution

Isolate risky code that might panic:

// Module panics are caught and converted to errors
match runtime.call(handle, "risky_operation", data) {
    Ok(result) => println!("Success"),
    Err(Error::ModulePanicked(msg)) => eprintln!("Module panicked: {}", msg),
    Err(e) => eprintln!("Error: {}", e),
}

API Reference

Core Traits

Key Types

Full API Documentation

Examples

Run the included examples:

# Multi-module concurrent calls

cargo run --example m2


# Build test modules first (Linux/WSL)

cd examples/modules/build

node build.js --linux

See examples/modules/README.md for module documentation.

Platform Support

License

Memlink Runtime is licensed under the Apache License 2.0 (LICENSE-APACHE).

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run cargo test and cargo clippy
4. Submit a pull request

Development

# Build

cargo build


# Test

cargo test


# Lint

cargo clippy --all-targets


# Format

cargo fmt --all


# Build docs

cargo doc --open

Related Crates

• memlink-shm - Shared memory IPC
• libloading - Underlying library loading
• dashmap - Concurrent hash map

Support

• Issues: GitHub Issues
• Documentation: docs.rs
• ABI Spec: docs/abi.md