Architecture
import { Code } from ‘@astrojs/starlight/components’;
This document outlines the architecture of the Chuks programming language, covering the Compiler Pipeline, Runtime Environment, and Core Subsystems (Memory, Concurrency, OOP).
Architecture Overview
Section titled “Architecture Overview”┌─────────────────────────────────────────────────────┐│ User Space & Tooling ││ ┌──────────────┐ ┌───────────┐ ┌──────────────┐ ││ │ Source (.chuks)│ │ CLI Tool │ │ Language │ ││ │ │ │ │ │ Server (LSP) │ ││ └──────┬───────┘ └─────┬─────┘ └──────────────┘ │└─────────┼────────────────┼──────────────────────────┘ │ │ ▼ ▼┌─────────────────────────────────────────────────────┐│ Compiler Pipeline (AOT) ││ Lexer → Parser → Type Checker → IR Generator ││ │ ││ ┌──────┴──────┐ ││ │ Optimizer │ ││ └──────┬──────┘ ││ ┌───────────┼───────────┐ ││ ▼ ▼ ▼ ││ ┌──────────┐ ┌─────────┐ ┌──────┐││ │ Bytecode │ │ LLVM │ │ WASM │││ │ Emitter │ │ Backend │ │ │││ └────┬─────┘ └────┬────┘ └──┬───┘│└────────────────────────┼────────────┼─────────┼────┘ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌───────┐ │ .ckb │ │ Native │ │ .wasm │ │ bytecode│ │ binary │ │ │ └────┬────┘ └────┬────┘ └───────┘ │ │ ▼ ▼┌─────────────────────────────────────────────────────┐│ Runtime Environment ││ ││ ┌──────────────────────────────────────────────┐ ││ │ Execution Engine │ ││ │ ┌────────────────┐ ┌───────────────────┐ │ ││ │ │ Bytecode VM │ │ Native Execution │ │ ││ │ │ (Stack-based) │ │ │ │ ││ │ └────────────────┘ └───────────────────┘ │ ││ └──────────────────────────────────────────────┘ ││ ││ ┌──────────────────┐ ┌────────────────────────┐ ││ │ Memory Model │ │ Hybrid Concurrency │ ││ │ • Stack │ │ • Event Loop (I/O) │ ││ │ • Heap (GC/ARC) │ │ • Coroutine Scheduler │ ││ │ • Go-style Ptrs │ │ • OS Thread Pool │ ││ │ • VMT (O(1)) │ │ │ ││ └──────────────────┘ └────────────────────────┘ ││ ││ ┌──────────────────┐ ││ │ Interop │ ││ │ • C/Go/Rust FFI │ ││ └──────────────────┘ │└─────────────────────────────────────────────────────┘User Space & Tooling
Section titled “User Space & Tooling”- CLI / Build Tool — The entry point for developers. Handles compilation, formatting, and project management (
chuks run,chuks build,chuks new). - Language Server (LSP) — Provides IDE support (autocomplete, go-to definition, hover info) using the static analysis engine.
Compiler Pipeline (AOT)
Section titled “Compiler Pipeline (AOT)”A multi-stage pipeline designed for speed and safety.
Frontend
Section titled “Frontend”The Lexer tokenizes source code, the Parser produces an AST, and the Type Checker performs rigorous static analysis including generics resolution and type safety.
Middle-end
Section titled “Middle-end”The AST is converted to Chuks IR (Intermediate Representation). The Optimizer performs:
- Monomorphization of generics
- Function inlining
- Dead code elimination (DCE)
- Constant folding
Backend Targets
Section titled “Backend Targets”| Target | Description |
|---|---|
| Bytecode Emitter | Fast compilation for dev/debug cycles. Outputs .ckb files. |
| LLVM Backend | Produces highly optimized native binaries for production. |
| WASM | WebAssembly output for browser and edge deployment. |
Runtime Environment
Section titled “Runtime Environment”Designed for predictability and high concurrency.
Memory Model
Section titled “Memory Model”| Component | Description |
|---|---|
| Stack | Fast storage for primitives and call frames |
| Heap | Managed storage for escaping objects. Supports pluggable GC or ARC strategies. |
| Go-style Pointers | Structs and primitives are values by default. Explicit *T and &x operators for sharing/mutation. |
| VMT | Virtual Method Tables ensure O(1) dynamic dispatch for class methods |
Escape Analysis determines whether variables stay on the Stack (fast) or move to the Heap (GC managed).
Hybrid Concurrency
Section titled “Hybrid Concurrency”Chuks uses a three-layer concurrency model:
| Layer | Role |
|---|---|
| Event Loop | Handles non-blocking I/O (network, file) efficiently |
| Coroutine Scheduler | Manages lightweight “green threads” for massive concurrency (10k+ tasks) using M:N threading |
| OS Thread Pool | Distributes CPU-bound work across OS threads for multi-core utilization |
The Scheduler coordinates between the Event Loop (for I/O) and the Thread Pool (for CPU), allowing async/await and spawn to work seamlessly together.
Interop
Section titled “Interop”Direct bindings to C/Rust libraries for ecosystem compatibility through the FFI layer.