mod-events 0.9.0

A high-performance, zero-overhead event dispatcher library for Rust
Documentation

Key Features

  • Zero-cost abstractions: No runtime overhead for event dispatch.
  • Type-safe: Compile-time guarantees, plus a typed ListenerError instead of Box<dyn Error>.
  • Thread-safe: Built for concurrent applications, with parking_lot locks that never poison.
  • Lock-free metrics: Per-event-type AtomicU64 counters; the dispatch path never takes a write lock.
  • Async support: Full async/await compatibility.
  • Flexible: Support for sync, async, and priority-based listeners (FIFO within equal priority).
  • Easy to use: Simple API and intuitive methods.
  • Performance: Optimized for high-throughput scenarios; subscribe is O(n), dispatch is read-lock-only.
  • Monitoring: Built-in metrics, middleware, and loom-verified concurrency invariants.

Quick Start

Add this to your Cargo.toml:

[dependencies]
mod-events = "0.9.0"

# For async support (default)
mod-events = { version = "0.9.0", features = ["async"] }

# Sync-only build
mod-events = { version = "0.9.0", default-features = false }

MSRV: Rust 1.81.

Basic Usage

use mod_events::prelude::*;

// Define your event
#[derive(Debug, Clone)]
struct UserRegistered {
    user_id: u64,
    email: String,
}

impl Event for UserRegistered {
    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
}

// Create dispatcher and subscribe
let dispatcher = EventDispatcher::new();
dispatcher.on(|event: &UserRegistered| {
    println!("Welcome {}!", event.email);
});

// Dispatch events
dispatcher.emit(UserRegistered {
    user_id: 123,
    email: "alice@example.com".to_string(),
});

Features

Priority System

use mod_events::{EventDispatcher, Priority};

let dispatcher = EventDispatcher::new();

// High priority listener executes first
dispatcher.subscribe_with_priority(|event: &MyEvent| {
    println!("High priority handler");
    Ok(())
}, Priority::High);

// Normal priority listener executes second
dispatcher.on(|event: &MyEvent| {
    println!("Normal priority handler");
});

Async Support

// Enable with the "async" feature
dispatcher.subscribe_async(|event: &MyEvent| async {
    // Async processing
    tokio::time::sleep(Duration::from_millis(100)).await;
    println!("Async handler completed");
    Ok(())
});

let result = dispatcher.dispatch_async(MyEvent { /* ... */ }).await;

Middleware

// Add middleware for logging, filtering, etc.
dispatcher.add_middleware(|event: &dyn Event| {
    println!("Processing: {}", event.event_name());
    true // Allow event to continue
});

Error Handling

Listeners return Result<(), ListenerError>. ListenerError wraps any Error + Send + Sync + 'static and converts from &str, String, or an existing Box<dyn Error + Send + Sync> via Into, so common patterns like Err("bad input".into()) keep working.

use mod_events::ListenerError;

dispatcher.subscribe(|event: &MyEvent| -> Result<(), ListenerError> {
    if event.message.is_empty() {
        return Err("message cannot be empty".into());
    }
    Ok(())
});

let result = dispatcher.dispatch(MyEvent { /* ... */ });

if result.all_succeeded() {
    println!("all handlers succeeded");
} else {
    for error in result.errors() {
        eprintln!("handler error: {}", error);
    }
}

Examples

Run the examples:

cargo run --example basic_usage
cargo run --features async --example async_usage

Benchmarks

cargo test --release benchmark

Documentation