# tencent/libco architecture

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

- Interactive diagram: https://gitdiagram.com/tencent/libco
- Repository: https://github.com/tencent/libco

## Overview

##### Project’s Nature and Purpose
- Project type: A C/C++ library for managing coroutines.
- Purpose: To enable developers to convert synchronous code into an asynchronous, high-concurrency coroutine-based service. It provides core interfaces (co_create, co_resume, co_yield) and supports a copy-stack mode for handling tens of millions of TCP connections.
- Key idea: Non-invasive asynchronous programming via system hooks and coroutine scheduling.

##### File Structure
- Core files (e.g., co_routine.cpp, co_routine.h, co_routine_inner.h, co_routine_specific.h) represent the heart of the coroutine scheduler and management.
- Context and stack management files (coctx.cpp, coctx.h, coctx_swap.S) form the basis for low-level context switching.
- System hook files (co_hook_sys_call.cpp) demonstrate how the library intercepts blocking system calls to convert them for asynchronous use.
- Networking and event polling (co_epoll.cpp, co_epoll.h) indicate integration with event-driven models using epoll (or equivalent).
- Communication-related and closure management (co_comm.cpp/co_comm.h, co_closure.h) illustrate support for asynchronous communication and callback management.
- Example files (e.g., example_echosvr.cpp, example_echocli.cpp, example_poll.cpp) provide usage scenarios and demonstrate how the components integrate.
- Build configuration files (Makefile, CMakeLists.txt, co.mk) support different build systems and environments.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Application Code (Libco API)"]:::app
    B["System Hook Layer"]:::hook
    C["Event Polling and I/O Integration"]:::event
    D["Coroutine Scheduler Core"]:::core
    E["Context Switching Mechanism"]:::context
    F["Communication & Closure Support"]:::comm
    G["Example Usage Modules"]:::example

    A -->|"invokes"| B
    B -->|"hooksCalls"| C
    C -->|"triggersResume"| D
    D -->|"suspendsAndResumes"| E
    D -->|"executesCallbacks"| F
    E -->|"returnsControl"| A
    A -->|"integratesWith"| G

    classDef app fill:#fef9c3,stroke:#b45309,stroke-width:2px;
    classDef hook fill:#dbeafe,stroke:#1e40af,stroke-width:2px;
    classDef event fill:#bbf7d0,stroke:#166534,stroke-width:2px;
    classDef core fill:#fed7aa,stroke:#c2410c,stroke-width:2px;
    classDef context fill:#fecaca,stroke:#991b1b,stroke-width:2px;
    classDef comm fill:#cffafe,stroke:#0369a1,stroke-width:2px;
    classDef example fill:#e0e7ff,stroke:#4338ca,stroke-width:2px;

    %% Click Events for Component Mappings
    click D "https://github.com/tencent/libco/blob/master/co_routine.cpp"
    click D "https://github.com/tencent/libco/blob/master/co_routine.h"
    click D "https://github.com/tencent/libco/blob/master/co_routine_inner.h"
    click D "https://github.com/tencent/libco/blob/master/co_routine_specific.h"
    
    click E "https://github.com/tencent/libco/blob/master/coctx.cpp"
    click E "https://github.com/tencent/libco/blob/master/coctx.h"
    click E "https://github.com/tencent/libco/blob/master/coctx_swap.S"
    
    click B "https://github.com/tencent/libco/blob/master/co_hook_sys_call.cpp"
    
    click C "https://github.com/tencent/libco/blob/master/co_epoll.cpp"
    click C "https://github.com/tencent/libco/blob/master/co_epoll.h"
    
    click F "https://github.com/tencent/libco/blob/master/co_comm.cpp"
    click F "https://github.com/tencent/libco/blob/master/co_comm.h"
    click F "https://github.com/tencent/libco/blob/master/co_closure.h"
    
    click G "https://github.com/tencent/libco/blob/master/example_echosvr.cpp"
    click G "https://github.com/tencent/libco/blob/master/example_echocli.cpp"
    click G "https://github.com/tencent/libco/blob/master/example_poll.cpp"
```
