Module engine 

Asynchronous Engine System with Type Erasure Support

This module provides the core asynchronous engine abstraction for Dynamo’s runtime system. It defines the AsyncEngine trait for streaming engines and provides sophisticated type-erasure capabilities for managing heterogeneous engine collections.

Type Erasure Overview

Type erasure is a critical feature that allows storing different AsyncEngine implementations with varying generic type parameters in a single collection (e.g., HashMap<String, Arc<dyn AnyAsyncEngine>>). This is essential for:

• Dynamic Engine Management: Registering and retrieving engines at runtime based on configuration
• Plugin Systems: Loading different engine implementations without compile-time knowledge
• Service Discovery: Managing multiple engine types in a unified registry

Implementation Details

The type-erasure system uses several advanced Rust features:

• Trait Objects (dyn Trait): For runtime polymorphism without compile-time type information
• std::any::TypeId: For runtime type checking during downcasting
• std::any::Any: For type-erased storage and safe downcasting
• PhantomData: For maintaining type relationships in generic wrappers
• Extension Traits: For ergonomic API design without modifying existing types

Safety Considerations

⚠️ IMPORTANT: The type-erasure system relies on precise type matching at runtime. When modifying these traits or their implementations:

• Never change the type ID logic in AnyAsyncEngine implementations
• Maintain the blanket Data implementation for all Send + Sync + 'static types
• Test downcasting thoroughly when adding new engine types
• Document any changes that affect the type-erasure behavior

Usage Example

use std::collections::HashMap;
use std::sync::Arc;
use crate::engine::{AsyncEngine, AsAnyAsyncEngine, DowncastAnyAsyncEngine};

// Create typed engines
let string_engine: Arc<dyn AsyncEngine<String, String, ()>> = Arc::new(MyStringEngine::new());
let int_engine: Arc<dyn AsyncEngine<i32, i32, ()>> = Arc::new(MyIntEngine::new());

// Store in heterogeneous collection
let mut engines: HashMap<String, Arc<dyn AnyAsyncEngine>> = HashMap::new();
engines.insert("string".to_string(), string_engine.into_any_engine());
engines.insert("int".to_string(), int_engine.into_any_engine());

// Retrieve and downcast safely
if let Some(typed_engine) = engines.get("string").unwrap().downcast::<String, String, ()>() {
    let result = typed_engine.generate("hello".to_string()).await;
}

Structs

ResponseStream

Adapter for a DataStream to a ResponseStream.

Traits

AnyAsyncEngine

A type-erased AsyncEngine.

AsAnyAsyncEngine

An extension trait that provides a convenient way to type-erase an AsyncEngine.

AsyncEngine

Engine is a trait that defines the interface for a streaming engine. The synchronous Engine version is does not need to be awaited.

AsyncEngineContext

The AsyncEngineContext trait defines the interface to control the resulting stream produced by the engine.

AsyncEngineContextProvider

Provides access to the AsyncEngineContext associated with an engine operation.

AsyncEngineController

AsyncEngineStream

A streaming asynchronous engine operation.

AsyncEngineUnary

A unary (single-response) asynchronous engine operation.

Data

All Send + Sync + 'static types can be used as AsyncEngine request and response types.

DowncastAnyAsyncEngine

An extension trait that provides a convenient method to downcast an AnyAsyncEngine.

Type Aliases

Context

DataStream

DataUnary

DataStream is a type alias for a stream of Data items. This can be adapted to a ResponseStream by associating it with a AsyncEngineContext.

Engine

EngineStream

EngineUnary

Attribute Macros

async_trait