# photon_rtc

**Repository Path**: Minyli/photon_rtc

## Basic Information

- **Project Name**: photon_rtc
- **Description**: a photon_rtc,designed by io_uring
- **Primary Language**: C++
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-26
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Photon-RPC 全新版

Photon-RPC 是一个基于 C++20 协程（Coroutines）与 Linux `io_uring` 构建的极致高性能 RPC 框架。它专为嵌入式 ARM 设备、边缘计算及 AI 推理服务器设计，旨在通过全链路零拷贝和内核级异步驱动，将底层通信损耗降低至极限。

---

## 项目运行原理与深度架构

Photon-RPC 的核心是一个**异步全双工 Reactor 模式**，通过 C++20 协程将原本碎片化的异步回调转化为线性、直观的业务逻辑。

### 1. 核心组件交互图

```mermaid
sequenceDiagram
    participant K as Linux Kernel (io_uring)
    participant L as IoLoop (心脏)
    participant H as Handler (状态机)
    participant D as Dispatcher (大脑)
    participant S as SlabPool (血液)

    L->>K: 1. io_uring_submit (集中提交 SQE)
    K-->>L: 2. io_uring_wait_cqe (批量收割完成事件)
    L->>H: 3. Precise Resume (精准唤醒协程)
    H->>S: 4. Allocate (从 Slab 池获取零碎片缓冲区)
    H->>K: 5. read_exact (安全循环读取 Header/Body)
    H->>D: 6. Dispatch (根据 MethodID 路由)
    D->>H: 7. Service Result (业务直写 SlabBuffer)
    H->>K: 8. writev (散射写: Header+Body 零拷贝发出)
```

### 2. 运行阶段详解

#### 第一阶段：心脏跳动 (IoLoop & io_uring)
- **事件驱动**: `IoLoop` 封装了 `io_uring` 实例。它不采用 epoll 的就绪通知模式，而是采用**完成通知模式**。
- **批量处理**: 每轮循环通过 `io_uring_submit` 批量提交，通过 `io_uring_peek_batch_cqe` 批量收割。这种设计将 1000 个 I/O 操作的系统调用成本降低了几个数量级。

#### 第二阶段：状态流转 (Handler & Coroutines)
- **协程挂起**: 当业务逻辑调用 `co_await read/write` 时，当前协程会被挂起（Suspending），其句柄被保存在 `Awaiter` 对象中，并通过 `user_data` 传递给内核。
- **无锁分发**: 当 CQE（完成事件）到达时，`IoLoop` 根据标识符精准恢复（Resume）协程。整个过程无需线程切换，无需任何加锁竞争，完全在单线程内闭环。

#### 第三阶段：内存流水线 (Slab & Zerocopy)
- **Slab 分配器**: 项目自定义了对齐至 64 字节（针对 ARM L1 缓存行优化）的 Slab 管理器。
- **数据直通**:
    - **Header**: 栈内存直接发送。
    - **Body**: 直接在 Slab 缓冲区中生成，通过 `writev` 散射写直传网卡。
    - **所有权移动**: 通过 `std::move(SlabBuffer)` 将结果跨层级传递，避免了传统 RPC 中频繁的 `std::vector` 构造与拷贝。

---

## 项目特性

*   **极致 CPU 保护**: 集中化提交与批量收割，使 CPU 能够专注于 AI 推理逻辑或控制算法，而非处理死板的系统中断。
*   **全链路零拷贝**: 真正意义上的零拷贝设计，涵盖从网络驱动到业务函数的所有环节。
*   **Zero Malloc**: 协程帧与报文缓冲区均走专用池，运行时不触发动态内存分配。
*   **安全读满机制**: 独有的 `read_exact` 协程逻辑，彻底规避 TCP 短读导致的协议解析崩溃风险。
*   **ARM 缓存优化**: 遵循 64 字节缓存行对齐，最大化嵌入式芯片的处理能效比。

---

## 文件结构与模块职责

```text
Photon-RPC/
├── photon/
│   ├── acceptor/      # 被动监听模块：负责端口绑定与 Accept 循环
│   ├── awaiters/      # 核心原语：封装 io_uring 操作 (Read, Write, Writev, Timeout)
│   ├── channel/       # 对外 API：提供 RpcChannel 及带超时的 CallAwaiter
│   ├── common/        # 基础设施：Header 定义、Task 包装、配置常量
│   ├── connector/     # 主动连接模块：负责 Connect 握手与端点映射
│   ├── coro/          # 协程原语：提供单线程无锁 Mutex 保护并发写
│   ├── dispatcher/    # 业务枢纽：method_id 到处理函数的 O(1) 路由
│   ├── handler/       # 连接精髓：实现全双工读写状态机与报文安全解析
│   ├── memory/        # 性能基石：64B 对齐的 Pool 与 Slab 分配器
│   ├── net/           # 底层驱动：io_uring 封装与 Socket RAII 管理
│   └── services/      # 业务逻辑：内建 Echo、Ping 等标准服务实现
```

---

## 快速开始

### 1. 定义业务 (零拷贝模式)
```cpp
void handle_inference(const uint8_t* in, size_t len, memory::SlabBuffer& out) {
    // 处理结果直接申请 Slab 空间并写入
    out = memory::g_slab.allocate(len); 
    std::memcpy(out.data(), processing_v, len);
    out.set_size(len);
}
```

### 2. 部署服务端
```cpp
int main() {
    net::IoLoop loop;
    rpc::Dispatcher disp;
    disp.register_handler(0x0001, handle_inference);
    
    acceptor::init(loop, 8080, disp); // 开启 8080 端口监听
    
    while(true) loop.run_once(); // 驱动事件环
}
```

## 编译环境
- **Linux 内核**: >= 5.1 (核心 io_uring 依赖)
- **编译器**: GCC 10+ / Clang 12+ (需开启 `-fcoroutines`)
- **核心库**: `liburing`

---
**作者**: Miny  
**日期**: 2026-03-02