registry-io 0.9.0

Highlights

• Cross-platform — Linux, macOS, Windows.
• Lock-free reads via ArcSwap snapshots. Many threads can notify concurrently with no coordination.
• Zero allocation on the no-panic sync notify path.
• Panic isolation — a panicking handler does not stop siblings nor propagate to the caller. Optional on_panic callback for observability. Works for both sync handlers and async futures.
• Priority ordering — register_with_priority(i32, ...). Higher fires first; ties broken in registration order.
• SyncRegistry<E> — generic over the event type. Handlers receive &E.
• AsyncRegistry<E> (feature: async) — same lock-free storage, futures-returning handlers, concurrent or sequential dispatch.
• RAII guards — register_guard returns a HandlerGuard / AsyncHandlerGuard that unregisters on drop.
• Send + Sync — share registries freely across threads.

Status

Active development — release-candidate gate. v0.9.0 is the final pre-1.0 documentation pass: a v1.0 stability contract (STABILITY-1.0.md), internal architecture walk-through (ARCHITECTURE.md), and per-platform behavior notes (PLATFORM-NOTES.md) all land in this release. The next release will be 1.0.0-rc.1.

v0.8.0 added the integration-pattern reference (PATTERNS.md) with four canonical patterns plus runnable examples for each.

v0.7.0 was the hardening milestone: property-based invariant tests via proptest, an Arc::strong_count leak canary over 10 000 register/unregister cycles, a cargo-fuzz target scaffold, and a published threat model. The public API contains zero unsafe code.

v0.6.0 shipped the performance verification: every target in the Performance Contract is met with significant headroom — sync notify at ~10 ns / 1 handler / 1 thread, ~25 ns / 4 handlers / 16 threads contended, and dhat-verified zero heap allocations on the hot path. Async concurrent dispatch is ~180 ns / 1 handler. See docs/PERFORMANCE.md for the full measurements.

v0.5.0 added AsyncRegistry with concurrent + sequential dispatch, AsyncHandlerGuard, and panic isolation across .await, behind the async feature. The synchronous side (v0.4.0) — SyncRegistry, priority ordering, RAII guards, panic isolation — remains the default. See .dev/ROADMAP.md for the path to 1.0.

Public API is not yet frozen — minor releases may break it. Pin specific versions; expect changes pre-1.0.

When to use it

Use registry-io when you have:

• Multiple components that need notification when something happens (config reload, file change, transaction commit, metric event, etc.).
• Fast, in-process handlers measured in microseconds or less.
• A need to register and unregister handlers dynamically.
• Performance-critical paths where channel allocation would dominate.

Do not use registry-io when you have:

• Cross-process or cross-network delivery needs — use NATS, Redis pub/sub, or similar message brokers.
• Heavy handler workloads requiring backpressure — use tokio::sync::broadcast or channels.
• Event sourcing or durability requirements — use a real event log.

Quick start

[dependencies]
registry-io = "0.9"

use std::sync::Arc;
use std::sync::atomic::{AtomicU32, Ordering};
use registry_io::SyncRegistry;

let registry: SyncRegistry<u32> = SyncRegistry::new();
let total = Arc::new(AtomicU32::new(0));

let sink = Arc::clone(&total);
let id = registry.register(move |value| {
    sink.fetch_add(*value, Ordering::Relaxed);
});

registry.notify(&5);
registry.notify(&7);
assert_eq!(total.load(Ordering::Relaxed), 12);

assert!(registry.unregister(id));

Priority ordering

use std::sync::{Arc, Mutex};
use registry_io::SyncRegistry;

let registry: SyncRegistry<()> = SyncRegistry::new();
let order = Arc::new(Mutex::new(Vec::<&'static str>::new()));

let o = Arc::clone(&order);
let _ = registry.register_with_priority(100, move |_| o.lock().unwrap().push("audit"));
let o = Arc::clone(&order);
let _ = registry.register(move |_| o.lock().unwrap().push("business"));
let o = Arc::clone(&order);
let _ = registry.register_with_priority(-50, move |_| o.lock().unwrap().push("cleanup"));

registry.notify(&());
assert_eq!(order.lock().unwrap().as_slice(), &["audit", "business", "cleanup"]);

RAII guards

use std::sync::Arc;
use registry_io::SyncRegistry;

let registry = Arc::new(SyncRegistry::<u32>::new());
{
    let _guard = registry.register_guard(|n| println!("scoped: {n}"));
    registry.notify(&1);
} // guard drops here -> handler is unregistered
assert!(registry.is_empty());

Panic isolation

use registry_io::SyncRegistry;

let registry: SyncRegistry<()> = SyncRegistry::new();
registry.on_panic(|info| {
    eprintln!(
        "handler {} panicked: {}",
        info.handler_id(),
        info.message().unwrap_or("<opaque>")
    );
});

let _ = registry.register(|_| panic!("oops"));
let _ = registry.register(|_| println!("still ran"));
registry.notify(&()); // returns cleanly; both effects observed

Async handlers (feature: async)

[dependencies]
registry-io = { version = "0.9", features = ["async"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

use std::sync::Arc;
use std::sync::atomic::{AtomicU32, Ordering};
use registry_io::r#async::AsyncRegistry;

#[tokio::main(flavor = "current_thread")]
async fn main() {
    let registry: AsyncRegistry<u32> = AsyncRegistry::new();
    let total = Arc::new(AtomicU32::new(0));

    for _ in 0..4 {
        let sink = Arc::clone(&total);
        let _ = registry.register(move |value| {
            let sink = Arc::clone(&sink);
            let v = *value;
            async move {
                tokio::task::yield_now().await;
                sink.fetch_add(v, Ordering::Relaxed);
            }
        });
    }

    // Concurrent dispatch — all 4 futures run in parallel.
    registry.notify(&10).await;
    assert_eq!(total.load(Ordering::Relaxed), 40);

    // Sequential dispatch — awaits each handler in priority order.
    registry.notify_sequential(&10).await;
    assert_eq!(total.load(Ordering::Relaxed), 80);
}

Same lock-free read path as SyncRegistry. Panics in handler futures are caught via an internal CatchUnwind adapter and surfaced through on_panic, just like sync handlers.

See examples/ for runnable programs and docs/API.md for the full reference.

Design philosophy

• Sync-first. The fast path is synchronous, runs on the calling thread, allocates nothing, and dispatches in nanoseconds.
• Lock-free reads. Multiple threads can call notify() concurrently without contention.
• Zero allocation on the hot path. Notify walks the handler list and dispatches without any heap allocation in the no-panic case.
• Focused scope. This is a local, in-process notification primitive. Not a message bus, not a distributed event system, not a pub/sub broker.

Documentation

• docs/API.md — full API reference with examples per item.
• docs/PATTERNS.md — four canonical integration patterns (hot reload, audit fan-out, metric events, transaction hooks), each with a runnable example.
• docs/ARCHITECTURE.md — internal structure walk-through, hot/slow path code excerpts, design decisions.
• docs/PERFORMANCE.md — cost model, benchmarks, and concurrency characteristics.
• docs/SECURITY.md — threat model, panic isolation detail, fuzz methodology.
• docs/STABILITY-1.0.md — the v1.0 stability contract (what's frozen, what can change).
• docs/PLATFORM-NOTES.md — per-platform behavior nuances (Linux/macOS/Windows).
• .dev/ROADMAP.md — milestone plan to 1.0.
• CHANGELOG.md — release history.

Standards

• REPS (Rust Efficiency & Performance Standards) governs every decision. See REPS.md.
• MSRV: Rust 1.85.
• Edition: 2024.
• Cross-platform: Linux, macOS, Windows.

License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.