# gooddbird/tinyrpc architecture

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

- Interactive diagram: https://gitdiagram.com/gooddbird/tinyrpc
- Repository: https://github.com/gooddbird/tinyrpc

## Overview

##### Project type and purpose
- tinyrpc is an open-source, header-only C++11 framework for building high-performance, asynchronous RPC services.
- It provides:
- A core runtime (logging, coroutines, reactor, TCP, HTTP, TinyPB codec)
- An RPC stub/dispatcher layer for Protobuf-based and HTTP−based RPC
- A code generator (`tinyrpc_generator.py`) that scaffolds new RPC services from `.proto` files
- Examples and test cases under `testcases/`

##### File structure
- Top‐level directories:
- `tinyrpc/comm` – common utilities (config, async‐logging, thread pool, error codes, string utils)
- `tinyrpc/coroutine` – libco‐based coroutine abstraction, hooks, coroutine pool
- `tinyrpc/net` – Reactor wrapper, TCP server/client, HTTP codec/dispatcher, TinyPB codec/dispatcher
- `generator` – Python script + templates for scaffolding new services/clients
- `testcases` – example protocols, servers, clients, unit tests
- `conf` – XML config samples (TinyPB and HTTP server)
- `.devcontainer`, `Dockerfile` – development environment setup
- `build.sh`, `CMakeLists.txt`, `makefile` – build scripts (CMake and Makefile)
- Configuration files: XML under `conf/` parsed via TinyXML
- Build scripts: `build.sh` invokes CMake; top-level `makefile` drives Makefile install/uninstall

##### README for architectural insights
- Core modules described in “概要设计” (Section 5)
- Indicates use of:
- Asynchronous logging (producer/consumer thread)
- m:n thread:coroutine model
- Reactor pattern (epoll under the hood)
- TCPServer / TCPConnection abstractions
- TinyPB (custom Protobuf binary protocol)
- HTTP Servlet interface

##### Main components & their relationships
- Protobuf library (serialization of business messages)
- TinyXML (XML config parsing)
- libco (underlying coroutine swap routines)
- Docker/DevContainer (optional development environment)
A. Configuration & Bootstrapping
- `InitConfig(xml)` → populates global settings
- `StartRpcServer()` → spins up I/O threads, Reactor, thread pool
B. Asynchronous Logging
- Logging macros (`DebugLog`, `AppInfoLog`)
- Log producer buffers → Async logger thread → file rolling
C. Coroutine Scheduler
- Hooks: `connect()`, `read()`, `write()` redirect to non-blocking + yield
- Coroutine Pool: `coctx`, `coroutine.cc`, `coroutine_pool`
D. Reactor
- `fd_event` registers events on epoll; dispatches readiness callbacks
- Tied to coroutines: on I/O readiness, resume appropriate coroutine
E. TCP Layer
- `TcpServer` listens, accepts → spawns per-connection coroutine
- `TcpConnection` reads raw bytes, hands off to appropriate codec
F. Protocol Codecs & Dispatchers
- TinyPB module: `tinypb_codec`, `tinypb_rpc_channel`, `tinypb_rpc_dispatcher`
- HTTP module: `http_codec`, `http_dispatcher`, `HttpServlet` plug-in
G. RPC Layer
- Business services inherit generated `Service` interfaces (from Protobuf)
- `REGISTER_SERVICE()` or `REGISTER_HTTP_SERVLET()` hooks implementation
H. Code Generator
- `generator/tinyrpc_generator.py` + `templates/`
- Produces skeleton: `interface/`, `service/`, `main.cc`, `makefile`, `test_client`

##### Architectural patterns & design principles
- Reactor pattern for scalable I/O multiplexing (epoll)
- m:n threading with cooperative coroutines for non-blocking concurrency
- Asynchronous producer/consumer logging
- Layered separation: config → logging → coroutine → reactor → transport → codec → dispatch → business
- Template-based code generation for rapid service scaffolding

##### Essential architectural elements
- M:n model: multiple IO threads share a central coroutine queue
- Asynchronous logging thread separate from I/O threads
- “REGISTER_SERVICE” and “REGISTER_HTTP_SERVLET” as plug-in registration points

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        Proto["Protobuf"]:::ext
        TinyXML["TinyXML"]:::ext
        Libco["libco"]:::ext
        DevEnv["DevContainer/Docker"]:::ext
    end

    %% Configuration & Bootstrapping
    subgraph "Configuration & Bootstrapping"
        Config["InitConfig(xml)"]:::blue
        Start["StartRpcServer()"]:::blue
    end

    %% Asynchronous Logging
    subgraph "Asynchronous Logging"
        LogMacros["Logging Macros"]:::blue
        LogThread["Async Logger Thread"]:::cylinder
    end

    %% Coroutine Scheduler
    subgraph "Coroutine Scheduler"
        Hooks["Coroutine Hooks"]:::blue
        CoPool["Coroutine Pool"]:::cylinder
    end

    %% Reactor
    subgraph "Reactor"
        FdEvent["fd_event"]:::blue
        ReactorCore["Reactor"]:::blue
    end

    %% TCP Layer
    subgraph "TCP Layer"
        TcpServer["TcpServer"]:::blue
        TcpConn["TcpConnection"]:::blue
        TcpClient["TcpClient"]:::blue
    end

    %% Protocol Modules
    subgraph "Protocol Modules"
        subgraph "HTTP Module"
            HttpCodec["HTTP Codec"]:::green
            HttpDisp["HTTP Dispatcher"]:::green
            HttpServlet["HttpServlet"]:::green
        end
        subgraph "TinyPB Module"
            TBCodec["TinyPB Codec"]:::green
            TBChannel["TinyPB RpcChannel"]:::green
            TBDisp["TinyPB Dispatcher"]:::green
        end
    end

    %% RPC Layer
    subgraph "RPC Layer"
        ServiceReg["REGISTER_SERVICE / REGISTER_HTTP_SERVLET"]:::blue
    end

    %% Code Generator
    subgraph "Code Generator"
        Generator["tinyrpc_generator.py"]:::orange
        Templates["templates"]:::orange
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        TestCases["testcases"]:::orange
    end

    %% Connections
    TinyXML -->|parses config| Config
    Proto -->|serializes messages| TBCodec
    Libco -->|implements swaps| Hooks
    DevEnv --> Start

    Config --> Start
    Start --> ReactorCore
    Start --> CoPool
    Start --> LogThread

    LogMacros --> LogThread

    ReactorCore -->|event readiness| Hooks
    Hooks --> CoPool
    CoPool -->|schedule| ReactorCore

    ReactorCore --> TcpServer
    TcpServer --> TcpConn
    TcpConn --> TBCodec
    TcpConn --> HttpCodec

    TBCodec --> TBDisp
    HttpCodec --> HttpDisp

    TBDisp --> ServiceReg
    HttpServlet --> ServiceReg

    ServiceReg -->|invokes| TBChannel
    TBChannel --> ReactorCore

    Generator --> Templates
    Generator --> ServiceReg
    Generator --> TestCases

    TestCases --> Proto

    %% Click Events
    click Config "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/comm/config.cc"
    click Start "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/comm/start.cc"
    click LogThread "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/comm/log.cc"
    click Hooks "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/coroutine/coroutine_hook.cc"
    click CoPool "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/coroutine/coroutine_pool.cc"
    click FdEvent "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/fd_event.cc"
    click ReactorCore "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/reactor.cc"
    click TcpServer "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/tcp/tcp_server.cc"
    click TcpConn "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/tcp/tcp_connection.cc"
    click TcpClient "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/tcp/tcp_client.cc"
    click HttpCodec "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/http/http_codec.cc"
    click HttpDisp "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/http/http_dispatcher.cc"
    click HttpServlet "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/http/http_servlet.cc"
    click TBCodec "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/tinypb/tinypb_codec.cc"
    click TBChannel "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/tinypb/tinypb_rpc_channel.cc"
    click TBDisp "https://github.com/gooddbird/tinyrpc/blob/main/tinyrpc/net/tinypb/tinypb_rpc_dispatcher.cc"
    click Generator "https://github.com/gooddbird/tinyrpc/blob/main/generator/tinyrpc_generator.py"
    click Templates "https://github.com/gooddbird/tinyrpc/tree/main/generator/template/"
    click TestCases "https://github.com/gooddbird/tinyrpc/tree/main/testcases"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085;
    classDef green fill:#d4edda,stroke:#155724,color:#155724;
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404;
    classDef ext fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef cylinder fill:#f8f9fa,stroke:#343a40,color:#343a40,shape:cylinder;
```
