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//! - **No-std Support**: Can run in `no_std` environments with `alloc` for embedded and constrained systems
16//!
17//! ## Basic Usage
18//!
19//! ```rust
20//! use luminal::Runtime;
21//!
22//! async fn hello_world() {
23//!     println!("Hello, world!");
24//! }
25//!
26//! fn main() {
27//!     let rt = Runtime::new().unwrap();
28//!     let rt_clone = rt.clone();
29//!     rt.block_on(async move {
30//!         rt_clone.spawn(hello_world()).await;
31//!     });
32//! }
33//! ```
34//!
35//! ## Explicit Runtime Usage
36//!
37//! ```rust
38//! use luminal::Runtime;
39//!
40//! fn main() {
41//!     let rt = Runtime::new().unwrap();
42//!     rt.block_on(async {
43//!         println!("Running on Luminal runtime!");
44//!     });
45//! }
46//! ```
47//!
48//! ## DLL Boundary Safety
49//!
50//! Unlike tokio, which uses thread-local storage for its runtime context, Luminal uses explicit context passing.
51//! This makes it safe to use across DLL boundaries:
52//!
53//! ```rust
54//! // Inside a DLL
55//! fn dll_function(runtime: luminal::Runtime) -> u32 {
56//!     // Safe to use the runtime passed from outside
57//!     runtime.block_on(async { 42 })
58//! }
59//!
60//! // From the main application
61//! fn main() {
62//!     let rt = luminal::Runtime::new().unwrap();
63//!     let result = dll_function(rt.clone());
64//!     assert_eq!(result, 42);
65//! }
66//! ```
67#![cfg_attr(not(feature = "std"), no_std)]
68
69
70#[cfg(not(feature = "std"))]
71extern crate alloc;
72
73// Re-export core components
74pub mod runtime;
75
76// Main runtime components
77pub use runtime::{
78    Runtime, Handle, JoinHandle, Executor,
79};
80
81// Global convenience functions (std only)
82#[cfg(feature = "std")]
83pub use runtime::{spawn, block_on};
84
85// Error types for the Luminal runtime
86pub use error::RuntimeError;
87
88/// Error types for the Luminal runtime
89pub mod error {
90    #[cfg(feature = "std")]
91    use std::fmt;
92    #[cfg(not(feature = "std"))]
93    use core::fmt;
94
95    #[cfg(not(feature = "std"))]
96    use alloc::string::String;
97
98    /// Errors that can occur when using the Luminal runtime
99    #[derive(Debug)]
100    pub enum RuntimeError {
101        /// The task queue is full and cannot accept more tasks
102        TaskQueueFull,
103
104        /// The runtime has not been properly initialized
105        RuntimeNotInitialized,
106
107        /// A task has panicked during execution
108        ///
109        /// Contains the panic message if available
110        TaskPanic(String),
111    }
112
113    impl fmt::Display for RuntimeError {
114        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
115            match self {
116                RuntimeError::TaskQueueFull => write!(f, "Task queue is full"),
117                RuntimeError::RuntimeNotInitialized => write!(f, "Runtime not initialized"),
118                RuntimeError::TaskPanic(msg) => write!(f, "Task panicked: {}", msg),
119            }
120        }
121    }
122
123    #[cfg(feature = "std")]
124    impl std::error::Error for RuntimeError {}
125}
luminal/lib.rs

luminal/
lib.rs
