Audience: Adopter · Status: stable · Verified-against: qb 3.2.1 (C++20 default, C++23 supported)
Fast-lookup material for working with qb: an API map, the build and dependency reference, the thread-safety and lifetime invariants each library upholds, the test and benchmark suites, plus an FAQ and a glossary.
Prerequisites: none — See also: Developer guides, qb-core module, qb-io module
The earlier sections teach concepts in narrative order. This section is the opposite: each page answers a specific factual question — which header owns a type, which CMake variable controls a feature, which thread may touch a given object, what a term means — without requiring you to read a tutorial first. Every claim is grounded in the header or build file that owns it, and the invariant pages are the contracts the libraries assume; read them before writing a custom actor, protocol, transport, or any code that touches a lock-free primitive directly.
| Page | What it covers |
|---|---|
| Public API overview | A reference map of the public API: the namespaces, key types, and signatures of qb-core and qb-io, each linked to the header that owns it. |
| Building from source | Configuring, building, testing, and installing qb with CMake — requirements, presets, options, generators, and the install layout. |
| CMake and third-party dependencies | How qb resolves each dependency as bundled in-tree, fetched on demand, or system-supplied, driven by QB_DEPS_FETCH_FALLBACK and the QB_USE_SYSTEM_* switches. |
| CMake options reference | Every QB_* CMake variable that configures a build, its default, and what it controls. |
| qb-core thread-safety and lifecycle invariants | The rules qb-core assumes and the guarantees it gives: which thread owns what, when an actor is alive, and in what order events arrive. Required reading before writing actor, coroutine, or event-router code. |
| qb-io invariants: threading, lifetime, and ownership | The rules the asynchronous stack assumes — one event loop per thread, where callbacks run, when objects may be destroyed, and who owns each socket. Required reading before writing a custom protocol, transport, or async base class. |
| Frequently asked questions | Short, grounded answers to the questions that come up most when adopting qb, each linking to the page that owns the full explanation. |
| Glossary | A definition for every domain term used across the documentation, grounded in the header that owns it and linked to the page that explains it in full. |
| Testing the framework | How the test suite is organized, how to build and run it with CTest and GoogleTest, and how the coverage option is wired. |
| Benchmarks | The qb-core micro-benchmark suite: the Google Benchmark targets gated by QB_BUILD_BENCHMARKS, what each one measures, and how to build, run, and read them. |
Reference pages are meant for lookup, not front-to-back reading. Use these entry points instead:
- Evaluating or first building qb. Start with Building from source, then CMake options reference and CMake and third-party dependencies when a configure step needs tuning.
- Looking up an API. Go straight to the Public API overview; follow its links into the owning headers. Keep the Glossary open for unfamiliar terms.
- Writing framework-level code (a custom actor base, protocol, transport, or anything using a lock-free primitive directly). Read qb-core thread-safety and lifecycle invariants and qb-io invariants: threading, lifetime, and ownership first; consult Concurrency primitives only if you call those structures yourself rather than through the engine.
- Contributing or measuring. Testing the framework for the suite layout and CTest workflow; Benchmarks for the micro-benchmark targets.
- Stuck on a specific question. Check the FAQ before reading a full page — each answer links to the page that owns the detail.
The lock-free ring buffers, the spinlock, the allocator pipe and the time vocabulary are not here: they sit below both libraries and are documented in Foundations.
For task-oriented, narrative material, see the Developer guides; for the conceptual treatment of each library, see qb-core and qb-io.