A Modern C++ Remote Procedure Call Library for High-Performance Distributed Systems
Canopy enables type-safe communication across execution contexts including in-process calls, inter-process communication, remote machines, embedded devices, and secure enclaves (SGX).
Note this is in Beta including the documentation and is in active development
- 🔒 Type-Safe: Full C++ type system integration with compile-time verification
- 🌐 Transport Agnostic: Local, TCP, SPSC, SGX Enclave, and custom transports
- 📦 Format Agnostic: JSON, YAS binary, Protocol Buffers support
- 🔄 Bi-Modal Execution: Same code runs in both blocking and coroutine modes
- 🛡️ SGX Enclave Support: Secure computation in Intel SGX enclaves
- 📊 Comprehensive Telemetry: Sequence diagrams, console output, HTML animations
- 🔧 Coroutine Library Agnostic: libcoro, libunifex, cppcoro, Asio (see 13-coroutine-libraries.md)
- 🧪 AddressSanitizer Support: Full ASan integration with 972 tests passing (100% memory safety validated)
Comprehensive documentation is available in the documents/ directory:
- Introduction - What is Canopy and its key features
- Core Concepts - Zones, services, smart pointers, proxies, and stubs
- IDL Guide - Interface Definition Language syntax and usage
- Transports - Local, TCP, SPSC, and SGX enclave transports
- Building Canopy - Build configuration and CMake presets
- Getting Started Tutorial - Step-by-step tutorials
- Bi-Modal Execution - Blocking and coroutine modes
- Error Handling - Error codes and handling patterns
- Telemetry - Debugging and visualization
- Memory Management - Reference counting and lifecycle
- Zone Hierarchies - Complex distributed topologies
- API Reference - Quick reference for main APIs
- Coroutine Libraries - Coroutine library support and porting
- Examples - Working examples and demos
- Best Practices - Design guidelines and troubleshooting
- Migration Guide - Upgrading from older versions
- YAS Serializer - Binary, JSON, and compressed formats
- Protocol Buffers - Cross-language serialization
- C++17 Compiler: Clang 10+, GCC 9.4+, or Visual Studio 2019+
- CMake: 3.24 or higher
- Build System: Ninja (recommended)
- Node.js: 18+ (for llhttp code generation)
- OpenSSL: Development headers (libssl-dev on Linux, OpenSSL SDK on Windows)
# Clone and configure
git clone https://github.com/edwardbr/Canopy.git
cd Canopy
# Choose Blocking
cmake --preset Debug
# Or Coroutines
cmake --preset Coroutine_Debug
# Or with AddressSanitizer (memory safety testing)
cmake --preset Debug_ASAN
cmake --preset Coroutine_Debug_ASAN
# Build core library
cmake --build build_debug --target rpc
# Run tests
ctest --test-dir build_debug --output-on-failure
# Run individual tests with ASan (recommended)
tests/scripts/run_asan_tests.sh# Execution mode
CANOPY_BUILD_COROUTINE=ON # Enable async/await support (requires C++20)
# Features
CANOPY_BUILD_ENCLAVE=ON # SGX enclave support
CANOPY_BUILD_TEST=ON # Test suite
CANOPY_BUILD_DEMOS=ON # Demo applications
# Development
CANOPY_USE_LOGGING=ON # Comprehensive logging
CANOPY_USE_TELEMETRY=ON # Debugging and visualization
CANOPY_DEBUG_GEN=ON # Code generation debugging
# Memory Safety
CANOPY_DEBUG_ADDRESS=ON # AddressSanitizer (detect memory errors)
CANOPY_DEBUG_THREAD=ON # ThreadSanitizer (detect data races)
CANOPY_DEBUG_UNDEFINED=ON # UndefinedBehaviorSanitizercalculator.idl:
namespace calculator {
[inline] namespace v1 {
[status=production]
interface i_calculator {
int add(int a, int b, [out] int& result);
};
}
}Usage:
#include "generated/calculator/calculator.h"
// Create service and connect to calculator zone
auto root_service = std::make_shared<rpc::service>("root", rpc::zone{1});
rpc::shared_ptr<calculator::v1::i_calculator> calc;
auto error = CO_AWAIT root_service->connect_to_zone<...>(
"calc_zone", rpc::zone{2}, nullptr, calc, setup_callback);
// Make RPC call
int result;
error = CO_AWAIT calc->add(5, 3, result);
std::cout << "5 + 3 = " << result << std::endl; // Output: 5 + 3 = 8| Transport | Description | Requirements |
|---|---|---|
| Local | In-process parent-child communication | None |
| TCP | Network communication between machines | Coroutines |
| SPSC | Single-producer single-consumer queues | Coroutines |
| SGX Enclave | Secure enclave communication | SGX SDK |
| Custom | User-defined transport implementations | Custom implementation |
See 04-transports.md for details.
- Windows: Visual Studio 2019+
- Linux: Ubuntu 18.04+, CentOS 8+
- Embedded: Any platform with C++17 support
- Clang: 10.0+
- GCC: 9.4+
- MSVC: Visual Studio 2019+
Git submodules manage external dependencies:
- YAS: Serialization framework
- libcoro: Coroutine support (when
CANOPY_BUILD_COROUTINE=ON) - range-v3: Range library support
- spdlog: Logging framework
canopy/
├── rpc/ # Core RPC library
├── generator/ # IDL code generator
├── transports/ # Transport implementations (local, tcp, spsc, sgx)
├── tests/ # Test suite
├── demos/ # Example applications
├── telemetry/ # Telemetry and logging
├── cmake/ # CMake build configuration modules
│ ├── Canopy.cmake # Main build configuration
│ ├── Linux.cmake # Linux-specific settings
│ ├── Windows.cmake # Windows-specific settings
│ ├── SGX.cmake # SGX enclave support
│ └── CanopyGenerate.cmake # IDL code generation
├── documents/ # Comprehensive documentation
├── submodules/ # External dependencies
└── CMakeLists.txt # Build configuration
This project uses cmake-format for CMake files and clang-format for C++ files.
Install cmake-format (version 0.6.13 required):
pip install cmake-format==0.6.13VSCode Setup:
- Open the project in VSCode
- Install recommended extensions when prompted (or manually install
cheshirekow.cmake-format) - The workspace settings will automatically use
.cmake-format.yamlfor formatting - Format-on-save is enabled by default
Manual formatting:
# Check CMake formatting
git ls-files -- \*.cmake \*CMakeLists.txt | xargs cmake-format --check
# Apply CMake formatting
git ls-files -- \*.cmake \*CMakeLists.txt | xargs cmake-format -i
# Apply C++ formatting
clang-format -i <file>Canopy is actively maintained.
- Performance optimizations
- New transport implementations
- Platform ports
- Documentation improvements
Copyright (c) 2026 Edward Boggis-Rolfe. All rights reserved.
See LICENSE for details.
SHA3 Implementation: Credit to brainhub/SHA3IUF
For technical questions and detailed API documentation, see the documents directory.