QB Actor Framework: High-Performance C++17 for Concurrent & Distributed Systems

Unlock the power of modern C++ for complex concurrent applications. QB is an actor-based framework meticulously engineered for developers seeking exceptional performance, scalability, and a more intuitive way to manage concurrency.

QB simplifies the art of building responsive, real-time systems, network services, and distributed computations by harmonizing the robust Actor Model with a high-efficiency Asynchronous I/O Engine. Focus on your application's logic; let QB handle the intricacies of parallelism and non-blocking I/O.

Quick Start with QB

Using the Project Generator

The fastest way to get started with QB is to use our boilerplate project generator:

Using cURL:

curl -o- https://raw.githubusercontent.com/isndev/qb/main/script/qb-new-project.sh | bash /dev/stdin MyProject

Using Wget:

wget -qO- https://raw.githubusercontent.com/isndev/qb/main/script/qb-new-project.sh | bash /dev/stdin MyProject

Build and run:

cd MyProject
cmake -DCMAKE_BUILD_TYPE=Release -B build
cd build && make
./my_project

Your First Actor in 30 Seconds

#include <qb/main.h>
#include <qb/actor.h>

// Define an event
struct GreetingEvent : qb::Event {
    qb::string message;
    GreetingEvent(std::string msg) : message(std::move(msg)) {}
};

// Define an actor
class GreeterActor : public qb::Actor {
public:
    bool onInit() final {
        registerEvent<GreetingEvent>(*this); // register event
        push<GreetingEvent>(id(), "Hello !"); // send to self 
        return true;
    }

    void on(const GreetingEvent& event) {
        qb::io::cout() << "Received: " << event.message << std::endl;
        kill(); // Job done, kill me
    }
};

int main() {
    qb::Main engine;
    auto actor_id = engine.addActor<GreeterActor>(0); // add actor to core 0
    
    engine.start();
    engine.join();
    return 0;
}

That's it! No mutexes, no thread management, no race conditions. Just pure actor communication.

Why QB Changes Everything

Multithreading Without the Pain

Traditional multithreading is complex, error-prone, and hard to debug. QB's actor model eliminates these problems:

// Traditional approach: Complex threading with mutexes
std::mutex mtx;
std::queue<Task> shared_queue;
std::condition_variable cv;

// QB approach: Clean actor communication
push<TaskEvent>(worker_actor, task_data);

Benefits:

No Shared State: Each actor owns its data, eliminating race conditions
No Mutexes: Actors communicate via messages, not shared memory
No Deadlocks: Sequential message processing per actor
Automatic Scaling: Distribute actors across CPU cores effortlessly

Cross-Platform by Design

QB runs everywhere your C++17 compiler can reach:

Platforms:

Linux (Ubuntu 18.04+, RHEL 7+, Alpine Linux)
macOS (10.14+, Intel & Apple Silicon)
Windows (Windows 10+, MSVC 2017+, MinGW)

Architectures:

x86_64 (Intel/AMD 64-bit)
ARM64 (ARMv8, Apple M1/M2, Raspberry Pi 4+)

Same code, same performance, everywhere.

Performance That Scales

QB is built for speed from the ground up:

// Distribute work across all CPU cores automatically
qb::Main engine;

auto num_cores = std::thread::hardware_concurrency();
// Add worker actors to different cores
for (int i = 0; i < num_cores; ++i) {
    engine.addActor<WorkerActor>(i);
}

// Lock-free message passing between cores
// Linear scaling with CPU count

Simplicity Meets Power

Simple APIs for complex problems:

// HTTP Server in 10 lines
class HttpActor : public qb::Actor, public qb::http::Server<> {
    bool onInit() final {
        router().get("/api/status", [](auto ctx) {
            ctx->response().body() = R"({"status": "ok"})";
            ctx->complete();
        });
        
        router().compile();
        if (!listen({"tcp://0.0.0.0:8080"}))
            return false;

        start(); // start async io
        return true;
    }
};

QB Modules Ecosystem

Extend QB's capabilities with our official modules:

Network & Communication

qbm-http - HTTP/1.1 & HTTP/2 client/server with routing, middleware, authentication
qbm-websocket - WebSocket protocol implementation (RFC 6455 compliant)

Database Integration

qbm-pgsql - Asynchronous PostgreSQL client with prepared statements and transactions
qbm-redis - Comprehensive Redis client supporting all data types and clustering

Adding Modules

# Add any module as a submodule
git submodule add https://github.com/isndev/qbm-http qbm/http

# CMakeLists.txt - Automatic module discovery
qb_load_modules("${CMAKE_CURRENT_SOURCE_DIR}/qbm")
target_link_libraries(my_app PRIVATE qbm::http)

// Use immediately
#include <http/http.h>

Core Features

Actor System (qb-core):

Lightweight actors with automatic lifecycle management
Type-safe event system with guaranteed message ordering
Efficient inter-core communication using lock-free queues
Built-in patterns: Service actors, periodic tasks, supervisors

Asynchronous I/O (qb-io):

Non-blocking TCP, UDP, and SSL/TLS networking
Extensible protocol framework with built-in parsers
File system watching and OS signal handling
Cross-platform event loop powered by libev

Performance & Scalability:

Multi-core distribution with CPU affinity control
Zero-copy message passing where possible
Cache-friendly data structures and minimal allocations

Developer Experience:

Modern C++17 with clean, expressive APIs
Extensive utility library (time, crypto, compression, containers)
Comprehensive documentation and examples

Build Information

Build Requirements

C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
CMake 3.14+
Git (for submodules)

Optional Dependencies

OpenSSL 1.1+ - SSL/TLS support, cryptographic functions
Argon2 - Password hashing and key derivation functions
Zlib - Compression features available

Building from Source

# Clone with submodules
git clone --recursive https://github.com/isndev/qb.git
cd qb

# Configure build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release \
      -DQB_IO_WITH_SSL=ON \
      -DQB_IO_WITH_ZLIB=ON \
      ..

# Build (parallel)
make -j$(nproc)  # Linux/macOS
# or
cmake --build . --parallel  # Cross-platform

CMake Configuration Options

| Option | Description | Default | |-----------------------|-------------|---------| | QB_IO_WITH_SSL | Enable SSL/TLS support | ON (if found) | | QB_IO_WITH_ZLIB | Enable compression support | ON (if found) | | QB_LOGGER | Enable high-performance logging | ON | | QB_BUILD_TESTS | Build unit tests | OFF | | QB_BUILD_BENCHMARKS | Build benchmark tests | OFF |

Platform-Specific Notes

Windows (Visual Studio):

cmake -G "Visual Studio 16 2019" -A x64 ..
cmake --build . --config Release

Windows (MinGW):

cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release ..
mingw32-make -j4

macOS (Xcode):

cmake -G Xcode ..
cmake --build . --config Release

Learn with Examples

Practical Examples Repository

# Add examples to any QB project
git submodule add https://github.com/isndev/qb-examples examples
add_subdirectory(examples)

Example categories:

Basic Patterns - Actor communication, lifecycle, timers
Network Applications - TCP servers, HTTP APIs, WebSocket chat
Database Integration - PostgreSQL and Redis patterns
Performance Examples - High-throughput systems, load balancing
Real-World Projects - Trading systems, distributed computing

Documentation Structure

The documentation is organized in these main sections:

readme/1_introduction/ - Philosophy and design principles
readme/2_core_concepts/ - Actors, events, async I/O, concurrency
readme/3_qb_io/ - Asynchronous I/O library details
readme/4_qb_core/ - Actor engine and messaging
readme/5_core_io_integration/ - How core and I/O work together
readme/6_guides/ - Practical patterns and performance tuning
readme/7_reference/ - API reference and FAQ

Advanced Documentation

For comprehensive technical documentation, implementation details, and in-depth framework guides:

📖 Complete QB Framework Documentation

This detailed documentation covers:

Introduction - Framework philosophy, design principles, and architectural overview
Core Concepts - Actor model, event system, concurrency patterns, and async I/O fundamentals
QB-IO Module - Asynchronous I/O library, networking, protocols, streams, and utilities
QB-Core Module - Actor engine, messaging system, lifecycle management, and patterns
Core-IO Integration - How the actor system integrates with async I/O operations
**[

Qb

Install / Use

README