Skip to content

C++ API

The C++ library is the reference implementation every other reader wraps. It targets C++20 and lives in the detent namespace.


CMake targetHeaderWhat it provides
detent::detentdetent/client.hhClient, InitOptions, HealthSnapshot, Metrics
detent/model.hhSnapshot, KnobDef, GroupOverride, GroupRollout, SnapshotPatch
detent/result.hhResult<T, E>
detent/errors.hhKnobError, ErrorCategory, UpdateError, UpdateRejectReason
detent/read_view.hhClientReadView, ReadSource, EvaluationView
detent/global.hhThe process-wide detent::global adapter
detent/testing.hhTestKnobs, TestGuard
detent/overrides.hhOverrideTable, parse_cli_overrides()
detent/validation.hhis_valid_knob_name(), is_valid_group_key()
detent::local_clientdetent_local/client_source.hhmake_local_read_source() for managed generations

detent::detent has no networking dependency. Only link detent::local_client when you use managed generations.


  1. Client: construction, reads, views, health and metrics.
  2. Sources: file, generic and managed-generation sources.
  3. Global Access and Testing: the detent::global adapter, TestKnobs, and CLI overrides.

  1. Errors are values on the read path. Reads return Result<T, KnobError>; only the _or_panic helpers abort.
  2. Errors are exceptions at startup. The Client constructor throws on invalid defaults, invalid CLI overrides, or invalid options.
  3. Optional arguments are std::optional<std::string_view>. Pass std::nullopt (or nothing) to omit a hash value or switch value.
  4. Nothing on the read path allocates, locks or does I/O.

Result<T, E> is a small std::expected-shaped type, since Detent targets C++20:

auto r = client.get("search:max_results");
if (r) { // or r.has_value()
std::int64_t v = r.value();
} else {
const detent::KnobError& e = r.error();
std::string message = e.what();
}