Skip to main content

Crate keyed_emitter

Crate keyed_emitter 

Source
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§

EventEmitterDeprecated
Registry of listeners keyed by event name.
ListenerIdDeprecated
Handle for one registered listener, returned by every registration method.