🔗 Nylon Ring

Ultra-Fast ABI-Stable Host–Plugin Interface for Rust

Build fast native plugins with an explicit C-compatible ABI.

Features • Quick Start • Performance • System Overview

🌟 Features

• Stable ABI v1 — C-compatible types, fixed status values, version and structure-size validation.
• Flexible calls — fire-and-forget, async unary, synchronous fast path, and bounded streaming with backpressure.
• Safe lifecycle — in-flight call guards, graceful unload/reload, timeouts, and automatic request cleanup.
• Cross-language validation — Rust examples plus a buildable C plugin.

The workspace provides:

• nylon-ring — ABI types, vtables, and the define_plugin! macro.
• nylon-ring-host — dynamic loading, routing, streaming, lifecycle controls, and metrics.

MSRV: Rust 1.88.

🚀 Quick start

Install

# Plugin
[dependencies]
nylon-ring = "0.1.3"

# Host
[dependencies]
nylon-ring-host = "0.1.3"

Plugin crates must also build as a dynamic library:

[lib]
crate-type = ["cdylib"]

Host

use nylon_ring_host::{NrStatus, NylonRingHost};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let mut host = NylonRingHost::new();
host.load("example", "target/release/libexample_plugin.so")?;

let plugin = host.plugin("example").expect("plugin was loaded");
let (status, response) = plugin.call_response("echo", b"hello").await?;

assert_eq!(status, NrStatus::Ok);
assert_eq!(response, b"hello");
# Ok(())
# }

Other call patterns:

plugin.call("notify", b"payload").await?;
plugin.call_response_fast("echo", b"hello").await?;
plugin.call_response_timeout("echo", b"hello", timeout).await?;
let (sid, stream) = plugin.call_stream("events", b"start").await?;

See the complete Rust plugin example and Rust host example.

Run the workspace demo:

cargo run --release --package ex-nyring-host

📊 Performance

Reference snapshot on an Apple M1 Pro (8 performance + 2 efficiency cores), release build. All host numbers come from the worker-loop harness in ex-nyring-host: workers await each call sequentially (in-flight depth 1 per worker) and every counted call is asserted Ok. Single-stream is the same harness at one worker, so the two columns are directly comparable. Each value is the median of three runs.

Throughput

Streaming times full 9-frame round trips (8 data frames + StreamEnd); its scaling is currently bounded by per-stream channel setup.

Unary payload curve (1 worker)

Non-empty payloads pay two alloc/free pairs and two copies under ABI v1: the response crosses the boundary as a foreign allocation and is copied into host-owned memory because allocator provenance cannot be proven across images.

These are reference measurements, not cross-platform guarantees; absolute numbers shift a few percent with thermal and scheduling state. Numbers published before 0.1.3 used per-iteration block_on (single-stream) and a join_all batch loop (multi-core) and are not comparable with this table. Reproduce with:

cargo build --release --package ex-nyring-host --package ex-nyring-plugin
NYRING_BENCH_OPERATION=all NYRING_BENCH_WORKERS=10 ./target/release/ex-nyring-host
# NYRING_BENCH_OPERATION: fire | fast | unary | stream | all
# Also: NYRING_BENCH_WORKERS, NYRING_BENCH_SECONDS, NYRING_BENCH_BATCH_SIZE,
#       NYRING_BENCH_PAYLOAD_BYTES, NYRING_BENCH_CPU_SAMPLES
cargo bench --package nylon-ring --bench abi_types   # ABI type microbenches

🏗 System overview

+------------------------------------------------------+
| Host (nylon-ring-host)                               |
|  NylonRingHost                                       |
|   ├─ LoadedPlugin + in-flight call gate              |
|   └─ HostContext                                     |
|       ├─ thread-local synchronous slot               |
|       ├─ sharded unary router + inline completion    |
|       └─ bounded stream queues                       |
+-------------------------+----------------------------+
                          | C ABI v1
                          | NrPluginVTable / NrHostVTable
+-------------------------+----------------------------+
| Plugin                                               |
|  define_plugin! → named handlers → send_result       |
+------------------------------------------------------+

The host validates and initializes a library, assigns each call a session ID, then routes plugin callbacks to the matching unary request or stream. Call guards keep the library loaded until active work finishes; graceful unload/reload stops new calls and waits for existing calls to drain.

🛡 Safety

• Host and plugin must use the same target and ABI version.
• NrStr and NrBytes are borrowed; copy them before retaining their data.
• Owned NrVec<T> values carry the producer's drop callback, avoiding cross-allocator frees.
• Plugins must stop worker threads and callbacks during shutdown.
• Only load trusted native libraries; this is not a security sandbox.

Development

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features

Publishing is handled by GitHub Actions in dependency order using the organization-level RUST_TOKEN secret.

License

MIT