Keyboard shortcuts

Press ← or β†’ to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RustF Event System Guide

🎯 Total.js-Inspired Event-Driven Architecture

This guide covers RustF’s comprehensive event system, designed to provide Total.js-style ON('ready', function()) patterns for application lifecycle management and extensible startup code execution.

Table of Contents

Overview

RustF’s event system enables developers to hook into application lifecycle events using a familiar, Total.js-inspired pattern. This system provides:

Key Features

βœ… Total.js-Style Syntax - Familiar ON('ready', handler) pattern
βœ… Lifecycle Events - Built-in events for all major application stages
βœ… Priority-Based Execution - Control handler execution order
βœ… Parallel Execution - Concurrent handler execution within priority groups for optimal performance
βœ… Built-in Handlers - Ready-to-use handlers for common tasks
βœ… Event Context - Rich context with app config, environment, and utilities
βœ… Auto-Discovery - Automatic event handler registration
βœ… Type Safety - Full compile-time type checking
βœ… Async Native - Built for async/await from the ground up
βœ… Performance Optimized - Fast-path execution, configurable timeouts, and error isolation

Event-Driven Benefits

  • Decoupled Code: Event handlers don’t need to know about each other
  • Extensible: Easy to add new functionality without modifying core code
  • Testable: Individual event handlers can be tested in isolation
  • Organized: Clean separation between initialization logic
  • Flexible: Conditional execution based on environment or configuration

Quick Start

Basic Event Registration

use rustf::prelude::*;

#[tokio::main]
async fn main() -> rustf::Result<()> {
    let app = RustF::new()
        // Register event handlers using familiar Total.js syntax
        .on("ready", |ctx| Box::pin(async move {
            println!("πŸš€ Application ready in {} mode!", ctx.env());
            Ok(())
        }))
        
        .on("startup", |ctx| Box::pin(async move {
            println!("⚑ Startup tasks executing...");
            // Database seeding, directory creation, etc.
            Ok(())
        }))
        
        .controllers(auto_controllers!());
    
    app.start().await
}

Using Built-in Handlers

#![allow(unused)]
fn main() {
use rustf::prelude::*;

let app = RustF::new()
    // Built-in handlers for common tasks
    .on("startup", builtin::directory_setup(&["uploads", "temp", "logs"]))
    .on("startup", builtin::cleanup_manager("temp/", Duration::from_secs(3600)))
    .on("config.loaded", builtin::configuration_validator)
    .on("ready", builtin::health_check)
    
    .controllers(auto_controllers!());
}

Application Lifecycle Events

RustF emits events automatically during application startup, providing hooks for every stage of initialization:

Core Lifecycle Events

EventWhen EmittedUse Case
config.loadedConfiguration loaded and validatedConfig validation, environment checks
database.readyDatabase connection establishedDatabase seeding, migration checks
modules.readyShared modules initializedModule-dependent initialization
middleware.readyMiddleware chain configuredMiddleware-dependent setup
routes.readyRoutes registeredRoute-dependent initialization
startupBefore server starts listeningFinal startup tasks
readyFramework fully initializedApplication ready notifications

Event Execution Order

1. config.loaded    ← Configuration loaded
2. database.ready   ← Database connected  
3. modules.ready    ← Shared modules initialized
4. middleware.ready ← Middleware configured
5. routes.ready     ← Routes registered
6. startup          ← Pre-server startup tasks
7. ready            ← Application fully ready
   ↓
   Server starts listening

Custom Events

Note: ctx.emit(...) from within an event handler is not currently wired. EventContext::emit (rustf/src/events.rs) only forwards to an emitter when one has been injected into the context, and the built-in event executors do not inject one. As a result, emitting custom events from inside a handler is a silent no-op today. The example below illustrates the intended API but will not trigger the chained custom.initialization handler until this is wired.

You can also emit custom events from within handlers:

#![allow(unused)]
fn main() {
.on("ready", |ctx| Box::pin(async move {
    println!("Application ready!");
    
    // Emit a custom event
    ctx.emit("custom.initialization", Some(json!({
        "timestamp": chrono::Utc::now().to_rfc3339(),
        "environment": ctx.env()
    }))).await?;
    
    Ok(())
}))

.on("custom.initialization", |ctx| Box::pin(async move {
    if let Some(data) = &ctx.data {
        println!("Custom event data: {}", data);
    }
    Ok(())
}))
}

Event Registration

Registration Methods

.on(event, handler) - Basic Registration

#![allow(unused)]
fn main() {
app.on("ready", |ctx| Box::pin(async move {
    println!("Application ready!");
    Ok(())
}))
}

.on_priority(event, priority, handler) - Priority-Based

#![allow(unused)]
fn main() {
app.on_priority("startup", -100, |ctx| Box::pin(async move {
    println!("High priority task (runs first)");
    Ok(())
}))

.on_priority("startup", 100, |ctx| Box::pin(async move {
    println!("Low priority task (runs last)");
    Ok(())
}))
}

.events_from(register_fn) - Bulk Registration

#![allow(unused)]
fn main() {
app.events_from(|emitter| {
    emitter.on("ready", startup_logger);
    emitter.on("database.ready", database_seeder);
    emitter.once("ready", one_time_setup);
})
}

.once(event, handler) - One-Time Handlers

#![allow(unused)]
fn main() {
// This handler will only execute once, even if the event is emitted multiple times
emitter.once("ready", |ctx| Box::pin(async move {
    println!("This runs only once!");
    Ok(())
}))
}

Parallel Execution

RustF’s event system features high-performance parallel execution of handlers within the same priority group, while maintaining strict priority ordering between groups.

How Parallel Execution Works

#![allow(unused)]
fn main() {
// Multiple handlers at the same priority execute in parallel
app.on("ready", |_ctx| Box::pin(async move {
    println!("Handler 1 starting...");
    tokio::time::sleep(Duration::from_millis(100)).await; // Simulated work
    println!("Handler 1 done");
    Ok(())
}))

.on("ready", |_ctx| Box::pin(async move {
    println!("Handler 2 starting...");
    tokio::time::sleep(Duration::from_millis(100)).await; // Simulated work  
    println!("Handler 2 done");
    Ok(())
}))

.on("ready", |_ctx| Box::pin(async move {
    println!("Handler 3 starting...");
    tokio::time::sleep(Duration::from_millis(100)).await; // Simulated work
    println!("Handler 3 done");
    Ok(())
}));

// All 3 handlers execute concurrently!
// Total execution time: ~100ms (instead of ~300ms sequential)
}

Priority Groups and Parallel Execution

#![allow(unused)]
fn main() {
app
    // Priority -100: Infrastructure handlers (execute first, in parallel)
    .on_priority("startup", -100, database_init_handler)    // Runs in parallel
    .on_priority("startup", -100, cache_init_handler)       // with this one
    .on_priority("startup", -100, logging_init_handler)     // and this one
    
    // Wait for all priority -100 handlers to complete...
    
    // Priority 0: Application handlers (execute second, in parallel)  
    .on("startup", user_service_init)     // Runs in parallel
    .on("startup", email_service_init)    // with this one
    .on("startup", file_service_init)     // and this one
    
    // Wait for all priority 0 handlers to complete...
    
    // Priority 100: Cleanup handlers (execute last, in parallel)
    .on_priority("startup", 100, temp_cleanup)         // Runs in parallel
    .on_priority("startup", 100, session_cleanup)      // with this one
}

Performance Benefits

Example Performance Improvement:

  • 4 handlers, each taking 100ms
  • Sequential execution: 400ms total
  • Parallel execution: 100ms total (4x faster!)

Performance Configuration

Configure event system performance settings for optimal behavior:

Basic Configuration

#![allow(unused)]
fn main() {
use rustf::events::EventEmitterConfig;
use std::time::Duration;

let app = RustF::new()
    .event_config(EventEmitterConfig::parallel() // Enable parallel execution
        .with_timeout(Duration::from_secs(30))    // Handler timeout protection
        .with_debug_logging(false)                // Disable debug logging for performance
        .with_max_concurrent(8))                  // Limit concurrent handlers
}

Configuration Presets

#![allow(unused)]
fn main() {
// High-performance configuration (production)
let config = EventEmitterConfig::parallel()
    .with_timeout(Duration::from_secs(60))
    .with_debug_logging(false);

// Debug-friendly configuration (development)
let config = EventEmitterConfig::sequential()
    .with_timeout(Duration::from_secs(10))
    .with_debug_logging(true);

let app = RustF::new().event_config(config);
}

Configuration Options

OptionDescriptionDefaultRecommendation
parallel_executionEnable parallel handler executiontruetrue for production, false for debugging
handler_timeoutMaximum handler execution time30 seconds30-60s for production, 10s for development
debug_loggingEnable detailed execution loggingcfg!(debug_assertions)false for production (performance)
max_concurrent_handlersLimit concurrent handlers per priority0 (unlimited)4-12 based on workload

Built-in Event Handlers

RustF provides ready-to-use event handlers for common startup tasks:

Database Seeder

Scans a directory for .sql seed files:

#![allow(unused)]
fn main() {
.on("database.ready", builtin::database_seeder("seeds/"))
}

Note: This handler is currently a stub/placeholder. It discovers and sorts .sql files but does not execute them against the database β€” for each file it only logs "Would execute SQL from: ..." (see rustf/src/events/builtin.rs). Direct SQL execution is pending. Until then, seed your database by other means.

Behavior:

  • Discovers .sql files and sorts them alphabetically (intended execution order)
  • Only runs in development by default
  • Logs the intended action per file rather than executing it

Directory Setup

Ensures required directories exist with proper permissions:

#![allow(unused)]
fn main() {
.on("startup", builtin::directory_setup(&[
    "uploads", "temp", "logs", "cache", "sessions"
]))
}

Features:

  • Creates missing directories
  • Sets appropriate permissions (755 on Unix)
  • Logs creation status
  • Safe for repeated execution

Cleanup Manager

Removes old temporary files and performs cleanup:

#![allow(unused)]
fn main() {
.on("startup", builtin::cleanup_manager("temp/", Duration::from_secs(86400)))
}

Features:

  • Removes files older than specified duration
  • Handles both files and directories
  • Logs cleanup statistics
  • Safe error handling

Configuration Validator

Validates critical configuration settings:

#![allow(unused)]
fn main() {
.on("config.loaded", builtin::configuration_validator)
}

Features:

  • Validates production-specific settings
  • Checks for default/insecure values
  • Environment-specific validation rules
  • Fails fast on critical issues

Health Check

Performs basic application health checks:

#![allow(unused)]
fn main() {
.on("ready", builtin::health_check)
}

Features:

  • Database connectivity check
  • System resource validation
  • Environment-specific checks
  • Detailed health reporting

Environment Check

Validates the application is running in the expected environment:

#![allow(unused)]
fn main() {
.on("startup", builtin::environment_check("production"))
}

Features:

  • Environment validation
  • Fails in production if mismatch detected
  • Configurable expected environment
  • Detailed error reporting

Custom Event Handlers

Creating Custom Handlers

#![allow(unused)]
fn main() {
// Simple handler function
async fn database_migration_check(ctx: EventContext) -> rustf::Result<()> {
    if ctx.is_production() {
        println!("Checking database migrations in production...");
        // Check migration status
        run_migration_check().await?;
    }
    Ok(())
}

// Register the handler
app.on("database.ready", |ctx| Box::pin(database_migration_check(ctx)))
}

Handler Functions vs Closures

#![allow(unused)]
fn main() {
// Function-based handler (reusable)
async fn reusable_handler(ctx: EventContext) -> rustf::Result<()> {
    println!("Handler executed for: {}", ctx.event);
    Ok(())
}

app.on("ready", |ctx| Box::pin(reusable_handler(ctx)))

// Closure-based handler (inline)
app.on("startup", |ctx| Box::pin(async move {
    println!("Inline handler for {}", ctx.event);
    // Access closure variables
    let config = &ctx.config;
    Ok(())
}))
}

Conditional Handlers

#![allow(unused)]
fn main() {
app.on("ready", |ctx| Box::pin(async move {
    match ctx.env() {
        "development" => {
            println!("Development setup");
            setup_dev_data().await?;
        }
        "production" => {
            println!("Production validation");
            validate_production_config(&ctx.config)?;
        }
        _ => {
            println!("Default environment setup");
        }
    }
    Ok(())
}))
}

Event Context

The EventContext provides rich information and utilities for event handlers:

Context Properties

#![allow(unused)]
fn main() {
async fn handler_example(ctx: EventContext) -> rustf::Result<()> {
    // Event information
    println!("Event: {}", ctx.event);
    println!("Environment: {}", ctx.env());
    
    // Environment checks
    if ctx.is_development() {
        println!("Running in development mode");
    }
    
    if ctx.is_production() {
        println!("Running in production mode");
    }
    
    // Configuration access
    let server_port = ctx.config.server.port;
    let database_url = &ctx.config.database.url;
    
    // Event data (if provided)
    if let Some(data) = &ctx.data {
        println!("Event data: {}", data);
    }
    
    // Emit other events
    // NOTE: ctx.emit is currently a no-op unless an emitter is injected into
    // the context, which the built-in executors do not do. Emitting events
    // from inside a handler does not trigger other handlers today.
    ctx.emit("custom.event", Some(json!({"from": ctx.event}))).await?;
    
    Ok(())
}
}

Available Context Methods

MethodDescriptionExample
ctx.eventCurrent event name"ready"
ctx.env()Current environment"development"
ctx.is_development()Development checktrue
ctx.is_production()Production checkfalse
ctx.configApplication configctx.config.server.port
ctx.dataEvent datajson!({"key": "value"})
ctx.emit(event, data)Emit another event (currently a no-op unless an emitter is injected β€” see note in Custom Events)Custom event emission

Priority System

Control the execution order of event handlers using priorities:

Priority Values

  • -200 to -100: Infrastructure (database, core systems)
  • -99 to -50: Security and authentication
  • -49 to -1: Business logic prerequisites
  • 0: Default priority (recommended for most handlers)
  • 1 to 99: Business logic
  • 100+: Post-processing and cleanup

Priority Examples

#![allow(unused)]
fn main() {
app
    // Critical infrastructure (runs first)
    .on_priority("startup", -100, builtin::directory_setup(&["logs"]))
    
    // Security setup
    .on_priority("startup", -50, security_initialization)
    
    // Default priority (most handlers)
    .on("startup", application_setup)
    
    // Cleanup tasks (runs last)
    .on_priority("startup", 100, final_cleanup)
}

Execution Flow

Priority -100: Infrastructure setup
Priority -50:  Security initialization  
Priority 0:    Application setup (default)
Priority 100:  Final cleanup

Auto-Discovery

RustF can automatically discover and register event handlers from your codebase:

File Structure

src/
  events/           ← Event handler modules
    database.rs     ← Database-related events
    filesystem.rs   ← File system events
    security.rs     ← Security events
    custom.rs       ← Custom application events

Event Handler Module

#![allow(unused)]
fn main() {
// src/events/database.rs
use rustf::events::{EventEmitter, EventContext};

pub fn install(emitter: &mut EventEmitter) {
    emitter.on("database.ready", seed_development_data);
    emitter.on("ready", database_health_check);
}

async fn seed_development_data(ctx: EventContext) -> rustf::Result<()> {
    if ctx.is_development() {
        println!("Seeding development data...");
        // Database seeding logic
    }
    Ok(())
}

async fn database_health_check(ctx: EventContext) -> rustf::Result<()> {
    println!("Running database health check...");
    // Health check logic
    Ok(())
}
}

Auto-Discovery Registration

#![allow(unused)]
fn main() {
// main.rs
use rustf::prelude::*;

let app = RustF::new()
    .events_from(auto_events!())  // Auto-discovers src/events/*.rs
    .controllers(auto_controllers!());
}

Note: Auto-discovery requires the auto-discovery feature to be enabled.

Common Patterns

Database Initialization Pattern

#![allow(unused)]
fn main() {
app.on("database.ready", |ctx| Box::pin(async move {
    if ctx.is_development() {
        // Seed development data
        println!("Seeding development database...");
        seed_database().await?;
    } else if ctx.is_production() {
        // Validate production database
        println!("Validating production database...");
        validate_database_schema().await?;
    }
    Ok(())
}))
}

Multi-Environment Setup

#![allow(unused)]
fn main() {
app.on("ready", |ctx| Box::pin(async move {
    match ctx.env() {
        "development" => {
            setup_debug_tools().await?;
            enable_hot_reload().await?;
        }
        "staging" => {
            setup_staging_environment().await?;
            enable_performance_monitoring().await?;
        }
        "production" => {
            validate_security_settings(&ctx.config)?;
            enable_production_monitoring().await?;
        }
        env => {
            log::warn!("Unknown environment: {}", env);
        }
    }
    Ok(())
}))
}

Dependency Chain Pattern

Note: This pattern depends on ctx.emit(...) triggering the next handler in the chain. As described in Custom Events, in-handler ctx.emit is currently a no-op (no emitter is injected by the executors), so the services.ready / dependencies.ready handlers below will not fire from these emits today. Treat this as the intended design, not current behavior. For now, sequence work using priorities within a single event.

#![allow(unused)]
fn main() {
app
    // Step 1: Initialize core services
    .on_priority("startup", -100, |ctx| Box::pin(async move {
        initialize_core_services().await?;
        ctx.emit("services.ready", None).await?;
        Ok(())
    }))
    
    // Step 2: Setup dependent services
    .on("services.ready", |ctx| Box::pin(async move {
        setup_dependent_services().await?;
        ctx.emit("dependencies.ready", None).await?;
        Ok(())
    }))
    
    // Step 3: Final application setup
    .on("dependencies.ready", |ctx| Box::pin(async move {
        finalize_application_setup().await?;
        Ok(())
    }))
}

Error Recovery Pattern

Note: The ctx.emit("database.connected", ...) / ctx.emit("database.fallback", ...) calls below are currently no-ops (see Custom Events), so they will not notify other handlers today. The error-handling logic itself (returning Err in production, running a fallback in development) works as written.

#![allow(unused)]
fn main() {
app.on("database.ready", |ctx| Box::pin(async move {
    match connect_to_database().await {
        Ok(()) => {
            println!("βœ… Database connected");
            ctx.emit("database.connected", None).await?;
        }
        Err(e) => {
            log::error!("❌ Database connection failed: {}", e);
            
            if ctx.is_production() {
                // Fail fast in production
                return Err(e);
            } else {
                // Try fallback in development
                setup_fallback_database().await?;
                ctx.emit("database.fallback", None).await?;
            }
        }
    }
    Ok(())
}))
}

Best Practices

1. Use Descriptive Event Names

#![allow(unused)]
fn main() {
// Good: Clear and descriptive
.on("database.schema.validated", handler)
.on("security.certificates.loaded", handler)
.on("cache.warmed", handler)

// Avoid: Generic or unclear
.on("done", handler)
.on("init", handler)
.on("setup", handler)
}

2. Leverage Priority System

#![allow(unused)]
fn main() {
// Good: Logical priority ordering
.on_priority("startup", -100, create_directories)    // Infrastructure
.on_priority("startup", -50, load_certificates)      // Security
.on_priority("startup", 0, initialize_services)      // Business logic
.on_priority("startup", 100, warm_caches)           // Optimization
}

3. Handle Errors Gracefully

#![allow(unused)]
fn main() {
.on("ready", |ctx| Box::pin(async move {
    match risky_operation().await {
        Ok(()) => {
            log::info!("βœ… Operation completed successfully");
        }
        Err(e) => {
            log::error!("❌ Operation failed: {}", e);
            
            // Don't fail the entire application for non-critical errors
            if is_critical_error(&e) {
                return Err(e);
            }
            
            // Try fallback or continue
            attempt_fallback().await.ok();
        }
    }
    Ok(())
}))
}

4. Use Environment-Specific Logic

#![allow(unused)]
fn main() {
.on("ready", |ctx| Box::pin(async move {
    if ctx.is_development() {
        setup_development_tools().await?;
        seed_test_data().await?;
    }
    
    if ctx.is_production() {
        validate_production_config(&ctx.config)?;
        setup_monitoring().await?;
    }
    
    Ok(())
}))
}

5. Emit Custom Events for Extension Points

#![allow(unused)]
fn main() {
.on("ready", |ctx| Box::pin(async move {
    initialize_core_application().await?;
    
    // Emit custom event for plugins/extensions
    ctx.emit("application.plugins.load", None).await?;
    
    finalize_initialization().await?;
    Ok(())
}))

// Extensions can hook into the custom event
.on("application.plugins.load", |ctx| Box::pin(async move {
    load_custom_plugins().await?;
    Ok(())
}))
}

6. Document Event Contracts

#![allow(unused)]
fn main() {
/// Emitted when the user authentication system is fully initialized
/// 
/// Context Data: None
/// Prerequisites: database.ready, security.certificates.loaded
/// Guarantees: User authentication is available for requests
.on("auth.system.ready", auth_system_handler)
}

Troubleshooting

Common Issues

1. Handlers Not Executing

Problem: Event handlers don’t seem to run.

Solutions:

  • Verify event names match exactly (case-sensitive)
  • Check that events are being emitted by the framework
  • Ensure handler registration happens before app.start()
#![allow(unused)]
fn main() {
// ❌ Incorrect event name
.on("readdy", handler)  // Typo

// βœ… Correct event name  
.on("ready", handler)
}

2. Handler Execution Order Issues

Problem: Handlers run in unexpected order.

Solutions:

  • Use priority system to control execution order
  • Check priority values (lower = earlier execution)
  • Avoid depending on registration order
#![allow(unused)]
fn main() {
// ❌ Relying on registration order
.on("startup", handler_a)  // Might run second
.on("startup", handler_b)  // Might run first

// βœ… Using explicit priorities
.on_priority("startup", 10, handler_a)  // Runs first
.on_priority("startup", 20, handler_b)  // Runs second
}

3. Async Handler Issues

Problem: Async operations not completing or compiler errors.

Solutions:

  • Always wrap handlers with Box::pin(async move { ... })
  • Ensure all async operations are awaited
  • Return rustf::Result<()> from handlers
#![allow(unused)]
fn main() {
// ❌ Missing Box::pin
.on("ready", |ctx| async move {  // Compiler error
    Ok(())
})

// βœ… Proper async handler
.on("ready", |ctx| Box::pin(async move {
    some_async_operation().await?;
    Ok(())
}))
}

4. Context Data Not Available

Problem: ctx.data is always None.

Solutions:

  • Check that events are emitted with data
  • Verify JSON serialization of event data
  • Use built-in events with expected data structure
#![allow(unused)]
fn main() {
// Emitting event with data
// NOTE: ctx.emit is currently a no-op (see Custom Events) β€” the receiving
// handler below will not fire from this emit yet.
ctx.emit("custom.event", Some(json!({
    "message": "Hello",
    "timestamp": chrono::Utc::now()
}))).await?;

// Receiving event data
.on("custom.event", |ctx| Box::pin(async move {
    if let Some(data) = &ctx.data {
        println!("Received: {}", data);
    }
    Ok(())
}))
}

5. Environment Detection Issues

Problem: Environment methods return unexpected values.

Solutions:

  • Set environment variables properly
  • Check supported environment variable names
  • Use explicit environment checks
# The environment comes from the application's configuration:
# RUSTF_ENV, or [app] environment in config.toml
export RUSTF_ENV=production
#![allow(unused)]
fn main() {
// Debug environment detection
.on("ready", |ctx| Box::pin(async move {
    println!("Environment: {}", ctx.env());
    println!("Is development: {}", ctx.is_development());
    println!("Is production: {}", ctx.is_production());
    Ok(())
}))
}

Debugging Events

Enable debug logging to see event execution:

#![allow(unused)]
fn main() {
// In main.rs
env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("debug")).init();

// Events will log execution details:
// [DEBUG] Registered event handler for 'ready' with priority 0 (id: 1)
// [INFO]  Emitting event: 'ready'
// [DEBUG] Executing handler 1 for 'ready' (priority: 0)
// [INFO]  Event 'ready' executed 1 handler(s)
}

Performance Considerations

Parallel vs Sequential Execution

RustF automatically optimizes event handler execution for maximum performance:

Parallel Execution (Default):

  • Handlers within the same priority group execute concurrently
  • Significantly faster for I/O bound tasks (database calls, file operations)
  • Optimal for production environments
  • Example: 4 handlers Γ— 100ms each = 100ms total (4x speedup)

Sequential Execution (Debug Mode):

  • Handlers execute one after another
  • Easier to debug and trace execution
  • Recommended for development and testing
  • Example: 4 handlers Γ— 100ms each = 400ms total

Performance Optimization Tips

1. Enable Parallel Execution in Production

#![allow(unused)]
fn main() {
let app = RustF::new()
    .event_config(EventEmitterConfig::parallel()
        .with_debug_logging(false));  // Disable debug logging for performance
}

2. Use Priority Groups Strategically

#![allow(unused)]
fn main() {
// βœ… Good: Group related handlers by priority
.on_priority("startup", -100, database_init)     // Infrastructure first
.on_priority("startup", -100, cache_init)        // (parallel with above)
.on_priority("startup", 0, service_init)         // Services second
.on_priority("startup", 0, api_init)             // (parallel with above)

// ❌ Avoid: Mixed priorities force sequential execution
.on_priority("startup", -100, database_init)
.on_priority("startup", 0, service_init)         // Must wait for database_init
.on_priority("startup", -99, cache_init)         // Must wait for service_init
}

3. Configure Timeouts Appropriately

#![allow(unused)]
fn main() {
// Production: Longer timeouts for complex operations
.event_config(EventEmitterConfig::parallel()
    .with_timeout(Duration::from_secs(60)))

// Development: Shorter timeouts to catch hung handlers
.event_config(EventEmitterConfig::sequential()
    .with_timeout(Duration::from_secs(10)))
}

4. Optimize Handler Design

#![allow(unused)]
fn main() {
// βœ… Good: Fast, focused handlers
.on("ready", |ctx| Box::pin(async move {
    log::info!("Application ready in {} mode", ctx.env());
    Ok(())
}))

// βœ… Good: Async I/O operations benefit from parallel execution
.on("startup", |_ctx| Box::pin(async move {
    database::migrate().await?;  // Can run in parallel with other I/O
    Ok(())
}))

// ❌ Avoid: CPU-intensive work that doesn't benefit from parallelism
.on("startup", |_ctx| Box::pin(async move {
    // Heavy CPU work - consider moving to background task
    expensive_computation();
    Ok(())
}))
}

Performance Monitoring

Runtime Performance Metrics

Enable debug logging to monitor handler performance:

#![allow(unused)]
fn main() {
let app = RustF::new()
    .event_config(EventEmitterConfig::parallel()
        .with_debug_logging(true));  // Enable in development

// Console output:
// [INFO]  Emitting event: 'startup' (parallel: true)
// [DEBUG] Executing 3 handler(s) for 'startup' at priority -100 (parallel: true)
// [DEBUG] Handler 1 completed in 145ms
// [DEBUG] Handler 2 completed in 203ms 
// [DEBUG] Event 'startup' executed 3 handler(s) with 0 error(s)
}

Production Monitoring

#![allow(unused)]
fn main() {
.on("ready", |ctx| Box::pin(async move {
    let start = std::time::Instant::now();
    
    // Your handler logic here
    initialize_services().await?;
    
    let duration = start.elapsed();
    if duration > Duration::from_millis(1000) {
        log::warn!("Slow handler execution: {}ms", duration.as_millis());
    }
    
    Ok(())
}))
}

Performance Best Practices

  1. Keep Handlers Fast: Event handlers block application startup
  2. Use Parallel Execution: Default configuration optimizes for production
  3. Group by Priority: Related handlers at same priority execute concurrently
  4. Set Appropriate Timeouts: Prevent runaway handlers from hanging startup
  5. Monitor in Production: Track handler execution times
  6. Defer Heavy Work: Move non-essential tasks to background jobs
  7. Disable Debug Logging: Reduces overhead in production

Performance Anti-Patterns

#![allow(unused)]
fn main() {
// ❌ Bad: Synchronous blocking operations
.on("startup", |_ctx| Box::pin(async move {
    std::thread::sleep(Duration::from_secs(5));  // Blocks executor!
    Ok(())
}))

// βœ… Good: Async operations
.on("startup", |_ctx| Box::pin(async move {
    tokio::time::sleep(Duration::from_secs(5)).await;  // Non-blocking
    Ok(())
}))

// ❌ Bad: Sequential chains that could be parallel
.on_priority("startup", 1, handler_a)
.on_priority("startup", 2, handler_b)  // Must wait for handler_a
.on_priority("startup", 3, handler_c)  // Must wait for handler_b

// βœ… Good: Parallel execution when possible
.on("startup", handler_a)  // All execute in parallel
.on("startup", handler_b)  
.on("startup", handler_c)
}

Summary

RustF’s event system provides a powerful, Total.js-inspired approach to application lifecycle management with advanced parallel execution capabilities:

βœ… Familiar Syntax - Total.js-style ON('ready', handler) patterns
βœ… Complete Lifecycle - Events for every stage of application startup
βœ… Parallel Execution - Concurrent handler execution with 4x+ performance improvements
βœ… Built-in Handlers - Ready-to-use handlers for common tasks
βœ… Priority Control - Fine-grained execution order management with parallel optimization
βœ… Performance Optimized - Fast-path execution, timeout protection, and error isolation
βœ… Type Safety - Full compile-time checking with excellent error messages
βœ… Auto-Discovery - Automatic handler registration from your codebase
βœ… Rich Context - Comprehensive context with config, environment, and utilities
βœ… Production Ready - Configurable performance settings and comprehensive monitoring