# ossrs/state-threads architecture

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

- Interactive diagram: https://gitdiagram.com/ossrs/state-threads
- Repository: https://github.com/ossrs/state-threads

## Overview

This project is the “state-threads” library – a lightweight threading (or coroutine) library originally forked and patched by SRS. Its purpose is to provide a cross-platform, efficient user-level threading mechanism with support for various operating systems (Linux, Darwin/OSX, Cygwin for Windows, and even more niche architectures like ARM, MIPS, LOONGARCH, RISCV, and Apple M1).

##### Main Components
- Library Core: The heart of the threading library, comprised of core source files such as event.c, io.c, key.c, sched.c, stk.c (stack management), and sync.c (synchronization primitives). These files represent the main functionalities including event handling, scheduling, and context switching.
- Assembly / Porting Layer: Look at files with assembly suffixes (md_cygwin64.S, md_darwin.S, md_linux.S, md_linux2.S) which are the architecture/platform-specific implementations of low-level routines essential for context switching.
- API/Headers: Common header files (common.h, public.h, libst.def) that expose the API to users of the library. These define public interfaces, macros, and configurations.
- Build and Configuration: The multiple Makefiles, Dockerfiles (Dockerfile.cov, Dockerfile.test), and build scripts in the “auto” directory indicate the build and test configuration setups.
- Testing and Validation:
- “utest” directory packed with Google Test integration (through st_utest.cpp, st_utest.hpp, st_utest_tcp.cpp, etc.) ensures unit testing.
- “tools” directory includes utilities (like backtrace, jmpbuf, porting, etc.) that assist in debugging, verification, and possibly demonstrating usage (e.g., tools/helloworld).
- Documentation & IDE Configurations:
- “docs” directory with various notes, reference, and analysis files serves as the documentation.
- “ide/st_clion” contains CMakeLists.txt for CLion-based project configuration.

##### Understand Component Relationships
- Users or higher-level software will invoke the state-threads API (as defined by the public headers). The API internally calls into the scheduler (sched.c) which, in turn, manages thread execution using a combination of event handling (event.c) and context switching (facilitated by low-level assembly in md_*.S files).
- The I/O operations (from io.c) interface with the event system to manage asynchronous operations.
- Synchronization and stack management (in sync.c and stk.c) support safe context switching and thread coordination.
- During execution, the library uses its integrated backtrace and debugging utilities (located under tools) to aid in fault diagnosis and performance analysis.
- The testing framework, including the specialized unit tests integrated with Google Test (in the “utest” directory), validates the thread library functionality.
- Build scripts (Makefile, auto scripts) ensure the library can be built in different modes (debug, with valgrind, coverage reports, etc.) for various target environments.

##### Architectural Patterns and Design Principles
- Modular Design: Each source file (e.g., event.c, sched.c, stk.c) represents a distinct module, making the library both extensible and easier to maintain.
- Portability and Conditional Compilation: The presence of different assembly implementations for various platforms indicates a design that uses compile-time flags (like EXTRA_CFLAGS in make commands) to choose the correct low-level routines based on the target CPU/OS.

##### Relevant Technologies and Tools
- C/C++: The core language used to implement the library.
- Assembly: For performance-critical operations and context switching.
- Google Test: For unit testing (found in the “utest” directory).
- Build Systems: Makefiles and CMake (for CLion support).
- Docker: For ensuring a consistent build environment using the provided Dockerfiles.
- CI Tools: GitHub Actions (in .github/workflows/test.yml) and Codecov for continuous integration and code coverage analysis.

##### Summary
- Under the Core Library, itemize the major components (scheduler, event, sync, stack) and illustrate their interactions.
- Supporting utilities (tools, tests, docs) off to the side with lines showing integration points (e.g., testing validates API and core functionality, build scripts manage compilation for multiple platforms).
- Finally, annotate with the technologies (C, Assembly, Google Test, Docker, etc.) and note conditional compilation usage for varying build flags (e.g., EXTRA_CFLAGS for architecture-specific builds).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application/User Layer"
        UA("User Application"):::user
    end

    subgraph "API/Headers"
        CH("common.h"):::api
        PH("public.h"):::api
        LD("libst.def"):::api
    end

    subgraph "Core Library"
        EH("Event Handling (event.c)"):::core
        IO("I/O Operations (io.c)"):::core
        KM("Key Management (key.c)"):::core
        SCH("Scheduler (sched.c)"):::core
        SM("Stack Management (stk.c)"):::core
        SYNC("Synchronization (sync.c)"):::core
    end

    subgraph "Platform Abstraction"
        CY("Cygwin Routines (md_cygwin64.S)"):::assembly
        DAR("Darwin/OSX Routines (md_darwin.S)"):::assembly
        LNX("Linux Routines (md_linux.S)"):::assembly
        LNX2("Linux Routines (md_linux2.S)"):::assembly
    end

    subgraph "Build & Configuration"
        MF("Makefile"):::build
        DC("Dockerfile.cov"):::build
        DT("Dockerfile.test"):::build
        AUTO("Auto Scripts (auto)"):::build
    end

    subgraph "Testing & Validation"
        UT("Unit Tests (utest)"):::test
        TOOLS("Tools (tools)"):::test
    end

    subgraph "Documentation & IDE"
        DOCS("Docs (docs)"):::docs
        CLION("CLion Config (ide/st_clion)"):::docs
    end

    %% Connections between layers
    UA -->|"calls"| CH
    UA -->|"calls"| PH
    UA -->|"calls"| LD

    CH -->|"invokes"| SCH
    PH -->|"invokes"| SCH
    LD -->|"invokes"| SCH

    SCH -->|"manages"| EH
    SCH -->|"manages"| IO
    SCH -->|"manages"| KM
    SCH -->|"uses"| SM
    SCH -->|"uses"| SYNC

    EH -->|"triggers"| IO

    SCH -->|"context_switch"| CY
    SCH -->|"context_switch"| DAR
    SCH -->|"context_switch"| LNX
    SCH -->|"context_switch"| LNX2

    MF -->|"builds"| SCH
    UT -->|"validates"| SCH
    TOOLS -->|"assists"| SCH

    DOCS -->|"documents"| SCH
    CLION -->|"configures"| SCH

    %% Click Events for Library Core
    click EH "https://github.com/ossrs/state-threads/blob/srs/event.c"
    click IO "https://github.com/ossrs/state-threads/blob/srs/io.c"
    click KM "https://github.com/ossrs/state-threads/blob/srs/key.c"
    click SCH "https://github.com/ossrs/state-threads/blob/srs/sched.c"
    click SM "https://github.com/ossrs/state-threads/blob/srs/stk.c"
    click SYNC "https://github.com/ossrs/state-threads/blob/srs/sync.c"

    %% Click Events for Assembly / Porting Layer
    click CY "https://github.com/ossrs/state-threads/blob/srs/md_cygwin64.S"
    click DAR "https://github.com/ossrs/state-threads/blob/srs/md_darwin.S"
    click LNX "https://github.com/ossrs/state-threads/blob/srs/md_linux.S"
    click LNX2 "https://github.com/ossrs/state-threads/blob/srs/md_linux2.S"

    %% Click Events for API/Headers
    click CH "https://github.com/ossrs/state-threads/blob/srs/common.h"
    click PH "https://github.com/ossrs/state-threads/blob/srs/public.h"
    click LD "https://github.com/ossrs/state-threads/blob/srs/libst.def"

    %% Click Events for Build and Configuration
    click MF "https://github.com/ossrs/state-threads/tree/srs/Makefile"
    click DC "https://github.com/ossrs/state-threads/blob/srs/Dockerfile.cov"
    click DT "https://github.com/ossrs/state-threads/blob/srs/Dockerfile.test"
    click AUTO "https://github.com/ossrs/state-threads/tree/srs/auto"

    %% Click Events for Testing and Validation
    click UT "https://github.com/ossrs/state-threads/tree/srs/utest"
    click TOOLS "https://github.com/ossrs/state-threads/tree/srs/tools"

    %% Click Events for Documentation & IDE Configurations
    click DOCS "https://github.com/ossrs/state-threads/tree/srs/docs"
    click CLION "https://github.com/ossrs/state-threads/tree/srs/ide/st_clion"

    %% Styles
    classDef user fill:#ffe6cc,stroke:#d35400,stroke-width:2px;
    classDef api fill:#ccffcc,stroke:#27ae60,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#2980b9,stroke-width:2px;
    classDef assembly fill:#ffcccc,stroke:#c0392b,stroke-width:2px;
    classDef build fill:#ffffcc,stroke:#f39c12,stroke-width:2px;
    classDef test fill:#e6ccff,stroke:#8e44ad,stroke-width:2px;
    classDef docs fill:#ccffff,stroke:#16a085,stroke-width:2px;
```
