🧅 Onion Virtual Machine

The runtime virtual machine for the Onion programming language. This package provides the execution environment, type system, and runtime services for Onion programs.

📚 Overview

The onion-vm package implements a register-based virtual machine designed specifically for functional programming with asynchronous execution capabilities. It features a sophisticated type system, garbage collection, and a generator-based execution model that enables seamless async/await functionality.

🏗️ Architecture

Bytecode → VM Instructions → Lambda Scheduler → Type System → Runtime Execution

Core Components

• Type System (types/) - Comprehensive type definitions and operations
• Lambda Runtime (lambda/) - Function execution and scheduling
• Scheduler (lambda/scheduler/) - Asynchronous task coordination
• Garbage Collection - Automatic memory management with reference counting

✨ Features

• 🚀 Asynchronous Execution - Generator-based coroutines with seamless async/await
• 🔒 Memory Safety - Automatic garbage collection and safe reference handling
• 🎯 Dynamic Type System - Flexible types with runtime type checking
• 📦 Modular Design - Clean separation between types, execution, and scheduling
• 🌊 Lazy Evaluation - Built-in support for lazy collections and streams
• 🔧 Extensible Runtime - Plugin architecture for custom types and operations

🎮 Type System

Core Types

• OnionObject - Base type for all Onion values
• OnionTuple - Immutable sequences and arrays
• OnionPair - Key-value pairs and associations
• OnionLambda - Functions and closures
• OnionLazySet - Lazy collections with streaming operations
• ...

Type Features

use onion_vm::types::object::OnionObject;
use onion_vm::types::tuple::OnionTuple;
use onion_vm::types::lambda::OnionLambda;

// Creating and manipulating types
let obj = OnionObject::new_integer(42);
let tuple = OnionTuple::from_vec(vec![obj]);
let lambda = OnionLambda::new(/* lambda definition */);

🔄 Execution Model

Lambda Scheduler

The VM uses a sophisticated scheduler that manages:

• Coroutines - Lightweight tasks with cooperative scheduling
• Generators - Pausable functions with yield points
• Async Operations - Non-blocking I/O and computation
• Resource Management - Automatic cleanup and lifecycle management

🏗️ Module Structure

onion-vm/
├── src/
│   ├── lib.rs              # Public API exports
│   ├── types/              # Type system implementation
│   │   ├── mod.rs
│   │   ├── object.rs       # Base object type
│   │   ├── tuple.rs        # Sequence types
│   │   ├── pair.rs         # Key-value pairs
│   │   ├── named.rs        # Named values
│   │   ├── lazy_set.rs     # Lazy collections
│   │   └── lambda/         # Function types
│   │       ├── mod.rs
│   │       ├── definition.rs
│   │       └── vm_instructions/
│   └── lambda/             # Execution runtime
│       ├── mod.rs
│       ├── runnable.rs     # Task execution interface
│       └── scheduler/      # Async scheduler
│           └── scheduler.rs
└── Cargo.toml

🎯 Design Principles

1. Safety First - Memory safety through garbage collection and type checking
2. Performance - Efficient execution with minimal overhead
3. Concurrency - Native async support without blocking
4. Simplicity - Clean abstractions that are easy to understand and extend

🔄 Execution Lifecycle

1. Loading - Bytecode is loaded and validated
2. Initialization - VM state and scheduler are set up
3. Execution - Instructions are executed by the scheduler
4. Yielding - Tasks can yield control for async operations
5. Completion - Results are collected and returned
6. Cleanup - Garbage collection reclaims unused memory

🤝 Integration

This package provides the runtime foundation for:

• onion-frontend - Executes compiled bytecode
• Standard Library - Implements built-in functions and types
• Language Extensions - Supports custom types and operations
• Debugging Tools - Provides introspection and profiling

📄 License

This package is part of the Onion programming language project and is licensed under the MIT License.