DEV Community: ISNDEV

One Runtime, Two Programs That Have Nothing in Common

ISNDEV — Wed, 26 Aug 2026 14:39:39 +0000

A C++20 actor framework where a REST API and a market-data pipeline run on the same execution rules.

Here are two functions from the same codebase.

The first is an HTTP handler. Reads a cache, falls back to Postgres, refreshes the cache, writes JSON:

qb::io::async::task<void>
TaskManager::handle_list_tasks(ctx_t ctx) {
    auto cached = co_await _redis.get("tasks:list");

    if (cached.ok() && cached.result().has_value() && !cached.result()->empty()) {
        ctx->response().add_header("X-Cache", "HIT");
        ctx->json(qb::json::parse(*cached.result()));
        co_return;
    }

    auto result = co_await _db->execute("select_all_tasks", qb::pg::params{});
    if (!result.ok()) {
        ctx->internal_server_error(result.error().what());
        co_return;
    }

    auto json = models::TaskList(result.result(), false).to_json();
    (void) co_await _redis.setex("tasks:list", 60LL, json.dump());

    ctx->response().add_header("X-Cache", "MISS");
    ctx->json(json);
}

The second is the hot path of a market-data hub. A foreign thread pushes quotes across a lock-free ring, and an ingest actor drains it once per loop turn:

void IngestActor::on(qb::LoopEvent const &) {
    Quote q;
    while (_ring.dequeue(q))                       // drain the SPSC bridge
        send<QuoteEvent>(_pool.for_key(q.symbol),  // sticky routing by symbol
                         q);
}

No HTTP, no SQL, no shared vocabulary at the application level.

There is also no configuration difference between these two programs. Same engine, same scheduler, same ownership rules. The second one isn't the framework running in some other mode; it's the framework doing the only thing it does.

One rule

One worker thread per lane. One event loop on that thread. Actors, sockets, timers and coroutine resumptions all live on it. Mutable state belongs to exactly one lane. To reach state on another lane, you send a message.

In qb a lane is a VirtualCore: one worker thread owning a set of actors, running one event loop over them, draining one private lock-free mailbox. An actor is thread-affine to the core that created it and never migrates.

The rest falls out of that. An actor's fields need no mutex because no second thread can reach them. An ActorId is a 32-bit {ServiceId, CoreId} pair, so the address carries its own route and a send resolves to a mailbox slot through a precomputed dense index — no registry, no hash lookup.

And the only memory that multiple threads concurrently mutate anywhere in the system is the inter-core mailbox: an MPSC ring where many cores enqueue and only the owner dequeues.

I want to be precise about that last claim, because it's the kind of thing everyone says and few people mean. The actor maps, the service-id pool, the thread_local event loop, the coroutine scheduler: one thread each, no synchronization on any of them. No std::mutex on the message path at all. Two locks exist in the engine — one guards a service-id map during static init, the other is the condition variable a core parks on when it goes genuinely idle. That's the list. If someone finds a third place where application-visible state is concurrently mutated, that's a bug report, not a design discussion, and I'd want it filed.

Three layers

qb-io is the async runtime: libev-based event loop, non-blocking TCP/UDP/SSL, a protocol layer, C++20 coroutines, timers, filesystem watching, crypto, compression, a logger, QUIC. It knows nothing about actors. You can write a whole program against it — qb::io::async::init(), drive the loop yourself, done. A whole tier of the example corpus does exactly that on purpose, twelve programs, not an actor in sight.

That separation isn't a retrofit. qb-io existed first and the actor layer grew on top of it, which is why the dependency runs one way and why it's still worth using alone.

qb-core adds the actor semantics: identity, lifecycle, ownership, message topology, placement, lock-free inter-core delivery. It doesn't demand that every async function in your program become an actor.

The qbm modules put application protocols on the same foundation — HTTP (1.1 always; HTTP/2, HTTP/3, WebSocket and JWT on SSL and QUIC builds), PostgreSQL, Redis. Separate repositories, added as submodules, discovered by CMake.

Now, the Postgres client is the one I'd defend hardest, and it's also the one people ask about most, so let me get into it. qbm-pgsql speaks the v3 frontend/backend protocol directly over a qb-io socket. Handshake, SCRAM-SHA-256 (and MD5, and cleartext, because you still meet both), the simple query protocol, the extended one, parameter type encoding across the OID table, LISTEN/NOTIFY, the SSLRequest upgrade. Seventeen translation units. No libpq anywhere.

People assume that's a purity thing. It isn't. Wrap a blocking client in a thread pool and your co_await hands its continuation to a foreign executor — at which point the actor's state is reachable from a thread that doesn't own it, and every guarantee in the section above is gone. Not weakened. Gone. There was no version of this where I got to reuse someone else's client. I spent longer on the Postgres wire format than on the actor scheduler, and I'd do it again, but I won't pretend it was fun.

What sharing one execution model actually gets you

Go back to handle_list_tasks. Three protocols cross it. The interesting part is the list of things that don't happen: the actor doesn't migrate, the database operation doesn't borrow a worker from a pool, the coroutine doesn't resume on an unrelated executor, and the Redis socket doesn't belong to a foreign runtime that has to marshal back into this one. HTTP session, both protocol clients, coroutine frame, actor: one VirtualCore. While Redis or Postgres is pending the frame sits suspended and the lane keeps serving everything else.

Now the ingest loop. Completely different application, same vocabulary:

qb::ICallback gives the actor an on(qb::LoopEvent const&) that fires once per loop turn, near the end, after the worker has flushed its outbound pipes and drained its mailbox. That's your hook for pumping a foreign source.
qb::lockfree::spsc::ringbuffer is the sanctioned bridge from a thread the engine doesn't own. A real std::thread producing quotes crosses in through it, explicitly, at one place in the program.
qb::WorkerPool::for_key does sticky routing — the same symbol always lands on the same shard, which is what makes per-symbol aggregation state safe to touch without a lock. Placement doing the work that discipline usually has to.
qb::batcher coalesces the aggregator output before it goes out.

PublisherActor then runs a qb::io::use<T>::tcp::server<Session> inside an actor, with a binary wire format built from the shipped framing toolbox, and SubscriberActor sits on the other end of that wire in the same process. Which means the format gets exercised rather than just specified.

Two applications, nothing in common at the domain level, one vocabulary underneath.

The small end

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

struct GreetingEvent : qb::Event {
    qb::string<64> message;
    explicit GreetingEvent(const char *msg) : message(msg) {}
};

class GreeterActor : public qb::Actor {
public:
    qb::io::async::task<bool> onInit() final {
        registerEvent<GreetingEvent>(*this);
        push<GreetingEvent>(id(), "Hello");
        co_return true;
    }

    void on(const GreetingEvent &event) {
        qb::io::cout() << "Received: " << event.message << '\n';
        kill();
    }
};

int main() {
    qb::Main engine;
    engine.addActor<GreeterActor>(0);
    engine.start();
    engine.join();
}

That's a complete program. No mutex, no condition variable, no shared queue — there's no second thread that could need one.

onInit() returns task<bool>, which matters more than it looks. It means startup stays sequential:

qb::io::async::task<bool> onInit() final {
    if (!co_await _db->connect(database_uri))
        co_return false;
    if (!(co_await prepare_statements()).ok())
        co_return false;
    if (!co_await _redis.connect(redis_uri))
        co_return false;
    configure_routes();
    co_return true;
}

And the runtime has an answer for the window while that's suspended, which took me three tries to get right. The actor sits in an Activating phase: inbound business events are held in a bounded FIFO and replayed in order once init succeeds, kill events and broadcasts have defined bypass behaviour, initialization has a deadline, and co_return false destroys the actor before it ever sees a message. The bypass rules are the fiddly part — hold everything indiscriminately and an init request waiting on its own correlated reply deadlocks itself.

An HTTP server is the same shape. Actor, mix in qb::http::Server<>, define routes, compile the router, listen:

class ApiServer : public qb::Actor, public qb::http::Server<> {
public:
    qb::io::async::task<bool> onInit() override {
        router().get("/users/:id", [](auto ctx) {
            ctx->response().body() = "user " + ctx->path_param("id");
            ctx->complete();
        });
        router().compile();

        if (listen({"tcp://0.0.0.0:8080"})) { start(); co_return true; }
        co_return false;
    }
};

What ships with it

Eleven headers under qb/core/patterns/: pub/sub, supervisor, worker pool, scatter/gather, resilience, streaming, saga, batching, idempotency, discovery, and qb::ask for request/response.

ask is the one I'm happiest with. Inside a scoped coroutine, co_await qb::ask(ctx, target, req, timeout) sends a request and resolves to the reply — correlation, timeout and cancel-on-kill all handled by a single awaiter, with no detached helper task hanging around. The correlation registry is a per-worker-thread thread_local map, so no locks. The slots live inside the awaiter, in the asking coroutine's own frame, and unregister themselves on resume, timeout, cancel or destruction. Getting that to work without a heap allocation per request took a while.

The coroutine layer also carries a structured-concurrency surface: scopes with exit policies, bounded fan-out, channels with select, generators, async streams, six sync primitives, retry, shared_task. Mono-thread per core, cooperative, no scheduler to configure.

Keeping the examples honest

The example corpus is a separate repository in seven tiers, meant to be read in order: actors, qb-io standalone, coroutines, patterns, services, modules, then three full applications.

The mechanism is the part I'd want to know about if this were someone else's project. Every program carries a header block — @teaches, @demonstrates, @prerequisites, @expect — and a script asserts that every @demonstrates name actually occurs in that file's code. A name that isn't true of the file under it is the recurring defect in an example corpus, and that check is the guard against it. The capability index is generated from those blocks and gated byte-exact.

@expect goes further. Where a program can measure the thing it teaches, it prints a whole sentence chosen by that measurement instead of splicing a number into one. So when the runner can't find the line, the behaviour changed, not the wording.

CMake targets and binary names derive from the path. 02-io/03-tcp.cpp becomes qb-example-io-tcp, always, never hand-written.

I bring this up because having examples is worth approximately nothing, and having examples that structurally cannot lie about what they demonstrate is worth something.

The bill

One blocking call poisons an entire lane. Architectural, not advisory. A blocking syscall or a long CPU loop delays every actor, socket, timer and coroutine on that worker. qb caps the ready-coroutine drain at 65,536 resumptions per loop turn so the scheduler queue can't monopolize a turn, but it does not preempt a running handler and enforces no per-task CPU budget. Your handler starves the lane until it returns.

No work stealing. Actors never migrate, so bad placement stays bad and a hot actor pins its lane while a neighbour idles. Placement is also an interference domain: a latency-sensitive actor colocated with a throughput-heavy one inherits that neighbour's scheduling delay even when nobody misbehaves. This model wants a natural partitioning key. Without one, a work-stealing pool beats it and I wouldn't argue.

An uncaught exception in a handler kills the process. The dispatch trampoline is noexcept, so a throw escaping on(Event&) is std::terminate. Not "restart that actor" — the process. A lane is a failure domain and actor semantics don't hand you Erlang isolation for free. I go back and forth on whether this was the right call. It's the honest default for a runtime that has no supervision tree, but it's also the answer that makes people wince, and they're not wrong to.

Events are relocated by memcpy. The engine moves event bytes and never runs the source destructor, so payloads have to be trivially relocatable, not merely copyable. A by-value std::string is rejected by contract: libstdc++'s short form stores _M_p addressing the object's own inline buffer, so relocating it leaves a pointer into dead storage. libc++ and MSVC don't have that shape, which means this particular bug corrupts on Linux and is invisible on macOS. Use qb::string<N> or an indirection.

There's no compile-time check for the general case, and C++ doesn't currently give me one. Trivial relocation went into C++26 at Hagenberg in February 2025, then came back out at Kona in November — partly over whether "trivially relocatable" should guarantee that a type is memcpy-able at all, which is precisely the guarantee I need. The work moved to C++29. In the meantime I'm making assumptions that aren't portable in principle and hold everywhere I've tested, which is uncomfortably close to what Boost.JSON says about its own situation. I don't have a better answer and I'd take one.

Cancellation is cooperative. An awaiter that registers no cancellation hook won't wake because a token changed. The Postgres reply awaiter is one of those: kill() neither wakes nor unwinds a coroutine parked on co_await db.execute(...). It stays parked until the operation completes on its own — safely, since the awaiter's alive flag makes a late completion a no-op, but not promptly. Wrapping it in ctx.cancellable(...) works by destroying the frame, which is a different thing from cancelling the operation, and the difference is worth understanding before you rely on it.

Memory and idle CPU. The routing topology allocates outbound pipes and inbound rings eagerly across the configured core set and never shrinks them: roughly 0.6 MiB at one core, 22.5 at eight, 85 MiB at sixteen. And the default idle latency is zero, meaning busy-spin at 100% of a core. Both are deliberate, both will surprise you if nobody says so out loud.

One more, from the examples rather than the runtime. co_await qb::io::async::tcp::connect<Transport>(uri, timeout) written directly in an actor's onInit() suspends and never resumes, even though the TCP connection genuinely is established. The same expression inside spawn() resumes normally. That's recorded in the market-data-hub notes because it cost me an afternoon, and I still don't have a satisfying explanation for it — only a reproduction and a workaround.

On numbers

The market-data-hub prints its end-to-end latency as a distribution — min, p50, p90, p99, max — rather than a single figure. One number would be a claim about hardware the program has never run on. And the 4 ms batch window plus the ring backlog dominate the tail by construction, so a p99 that looks terrible is usually a batch that was waiting on purpose.

Compare the shape between two builds on one machine. Don't compare medians between machines. That's the only guidance I trust.

The architecture has plausible performance properties: no synchronization on lane-local state, state that stays hot in one core's cache because it never migrates, O(1) routing, batched message movement, no executor hop for async I/O. Properties, not results. Name a configuration you'd find convincing and I'll run it and publish the method next to the number.

Where it fits

Good fit when mutable state has a natural owner or shard key, when the workload is mostly non-blocking I/O, when placement and locality matter, and when the team will actually hold the no-blocking line. Protocol gateways, stateful network services, market data, game backends, telemetry, anything partitioned by account or session or instrument or tenant.

Bad fit when most of the work is independent CPU-bound computation, when your critical dependencies only expose blocking APIs, when state genuinely has to be mutated from arbitrary threads, or when skew shifts faster than you can reshard.

C++20 by default, C++23 supported, Linux/macOS/Windows on x86_64 and ARM64, CMake 3.24, Apache-2.0.

The question I started with wasn't whether a C++ library can expose actors, async I/O and coroutines at once — plenty can, and the names are cheap. It was whether one execution model could carry an application from a REST endpoint to a binary market-data pipeline without quietly becoming a different framework somewhere in the middle. I think the answer is yes. I'd like to know where it stops being yes, and that's a more useful thing to send me than a star.

github.com/isndev/qb · examples · threading model · core invariants

Four Bugs in Fourteen Lines

ISNDEV — Wed, 26 Aug 2026 14:34:50 +0000

Lock contention, starvation, false sharing, cache misses. They're not four bugs. They're one decision, made on day one, that nobody wrote down.

Here is a class you have written. Maybe not this one exactly, but one shaped like it.

class SessionRegistry {
    std::mutex                       mu_;
    std::unordered_map<u64, Session> sessions_;
    std::atomic<uint64_t>            hits_{0};
    std::atomic<uint64_t>            misses_{0};

public:
    Session *find(u64 id) {
        std::lock_guard lock(mu_);
        auto it = sessions_.find(id);
        if (it == sessions_.end()) { misses_.fetch_add(1); return nullptr; }
        hits_.fetch_add(1);
        return &it->second;
    }

    void refresh(u64 id) {
        std::lock_guard lock(mu_);
        auto &s = sessions_[id];
        s.data  = db_.query(id);        // network round trip
        s.stamp = now();
    }
};

Fourteen lines. It compiles clean, passes review, passes tests, and ships. Nobody wrote it carelessly. Every line is the obvious line.

It also contains, simultaneously, all four of the classic multithreading pathologies.

Lock contention. One mutex, every lookup. Twelve worker threads funnel through a single serialization point on the hottest path in the service. Under load, your profile stops being about your code and starts being about the futex.

Starvation. db_.query() is a network round trip, and it runs while the lock is held. That's not milliseconds of critical section — that's milliseconds times however unlucky the network feels. Every reader in the process queues behind one writer waiting on a socket. The reviewer didn't catch it because the blocking call is one level down, behind a member function that looks like an accessor.

False sharing. hits_ and misses_ are eight bytes each, declared adjacently, almost certainly in the same 64-byte cache line. They share nothing logically. Every core that increments one invalidates the other's line on every other core. Two counters nobody reads until the metrics endpoint is hit, generating coherence traffic on every single lookup.

(They also don't need to be atomic. They're only ever touched under the lock. Everyone writes them that way anyway, because std::atomic on a counter has become a reflex.)

Cache misses. find returns a raw pointer into a map, after releasing the lock — which is separately a lifetime bug, since a concurrent refresh can rehash and invalidate it. But set that aside. The session's cache lines get pulled into whichever core the thread pool happened to pick this time. Next request for the same session lands on a different core, and the lines migrate again. The working set never settles anywhere.

Now, each of these has a well-known fix. Shard the mutex. Move the query outside the critical section. Pad the counters to a cache line. Pin the threads, or add a per-thread cache in front.

Four fixes, four pull requests, four benchmarks proving each one helped. All of them real. And all of them applied after the architecture already made the mistake.

Because these aren't four bugs. They're one decision, made implicitly on the first day of the project and never written down anywhere:

More than one thread is allowed to reach this memory.

Once that's true, everything downstream is damage control. You don't prevent contention, you negotiate it. You don't prevent false sharing, you pad around it. You don't get locality, you fight for it against a scheduler that doesn't know what your data means. The bug isn't in SessionRegistry. It's one level up, in a decision that never appeared in a review.

I got tired of patching the symptom. So I wrote a runtime around the opposite decision.

The rule

One worker thread per lane. One event loop on that thread. Actors, sockets, timers and coroutine resumptions all live on it. Mutable state belongs to exactly one lane. To touch state on another lane, you send a message.

The runtime is qb — C++20, Apache-2.0, mine. A lane is a VirtualCore: one worker thread that owns a set of actors, runs a single event loop over them, and drains one private lock-free mailbox.

An actor is thread-affine to the VirtualCore that created it and never migrates, for its entire lifetime. That one invariant is what the rest of this article is about, because it's what turns the four pathologies from discouraged into unavailable.

SessionRegistry under that rule isn't a fixed version of the class above. It's a class with no mutex, no atomics, and a plain std::unordered_map, because there is no second thread that could reach it.

Going back through the four

I want to be precise, including where the honest answer is "partly."

Contention: eliminated on actor state. Not reduced — absent. There's no lock because there's no second thread that can reach the memory. The fields are ordinary single-threaded C++ variables that happen to live inside a concurrent program. The compiler can keep them in registers across a handler. No acquire/release fence bracketing every access, no coherence traffic from the lock word itself.

Starvation: reframed, not deleted. Nobody waits on a lock, so lock-based starvation is gone. But actors on one lane share a worker, and that worker runs one handler at a time. A slow handler starves its lane-mates. The failure moved from unpredictable, depends on acquisition order to predictable, depends on placement, and shows up in a profile as one named handler. That's a real improvement. It is not a free lunch, and I come back to it in the costs.

False sharing: eliminated between lanes, still yours inside one. Two actors on two cores cannot false-share their hot state, because there is no shared state to accidentally colocate. What's left is the inter-core ring buffer — framework code, which is where the padding belongs. What is not solved: false sharing inside one actor's own structures, or between an actor and something foreign you handed it. The model shrinks the surface. It does not align your structs for you.

Cache locality: this is the real prize. Actor state is touched by exactly one thread, on one core, for the actor's whole life. It stays hot in that core's L1/L2 instead of being dragged around by a scheduler that has no idea what it is. No migration, no cold refill. No sharing, no coherence traffic. And because one lane processes a run of similar events in sequence, the code path stays hot alongside the data.

You can make it deliberate, too. CoreInitializer::setAffinity pins the worker to physical CPUs — pthread_setaffinity_np on POSIX, SetThreadAffinityMask on MSVC. Note best effort: a failed pin logs a warning and startup continues, and logical core ids are not CPU numbers. engine.core(7) is logical core 7; it lands on physical CPU 7 only if you ask.

Branch prediction: plausible, and the one I'd argue about. The story is that dispatching many events of one type to one actor keeps the predictor warm and the i-cache hot, versus a pool where consecutive tasks are arbitrary. I believe it. I haven't isolated it from the cache effects in a way that would convince me if someone else claimed it, so I'm listing it as a hypothesis, not a benefit. If you've measured this properly on a shard-per-core system, I'd like to see it.

There is exactly one multithreaded surface, and it isn't yours

None of this makes concurrency disappear. It concentrates it into one place.

In qb, the only memory that multiple threads concurrently mutate is the inter-core mailbox layer. Each VirtualCore consumes from exactly one inbound mailbox — a multi-producer, single-consumer lock-free ring. Many cores enqueue; only the owner ever dequeues.

Everything an actor can see is single-thread-per-core with no synchronization whatsoever. The actor maps, the service-id pool, the thread_local event loop, the coroutine scheduler: one thread each, not one atomic among them.

That's the actual trade. The hard concurrent code doesn't go away — it gets written once, in one file, and never again in application code. Routing is O(1): a destination core resolves to a mailbox slot through a precomputed dense index, no hash lookup. Each loop iteration flushes outbound events to peer mailboxes, then drains its own.

What I like about this framing is that it's falsifiable. If someone finds a second place where application-visible state is concurrently mutated, that's a bug in the runtime — not a design discussion.

Owning state doesn't teach you how to wait

Share-nothing tells you who may mutate what. It says nothing about waiting.

An actor can still do this, and it's worse than the mutex was:

auto result = blocking_database_query();

Ten actors, three sockets and a timer are now stuck behind that call. You preserved state ownership and destroyed progress. At least the mutex only blocked contenders.

So I/O has to be non-blocking, and dependent operations have to stay readable. That's what C++20 coroutines do here:

auto reply = co_await database.execute("select_user", params);

At the suspension point the frame holds the operation's state, the stack unwinds to the scheduler, and the lane goes elsewhere — dispatches another actor, services a socket, fires a timer, resumes a different coroutine. When the reply lands, the coroutine resumes on the same lane. Same thread, same cache, same ownership boundary. No thread was spawned because you typed co_await, and no continuation was handed to a foreign executor.

That last clause is the entire reason to put the coroutine scheduler on the event loop rather than beside it.

What it looks like

Smallest version:

struct GreetingEvent : qb::Event {
    qb::string<64> message;
    explicit GreetingEvent(const char *msg) : message(msg) {}
};

class GreeterActor : public qb::Actor {
public:
    qb::io::async::task<bool> onInit() final {
        registerEvent<GreetingEvent>(*this);
        push<GreetingEvent>(id(), "Hello");
        co_return true;
    }

    void on(const GreetingEvent &event) {
        qb::io::cout() << "Received: " << event.message << '\n';
        kill();
    }
};

int main() {
    qb::Main engine;
    engine.addActor<GreeterActor>(0);
    engine.start();
    engine.join();
}

No mutex, no condition variable, no shared queue — not avoided, just not applicable.

And a handler crossing three protocols:

qb::io::async::task<void>
TaskManager::handle_list_tasks(ctx_t ctx) {
    auto cached = co_await _redis.get("tasks:list");

    if (cached.ok() && cached.result().has_value() && !cached.result()->empty()) {
        ctx->response().add_header("X-Cache", "HIT");
        ctx->json(qb::json::parse(*cached.result()));
        co_return;
    }

    auto result = co_await _db->execute("select_all_tasks", qb::pg::params{});

    if (!result.ok()) {
        ctx->internal_server_error(result.error().what());
        co_return;
    }

    auto json = models::TaskList(result.result(), false).to_json();
    (void) co_await _redis.setex("tasks:list", 60LL, json.dump());

    ctx->response().add_header("X-Cache", "MISS");
    ctx->json(json);
}

HTTP session, Redis client, Postgres client, coroutine frame and actor: one VirtualCore. Three protocols, one execution context, zero affinity handoffs. While Redis or Postgres is pending the frame is suspended and the lane keeps serving everyone else.

The Postgres and Redis clients speak their wire protocols directly rather than wrapping blocking libraries. That's the only way this property survives contact with a real database.

The bill

If I stopped here this would be marketing. Here's what the rule costs.

One blocking call poisons an entire lane. Architectural, not advisory. A blocking syscall or a long CPU loop delays every actor, socket, timer and coroutine on that worker. qb caps the ready-coroutine drain at 65,536 resumptions per loop turn so the scheduler queue can't monopolize a turn, but it does not preempt a running handler and enforces no per-task CPU budget. Your handler starves the lane until it returns. Heavy CPU work has to be chunked around explicit yields, isolated on its own lane, or pushed out through a bridge.

No work stealing. Bad placement stays bad. Actors never migrate, so a hot actor pins its lane while a neighbour idles and nothing rebalances it. Placement is also an interference domain: a latency-critical actor colocated with a throughput-heavy one inherits that neighbour's scheduling delay even when nobody blocks and nobody misuses the API. Colocation buys locality and sells coupling. This model wants a natural partitioning key — account, session, instrument, tenant, symbol. Without one, a work-stealing pool wins.

An uncaught exception in a handler kills the process. The typed dispatch trampoline is noexcept, so a throw escaping on(Event&) calls std::terminate. It does not kill and restart that one actor. A lane is a failure domain, and actor semantics do not hand you Erlang-style isolation for free.

Cross-core transport relocates raw bytes, which is an ABI bet. Events move between buffers by relocating bytes; the source is abandoned without running a destructor there. Trivially copyable types aren't the issue — qb also treats selected non-trivially-copyable representations as bitwise relocatable, and C++20 gives you no portable operation for that. WG21 P2786 exists precisely because byte-moving such an object violates the object model. So this is empirical behaviour on the compiler and standard-library combinations qb targets, not a guarantee from the abstract machine, and I don't want it mistaken for one. By-value std::string is rejected by contract: libstdc++'s short-string form stores a pointer into the object's own inline buffer, so relocating it yields a self-pointer into dead storage. Use plain data or qb::string<N>. A debug scan catches the common cases on the cross-core hop; it can't prove correctness.

The routing topology costs memory, quadratically. Outbound pipes and inbound rings are allocated eagerly across the configured core set and never shrink: roughly 0.6 MiB at one core, 6.3 at four, 22.5 at eight, 85 MiB at sixteen. Values are build-dependent; the shape isn't. That's the price of avoiding shared cursors and steady-state allocator traffic, and you should budget it before configuring a lot of lanes.

The default burns a CPU while idle. setLatency(zero) — the default — is busy-spin: the loop never blocks and holds its core at 100% for minimum wake-up delay. With a non-zero latency, recent activity earns a spin credit and then the worker parks on a condition variable until a peer notifies it. Lower idle CPU, possible wake-up delay. A market-data process and an admin service shouldn't make the same choice, and the runtime can't make it for them.

Sequential handling is not global ordering. Ordered push preserves FIFO only from one source actor to one destination actor. Independent senders, different destinations and broadcasts have no global order. Absence of data races does not imply deterministic distributed behaviour, and conflating the two is an excellent way to ship a subtle bug.

Why there's no benchmark number here

The performance story is obvious: no synchronization on lane-local state, hot caches, O(1) routing, batched message movement, no executor hop for async I/O.

That's a list of properties, not a result. Messages-per-second means nothing without hardware and topology, compiler and flags, actor and core counts, the same-core versus cross-core mix, payload size, allocation behaviour, how much real work each handler does, and latency percentiles next to throughput. A number without those is decoration.

So I left it out rather than post one that flatters my own design. Name a configuration you'd find convincing and I'll run it and publish the method with it.

What I actually think

This shouldn't be the execution model for most C++ applications. If your work is independent and CPU-bound, a work-stealing pool is better. If your critical dependencies only expose blocking APIs, you'll fight this daily. If your state genuinely must be mutated from arbitrary threads, no amount of discipline makes this the right tool.

But go back to those fourteen lines. Nothing in SessionRegistry is exotic, and nothing in it is stupid. It's the default outcome of an execution model where any thread may touch any memory — and we've collectively agreed to treat that as a law of nature instead of what it is.

It's a choice. Making the other one costs you work stealing, transparent placement, and a hard rule about blocking. That's the trade, stated plainly, and I'd rather argue about the trade than about the pitch.

So: where does this break down? Which workload of yours would this have made worse, and by how much? I'm more interested in that than in another star.

Code: github.com/isndev/qb — C++20/23, Linux/macOS/Windows, x86_64 and ARM64, Apache-2.0. If you read one page, read the threading model.

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.

DEV Community: ISNDEV

One Runtime, Two Programs That Have Nothing in Common

A C++20 actor framework where a REST API and a market-data pipeline run on the same execution rules.

One rule

Three layers

What sharing one execution model actually gets you

The small end

What ships with it

Keeping the examples honest

The bill

On numbers

Where it fits

Four Bugs in Fourteen Lines

Lock contention, starvation, false sharing, cache misses. They're not four bugs. They're one decision, made on day one, that nobody wrote down.

The rule

Going back through the four

There is exactly one multithreaded surface, and it isn't yours

Owning state doesn't teach you how to wait

What it looks like

The bill

Why there's no benchmark number here

What I actually think

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

1. High-Performance Caching

2. Reliable Job Queues with Lists

3. Real-Time Messaging with Publish/Subscribe

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

1. Expressive Routing: Parameters and Wildcards

2. Middleware: The Power of Composition

3. The Controller Pattern: Organizing Your API

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

Core Features of qbm-http

Your First HTTP Server

The Power of Asynchronous Handlers

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

What is the Actor Model?

Why qb? The Core Philosophy

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

Who is qb For?

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

How qb Manages Cores

Example: A Multi-Core Dispatcher System

Key Benefits of qb's Multi-Core Approach

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

The Three Pillars of a qb Actor

Request-Response: The Hello World of Actor Communication

Why This is a Big Deal

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

The Agony of Traditional Threading

Introducing the Actor Model

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

Building Our First Actors: Ping & Pong

Events: The Language of Actors

The Actors

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

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

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

Core Features of `qbm-http`

Why `qb`? The Core Philosophy

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

Who is `qb` For?

How `qb` Manages Cores

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

The Three Pillars of a `qb` Actor

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

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