🚀 PhotonRPC (v1.0)

📘 English | 📙 中文

---

📌 Overview

PhotonRPC is a high-performance RPC runtime implemented in C++20, designed as a communication substrate for distributed control planes.

Unlike general-purpose RPC frameworks that primarily target business logic, PhotonRPC is built to serve control paths, such as:

• Metadata services
• Schedulers and coordinators
• State management and notification mechanisms in distributed systems

v1.0 focuses on building a clean, explainable, and evolvable RPC data plane, laying a solid foundation for future control-plane capabilities.

---

🔥 Design Goals

The long-term design goals of PhotonRPC include:

• Control-plane oriented: optimized for low load, low latency, and strong consistency
• Low latency & predictability: explicit event loops and well-defined critical paths
• Explainability first: avoiding black-box abstractions, easy to learn and debug
• Natural evolution: from synchronous RPC to coroutines, consensus, and state replication

---

✨ Core Features

• High-performance networking

  • Non-blocking I/O based on epoll + Reactor pattern
  • Supports high concurrency connections

• Protocol support

  • Custom application-layer protocol (Magic + MsgID + Data)
  • Effectively handles TCP packet fragmentation and coalescing

• Serialization

  • Deep integration with Google Protobuf
  • Efficient binary serialization and deserialization

• Service runtime

  • XML-based configuration loading
  • Application-level Buffer abstraction with dynamic growth
  • Automatic service registration and reflection-based invocation

• Infrastructure

  • High-performance asynchronous logging via spdlog
  • Unit testing based on Google Test, with 90%+ coverage on critical components

---

🏗️ Architecture

(To be completed)

---

🛠️ Build & Installation

Requirements

• OS: Linux (Ubuntu 20.04+ recommended)
• Compiler: g++ >= 10.0 (C++20 support)
• CMake >= 3.10
• Protobuf (protobuf-compiler, libprotobuf-dev)

Build Steps

# 1. Clone the repository
git clone https://github.com/Raltour/PhotonRPC
cd PhotonRPC

# 2. Build with the provided script
chmod +x autobuild.sh
./autobuild.sh

# After build:
# Static library: lib/libphotonrpc.a
# Examples: bin/

---

💻 Usage Example

1. Define Service (Protobuf)

Create echo_service.proto:

syntax = "proto3";
package photonrpc;
option cc_generic_services = true;

message EchoRequest { string msg = 1; }
message EchoResponse { string msg = 1; }

service EchoService {
  rpc Echo(EchoRequest) returns (EchoResponse);
}

2. Server (Provider)

#include <photonrpc/rpc/rpc_server.h>
#include "echo_service.pb.h"

class EchoServiceImpl : public photonrpc::EchoService {
public:
    void Echo(google::protobuf::RpcController* controller,
              const photonrpc::EchoRequest* req,
              photonrpc::EchoResponse* res,
              google::protobuf::Closure* done) override {
        res->set_msg("Server Echo: " + req->msg());
        if (done) done->Run();
    }
};

int main() {
    photonrpc::RpcServer server;
    server.RegisterService(new EchoServiceImpl());
    server.Start();
    return 0;
}

3. Client (Consumer)

#include <photonrpc/rpc/rpc_channel.h>
#include "echo_service.pb.h"

int main() {
    photonrpc::RpcChannel channel("127.0.0.1", 12345);
    photonrpc::EchoService_Stub stub(&channel);

    photonrpc::EchoRequest req;
    req.set_msg("Hello PhotonRPC!");
    photonrpc::EchoResponse res;
    photonrpc::RpcController controller;

    stub.Echo(&controller, &req, &res, nullptr);

    if (!controller.Failed()) {
        std::cout << "Success: " << res.msg() << std::endl;
    }
    return 0;
}

---

📊 Benchmark

Single-threaded Reactor, Echo RPC (100B payload):

• Environment: Ubuntu 24.04, AMD Ryzen 7 8845H, 32GB RAM
• Connections: 8 concurrent connections
• QPS: ~76k
• P50 Latency: ~50us
• P95 Latency: ~500us
• P99 Latency: ~630s

This benchmark serves as a baseline measurement, used to validate correctness and identify performance bottlenecks, rather than competing directly with production-grade RPC frameworks.

---

📁 Directory Structure

Click to expand

├── CMakeLists.txt
├── README.md
├── auto_build.bash
├── conf
│   └── photonrpc.xml
├── include
│   └── photonrpc
│       ├── common
│       ├── net
│       ├── protocol
│       └── rpc
├── src
├── test
└── third_party

---

🗺️ Roadmap

PhotonRPC follows an iterative development model, aiming to evolve into a modern distributed communication substrate.

• v1.0 (Current) – MVP release

  • Reactor-based networking and epoll multiplexing
  • Protobuf-based RPC and service reflection

• v1.1 – Performance & robustness

  • Deep profiling (perf / gprof), P99 latency optimization
  • ASan / Valgrind for full memory safety

• v1.2 – High-concurrency architecture

  • Multi-Reactor (One Loop Per Thread)
  • Efficient wake-up and task dispatch via eventfd

• v2.0 – Asynchronous programming

  • C++20 coroutine-based RPC (co_await)
  • Eliminating callback-style async programming

• v3.0 – Control plane evolution

  • Simplified Raft consensus (leader election, log replication)
  • From RPC data plane to a replicated control plane for metadata services

• v4.0 – Heterogeneous transport (RDMA)

  • Transport abstraction with RDMA (RoCE v2)
  • Kernel-bypass and zero-copy for microsecond-level latency

---

📚 Third-party Libraries

Library	Purpose	License
spdlog	High-performance asynchronous logging	MIT
tinyxml2	Lightweight XML parser for configuration	zlib
GoogleTest	Unit and integration testing framework	BSD-3-Clause