luminal/
lib.rs

1//! # Luminal
2//!
3//! Luminal is a high-performance async runtime designed to solve
4//! tokio's DLL boundary issues while maintaining similar performance and API compatibility.
5//!
6//! ## Key Features
7//!
8//! - **DLL Boundary Safe**: Unlike tokio, Luminal doesn't rely on thread-local storage, making it 100% safe to pass across DLL boundaries
9//! - **Explicit Handle Passing**: All runtime context is explicit rather than implicit via TLS
10//! - **Drop-in Replacement**: Provides tokio-compatible APIs like `spawn`, `block_on`, and `JoinHandle`
11//! - **Cross-Platform**: Works on Windows, Linux, and macOS
12//! - **Multi-threaded**: Uses a work-stealing scheduler with multiple worker threads for optimal CPU utilization
13//! - **Efficient Work Stealing**: Implements a sophisticated work-stealing algorithm to distribute tasks evenly across worker threads
14//! - **Memory Efficient**: Minimizes allocations and memory overhead in the task scheduling system
15//!
16//! ## Basic Usage
17//!
18//! ```rust
19//! use luminal::Runtime;
20//!
21//! async fn hello_world() {
22//!     println!("Hello, world!");
23//! }
24//!
25//! fn main() {
26//!     let rt = Runtime::new().unwrap();
27//!     let rt_clone = rt.clone();
28//!     rt.block_on(async move {
29//!         rt_clone.spawn(hello_world()).await;
30//!     });
31//! }
32//! ```
33//!
34//! ## Explicit Runtime Usage
35//!
36//! ```rust
37//! use luminal::Runtime;
38//!
39//! fn main() {
40//!     let rt = Runtime::new().unwrap();
41//!     rt.block_on(async {
42//!         println!("Running on Luminal runtime!");
43//!     });
44//! }
45//! ```
46//!
47//! ## DLL Boundary Safety
48//!
49//! Unlike tokio, which uses thread-local storage for its runtime context, Luminal uses explicit context passing.
50//! This makes it safe to use across DLL boundaries:
51//!
52//! ```rust
53//! // Inside a DLL
54//! fn dll_function(runtime: luminal::Runtime) -> u32 {
55//!     // Safe to use the runtime passed from outside
56//!     runtime.block_on(async { 42 })
57//! }
58//!
59//! // From the main application
60//! fn main() {
61//!     let rt = luminal::Runtime::new().unwrap();
62//!     let result = dll_function(rt.clone());
63//!     assert_eq!(result, 42);
64//! }
65//! ```
66
67// Re-export core components
68pub mod runtime;
69
70// Main runtime components
71pub use runtime::{
72    Runtime, Handle, JoinHandle, Executor,
73    spawn, block_on
74};
75
76// Error types for the Luminal runtime
77pub use error::RuntimeError;
78
79/// Error types for the Luminal runtime
80pub mod error {
81    use std::fmt;
82
83    /// Errors that can occur when using the Luminal runtime
84    #[derive(Debug)]
85    pub enum RuntimeError {
86        /// The task queue is full and cannot accept more tasks
87        TaskQueueFull,
88        
89        /// The runtime has not been properly initialized
90        RuntimeNotInitialized,
91        
92        /// A task has panicked during execution
93        ///
94        /// Contains the panic message if available
95        TaskPanic(String),
96    }
97
98    impl fmt::Display for RuntimeError {
99        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100            match self {
101                RuntimeError::TaskQueueFull => write!(f, "Task queue is full"),
102                RuntimeError::RuntimeNotInitialized => write!(f, "Runtime not initialized"),
103                RuntimeError::TaskPanic(msg) => write!(f, "Task panicked: {}", msg),
104            }
105        }
106    }
107
108    impl std::error::Error for RuntimeError {}
109}
luminal/lib.rs

luminal/
lib.rs
