keyed-emitter 0.1.1

Deprecated: String-keyed event emitter with typed payloads and synchronous dispatch. Mismatched types are skipped. Exhausted listeners leave in the same emit.
Documentation
  • Coverage
  • 100%
    10 out of 10 items documented1 out of 10 items with examples
  • Size
  • Source code size: 46.6 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 141.6 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • hey-jj/keyed-emitter
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • hey-jj

Deprecated

This crate is deprecated as of 2026-10. It will receive no new features. Existing 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.


keyed-emitter

String-keyed event emitter with typed payloads and synchronous dispatch.

Register closures under an event name, each for one payload type. emit borrows a payload, runs every listener on that event whose type matches, and returns how many ran. Listeners for another type are skipped and keep their call budget. Dispatch happens on the caller's thread, and the crate has no dependencies.

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));
let id = emitter.once::<String, _>("tick", |s| println!("named tick: {s}"));

assert_eq!(emitter.emit("tick", &7u32), 1);
assert_eq!(emitter.emit("tick", &"x".to_string()), 1);
assert_eq!(emitter.emit("tick", &"y".to_string()), 0);
assert_eq!(*seen.lock().unwrap(), vec![7]);
assert!(!emitter.remove_listener(id));

Dispatch rules

  • Every callback runs on the caller's thread before emit returns, in registration order.
  • A listener runs only when its registered T equals the emitted T. A mismatched listener is skipped and keeps its budget. One event name can carry listeners for several types.
  • The return value is the number of callbacks invoked. An unknown event, an empty event, or an all-mismatched event returns 0.
  • T needs 'static and nothing else. Payloads that are not Clone, not Send, and not serializable work, because the listener gets &T.
  • once and on_limited(n) listeners are charged only when they run, and a listener whose budget hits zero is removed within that same emit. on_limited(_, 0, _) stores nothing.
  • remove_listener returns true once per live listener and false for an unknown, removed, or exhausted id. listener_count reports live listeners on an event across all types.
  • ListenerId is unique within one emitter for its lifetime. Two emitters can mint the same id.

Threads

EventEmitter is Send and not Sync. Registration and dispatch take &mut self. To share one across threads, wrap it in a Mutex. A static OnceLock<Mutex<_>> gives a process-wide emitter. See the crate docs for the full example.

Locking that Mutex again from inside a callback is a self-deadlock. Record what you need in the callback and act on it after emit returns.

Panics

No method 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 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. The test suite drives this case in debug and release.

Cost

A single emit over n listeners is O(n), including the prune of exhausted listeners. benches/emit_linearity.rs and the emit_linearity test measure interleaved once and on listeners at 20k, 40k, and 80k and fail when the time per doubling exceeds 3x. remove_listener is a linear scan over all events.

Toolchain

Rust 1.70 or newer. Zero dependencies. #![forbid(unsafe_code)]. CI runs the suite on stable, 1.70.0, and beta, and runs the no-panic suite under panic = "abort" on nightly.

License

MIT.