# liten-rs/liten architecture

> Architecture diagram of the GitHub repository liten-rs/liten, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liten-rs/liten
- Repository: https://github.com/liten-rs/liten

## Overview

##### Project Type & Purpose
- Liten is an async runtime—a low-level framework that provides asynchronous execution, scheduling, and I/O handling specifically designed for Rust.
- The README highlights its N:M multithreaded model, a work stealing scheduler, integrated networking (TCP, UDP), and efficient I/O handling using mio. This tells us that the architecture revolves around core concurrency primitives and asynchronous event handling.

##### Main Components (Based on the File Structure)
- Core Runtime (located in the “liten/src/runtime” directory):
- Main Executor and event loop (e.g., main_executor.rs)
- Scheduler: work stealing scheduler, worker threads (liten/src/runtime/scheduler and submodules)
- Waker mechanism for task wake-ups (e.g., runtime/waker.rs)
- Task Management (liten/src/task):
- Task builder, spawn functions, task state management, etc.
- Asynchronous I/O & Networking:
- IO handling (liten/src/io and its subdirectories)
- Networking modules (liten/src/net): TCP (listener and stream support) and potential UDP handling.
- Synchronization Primitives (liten/src/sync):
- mpsc channels, mutexes, oneshot channels, semaphores, and utility synchronization methods.
- Time & Delays (liten/src/time):
- Managing timers, sleep functionality, etc.
- Macro Support (in the “liten-macros” crate):
- This likely provides compile-time helpers or custom attributes to simplify usage of the runtime’s APIs.
- Examples & Testing:
- Various examples of usage in “examples/” and tests in “liten/tests” help illuminate functionalities.

##### Relationships & Interactions Between Components
- At the core, the Runtime initializes the event loop which integrates with the IO layer (powered by mio) to wait on asynchronous events.
- The Scheduler distributes tasks (created via the Task modules) across several worker threads. Workers use a work stealing strategy to balance the load.
- When an asynchronous event occurs (e.g., incoming network connection via a TcpListener), it is captured by the IO module and relayed through the event loop to the appropriate task.
- Synchronization primitives ensure safe concurrency between tasks and threads.
- The Macro crate (“liten-macros”) presses into service to simplify creation and registration of tasks or to annotate functions that require async handling.

##### Architectural Patterns & Design Principles
- Textbook N:M threading model – mapping many lightweight tasks onto a fewer number of OS threads.
- Work Stealing Scheduler – tasks are dynamically assigned and redistributed among worker threads.
- Modular Architecture – separates concerns: runtime, I/O, networking, task management, and synchronization are kept in distinct modules.
- Minimal Dependencies – design is lightweight, focusing on just the necessary features.

- Design patterns like the N:M threading model and work-stealing mechanism, perhaps adding brief textual annotations near those components.
- Finally, ensure to highlight the minimal and efficient design philosophy as central to the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Runtime Subgraph
    subgraph "Core Runtime"
        RT1["Main Executor & Event Loop"]:::core
        RT2["Waker Mechanism"]:::core
    end

    %% Task Management Subgraph
    subgraph "Task Management"
        TM["Task Manager"]:::task
    end

    %% Scheduler Subgraph
    subgraph "Scheduler"
        SCH["Work Stealing Scheduler"]:::sched
    end

    %% Other Components
    IO["Async I/O Handling"]:::io
    NET["Networking (TCP/UDP)"]:::net
    SYNC["Synchronization Primitives"]:::sync
    TIME["Time Management"]:::time
    MACRO["Macro Helpers"]:::macro
    TEST["Examples & Tests"]:::tests

    %% Relationships
    TM -->|"schedules"| SCH
    SCH -->|"executesTasks"| RT1
    RT1 -->|"pollsEvents"| IO
    IO -->|"handlesEvents"| NET
    NET -->|"signalsEvents"| RT1
    TIME -->|"timerEvents"| RT1
    RT2 -->|"wakesTasks"| TM
    TM -->|"usesSync"| SYNC
    SCH -->|"usesSync"| SYNC
    MACRO -->|"assistsAPI"| TM

    %% Click Events
    click RT1 "https://github.com/liten-rs/liten/blob/main/liten/src/runtime/main_executor.rs"
    click RT2 "https://github.com/liten-rs/liten/blob/main/liten/src/runtime/waker.rs"
    click SCH "https://github.com/liten-rs/liten/tree/main/liten/src/runtime/scheduler/"
    click TM "https://github.com/liten-rs/liten/tree/main/liten/src/task"
    click IO "https://github.com/liten-rs/liten/tree/main/liten/src/io"
    click NET "https://github.com/liten-rs/liten/tree/main/liten/src/net"
    click SYNC "https://github.com/liten-rs/liten/tree/main/liten/src/sync"
    click TIME "https://github.com/liten-rs/liten/tree/main/liten/src/time"
    click MACRO "https://github.com/liten-rs/liten/blob/main/liten-macros/src/lib.rs"
    click TEST "https://github.com/liten-rs/liten/tree/main/examples/"

    %% Styles
    classDef core fill:#f96,stroke:#333,stroke-width:2px;
    classDef sched fill:#6f9,stroke:#333,stroke-width:2px;
    classDef task fill:#9cf,stroke:#333,stroke-width:2px;
    classDef io fill:#fc9,stroke:#333,stroke-width:2px;
    classDef net fill:#ccf,stroke:#333,stroke-width:2px;
    classDef sync fill:#cfc,stroke:#333,stroke-width:2px;
    classDef time fill:#fcc,stroke:#333,stroke-width:2px;
    classDef macro fill:#cff,stroke:#333,stroke-width:2px;
    classDef tests fill:#fcf,stroke:#333,stroke-width:2px;
```
