onion_vm/
lib.rs

1//! OnionVM 虚拟机核心库。
2//!
3//! 本 crate 提供 Onion 语言运行时的核心类型、虚拟机执行引擎、
4//! Lambda 表达式、垃圾回收、类型系统与高性能工具集。
5//!
6//! # 主要模块
7//! - `types`：Onion 运行时核心类型系统（对象、元组、lambda、集合等）
8//! - `lambda`：抽象可调度匿名函数对象及调度器实现
9//! - `utils`：高性能工具与辅助结构（如 FastMap）
10//!
11//! # 主要导出
12//! - `GC`：基于 arc_gc 的垃圾回收器
13//! - `GCTraceable`：GC 跟踪 trait
14//! - `GCArc`/`GCArcWeak`：GC 智能指针
15//!
16//! # 使用指南
17//!
18//! ## 基本VM执行流程
19//!
20//! OnionVM 执行字节码的标准流程如下：
21//!
22//! ```ignore
23//! // 1. 创建垃圾回收器，设置内存阈值
24//! let mut gc = GC::new_with_memory_threshold(1024 * 1024); // 1 MB threshold
25//!
26//! // 2. 验证VM指令包（假设已有vm_instructions_package）
27//! VMInstructionPackage::validate(&vm_instructions_package)?;
28//!
29//! // 3. 创建标准库和捕获变量
30//! let stdlib = stdlib::build_module();
31//! let mut capture = OnionFastMap::new(vm_instructions_package.create_key_pool());
32//! capture.push("stdlib", stdlib.weak().clone());
33//!
34//! // 4. 创建Lambda定义
35//! let lambda = OnionLambdaDefinition::new_static(
36//!     LambdaParameter::Multiple([].into()),
37//!     LambdaBody::Instruction(Arc::new(vm_instructions_package.clone())),
38//!     capture,
39//!     "__main__".into(),
40//!     LambdaType::Atomic,
41//! );
42//!
43//! // 5. 创建调度器和执行循环
44//! let args = OnionTuple::new_static(vec![]);
45//! let mut scheduler: Box<dyn Runnable> = Box::new(Scheduler::new(vec![
46//!     Box::new(OnionLambdaRunnableLauncher::new(lambda.weak(), args, Ok)?)
47//! ]));
48//!
49//! // 6. 主执行循环
50//! loop {
51//!     match scheduler.step(&mut gc) {
52//!         StepResult::Continue => continue,
53//!         StepResult::Return(result) => {
54//!             // 处理返回结果
55//!             break;
56//!         }
57//!         StepResult::Error(error) => {
58//!             // 处理运行时错误
59//!             return Err(error);
60//!         }
61//!         _ => {
62//!             // 处理其他情况
63//!         }
64//!     }
65//! }
66//! ```
67//!
68//! ## 核心组件说明
69//!
70//! ### 垃圾回收器 (GC)
71//! - 基于 arc_gc 实现的增量垃圾回收器
72//! - 可设置内存阈值触发自动回收
73//! - 在调试模式下建议每步执行后手动回收
74//!
75//! ### Lambda系统
76//! - `OnionLambdaDefinition`：Lambda函数定义
77//! - `OnionLambdaRunnableLauncher`：Lambda启动器
78//! - `Scheduler`：多任务调度器，管理可运行对象队列
79//!
80//! ### 执行状态
81//! - `StepResult::Continue`：继续执行下一步
82//! - `StepResult::Return(value)`：正常返回结果
83//! - `StepResult::Error(error)`：运行时错误
84//! - `StepResult::SpawnRunnable(runnable)`：生成新的异步任务
85//! - `StepResult::Pending`：等待状态，需要继续轮询
86//!
87//! ### 错误处理
88//! - 运行时错误会包含详细的上下文信息
89//! - 可通过 `scheduler.format_context()` 获取完整执行上下文
90//! - 程序逻辑错误通过返回值的success字段标识
91//!
92//! ## 类型系统
93//! - 所有对象都基于 `OnionObject` 枚举
94//! - 支持弱引用和强引用转换
95//! - 内置类型包括：字符串、数字、布尔值、元组、Lambda等
96//!
97//! ## 性能优化
98//! - 使用 `OnionFastMap` 替代标准 HashMap 获得更好性能
99//! - 字符串池 (`OnionKeyPool`) 减少内存分配
100//! - 增量垃圾回收避免长时间停顿
101
102pub mod types;
103pub mod lambda;
104pub use arc_gc::gc::GC as GC;
105pub use arc_gc::traceable::GCTraceable as GCTraceable;
106pub use arc_gc::arc::GCArc as GCArc;
107pub use arc_gc::arc::GCArcWeak as GCArcWeak;
108pub mod utils;
onion_vm/lib.rs

onion_vm/
lib.rs
