# scylladb/seastar architecture

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

- Interactive diagram: https://gitdiagram.com/scylladb/seastar
- Repository: https://github.com/scylladb/seastar

## Overview

Overview:

Key Components to Include:
##### Core Framework Components
- Reactor/ Event Loop: Illustrate the central event loop (found in src/core/reactor.cc and related files) that drives the non-blocking execution.
- Scheduler & Concurrency Management: Show how seastar manages tasks, futures, coroutines, and scheduling (modules like src/core/smp.cc, src/core/thread.cc, src/core/future.cc).
- Memory & Resource Management: Indicate the custom allocator usage and memory management utilities (src/core/memory.cc, include/seastar/util).

##### Networking and Protocol Support
- Native TCP/IP Stack: Represent the framework's own userspace TCP/IP stack (referenced in README under “The Native TCP/IP Stack” and in src/net/*).
- HTTP and RPC Components: Include separate modules for HTTP (src/http and include/seastar/http) and RPC functionalities (src/rpc, include/seastar/rpc).

##### Build and Configuration Infrastructure
- Build System: Outline how CMake (with modes debug, release, dev, sanitize) is used to configure and build the entire project including submodules like DPDK. Emphasize the roles of top-level build scripts (configure.py, CMakeLists.txt in various directories).

##### Sample Applications and Demos
- Apps Directory: Break out the sample applications (httpd, memcached, rpc_tester, io_tester, etc.) that demonstrate how to utilize Seastar’s capabilities. Indicate that these serve as both demos and testing grounds.
- Demos: Similarly, include the demos (under demos/) which show standalone examples like echo servers, TCP demos, and coroutine demonstrations.

##### Testing and Documentation
- Testing Framework: Capture how unit tests (tests/unit) and performance tests (tests/perf) ensure system correctness.
- Documentation & Examples: Mention the extensive documentation (in doc/) and tutorials, which help guide developers to integrate and extend Seastar within their own applications.

- Use clear, labeled blocks to represent each major component (Reactor, Scheduler, I/O, Networking, etc.). Provide hierarchical detail starting from core library internals (src and include directories) then branch out to supporting systems (apps, demos, tests).
– App → Seastar application template (src/core/app-template.cc) → Event loop reactor (src/core/reactor.cc).
– Networking layers: HTTP components depend on the underlying TCP/IP stack and reactor.
- Design patterns or principles: For example, note the asynchronous programming model based on futures and continuations, and how sharded components (e.g., in src/core/sharded.cc) enable scalability on multi-core systems.
- Supplemental details:
– Configuration flow: How the configure.py script wraps around CMake.
– Build modes and their implications on performance and testing (highlight debug, release, dev, sanitize modes).

– Since Seastar is a library/framework rather than a typical full-stack application, concentrate on its internal architectural layers and APIs rather than a frontend/back-end separation.
– Focus on how the efficient event loop and non-blocking I/O architecture interlock with the networking protocols and RPC mechanisms.
– Emphasize extension points: illustrate where external applications or services plug into the framework (for example, user-written apps linking against the Seastar API via pkg-config and CMake integration).

- Event Loop/Reactor
- Scheduler & Concurrency Engine
- I/O and Resource Manager
2. Adjacent blocks for “Networking & Protocols” that branch from the core (TCP/IP stack, HTTP, RPC).
5. Component with relevant technologies (e.g., C++20/23 standard, use of futures, coroutine support).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Build & Configuration"
        Build["Build & Configuration System"]:::build
        DPDK["External Dependencies & DPDK Integration"]:::external
    end

    subgraph "Seastar Core Framework"
        Reactor["Event Loop/Reactor"]:::core
        Scheduler["Scheduler & Concurrency"]:::core
        IO["I/O Subsystem"]:::core
        Memory["Memory & Resource Management"]:::core
    end

    subgraph "Networking & Protocols"
        TCPIP["Native TCP/IP Stack"]:::net
        HTTP["HTTP Components"]:::net
        RPC["RPC Components"]:::net
    end

    subgraph "Applications & Demos"
        Apps["Sample Applications"]:::apps
        Demos["Demos"]:::apps
    end

    Testing["Testing Framework"]:::test
    Docs["Documentation & Examples"]:::docs

    %% Connections from Build to Core components
    Build -->|"configures"| Reactor
    Build -->|"configures"| Scheduler
    Build -->|"configures"| IO
    Build -->|"configures"| Memory

    %% DPDK integration with Networking
    DPDK -->|"integrates_with"| TCPIP

    %% Core to Networking connections
    Reactor -->|"dispatches_to"| TCPIP
    Scheduler -->|"schedules_IO"| IO
    IO -->|"supports_memory"| Memory
    TCPIP -->|"enables_HTTP"| HTTP
    TCPIP -->|"enables_RPC"| RPC

    %% Sample Applications and Demos relying on Core and Networking
    Apps -->|"utilizes"| Reactor
    Apps -->|"utilizes"| TCPIP
    Demos -->|"demonstrates"| Reactor
    Demos -->|"demonstrates"| TCPIP
    Apps -->|"built_by"| Build

    %% Testing and Documentation linked to Core and Build
    Testing -->|"tests"| Reactor
    Testing --> Build
    Docs -->|"documents"| Reactor
    Docs --> Build

    %% Styles
    classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef net fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef build fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef apps fill:#ccffff,stroke:#009999,stroke-width:2px;
    classDef test fill:#e0e0e0,stroke:#666666,stroke-width:2px;
    classDef docs fill:#ffe0b3,stroke:#cc6600,stroke-width:2px;

click Reactor "https://github.com/scylladb/seastar/blob/master/src/core/reactor.cc"
click Reactor "https://github.com/scylladb/seastar/blob/master/include/seastar/core/reactor.hh"

click Scheduler "https://github.com/scylladb/seastar/blob/master/src/core/smp.cc"
click Scheduler "https://github.com/scylladb/seastar/blob/master/src/core/thread.cc"
click Scheduler "https://github.com/scylladb/seastar/blob/master/src/core/future.cc"
click Scheduler "https://github.com/scylladb/seastar/blob/master/include/seastar/core/future.hh"
click Scheduler "https://github.com/scylladb/seastar/blob/master/include/seastar/core/smp.hh"

click IO "https://github.com/scylladb/seastar/blob/master/src/core/linux-aio.cc"
click IO "https://github.com/scylladb/seastar/tree/master/src/net"
click IO "https://github.com/scylladb/seastar/tree/master/include/seastar/net"

click Memory "https://github.com/scylladb/seastar/blob/master/src/core/memory.cc"
click Memory "https://github.com/scylladb/seastar/tree/master/include/seastar/util"

click TCPIP "https://github.com/scylladb/seastar/blob/master/src/net/native-stack.cc"
click TCPIP "https://github.com/scylladb/seastar/blob/master/include/seastar/net/native-stack.hh"

click HTTP "https://github.com/scylladb/seastar/tree/master/src/http"
click HTTP "https://github.com/scylladb/seastar/tree/master/include/seastar/http"

click RPC "https://github.com/scylladb/seastar/tree/master/src/rpc"
click RPC "https://github.com/scylladb/seastar/tree/master/include/seastar/rpc"

click Build "https://github.com/scylladb/seastar/blob/master/CMakeLists.txt"
click Build "https://github.com/scylladb/seastar/blob/master/configure.py"
click Build "https://github.com/scylladb/seastar/blob/master/cmake/Finddpdk.cmake"
click Build "https://github.com/scylladb/seastar/blob/master/cmake/SeastarConfig.cmake.in"

click DPDK "https://github.com/scylladb/seastar/tree/master/dpdk"
click DPDK "https://github.com/scylladb/seastar/blob/master/cmake/Finddpdk.cmake"

click Apps "https://github.com/scylladb/seastar/tree/master/apps/httpd"
click Apps "https://github.com/scylladb/seastar/tree/master/apps/memcached"
click Apps "https://github.com/scylladb/seastar/tree/master/apps/rpc_tester"
click Apps "https://github.com/scylladb/seastar/tree/master/apps/io_tester"

click Demos "https://github.com/scylladb/seastar/tree/master/demos"

click Testing "https://github.com/scylladb/seastar/tree/master/tests/unit"
click Testing "https://github.com/scylladb/seastar/tree/master/tests/perf"

click Docs "https://github.com/scylladb/seastar/tree/master/doc"
```
