Skip to content

README.md

Latest commit

 

History

History
484 lines (338 loc) · 19.5 KB

README.md

File metadata and controls

484 lines (338 loc) · 19.5 KB
Raw

Areg SDK Home

Areg SDK Documentation

Welcome to the Areg SDK Technical Documentation. This wiki provides comprehensive guides, tutorials, and reference materials for building distributed, service-oriented C++ applications with the Areg Framework.

Areg Framework is an interface-centric C++ framework for building real-time, asynchronous, and distributed systems in embedded, desktop, cloud, and mist-computing environments.

Quick Start

Never used Areg SDK? Start here:

  1. Quick Project Setup ⭐ Create a working project in 30 seconds
  2. Build Areg SDK - Build from source (5-10 minutes)
  3. Install with vcpkg - Use package manager (fastest)
  4. Examples and Tests - Run sample applications
  5. Performance Benchmarks - Measured latency, throughput, and data rate across platforms

Already familiar? Jump to: Documentation by Topic | Search by Task | Search by Role

What is Areg SDK?

Areg SDK is a lightweight framework for building distributed micro-services in C++. Applications expose and consume services across process and network boundaries with automatic message routing, type-safe interfaces, and zero manual synchronization.

Key Features

  • ✅ Service-Oriented Architecture: Define services, implement providers, connect consumers
  • ✅ Automatic Message Routing: Built-in IPC and network communication
  • ✅ Type-Safe Interfaces: Compile-time verified service contracts
  • ✅ Zero Manual Threading: Framework handles all synchronization
  • ✅ Cross-Platform: Linux, Windows, macOS, embedded systems
  • ✅ Real-Time Logging: Centralized monitoring and diagnostics

Why Areg SDK?

Traditional Approach:

// Manual threading, locks, networking code
std::mutex mtx;
void handleRequest() {
    std::lock_guard<std::mutex> lock(mtx);
    // Complex synchronization logic...
}

With Areg SDK:

// Define interface, framework handles everything
virtual void request_greeting(const String& name) override {
    response_greeting("Hello, " + name + "!");
}

No locks. No threads. No networking code. Just business logic.

Documentation by Topic

📦 Installation and Build

Get Areg SDK running on your system:

Guide Platform Method Time
Quick Project Setup ⭐ All Interactive tool 30 sec
vcpkg Installation All Package manager 5 min
CMake Build Linux, Windows, macOS Source build 10 min
MSVC Build Windows Visual Studio 5 min
WSL Build Windows Linux on Windows 10 min

🔧 Integration and Configuration

Integrate Areg SDK into your projects:

CMake Projects:

Visual Studio Projects:

Advanced Configuration:

🌐 Networking and Communication

Configure distributed communication:

📊 Logging and Monitoring

Centralized logging for distributed systems:

Configuration:

Development:

Runtime Tools:

Recorded Logs:

💾 Persistence

Configuration and data persistence:

🛠️ Development Tools

Tools that accelerate development:

Core Tools:

Lusan - Visual Development Tool:

🔍 Troubleshooting

Solutions for common issues:

Platform-Specific:

Integration:

Networking:

📚 Examples and Demos

Hands-on learning resources:

Official Examples:

Benchmark Examples:

Demo Projects:

📊 Performance and Benchmarks

Areg SDK is built on a performance mandate: latency, throughput, stability, and security are primary design constraints – not secondary concerns. Every IPC path is measured on production code – service discovery, routing, dispatch, and serialization all active. Nothing is stripped for the benchmark.

Run the benchmarks on your own hardware and share results. Community measurements from diverse hardware help the project and may be published here. If you find a performance regression, open a GitHub issue – regressions are treated as bugs.

Measured results:

  • areg-sdk Performance Benchmarks – Full latency and throughput data across Linux, Windows, and macOS. Includes methodology, timestamp placement, and reproduction instructions.
  • areg-sdk vs ZMQ / NanoMsg / NNG – Direct TCP comparison against the Hitachi Energy Research benchmark (arXiv:2508.07934v1), using raw CSV data.
  • areg-sdk Framework Rankings – Competitive position across latency, message rate, and data rate versus all known frameworks with cited sources.

📁 Prefix note: These files use the 08 prefix alongside examples, since benchmarks run via examples 23 and 30. If additional benchmark documents are added, a dedicated 09 prefix is recommended.

Reproduce the results:

Quick Navigation by Task

I want to...

...get started quickly

→ Quick Project Setup (30 seconds)
→ Build Areg SDK (10 minutes)
→ Run First Example

...install Areg SDK

→ vcpkg Installation (package manager)
→ CMake Build (from source)
→ MSVC Build (Visual Studio)

...integrate Areg into my project

→ CMake Integration (CMake projects)
→ MSVC Integration (Visual Studio projects)
→ CMake Functions (helper functions)

...design service interfaces

→ Service Interface Design (visual editor)
→ Code Generator (automated code generation)

...monitor logs from distributed apps

→ Live Log Monitoring (Lusan GUI)
→ Log Observer (command-line tool)

...debug a problem

→ Log Analysis (offline logs)
→ Log Database Format (query recorded logs with SQL)
→ Troubleshooting Guides (common issues)

...configure logging and services

→ Logging Configuration (scopes and priorities)
→ Areg Configuration Reference (areg.init file)

...build for embedded systems

→ CMake Cross-Compilation (ARM, etc.)
→ CMake Troubleshooting (build issues)

...increase message and data streaming

→ Low-Latency TCP Tuning (GBytes data and 1M messages per second)

...measure or validate performance

→ Performance Benchmarks – latency and throughput data with methodology
→ vs ZMQ / NanoMsg / NNG – direct TCP comparison (Hitachi paper)
→ Framework Rankings – competitive position table
→ Run 30_publatency – reproduce latency measurements
→ Run 23_pubdatarate – reproduce throughput measurements

Quick Navigation by Role

👨‍💻 Application Developer

Getting Started:

  1. Quick Project Setup - Create your first project
  2. Examples - Learn from working code
  3. Service Interface Design - Create service contracts

Development:

Debugging:

🏗️ System Architect

Architecture:

Integration:

Tools:

🚀 DevOps Engineer

Build and Deploy:

Monitoring:

Troubleshooting:

🧪 QA Engineer

Testing:

Log Analysis:

Tools:

Architecture and Core Concepts

Service-Oriented Architecture

Areg SDK implements a Service Provider-Consumer model:

  • Service Interface: Contract defined in .siml files
  • Service Provider: Implements the service (server)
  • Service Consumer: Uses the service (client)
  • Message Router: Handles automatic routing and synchronization

Communication Patterns

Local Services (Multithreading):

  • Communication between threads in the same process
  • Zero-copy optimization
  • Automatic synchronization

IPC Services (Multiprocessing):

  • Communication between processes
  • Automatic serialization/deserialization
  • Network-transparent

Remote Services (Networking):

  • Communication across network boundaries
  • Same API as local/IPC services
  • Automatic message routing

Key Components

Your Application
    ↓ uses
Service Interface (.siml)
    ↓ generates (codegen.jar)
Service Provider/Consumer Code
    ↓ links
Areg Framework (libareg)
    ↓ communicates via
Message Router (mtrouter)
    ↓ monitored by
Log Collector (logcollector)
    ↓ visualized in
Lusan GUI

Platform Support

Platform Status Compilers Architectures
Linux ✅ Fully Supported GCC, Clang x86, x86_64, ARM, ARM64
Windows ✅ Fully Supported MSVC, MinGW, Clang x86, x86_64
macOS ✅ Fully Supported Clang, GCC x86_64, ARM64
WSL ✅ Fully Supported GCC, Clang x86_64, ARM64
Embedded Linux ✅ Supported GCC (cross-compile) ARM, ARM64, MIPS

Community and Support

Get Help

Contributing

Help improve the documentation:

Found an issue?

  • Submit a pull request
  • Open a discussion
  • Create an issue

Want to contribute?

  • Improve existing documentation
  • Add missing examples
  • Translate documentation
  • Share your use cases

Stay Updated

Additional Resources

Example Projects

External Tools

Documentation

Next Steps

For First-Time Users

  1. ✅ Quick Project Setup - Create working project (30 sec)
  2. ✅ Run Examples - See Areg SDK in action (5 min)
  3. ✅ Design Services - Create your first service (10 min)
  4. ✅ Build Edge AI Demo - Real-world application (20 min)

For Experienced Developers

  1. ✅ CMake Integration - Integrate into existing projects
  2. ✅ CMake Functions - Advanced build configuration
  3. ✅ Log Monitoring - Setup production logging
  4. ✅ Cross-Compilation - Build for embedded systems

For Team Leads

  1. ✅ Architecture Overview - Understand service model
  2. ✅ Toolchain Overview - Complete development tools
  3. ✅ CI/CD Setup - Automated builds
  4. ✅ Troubleshooting - Common issues

For Testing

  1. ✅ Low-Latency TCP Network Tuning - Guide for High-Performance Networking
  2. ✅ Performance Benchmarks - Reference results and methodology
  3. ✅ Run 30_publatency - Reproduce latency on your hardware
  4. ✅ Run 23_pubdatarate - Reproduce throughput on your hardware

Ready to build distributed applications?
Start with Quick Project Setup or explore Examples!

Copyright © 2023–2026 Aregtech (Artak Avetyan)
https://www.areg.tech
Contact: info[at]areg.tech