Expand description
String-keyed event emitter with typed payloads and synchronous dispatch.
An EventEmitter maps event names to listeners. Each listener is a closure
that takes &T for one payload type T. EventEmitter::emit borrows a
payload, invokes every listener on that event whose registered type equals
the payload type, and returns how many callbacks ran. Listeners registered
for a different type are skipped and keep their call budget.
Every callback runs on the caller’s thread before emit returns, in
registration order. The crate has no dependencies.
§Example
use keyed_emitter::EventEmitter;
use std::sync::{Arc, Mutex};
let seen = Arc::new(Mutex::new(Vec::new()));
let sink = Arc::clone(&seen);
let mut emitter = EventEmitter::new();
emitter.on::<u32, _>("tick", move |n| sink.lock().unwrap().push(*n));
assert_eq!(emitter.emit("tick", &7u32), 1);
assert_eq!(emitter.emit("tick", &"wrong type"), 0);
assert_eq!(*seen.lock().unwrap(), vec![7]);§Payload types
T needs 'static and nothing else. Payloads that are not Clone, not
Send, and not serializable all work, because the emitter hands the
listener a shared borrow and never copies or stores the value.
§Budgets
EventEmitter::once and EventEmitter::on_limited give a listener a
call budget. The budget is charged only when the callback runs, so a
mismatched emit leaves it untouched. A listener whose budget reaches zero is
removed within the emit call that exhausted it.
§Panics
No method of this crate panics on any input. Allocation failure, a panic
raised by a user callback, or a panic raised by a callback capture’s
destructor during listener pruning can cross emit. A callback panic
unwinds out of emit with the emitter left coherent. The budget is charged
before the callback runs, so a once listener that panicked does not fire
again. Exhausted entries are pruned before that panic is re-raised.
§Sharing across threads
EventEmitter is Send and not Sync. Registration and dispatch take
&mut self, so sharing means wrapping it in a Mutex. A
static OnceLock<Mutex<_>> gives a process-wide emitter:
use keyed_emitter::EventEmitter;
use std::sync::{Mutex, OnceLock};
static EVENTS: OnceLock<Mutex<EventEmitter>> = OnceLock::new();
fn events() -> &'static Mutex<EventEmitter> {
EVENTS.get_or_init(|| Mutex::new(EventEmitter::new()))
}
struct Signal {
code: u16,
}
events().lock().unwrap().on::<Signal, _>("signal", |s| {
assert_eq!(s.code, 200);
});
let fired = std::thread::spawn(|| {
events().lock().unwrap().emit("signal", &Signal { code: 200 })
})
.join()
.unwrap();
assert_eq!(fired, 1);Calling back into the same Mutex from inside a callback locks a mutex the
current thread already holds. That is a self-deadlock. Record what you need
in the callback and act on it after emit returns.
§Deprecated
This crate is deprecated as of 0.1.1. It will receive no new features.
Existing published versions remain on crates.io. For a few handlers, a
hand-rolled HashMap<K, Vec<Box<dyn Fn>>> is straightforward. For a
fuller API, search crates.io for established event-emitter crates.
Structs§
- Event
Emitter Deprecated - Registry of listeners keyed by event name.
- Listener
Id Deprecated - Handle for one registered listener, returned by every registration method.