DEV Community: ISNDEV

Caching, Queuing, and Pub/Sub: Supercharging Your C++ App with Redis and `qbm-redis`

ISNDEV — Wed, 11 Jun 2025 07:39:01 +0000

Redis is more than a cache; it's a multi-tool for building high-performance systems. Discover how qb's asynchronous qbm-redis client makes it easy to leverage Redis for caching, message queuing, and real-time Pub/Sub in your C++ applications.

Target Audience: Intermediate to Advanced C++ developers building systems that require caching, job queues, or real-time messaging.

GitHub: https://github.com/isndev/qbm-redis

In modern distributed systems, performance and scalability often depend on fast access to data and efficient communication between components. Redis, the in-memory data structure store, is the industry standard for solving these problems.

The qbm-redis module brings the full power of Redis to the qb actor framework with a clean, asynchronous, and type-safe C++ client. It allows your actors to interact with Redis without ever blocking, enabling you to build incredibly responsive and scalable systems.

Let's explore three common patterns where qbm-redis shines.

1. High-Performance Caching

The most common use for Redis is as a distributed cache to reduce database load and speed up response times. qbm-redis makes this trivial.

The pattern is simple: before making an expensive database call or computation, check the cache.

// In a qb::Actor that needs to fetch user data...
#include <redis/redis.h>

class UserDataService : public qb::Actor {
private:
    qb::redis::tcp::client _redis{"tcp://localhost:6379"};
    // ... database connection member ...

public:
    bool onInit() override {
        if (!_redis.connect()) {
            qb::io::cerr() << "Failed to connect to Redis" << std::endl;
            return false;
        }
        // ...
        return true;
    }

    void handle_user_request(int user_id) {
        std::string cache_key = "user:" + std::to_string(user_id);

        // 1. Check the cache first (using async call with callback)
        _redis.get(cache_key, [this, user_id, cache_key](auto&& reply) {
            if (reply.ok() && reply.result().has_value()) {
                // Cache hit! Use the cached data.
                qb::io::cout() << "Cache HIT for user " << user_id << std::endl;
                std::string user_json = *reply.result();
                // ... process user_json and send response ...
                return;
            }

            // 2. Cache miss. Fetch from the database (this would be another async call).
            qb::io::cout() << "Cache MISS for user " << user_id << ". Fetching from DB." << std::endl;
            std::string data_from_db = "{\"id\": " + std::to_string(user_id) + ", \"name\": \"Alice\"}";

            // 3. Store the result in the cache for next time with an expiration.
            //    SETEX sets a key with a Time-To-Live (TTL).
            _redis.setex(cache_key, 300, data_from_db); // Cache for 5 minutes

            // ... process data_from_db and send response ...
        });
    }
};

This simple pattern can dramatically improve your application's performance by offloading work from your primary database.

2. Reliable Job Queues with Lists

How do you distribute work among a pool of worker actors? A Redis List is a perfect tool for a reliable job queue. Producers LPUSH jobs onto one end of the list, and workers use BRPOP (blocking list pop) to atomically pull jobs from the other end.

BRPOP is a blocking command, but when used with qbm-redis in a qb actor, it's non-blocking from the framework's perspective. The actor remains responsive to other events while waiting for a job.

Based on examples/qbm/redis/example3_list_operations.cpp

// In a WorkerActor...
#include <redis/redis.h>

class WorkerActor : public qb::Actor, public qb::ICallback {
private:
    qb::redis::tcp::client _redis{"tcp://localhost:6379"};
    const std::string _queue_key = "jobs:image_processing";

public:
    bool onInit() override {
        _redis.connect();
        registerCallback(*this); // Periodically check for jobs
        return true;
    }

    // Periodically check for a new job
    void onCallback() override {
        // Use BRPOP with a timeout of 1 second.
        // The callback-based version is ideal here.
        _redis.brpop({_queue_key}, 1, [this](auto&& reply) {
            if (reply.ok() && reply.result().has_value()) {
                // Job received! The result is a pair of {key, value}
                auto& job_data = reply.result()->second;
                qb::io::cout() << "Worker " << id() << " processing job: " << job_data << std::endl;
                // ... do the actual work ...
            } else {
                // No job received in the last second.
                qb::io::cout() << "Worker " << id() << ": No jobs in queue." << std::endl;
            }
        });
    }
};

// In a ProducerActor...
void submit_job(const std::string& job_data) {
    // LPUSH pushes to the head of the list.
    _redis.lpush("jobs:image_processing", job_data);
}

3. Real-Time Messaging with Publish/Subscribe

For broadcasting real-time events, Redis Pub/Sub is a powerful and simple solution. Publishers send messages to a "channel" without knowing who, if anyone, is listening. Subscribers express interest in one or more channels and receive messages as they are published.

qbm-redis provides a specialized cb_consumer client for handling subscriptions efficiently.

Based on examples/qbm/redis/example5_pubsub_example.cpp

#include <redis/redis.h>

// 1. The Subscriber Actor
class SubscriberActor : public qb::Actor {
private:
    // The cb_consumer takes a callback in its constructor for handling messages.
    qb::redis::tcp::cb_consumer _consumer{"tcp://localhost:6379", 
        [this](auto&& msg) {
            // This lambda is called by the consumer when a message arrives
            qb::io::cout() << "Subscriber " << id() << " received on '" 
                           << msg.channel << "': " << msg.message << std::endl;
        }
    };
public:
    bool onInit() override {
        _consumer.connect();
        // Subscribe to a channel
        _consumer.subscribe("app:notifications");
        return true;
    }
};

// 2. The Publisher Actor
class PublisherActor : public qb::Actor {
private:
    qb::redis::tcp::client _redis{"tcp://localhost:6379"};
public:
    bool onInit() override {
        _redis.connect();
        return true;
    }

    void send_notification(const std::string& message) {
        // Publish a message to the channel
        long subscribers_count = _redis.publish("app:notifications", message);
        qb::io::cout() << "Published notification to " << subscribers_count 
                       << " subscribers." << std::endl;
    }
};

This pattern is perfect for building real-time dashboards, chat systems, or any application where components need to react instantly to events happening elsewhere in the system.

With qbm-redis, you can easily integrate these powerful Redis patterns into your high-performance C++ actor system, building applications that are fast, scalable, and resilient.

Explore the qbm-redis module on GitHub:

https://github.com/isndev/qbm-redis
Full Examples: https://github.com/isndev/qb-examples/tree/main/examples/qbm/redis

Building a REST API in C++: Advanced Routing & Middleware with `qbm-http`

ISNDEV — Wed, 11 Jun 2025 07:25:47 +0000

Go beyond "Hello World." Learn how to build a feature-rich REST API in C++ with qbm-http, leveraging path parameters, powerful middleware, and the clean controller pattern for organized, maintainable code.

Target Audience: Intermediate to Advanced C++ developers building web APIs.

GitHub: https://github.com/isndev/qbm-http

A modern web framework needs more than just basic request handling. It needs a robust routing system, a way to handle cross-cutting concerns cleanly, and patterns for organizing code as an application grows. qbm-http provides all of these with a focus on performance and C++ language elegance.

In this article, we'll explore three powerful features: parameterized routing, middleware, and the controller pattern.

1. Expressive Routing: Parameters and Wildcards

Real-world APIs need to handle dynamic URLs, like fetching a user by their ID (/users/123). qbm-http's router makes this trivial.

Path Parameters: Use a colon (:) to define a named parameter.
Wildcard Routes: Use an asterisk (*) to catch all subsequent path segments.

The values are easily accessible inside your handler via the ctx->path_param("name") method.

// From examples/qbm/http/03_basic_routing.cpp

// GET /api/users/:id
router().get("/api/users/:id", [this](auto ctx) {
    // Retrieve the 'id' parameter from the path
    int user_id = std::stoi(ctx->path_param("id"));

    // ... find user by ID and send response ...
});

// GET /files/images/avatars/user.png
router().get("/files/*filepath", [this](auto ctx) {
    // 'filepath' will contain "images/avatars/user.png"
    std::string path = ctx->path_param("filepath");

    // ... serve the file from the filesystem ...
});

2. Middleware: The Power of Composition

Middleware functions are the heart of a modern web framework. They are small, reusable handlers that inspect or modify a request before it reaches your main logic, or modify the response on its way out. They form a chain, processing requests in a specific order.

qbm-http's middleware is implemented as a simple lambda that receives the Context and a next function. You call next() to pass control to the next middleware in the chain.

This is perfect for:

Logging: Recording every incoming request.
Authentication: Checking for a valid JWT or API key.
CORS: Adding cross-origin resource sharing headers.
Compression: Gzip/deflate encoding responses.
Caching: Adding cache-control headers.

Here is a corrected example of a logging and timing middleware that correctly handles asynchronous operations using LifecycleHook.

// A single middleware for logging and timing, demonstrating the correct async pattern.
router().use([](auto ctx, auto next) {
    // 1. Store the start time in the context. This is safe across async boundaries.
    ctx->set("start_time", std::chrono::high_resolution_clock::now());

    std::cout << "[LOG] Request Start: " << ctx->request().method()
              << " " << ctx->request().uri().path() << std::endl;

    // 2. Add a lifecycle hook. This lambda will be executed by the framework
    //    just before the response is sent to the client.
    ctx->add_lifecycle_hook([](auto& context, auto point) {
        // We only care about the point just before sending the response.
        if (point != qb::http::routing::HookPoint::PRE_RESPONSE_SEND) {
            return;
        }

        // 3. Calculate the duration now that we know the response is ready.
        auto start_time_any = context.template get<std::chrono::high_resolution_clock::time_point>("start_time");
        if (start_time_any) {
            auto end_time = std::chrono::high_resolution_clock::now();
            auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end_time - *start_time_any);

            // Add the timing header to the final response.
            context.response().add_header("X-Response-Time-us", std::to_string(duration.count()));

            std::cout << "[LOG] Request End: " << context.request().method()
                      << " " << context.request().uri().path()
                      << " -> " << context.response().status().code()
                      << " in " << duration.count() << "us" << std::endl;
        }
    });

    // 4. Pass control to the next middleware or route handler.
    //    If the handler is async, this call returns immediately.
    next();
});

// A simple authentication middleware for a specific group of routes
auto protected_group = router().group("/api");
protected_group->use([](auto ctx, auto next) {
    std::string token = ctx->request().header("Authorization");

    if (token != "Bearer secret-token-123") {
        ctx->response().status() = qb::http::Status::UNAUTHORIZED;
        ctx->response().body() = R"({"error": "Invalid token"})";
        // Stop processing and send the response immediately
        ctx->complete(); 
        return;
    }

    // Token is valid, proceed to the handler
    next();
});

protected_group->get("/profile", [](auto ctx) { /* ... user profile logic ... */ });

3. The Controller Pattern: Organizing Your API

As your API grows, putting all your logic into a single server class becomes unmanageable. The Controller pattern solves this by grouping related routes into dedicated classes.

A qb::http::Controller is a class that inherits from IHandlerNode and defines its own routes. You can then "mount" this controller on a specific path prefix in your main router.

From examples/qbm/http/05_controller_pattern.cpp

// 1. Define the Controller class for user-related routes
class UserController : public qb::http::Controller<qb::http::DefaultSession> {
private:
    // This controller can have its own state, e.g., a DB connection
    qb::unordered_map<int, qb::json> _users;
    int _next_id = 1;

public:
    UserController() { /* ... initialize _users ... */ }

    // This method is called by the router to set up the controller's routes
    void initialize_routes() override {
        // Define routes relative to the controller's mount point
        // e.g., if mounted at "/api/users", this becomes GET /api/users/
        get("/", MEMBER_HANDLER(&UserController::list_users));

        // This becomes GET /api/users/:id
        get("/:id", MEMBER_HANDLER(&UserController::get_user));

        // This becomes POST /api/users/
        post("/", MEMBER_HANDLER(&UserController::create_user));
    }

    // 2. Implement the route handlers as member functions
    void list_users(std::shared_ptr<qb::http::Context<qb::http::DefaultSession>> ctx) {
        // ... logic to list all users ...
        ctx->response().body() = qb::json{{"users", _users}};
        ctx->complete();
    }

    void get_user(std::shared_ptr<qb::http::Context<qb::http::DefaultSession>> ctx) {
        // ... logic to get a single user by id ...
        ctx->complete();
    }

    void create_user(std::shared_ptr<qb::http::Context<qb::http::DefaultSession>> ctx) {
        // ... logic to create a new user ...
        ctx->complete();
    }
};

// 3. In your main server actor's onInit()
class ApiServer : public qb::Actor, public qb::http::Server<> {
public:
    bool onInit() override {
        // ...
        // Mount the UserController at the "/api/users" path
        router().controller<UserController>("/api/users");

        router().compile();
        // ...
        return true;
    }
};

This pattern provides a clean separation of concerns, making your API more modular, testable, and easier to navigate.

By combining expressive routing, a flexible middleware chain, and the organizational power of controllers, qbm-http provides a robust foundation for building sophisticated, high-performance web services in C++.

Explore the qbm-http module and its examples on GitHub:

qbm-http Module: https://github.com/isndev/qbm-http
Official Examples: https://github.com/isndev/qb-examples/tree/main/examples/qbm/http

Blazing-Fast C++ Web Services with `qbm-http`

ISNDEV — Wed, 11 Jun 2025 05:06:48 +0000

Forget slow, bloated web frameworks. Learn how to build high-performance, asynchronous HTTP/1.1 and HTTP/2 servers in modern C++ using qb's powerful qbm-http module.

Target Audience: Intermediate C++ developers looking to build fast and scalable web backends.

GitHub: https://github.com/isndev/qbm-http

When you think of C++ and web servers, you might think of old, complex libraries. The qbm-http module, part of the qb actor framework, changes that. It provides a modern, expressive, and incredibly fast way to build HTTP services, from simple REST APIs to complex, real-time applications.

Built on qb-io's asynchronous, non-blocking core, qbm-http is designed for high throughput and low latency, making it perfect for performance-critical web services.

Core Features of `qbm-http`

Asynchronous by Default: Handles thousands of concurrent connections without breaking a sweat.
Expressive Routing: A powerful, fluent API for defining routes, including path parameters and wildcards.
Middleware Support: Easily add cross-cutting concerns like logging, authentication, CORS, and compression.
Controller Pattern: Organize your API into clean, reusable qb::http::Controller classes.
HTTP/2 Ready: Full support for HTTP/2, including multiplexing and server push, for modern web performance.
Seamless Integration: Works perfectly within the qb actor model, allowing your HTTP server to be just one part of a larger concurrent system.

Your First HTTP Server

Let's build a simple "Hello World" server. The entire server, with routing, fits inside a single qb actor.

The key components are:

qb::http::Server<>: A base class that gives our actor HTTP server capabilities.
router(): The entry point for defining URL endpoints.
router().get(path, handler): Defines a handler for an HTTP GET request.
ctx (Context): An object passed to every handler, containing the request, response, and session information.
listen() and start(): Methods to bind the server to a port and begin accepting connections.

From examples/qbm/http/01_hello_world_server.cpp

#include <iostream>
#include <qb/main.h>
#include <http/http.h>

// Define our HTTP server actor by inheriting from qb::Actor and qb::http::Server
class HelloWorldServer : public qb::Actor, 
                         public qb::http::Server<> {
public:
    HelloWorldServer() = default;

    // onInit is the entry point for actor initialization
    bool onInit() override {
        std::cout << "Initializing Hello World HTTP Server..." << std::endl;

        // 1. Set up a route for the root path "/"
        router().get("/", [](auto ctx) {
            ctx->response().status() = qb::http::Status::OK;
            ctx->response().add_header("Content-Type", "text/plain; charset=utf-8");
            ctx->response().body() = "Hello, World!\nWelcome to the QB HTTP Framework!";

            // 2. Signal that the request is complete
            ctx->complete();
        });

        // 3. Set up another route for a JSON response
        router().get("/hello", [](auto ctx) {
            ctx->response().status() = qb::http::Status::OK;
            ctx->response().add_header("Content-Type", "application/json");
            ctx->response().body() = R"({"message": "Hello from QB!", "framework": "qb-http"})";
            ctx->complete();
        });

        // 4. Compile the router after defining all routes
        router().compile();

        // 5. Start listening for connections on port 8080
        if (listen({"tcp://0.0.0.0:8080"})) {
            start(); // Starts the internal acceptor
            std::cout << "Server listening on http://localhost:8080" << std::endl;
            std::cout << "Routes:\n  GET /\n  GET /hello" << std::endl;
        } else {
            std::cerr << "Failed to start listening on port 8080" << std::endl;
            return false;
        }

        return true;
    }
};

int main() {
    try {
        qb::Main engine;

        // Add our server actor to the engine
        engine.addActor<HelloWorldServer>(0);

        // Start the engine and wait for it to stop (e.g., via Ctrl+C)
        engine.start();
        engine.join();

        std::cout << "Server stopped gracefully." << std::endl;

    } catch (const std::exception& e) {
        std::cerr << "Server error: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

The Power of Asynchronous Handlers

In the example above, the handlers are simple. But what if you need to query a database or call another microservice? qbm-http's asynchronous nature shines here. A handler can initiate a long-running operation and return immediately, freeing up the server thread to handle other requests. When the operation completes, its callback finishes the HTTP response.

#include <qb/io/async.h> // For qb::io::async::callback

// ... inside your server actor ...
router().get("/async/data", [](auto ctx) {
    std::cout << "Request received. Starting simulated DB query..." << std::endl;

    // Simulate a 1-second database query without blocking the server
    qb::io::async::callback([ctx]() {
        // This lambda executes after 1 second on the actor's event loop

        // Check if the request context is still valid (client might have disconnected)
        if (!ctx->session() || !ctx->session()->is_alive()) return;

        std::cout << "DB query finished. Sending response." << std::endl;

        ctx->response().status() = qb::http::Status::OK;
        ctx->response().add_header("Content-Type", "application/json");
        ctx->response().body() = R"({"data": "This data came from an async operation"})";

        // Complete the request
        ctx->complete();

    }, 1.0); // 1.0 second delay
});

This pattern allows a single-threaded qb actor to handle tens of thousands of concurrent requests that are waiting on I/O, making it incredibly efficient.

qbm-http combines the raw performance of C++ with the modern, high-level abstractions you expect from a web framework. Whether you're building a simple API or a complex distributed backend, it provides the tools to do it efficiently and elegantly.

Next Steps:

Explore qbm-http on GitHub: https://github.com/isndev/qbm-http
Check out more examples: https://github.com/isndev/qb-examples/tree/main/examples/qbm/http
Learn about routing and middleware in our next article!

Meet `qb`: The High-Performance C++17 Actor Framework You've Been Waiting For

ISNDEV — Wed, 11 Jun 2025 04:59:37 +0000

A modern, actor-based C++ framework designed for building scalable, high-performance, and resilient network applications with ease and elegance.

GitHub: https://github.com/isndev/qb

C++ has always been the king of performance, but modern systems demand more: concurrency, scalability, and maintainability. Traditional threading models with mutexes and locks are notoriously difficult to get right. What if you could write highly parallel C++ code that is both safe by design and incredibly fast?

Enter qb, a C++17 framework built on the Actor Model and asynchronous I/O. It's designed from the ground up to leverage multi-core architectures, making complex concurrency patterns feel simple and intuitive.

What is the Actor Model?

The Actor Model is a conceptual model for concurrent computation. It simplifies development by avoiding shared state. Instead of locks and shared memory, your application is built from lightweight, independent "actors."

+-----------------------------+
|         Your System         |
|                             |
|  +---------+     +---------+  <-- Events
|  | Actor A |     | Actor B ||
|  | (State) |<--->| (State) ||
|  +---------+     +---------+|
|      ^               |      |
|      | Events        | Events
|      v               v.     |
|  +---------+     +---------+|
|  | Actor C |     | Actor D ||
|  | (State) |<--->| (State) ||
|  +---------+     +---------+|
|                             |
+-----------------------------+

Each actor has:

Private State: No other actor can access its internal state directly.
A Mailbox: It receives messages (events) from other actors.
Behavior: It processes messages sequentially, one at a time.

This sequential, one-message-at-a-time processing within each actor is the key. It means you never need a mutex to protect an actor's state, eliminating a whole class of concurrency bugs like race conditions and deadlocks.

Why `qb`? The Core Philosophy

The qb framework is built on a few key principles:

Performance First: qb uses a high-performance, lock-free message queue for communication between cores. Its asynchronous I/O engine (qb-io) is built on libev, ensuring minimal overhead for network and timed operations.
Scalability by Design: By distributing actors across multiple CPU cores, qb applications scale naturally with the available hardware. You can pin actors to specific cores for cache optimization and predictable latency.
Clarity and Simplicity: qb provides high-level abstractions that hide the complexity of threading and synchronization. Writing a concurrent application feels like defining simple objects and the events they react to.
A Rich Ecosystem: qb is more than just a core framework. It comes with powerful modules (qbm) for common backend needs:
- qbm-http: Build blazing-fast HTTP/1.1 and HTTP/2 servers and clients.
- qbm-websocket: Add real-time capabilities with a fully compliant WebSocket layer.
- qbm-pgsql: A high-performance, asynchronous PostgreSQL client.
- qbm-redis: A feature-rich, asynchronous Redis client.

A Taste of `qb`: A Simple "Hello World" Actor

Let's see what a basic qb actor looks like. This example features a SimpleActor that receives a message and a SenderActor that sends it, illustrating the core actor-to-actor communication pattern.

From examples/core/example1_simple_actor.cpp

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

// 1. Define the message (event)
struct SimpleEvent : public qb::Event {
    int value;
    explicit SimpleEvent(int val) : value(val) {}
};

// 2. Define the receiving actor
class SimpleActor : public qb::Actor {
public:
    bool onInit() override {
        // Register the event handler for SimpleEvent
        registerEvent<SimpleEvent>(*this);
        qb::io::cout() << "SimpleActor: Initialized and ready." << std::endl;
        return true;
    }

    // 3. Define the event handler
    void on(const SimpleEvent& event) {
        qb::io::cout() << "SimpleActor: Received SimpleEvent with value " 
                       << event.value << std::endl;

        // After receiving the 5th event, the actor terminates itself
        if (event.value >= 5) {
            kill();
        }
    }
};

// 4. Define a sending actor
class SenderActor : public qb::Actor, public qb::ICallback {
private:
    qb::ActorId _target_id;
    int _counter = 1;

public:
    explicit SenderActor(qb::ActorId target_id) : _target_id(target_id) {}

    bool onInit() override {
        registerCallback(*this); // Register for periodic calls
        return true;
    }

    void onCallback() override {
        if (_counter > 5) {
            qb::io::cout() << "SenderActor: All events sent. Terminating." << std::endl;
            kill();
            return;
        }

        qb::io::cout() << "SenderActor: Sending event #" << _counter << std::endl;
        // Actors push messages to other actors
        push<SimpleEvent>(_target_id, _counter++);
    }
};


int main() {
    // 5. Set up and run the engine
    qb::Main engine;

    // Create the SimpleActor on core 0
    auto simple_actor_id = engine.addActor<SimpleActor>(0);

    // Create the SenderActor on core 0, giving it the SimpleActor's ID
    engine.addActor<SenderActor>(0, simple_actor_id);

    engine.start();
    engine.join();

    qb::io::cout() << "Application finished." << std::endl;
    return 0;
}

Who is `qb` For?

qb is designed for C++ developers building systems where performance, latency, and scalability are critical.

High-Frequency Trading & Finance: Low-latency order matching engines and market data systems.
Game Servers: Highly concurrent backends for multiplayer games.
IoT & Edge Computing: Efficient data processing and message brokers.
High-Performance Web Services: Scalable REST APIs, WebSocket servers, and real-time backends.
Distributed Systems: Any application requiring robust, safe communication between components.

If you're looking for a modern C++ framework that embraces concurrency without the headaches of traditional multi-threading, it's time to give qb a try.

Explore the framework on GitHub: https://github.com/isndev/qb

Check out the examples: https://github.com/isndev/qb-examples

Unlocking True Parallelism: A Guide to Multi-Core C++ with `qb`

ISNDEV — Wed, 11 Jun 2025 04:49:28 +0000

Modern CPUs have multiple cores, but writing correct, scalable parallel code is hard. Learn how the qb framework makes it trivial to distribute work across all available CPU power, turning concurrency into true parallelism.

Target Audience: Intermediate C++ developers looking to improve the performance and scalability of their applications.

GitHub: https://github.com/isndev/qb

Your C++ application might be concurrent, but is it truly parallel? Concurrency is about managing multiple tasks at once, but parallelism is about executing multiple tasks at the same time. On a multi-core CPU, this is the key to unlocking maximum performance.

The qb actor framework is designed specifically for this. It abstracts away the complexities of thread management, affinity, and inter-thread communication, allowing you to focus on your application logic while the framework handles the parallel execution.

How `qb` Manages Cores

The qb::Main engine maintains a pool of worker threads, each pinned to a specific CPU core. This is called a VirtualCore. When you create an actor, you simply tell the engine which core it should live on.

+-----------------------+      +-----------------------+      +-----------------------+
|        Core 0         |      |        Core 1         |      |        Core 2         |
|                       |      |                       |      |                       |
|  +-----------------+  |      |  +-----------------+  |      |  +-----------------+  |
|  | DispatcherActor |  |      |  |   WorkerActor A |  |      |  |   WorkerActor B |  |
|  +-----------------+  |      |  +-----------------+  |      |  +-----------------+  |
|                       |      |                       |      |                       |
+-----------|-----------+      +-----------^-----------+      +-----------^-----------+
            |                              |                          |
            |     push<WorkEvent>(...)     |                          |
            +------------------------------+--------------------------+

          Lock-Free, Inter-Core Message Queues (Transparent to Developer)

Each VirtualCore runs its own event loop, processing the mailboxes of its assigned actors. When an actor on Core 0 sends a message to an actor on Core 1, qb transparently handles the cross-core communication using high-performance, lock-free queues. You, the developer, just call push<Event>(...)—the framework does the rest.

Example: A Multi-Core Dispatcher System

Let's look at a practical example. We'll create a DispatcherActor on one core that sends work to multiple WorkerActors distributed across other available cores. This is a common pattern for load balancing and parallel processing.

From examples/core/example3_multicore.cpp

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

// Event to represent a piece of work
struct WorkEvent : public qb::Event {
    int value;
    explicit WorkEvent(int val) : value(val) {}
};

// The worker actor, designed to run on any core
class WorkerActor : public qb::Actor {
public:
    WorkerActor() {
        registerEvent<WorkEvent>(*this);
    }

    bool onInit() override {
        // Announce which core this worker is running on
        qb::io::cout() << "Worker " << id() << ": Online on core " << getIndex() << std::endl;
        return true;
    }

    void on(WorkEvent& event) {
        qb::io::cout() << "Worker " << id() << " (on core " << getIndex() 
                       << "): Processing work item " << event.value << std::endl;
        // Simulate work
        std::this_thread::sleep_for(std::chrono::milliseconds(50));
    }
};

// The dispatcher actor, which distributes work
class DispatcherActor : public qb::Actor, public qb::ICallback {
private:
    std::vector<qb::ActorId> _workers;
    int _work_item_counter = 0;

public:
    explicit DispatcherActor(std::vector<qb::ActorId> workers) : _workers(std::move(workers)) {}

    bool onInit() override {
        qb::io::cout() << "Dispatcher on core " << getIndex() 
                       << ": Managing " << _workers.size() << " workers." << std::endl;
        registerCallback(*this); // Use a periodic callback to send work
        return true;
    }

    void onCallback() override {
        if (_work_item_counter >= 20) {
            // After sending 20 items, broadcast a shutdown and terminate
            qb::io::cout() << "Dispatcher: All work sent. Broadcasting shutdown." << std::endl;
            broadcast<qb::KillEvent>(); // a system-wide shutdown event
            return;
        }

        // Distribute work in a round-robin fashion
        qb::ActorId target_worker = _workers[_work_item_counter % _workers.size()];
        push<WorkEvent>(target_worker, _work_item_counter++);
    }
};

int main() {
    // Use up to 4 hardware cores for this demo
    const unsigned int cores_to_use = std::min(4u, std::thread::hardware_concurrency());
    qb::io::cout() << "Main: Using " << cores_to_use << " cores for the demo." << std::endl;

    qb::Main engine;

    // 1. Create worker actors and distribute them across cores
    std::vector<qb::ActorId> worker_ids;
    for (unsigned int i = 0; i < (cores_to_use - 1) * 2; ++i) { // 2 workers per core
        // Assign workers to cores 1, 2, 3...
        qb::CoreId core_id = 1 + (i % (cores_to_use - 1));
        worker_ids.push_back(engine.addActor<WorkerActor>(core_id));
    }

    // 2. Create the dispatcher on a dedicated core (core 0)
    engine.addActor<DispatcherActor>(0, worker_ids);

    // 3. Start the engine and watch the parallel execution
    engine.start();
    engine.join(); // Wait for all actors to finish

    qb::io::cout() << "Main: All actors have terminated." << std::endl;
    return 0;
}

When you run this code, you'll see output from workers on different cores processing work items simultaneously. The dispatcher on Core 0 seamlessly sends messages to workers on Cores 1, 2, and 3 without any manual thread management.

Key Benefits of `qb`'s Multi-Core Approach

Effortless Parallelism: You write standard actor logic; the framework handles the parallel execution. Adding an actor to a different core is a one-line change: engine.addActor<MyActor>(core_id).
No Data Races: Because actors don't share state, you are protected from data races between actors on different cores.
Improved Cache Performance: By pinning actors to specific cores (setAffinity), you can ensure that an actor's data stays hot in its CPU core's L1/L2 cache, which is critical for low-latency applications.
Predictable Performance: Isolating critical, low-latency actors (like a matching engine) on a dedicated core prevents them from being impacted by "noisy neighbors" (other less critical tasks).

The qb framework provides the tools to easily and safely build truly parallel C++ applications, allowing you to fully harness the power of modern multi-core processors.

Explore the qb framework and its modules:

qb Core Framework: https://github.com/isndev/qb
Official Examples: https://github.com/isndev/qb-examples

Beyond Threads: A Guide to the Actor Model in C++ with `qb`

ISNDEV — Wed, 11 Jun 2025 04:46:28 +0000

Stop thinking in threads and mutexes. Start thinking in actors and messages. Discover how qb's implementation of the Actor Model simplifies concurrent programming and eliminates entire classes of bugs.

Target Audience: Beginner / Intermediate C++ developers curious about concurrent programming models.

GitHub: https://github.com/isndev/qb

If you've ever written multi-threaded C++ code, you know the pain of shared state. std::mutex, std::atomic, and std::condition_variable are powerful tools, but they're also a minefield of potential deadlocks, race conditions, and complexity.

The qb framework offers a more elegant solution: the Actor Model. Instead of sharing memory, actors share nothing. They are completely isolated, stateful entities that communicate only by sending immutable messages to each other. This fundamental design choice makes concurrent programming dramatically simpler and safer.

The Three Pillars of a `qb` Actor

Every actor in the qb framework adheres to three simple rules:

It has a private state. An actor's member variables can only be touched by the actor itself. This isolation is the cornerstone of its safety.
It has an address. Every actor has a unique qb::ActorId, which other actors use to send it messages.
It processes messages sequentially. Each actor has a "mailbox." It pulls one message at a time from this mailbox and processes it completely before moving to the next. This guarantees that an actor's internal state is never accessed concurrently.

             +-----------------+
             |   SenderActor   |
             +-----------------+
                    |
                    | sends MessageEvent(data)
                    |
+-------------------+-------------------+
|                   v                   |
|         +-----------------+           |
|         | Mailbox (Queue) |           |
|         +-----------------+           |
|         |   MessageEvent  |           |
|         |   AnotherEvent  |           |
|         |       ...       |           |
|         +-----------------+           |
|                   |                   |
|                   | process one-by-one|
|                   v                   |
|         +-----------------+           |
|         |  ReceiverActor  |           |
|         | (private state) |           |
|         +-----------------+           |
|                                       |
+---------- Core QB Framework ----------+

Request-Response: The Hello World of Actor Communication

One of the most common interaction patterns is request-response. Let's see how this works in qb with a simple example where "Sender" actors ask a "Receiver" to do some work and reply.

This example demonstrates two key concepts:

A sender pushing a message to a known destination (receiver_id).
A receiver using event.getSource() to dynamically discover the sender's address and send a reply.

From examples/core/example2_basic_actors.cpp

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

// 1. Define the request and response events
struct MessageEvent : public qb::Event {
    std::string content;
    MessageEvent(std::string msg) : content(std::move(msg)) {}
};

struct ResponseEvent : public qb::Event {
    std::string content;
    ResponseEvent(std::string msg) : content(std::move(msg)) {}
};

// 2. The ReceiverActor processes requests and sends back responses
class ReceiverActor : public qb::Actor {
public:
    ReceiverActor() {
        registerEvent<MessageEvent>(*this);
    }

    // Process a message and reply to the original sender
    void on(MessageEvent& event) { // Note: event is non-const
        qb::io::cout() << "Receiver " << id() 
                       << ": Received '" << event.content << "' from " 
                       << event.getSource() << "\n";

        // To reply, we use the source ID from the incoming event
        auto original_sender = event.getSource();
        std::string response_msg = "Acknowledged: " + event.content;

        // Push a response event back to the sender
        push<ResponseEvent>(original_sender, response_msg);
    }
};

// 3. The SenderActor sends requests and waits for responses
class SenderActor : public qb::Actor {
private:
    qb::ActorId _receiver_id;

public:
    SenderActor(qb::ActorId receiver_id) : _receiver_id(receiver_id) {
        registerEvent<ResponseEvent>(*this);
    }

    bool onInit() override {
        qb::io::cout() << "Sender " << id() << ": Sending message to receiver "
                       << _receiver_id << "\n";

        // Send a request to the receiver
        push<MessageEvent>(_receiver_id, "Hello from Sender!");
        return true;
    }

    // Handle the response from the receiver
    void on(ResponseEvent& event) {
        qb::io::cout() << "Sender " << id() 
                       << ": Received response '" << event.content 
                       << "' from " << event.getSource() << "\n";

        // Task complete, shut down
        kill();
    }
};

int main() {
    qb::Main engine;

    // Create the receiver first to get its ID
    auto receiver_id = engine.addActor<ReceiverActor>(0);

    // Create the sender and give it the receiver's ID
    engine.addActor<SenderActor>(0, receiver_id);

    engine.start();
    engine.join();

    qb::io::cout() << "Application finished." << std::endl;
    return 0;
}

Why This is a Big Deal

No Locks, No Race Conditions: Notice the complete absence of std::mutex. The ReceiverActor can be hammered with messages from hundreds of senders on different threads, and its internal state remains safe because the on(MessageEvent&) handler is guaranteed to execute atomically for each message.
Location Transparency: The sender doesn't know or care if the receiver is on the same core, a different core, or even a different machine (in a distributed qb system). The push<Event>(destination, ...) API remains the same.
Decoupled & Testable: Actors are naturally decoupled. You can test ReceiverActor in isolation by simply sending it MessageEvents and asserting that it produces the correct ResponseEvents.

By embracing the actor model, qb provides a powerful yet simple mental framework for building complex, concurrent systems. It lets you focus on your application's logic and flow, not on the low-level mechanics of synchronization.

Ready to dive deeper? Explore the qb framework and its examples on GitHub.

qb Core Framework: https://github.com/isndev/qb
Official Examples: https://github.com/isndev/qb-examples

Goodbye, Mutexes: An Introduction to the C++ Actor Model with `qb`

ISNDEV — Tue, 10 Jun 2025 19:45:32 +0000

Description: Feeling the pain of multithreading with locks and condition variables? Discover the Actor Model, a powerful paradigm for writing concurrent C++ that is simpler, safer, and more scalable. We'll build a "Ping-Pong" application from scratch using the qb framework to see how it works in practice.

Target Audience: Beginner / Intermediate C++ developers curious about modern concurrency.

The Agony of Traditional Threading

For decades, concurrent C++ has been synonymous with std::thread, std::mutex, and std::condition_variable. While powerful, these tools force you to manually manage shared state, leading to a minefield of potential issues:

Race Conditions: When multiple threads access shared data and at least one access is a write, leading to unpredictable results.
Deadlocks: Two or more threads waiting for each other to release a lock, freezing your application forever.
Complexity: Reasoning about all possible interleavings of thread execution becomes exponentially harder as your application grows.

There has to be a better way.

Introducing the Actor Model

The Actor Model offers a fundamentally different approach to concurrency. Instead of sharing memory, your application is composed of isolated, independent "actors."

Isolation: An actor maintains its own private state that no other actor can touch directly.
Message-Driven: Actors communicate exclusively by sending asynchronous, immutable messages (or "events") to each other.
Mailbox: Each actor has a "mailbox" where incoming messages are queued. It processes these messages one at a time, sequentially.

This sequential, single-threaded processing within each actor eliminates data races on its internal state by design. The complexity shifts from low-level locking to high-level message flow.

Meet the `qb` Framework: Your C++17 Toolkit for Concurrency

The qb Framework is a modern C++17 library designed from the ground up around the Actor Model. It provides the tools to build high-performance, scalable, and robust concurrent systems without the manual pain of thread and mutex management.

Building Our First Actors: Ping & Pong

Let's build the "Hello, World!" of actor systems. One actor, PingerActor, will send a PingEvent to another, PongerActor, which will simply print a message.

First, we need to define the message itself. In qb, these are called events.

Events: The Language of Actors

An event is just a data structure that inherits from qb::Event.

// An event to signal the Ponger.
struct PingEvent : qb::Event {
    // We can add any data we need to send.
    int ping_number;

    // A constructor makes creating events easy.
    PingEvent(int number) 
        : ping_number(number) {}
};

The Actors

Now, let's define our PongerActor. It waits for a PingEvent and prints a message.

#include <qb/actor.h>
#include <qb/event.h>
#include <qb/io.h> // For thread-safe cout

class PongerActor : public qb::Actor {
public:
    // This is called once after the actor is created.
    bool onInit() override {
        qb::io::cout() << "PongerActor is ready to receive pings!\n";
        // CRUCIAL: We must register which events we want to handle.
        registerEvent<PingEvent>(*this);
        return true;
    }

    // This method is the handler for PingEvent.
    // The framework calls this automatically when a PingEvent arrives.
    void on(const PingEvent& event) {
        qb::io::cout() << "Ponger received Ping #" << event.ping_number 
                       << " from actor " << event.getSource() << ".\n";
        // In a real app, we would push a PongEvent back.
        // For this simple example, we'll stop here.
    }
};

The `qb::Main` Engine: Bringing It All to Life

Actors don't run on their own. They are managed by the qb::Main engine, which orchestrates their creation, scheduling, and message delivery.

#include <qb/main.h>

// Include our actor definitions...

int main() {
    qb::io::cout() << "--- Starting Ping-Pong Example ---\n";

    // 1. Create the engine.
    qb::Main engine;

    // 2. Add actors to a virtual core (a worker thread).
    // Let's create the Ponger first on core 0.
    auto ponger_id = engine.addActor<PongerActor>(0);

    // Now, create the Pinger. We need to pass the Ponger's ID to its constructor.
    // In a full app, you would define PingerActor similarly to PongerActor.
    // auto pinger_id = engine.addActor<PingerActor>(0, ponger_id);

    // 3. Start the engine.
    qb::io::cout() << "Engine starting...\n";
    // `start(false)` runs the engine in the current thread and blocks until it's done.
    engine.start(false); 

    qb::io::cout() << "Engine stopped.\n";
    return 0;
}

This simple structure already gives us enormous benefits. We wrote concurrent logic without a single std::mutex or std::thread. The PongerActor can process PingEvent messages safely, and if we had thousands of such actors, the qb engine could efficiently schedule them across multiple CPU cores.

Conclusion: A New Way to Think About C++ Concurrency

The Actor Model, powered by the qb framework, isn't just another library; it's a paradigm shift. It encourages you to design systems as collections of independent, message-passing components, leading to code that is:

Safer: Eliminates entire classes of concurrency bugs by design.
Simpler: Easier to reason about than complex lock-based code.
Scalable: Naturally maps to multi-core architectures.

This was just a small taste. In future articles, we'll explore how qb and its modules (qbm) make it easy to build high-performance web servers, database clients, and real-time WebSocket applications with the same elegant, actor-based principles.

Find out more:

qb Framework on GitHub: https://github.com/isndev/qb
qb-examples Repository: https://github.com/isndev/qb-examples

C++ Doesn’t Have to Be Complicated: Meet qb, a Minimalist Framework Built from Pure Passion

ISNDEV — Mon, 09 Jun 2025 16:26:30 +0000

After years of building real-world software in C++, I hit a wall.

C++ is a powerful language — no doubt — but developing in it often feels like solving puzzles that shouldn’t exist in the first place. Boilerplate code, messy integrations, overcomplicated libraries… it all gets in the way.

I didn’t want to give up on C++. I love this language. I just wanted it to be more enjoyable to work with — without losing its strengths.

So I built qb.

🛠️ What is qb?

qb is a lightweight, modular C++ framework designed to make building modern applications in C++ simple, fast, and maintainable — without the usual complexity.

It was built in my free time, out of pure passion, with one goal in mind:

✨ Make C++ development a joy again.

It provides just enough structure to build stable, high-performance applications — without boxing you into someone else’s architecture.

⸻

🧩 The Ecosystem So Far

qb is intentionally minimal at the core, but comes with a growing set of focused modules:
• qbm-http: Lightweight HTTP1.1/HTTP2
• qbm-websocket: Fully async WebSocket support
• qbm-pgsql: Async PostgreSQL client
• qbm-redis: Clean and simple Redis integration

And this is just the beginning.

Upcoming modules include MQTT, QUIC, SMTP, and more. The goal is to provide a complete, consistent, and developer-friendly set of building blocks for C++ applications — from backend services to full-stack systems.

⸻

🔍 Why Should You Care?
✅ You want to write real C++ apps without drowning in complexity
✅ You value clean abstractions, but not at the cost of performance
✅ You want to build things — not fight your tools
✅ You’re tired of frameworks that feel like they were designed for another language

⸻

🙌 Community Matters

This project isn’t backed by a company. It wasn’t built for profit.

It was built by a developer, for developers, and it can only get better with your feedback and contributions.

I’d love to hear your thoughts. What would you want to see next? What’s missing for you? Would you use this on a real project?

⸻

🔗 Check It Out
Core framework
HTTP
Websocket
Postgresql
Redis
Examples

Feel free to open issues, star the repo, or even just say hi in a discussion.
Let’s make C++ fun again — one module at a time.