Void Rust SDK (void-sdk-rust)

The official Rust SDK for building high-performance WebAssembly plugins on top of the Void framework.

Installation

Add this dependency to your plugin's Cargo.toml:

[dependencies]
void-sdk-rust = "1.0.0"

Quick Start

Create a CDYLIB library and use the void_plugin! macro to register functions:

use std::collections::HashMap;
use void_sdk_rust::{register, void_plugin, get_string, Value};

fn hello(args: HashMap<String, Value>) -> Result<Value, String> {
    let name = get_string(&args, "name").unwrap_or_else(|_| "World".to_string());
    Ok(Value::String(format!("Hello, {}!", name)))
}

fn setup() {
    register("hello", hello);
}

void_plugin!(setup);

Input Extraction API

The SDK provides helper functions to safely extract typed JSON values from incoming parameters:

• get_string(&args, "key") -> Result<String, String>
• get_bool(&args, "key", default_val) -> bool
• get_int(&args, "key") -> Result<i64, String>
• get_float(&args, "key") -> Result<f64, String>
• get_array(&args, "key") -> Result<Vec<Value>, String>
• get_object(&args, "key") -> Result<Map<String, Value>, String>
• get_value(&args, "key") -> Result<Value, String>
• get_null(&args, "key") -> Result<(), String>

Memory Management & Safety API

The SDK automatically manages heap memory during FFI boundaries. You can inspect FFI heap activity or manually allocate/release blocks using these utilities:

Check Memory Statistics

Inspect counts of currently active FFI allocations and total allocated memory size:

let stats = void_sdk_rust::get_memory_stats();
// stats.allocated_objects (usize)
// stats.total_bytes_pinned (u64)

Manual Pinning Helpers

For manually pinning raw arrays of bytes outside the standard invocation lifecycles:

// Pin a slice on the heap and get its pointer
let ptr = unsafe { void_sdk_rust::pin_memory(&my_bytes) };

// Unpin the block once finished to avoid memory leaks
unsafe { void_sdk_rust::unpin_memory(ptr, my_bytes.len()) };

License

ISC License. See LICENSE for details.