registry-io 0.4.0

High-performance event/callback registry for Rust. Sync-first with optional async. Lock-free reads, zero-allocation hot path, sub-50ns notify target. Designed as the foundation primitive for portfolio crates needing fast in-process notification.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

//! # registry-io
//!
//! High-performance event and callback registry primitive for Rust.
//!
//! `registry-io` provides a focused alternative to channel-based notification
//! when several components need to react to the same in-process event with
//! the lowest possible dispatch overhead. The hot path is **lock-free**,
//! **allocation-free**, and **panic-isolating**.
//!
//! # Design philosophy
//!
//! - **Sync-first.** The default registry runs handlers inline on the
//!   calling thread, with sub-microsecond dispatch overhead.
//! - **Lock-free reads.** Multiple threads can fire [`SyncRegistry::notify`]
//!   concurrently without serialization.
//! - **Zero allocation on the hot path.** `notify` walks an
//!   [`arc_swap::ArcSwap`] snapshot of `Arc<dyn Fn>` pointers and dispatches
//!   each one — no allocations along the no-panic path.
//! - **Panic isolation.** A panic in one handler is caught and does **not**
//!   stop sibling handlers or propagate to the caller.
//! - **Priority ordering.** Handlers may be registered with a priority value;
//!   higher priorities fire first, ties broken in registration order.
//! - **RAII unregistration.** [`HandlerGuard`] cleans up automatically.
//!
//! # Quick start
//!
//! ```
//! use std::sync::Arc;
//! use std::sync::atomic::{AtomicU32, Ordering};
//! use registry_io::SyncRegistry;
//!
//! let registry: SyncRegistry<u32> = SyncRegistry::new();
//! let counter = Arc::new(AtomicU32::new(0));
//!
//! let sink = Arc::clone(&counter);
//! let id = registry.register(move |value| {
//!     sink.fetch_add(*value, Ordering::Relaxed);
//! });
//!
//! registry.notify(&5);
//! registry.notify(&7);
//! assert_eq!(counter.load(Ordering::Relaxed), 12);
//!
//! assert!(registry.unregister(id));
//! ```
//!
//! # Feature flags
//!
//! - `std` (default) — enables the standard library. Required for sync and
//!   async registries.
//! - `sync` (default) — exposes [`SyncRegistry`]. Implies `std`.
//! - `async` — reserved for a future release; exposes `AsyncRegistry` for
//!   `async fn` handlers. Implies `std`.
//! - `hybrid` — activates both `sync` and `async`.
//!
//! # Out of scope
//!
//! `registry-io` is a local, in-process primitive. It is **not** a pub/sub
//! broker, **not** a message bus, and **not** a replacement for channels
//! when you need cross-process or cross-network delivery with backpressure.
//! See the project README for a list of when **not** to use it.
//!
//! # License
//!
//! Dual-licensed under Apache-2.0 OR MIT.

#![doc(html_root_url = "https://docs.rs/registry-io/0.4.0")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(not(feature = "std"), no_std)]
#![deny(missing_docs)]
#![deny(unsafe_op_in_unsafe_fn)]
#![deny(unused_must_use)]
#![deny(unused_results)]
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![deny(clippy::todo)]
#![deny(clippy::unimplemented)]
#![deny(clippy::print_stdout)]
#![deny(clippy::print_stderr)]
#![deny(clippy::dbg_macro)]
#![deny(clippy::undocumented_unsafe_blocks)]
#![deny(clippy::missing_safety_doc)]
#![warn(clippy::pedantic)]
#![allow(clippy::module_name_repetitions)]

extern crate alloc;

#[cfg(feature = "std")]
extern crate std;

mod handler_id;

#[cfg(feature = "sync")]
mod panic;

#[cfg(feature = "sync")]
pub mod sync;

pub use handler_id::HandlerId;

#[cfg(feature = "sync")]
#[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
pub use panic::PanicInfo;

#[cfg(feature = "sync")]
#[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
pub use sync::{HandlerGuard, SyncRegistry};

/// Crate version string, populated by Cargo at build time.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");