iris_core/
lib.rs

1//! Iris Core - Foundation Kernel Layer
2//! Iris Core —— 底层内核底座
3//!
4//! Provides cross-platform window management, async scheduling, memory pools, file I/O, native network stack, and caching system.
5//! 提供跨端窗口管理、异步调度、内存池、文件 IO、原生网络栈、缓存系统等基础能力。
6//!
7//! This is the foundation of the entire Iris engine, with no dependencies on upper-layer crates.
8//! 是整个 Iris 引擎的根基，不依赖任何上层 crate。
9//!
10//! ## Features | 功能特性
11//!
12//! - Cross-platform window management via winit
13//! - 通过 winit 实现跨平台窗口管理
14//! - Async runtime based on Tokio multi-threaded executor
15//! - 基于 Tokio 多线程执行器的异步运行时
16//! - Application lifecycle management (initialize, update, exiting)
17//! - 应用生命周期管理（初始化、更新、退出）
18//! - Event loop integration for desktop applications
19//! - 桌面应用事件循环集成
20//!
21//! ## Architecture | 架构设计
22//!
23//! ```text
24//! Context (Tokio Runtime) ←→ Window Event Loop (winit)
25//!     ↓
26//! Application trait (lifecycle callbacks)
27//! ```
28//!
29//! The core layer provides the infrastructure for all upper layers (GPU, DOM, Layout, JS, SFC).
30//! 核心层为所有上层（GPU、DOM、Layout、JS、SFC）提供基础设施。
31
32#![allow(missing_docs)]
33
34pub mod io;
35pub mod memory_pool;
36pub mod net;
37pub mod runtime;
38pub mod window;
39
40use std::sync::Arc;
41
42use crate::memory_pool::BufferPool;
43
44/// Iris 核心上下文。
45///
46/// 聚合异步运行时与平台能力，供上层 crate 使用。
47pub struct Context {
48    /// Tokio 多线程运行时。
49    runtime: tokio::runtime::Runtime,
50    /// 全局缓冲区池（GPU 传输、IO 操作共享）。
51    buffer_pool: BufferPool,
52}
53
54impl Context {
55    /// 创建并启动 Iris 核心上下文。
56    pub fn new() -> Self {
57        let runtime = tokio::runtime::Builder::new_multi_thread()
58            .worker_threads(4)
59            .thread_name("iris-worker")
60            .enable_all()
61            .build()
62            .expect("Failed to create Tokio runtime");
63        Self {
64            runtime,
65            buffer_pool: BufferPool::default(),
66        }
67    }
68
69    /// 获取缓冲区池引用。
70    pub fn buffer_pool(&self) -> &BufferPool {
71        &self.buffer_pool
72    }
73
74    /// 获取 Tokio 运行时句柄，用于 spawn 异步任务。
75    pub fn handle(&self) -> &tokio::runtime::Handle {
76        self.runtime.handle()
77    }
78
79    /// 在运行时上 spawn 一个异步任务。
80    pub fn spawn<F>(&self, future: F) -> tokio::task::JoinHandle<F::Output>
81    where
82        F: std::future::Future + Send + 'static,
83        F::Output: Send + 'static,
84    {
85        self.runtime.spawn(future)
86    }
87
88    /// 阻塞当前线程执行异步任务，直到完成。
89    ///
90    /// 用于在主线程（winit 事件循环线程）中同步初始化异步资源（如 wgpu Device/Queue）。
91    pub fn block_on<F>(&self, future: F) -> F::Output
92    where
93        F: std::future::Future,
94    {
95        self.runtime.block_on(future)
96    }
97}
98
99impl Default for Context {
100    fn default() -> Self {
101        Self::new()
102    }
103}
104
105/// 应用程序生命周期 trait（桌面端）。
106///
107/// 上层 crate（如 iris-app）实现此 trait 来定义应用生命周期。
108#[cfg(not(target_arch = "wasm32"))]
109pub trait Application: Send + 'static {
110    /// 当事件循环启动、窗口即将创建时调用。
111    fn initialize(&mut self, ctx: &Context, event_loop: &winit::event_loop::ActiveEventLoop);
112
113    /// 窗口事件回调。
114    fn window_event(
115        &mut self,
116        ctx: &Context,
117        event_loop: &winit::event_loop::ActiveEventLoop,
118        window_id: winit::window::WindowId,
119        event: winit::event::WindowEvent,
120    );
121
122    /// 设备/系统事件回调（如屏幕 DPI 变化、时间戳等）。
123    #[allow(unused_variables)]
124    fn device_event(
125        &mut self,
126        ctx: &Context,
127        event_loop: &winit::event_loop::ActiveEventLoop,
128        device_id: winit::event::DeviceId,
129        event: winit::event::DeviceEvent,
130    ) {
131    }
132
133    /// 每帧更新回调（AboutToWait 事件）。
134    #[allow(unused_variables)]
135    fn update(&mut self, ctx: &Context, event_loop: &winit::event_loop::ActiveEventLoop) {}
136
137    /// 当应用即将退出时调用。
138    #[allow(unused_variables)]
139    fn exiting(&mut self, ctx: &Context) {}
140}
141
142/// 启动 Iris 桌面应用程序。
143///
144/// 阻塞当前线程，启动 winit 事件循环与 Tokio 运行时。
145#[cfg(not(target_arch = "wasm32"))]
146pub fn run_app<A: Application>(app: A) -> Result<(), Box<dyn std::error::Error>> {
147    use winit::application::ApplicationHandler;
148    use winit::event::{DeviceEvent, StartCause, WindowEvent};
149    use winit::event_loop::{ActiveEventLoop, ControlFlow, EventLoop};
150
151    struct WinitApp<A> {
152        ctx: Arc<Context>,
153        app: A,
154    }
155
156    impl<A: Application> ApplicationHandler for WinitApp<A> {
157        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
158            self.app.initialize(&self.ctx, event_loop);
159        }
160
161        fn window_event(
162            &mut self,
163            event_loop: &ActiveEventLoop,
164            window_id: winit::window::WindowId,
165            event: WindowEvent,
166        ) {
167            self.app
168                .window_event(&self.ctx, event_loop, window_id, event);
169        }
170
171        fn device_event(
172            &mut self,
173            event_loop: &ActiveEventLoop,
174            device_id: winit::event::DeviceId,
175            event: DeviceEvent,
176        ) {
177            self.app
178                .device_event(&self.ctx, event_loop, device_id, event);
179        }
180
181        fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
182            self.app.update(&self.ctx, event_loop);
183        }
184
185        fn new_events(&mut self, _event_loop: &ActiveEventLoop, _cause: StartCause) {}
186
187        fn suspended(&mut self, _event_loop: &ActiveEventLoop) {}
188
189        fn exiting(&mut self, _event_loop: &ActiveEventLoop) {
190            self.app.exiting(&self.ctx);
191        }
192    }
193
194    let ctx = Arc::new(Context::new());
195    let event_loop = EventLoop::new()?;
196    event_loop.set_control_flow(ControlFlow::Poll);
197
198    let mut winit_app = WinitApp { ctx, app };
199    event_loop.run_app(&mut winit_app)?;
200
201    Ok(())
202}
203
204/// 初始化 Iris 核心（兼容旧 API）。
205pub fn init() {
206    println!("iris-core initialized");
207}
iris_core/lib.rs

iris_core/
lib.rs
