Mod Events
^{RUST EVENTS LIBRARY}

     

A high-performance, zero-overhead event dispatcher library for Rust that implements the observer pattern with compile-time type safety and runtime efficiency.

This library enables decoupled, event-driven architectures by allowing components to communicate through strongly-typed events without direct dependencies. Built for performance, it uses zero-cost abstractions and efficient memory management to ensure event dispatch has minimal runtime overhead, making it suitable for high-throughput applications, real-time systems, and microservice architectures.

This event dispatcher supports both synchronous and asynchronous event handling with a priority-based execution system that allows fine-grained control over listener execution order.

Thread-safe by design, it handles concurrent access efficiently using read-write locks that allow multiple threads to dispatch events simultaneously without blocking.

This library includes a flexible middleware system for event filtering, transformation, and logging. It uses a comprehensive error handler that doesn't stop event propagation on individual listener failures, and it has built-in metrics for monitoring event dispatch performance and debugging.

Unlike string-based event systems common in other languages, this library leverages Rust's type system to prevent runtime errors and ensure listeners receive correctly typed events.

Key Features

• Zero-cost abstractions: No runtime overhead for event dispatch.
• Type-safe: Compile-time guarantees for event handling.
• Thread-safe: Built for concurrent applications.
• Async support: Full async/await compatibility.
• Flexible: Support for sync, async, and priority-based listeners.
• Easy to use: Simple API and intuitive methods.
• Performance: Optimized for high-throughput scenarios.
• Monitoring: Built-in metrics and middleware support.

Quick Start

Add this to your Cargo.toml:

[dependencies]
mod-events = "0.1"

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: "[email protected]".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

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

• Quick Start Guide
• API Reference
• Performance Guide
• Examples
• Best Practices
• Migration Guide

---

📌 License

Licensed under the Apache License, version 2.0 (the "License"); you may not use this software, including, but not limited to the source code, media files, ideas, techniques, or any other associated property or concept belonging to, associated with, or otherwise packaged with this software except in compliance with the License.

You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the LICENSE file included with this project for the specific language governing permissions and limitations under the License.

^{COPYRIGHT © 2025 JAMES GOBER.}