registry-io 1.0.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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

//! # 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/1.0.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(any(feature = "sync", feature = "async"))]
mod panic;

#[cfg(feature = "async")]
mod future_ext;

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

#[cfg(feature = "async")]
#[path = "async_registry/mod.rs"]
pub mod r#async;

pub use handler_id::HandlerId;

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

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

#[cfg(feature = "async")]
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
pub use r#async::{AsyncHandlerGuard, AsyncRegistry};

/// Crate version string, populated by Cargo at build time.
///
/// # Examples
///
/// ```
/// // VERSION is the canonical place to read the running crate version,
/// // for diagnostic logging or version-gated behavior.
/// assert!(!registry_io::VERSION.is_empty());
/// assert!(registry_io::VERSION.starts_with("0.") || registry_io::VERSION.starts_with("1."));
/// ```
pub const VERSION: &str = env!("CARGO_PKG_VERSION");