# swoole/swoole-src architecture

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

- Interactive diagram: https://gitdiagram.com/swoole/swoole-src
- Repository: https://github.com/swoole/swoole-src

## Overview

##### Project Type & Purpose
- Swoole is a high-performance PHP extension that implements event-driven, asynchronous, coroutine-based concurrency. It makes PHP capable of running network servers (HTTP, TCP, UDP, WebSocket, and more) and acting as a client for various asynchronous I/O operations.
- The project contains the core libraries (in the “src” and “include” directories), the PHP extension layer (in “ext-src”), bindings/stubs (ext-src/stubs), tests, examples, and third-party integrations (e.g., nghttp2, hiredis, nlohmann json). The Readme and numerous examples in the “examples” folder as well as the documentation all emphasize how to set up servers and clients with coroutine-driven flows.

##### Key Components
a. PHP Extension & Interface Layer:
– This layer provides the integration of Swoole into PHP. It consists of the C/C++ files in “ext-src” (like php_swoole.cc, php_swoole_http_server.h, etc.) and stubs that define the PHP API.
– It also includes the “include/” directory which provides headers for the Swoole C API.
– Indicate how this layer exposes classes and functions (e.g., Swoole\Http\Server, Swoole\Coroutine, etc.) to PHP user applications.

b. Core Engine and Runtime:
– Located mainly in the “src” directory. Break it down into sub-components such as:
- Reactor/Event Loop: Found in “src/reactor” (files such as epoll.cc, kqueue.cc, poll.cc, select.cc) which handle underlying event-driven I/O using OS primitives.
- Coroutine Scheduler & Management: See components in “src/coroutine” (base.cc, channel.cc, hook.cc, thread_context.cc) which schedule and manage lightweight coroutines.
- Core Utilities: “src/core” contains utility functions (base, log, timer, hash, etc.) that support memory, logging, and other low-level services.
- Locking and Synchronization: “src/lock” which provides implementations of mutexes, rw-locks, and other synchronization primitives.

c. Network & Protocol Modules:
– “src/network”, “src/protocol” (HTTP, HTTP2, WebSocket, DTLS, mqtt, redis, mime_type, etc.) hold the logic that handles network addresses, building/parsing HTTP messages, secure protocols, and other communication protocols.
– “src/server” contains the server management modules (e.g., master, worker, task_worker, manager) which are responsible for process management, load distribution, and message processing.

d. Asynchronous Clients & I/O Hooks:
– The runtime hook module (demonstrated in the Readme via Swoole\Runtime::enableCoroutine()) intercepts standard PHP blocking I/O calls so that they become non-blocking when executed in coroutines. Note that many I/O related operations (stream functions, CURL, database access, filesystem) are “hooked” into the asynchronous layer.
– Include a sub-component that represents “Coroutine Clients” (HTTP, TCP, HTTP2, WebSocket) found in both examples and in dedicated client classes in the source.

e. Test, Examples & Third-Party Dependencies:
– The “tests” and “examples” directories show how multifaceted Swoole is. Additionally, the “thirdparty” folder integrates libraries such as nghttp2, hiredis, boost asm files, and JSON libraries.

##### Relationships and Data Flow
- User PHP code calls into the PHP extension (swoole.so) using classes and functions.
- The extension layer then transfers calls into the core engine (which is implemented primarily in the “src” branch).
- Inside the core, the Reactor/event loop detects I/O events and delegates control to the coroutine scheduler.
- The coroutine scheduler uses channels, timers, and client modules to implement asynchronous I/O. This includes network protocol parsing/handling from the network and protocol modules.
- The core then interacts with external libraries (from “thirdparty”) when specialized functionality is needed (e.g., HTTP2 using nghttp2, redis protocols via hiredis).
- The extension layer is responsible also for providing stubs and method signatures back into the PHP userland.

##### Architectural Patterns and Design Principles
- Event-driven and Reactive: The reactor modules (epoll/kqueue/select) underpin the asynchronous event loop.
- Coroutine Scheduling: Lightweight user-level threads are scheduled using coroutine primitives (see src/coroutine, src/lock, and channels) to ensure high concurrency.
- Separation of Concerns: Distinct modules for network protocols, server process management, and low-level I/O allow for extension and maintenance.
- Runtime Hooking: Swoole replaces standard PHP blocking calls with its own non-blocking implementations transparently, enabling easier migration of code to a concurrent model.

##### Final Steps
- In a more detailed view, further break down the Core Engine into its sub-components (e.g., Reactor/Loop handling, Coroutine Scheduler, Timer/Channel, Process Pools).
- Verify each component and its connections by referencing specific directories in the file tree (e.g., “src/reactor” for the event loop, “ext-src” for the PHP interface).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("PHP User Code"):::user

    subgraph "PHP Interface Layer"
        B("PHP Extension Layer"):::extension
    end

    subgraph "Core Engine"
        C("Event Reactor/Loop"):::core
        D("Coroutine Scheduler"):::core
        E("Core Utilities"):::core
        F("Locking & Synchronization"):::core
        G("Memory Management"):::core
    end

    subgraph "Network & Protocol Modules"
        H("Network I/O"):::network
        I("Protocol Handling"):::network
        J("Server Process Management"):::network
    end

    K("Third-Party Integrations"):::external

    L("PHP Userland Examples"):::examples
    M("Test Suite"):::tests

    %% Connections
    A -->|"calls"| B
    B -->|"delegates"| C
    C -->|"triggers"| D
    D -->|"utilizes"| E
    D -->|"synchronizes"| F
    D -->|"manages"| G
    D -->|"handlesAsync"| H
    H -->|"parses"| I
    I -->|"manages"| J
    J -->|"integrates"| K
    B -->|"demonstratedBy"| L
    B -->|"validatedBy"| M

    %% Click Events
    click B "https://github.com/swoole/swoole-src/tree/master/ext-src"
    click C "https://github.com/swoole/swoole-src/tree/master/src/reactor"
    click D "https://github.com/swoole/swoole-src/tree/master/src/coroutine"
    click E "https://github.com/swoole/swoole-src/tree/master/src/core"
    click F "https://github.com/swoole/swoole-src/tree/master/src/lock"
    click G "https://github.com/swoole/swoole-src/tree/master/src/memory"
    click H "https://github.com/swoole/swoole-src/tree/master/src/network"
    click I "https://github.com/swoole/swoole-src/tree/master/src/protocol"
    click J "https://github.com/swoole/swoole-src/tree/master/src/server"
    click L "https://github.com/swoole/swoole-src/tree/master/examples"
    click M "https://github.com/swoole/swoole-src/tree/master/tests"
    click K "https://github.com/swoole/swoole-src/tree/master/thirdparty"

    %% Styles
    classDef user fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef extension fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef core fill:#f94144,stroke:#333,stroke-width:2px;
    classDef network fill:#577590,stroke:#333,stroke-width:2px;
    classDef external fill:#277da1,stroke:#333,stroke-width:2px;
    classDef examples fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef tests fill:#43aa8b,stroke:#333,stroke-width:2px;
```
