Skip to content

Using Detent in a C++ Application

This guide adds Detent to an existing C++20 program: ship baked defaults with the binary, construct one client, and read knobs on the hot path.


include(FetchContent)
FetchContent_Declare(detent
GIT_REPOSITORY https://github.com/Kronuz/Detent.git
GIT_TAG main)
FetchContent_MakeAvailable(detent)
target_link_libraries(my_app PRIVATE detent::detent)

detent::detent has no networking dependencies.


Ship a defaults file alongside your binary. It’s the configuration your process starts with before any live data arrives, and the fallback for any knob the live snapshot omits:

defaults.json
{
"schema_version": 1,
"knobs": {
"checkout:killswitch_new_path": { "default": 0 },
"search:max_results": { "default": 25 },
"payments:new_processor": { "default": 0 }
}
}

A defaults file has no version; it’s always version 0. Keep it in source control next to the code that reads the knobs: adding a knob read and its safe default in the same change is what makes a missing knob impossible.


#include "detent/client.hh"
detent::InitOptions opts;
opts.defaults_path = "/etc/myapp/defaults.json";
detent::Client client(std::move(opts));

Construct one client per process and share it. The constructor parses the defaults synchronously and throws std::runtime_error if the file is missing or invalid. That’s deliberate: a process that can’t load its safe defaults should fail at startup, not serve with an empty configuration.

If you’d rather not thread a Client& through your code, the detent::global adapter holds one process-wide instance:

#include "detent/global.hh"
detent::global::init(std::move(opts));
bool on = detent::global::get_or_panic("checkout:killswitch_new_path") == 1;

Every knob holds one int64; a flag is a knob whose values are 0 and 1. There are two styles of read. get_or_panic returns the value directly and aborts on any error; it’s the recommended default for knob names written in your code:

bool killswitch = client.get_or_panic("checkout:killswitch_new_path") == 1;
std::int64_t max_results = client.get_or_panic("search:max_results");

The plain forms return a Result for code that must handle errors itself, such as a library that can’t abort its host process:

auto r = client.get_as<bool>("checkout:killswitch_new_path");
if (r) {
use(r.value());
} else {
log(r.error().what()); // e.g. "MissingKnob: ..."
}

Pass a hash value for rollouts and a switch value for group overrides:

bool enabled = client.get_or_panic(
"payments:new_processor",
/*hash_val=*/user_id,
/*switch_val=*/user_group) == 1;

For a checked conversion, use get_as<T>. get_as<bool> takes only 0 and 1:

auto limit = client.get_as<std::uint16_t>("search:max_results");
// ConversionFailed if the value doesn't fit, never truncated.

Each individual read sees one complete snapshot, but two separate reads may see two different snapshots if an update lands between them. When several knobs must agree, pin one view:

auto view = client.read_view();
auto max = view.get("search:max_results");
auto on = view.get_as<bool>("checkout:killswitch_new_path");
// Both reads observed the same snapshot.

A view stays valid across later updates and even after the client is destroyed.


So far the process only knows its baked defaults. To receive updates without a restart, give the client one source, a file it polls or a function you supply:

opts.source_path = "/var/lib/myapp/live_knobs.json";
opts.poll_interval = std::chrono::milliseconds{200};

Live Updates covers file sources in detail, and Sources the custom and managed ones.


client.health() returns a small diagnostic snapshot you can expose on your own status page:

auto h = client.health();
// h.initialized, h.source_connected, h.accepted_version,
// h.staleness_seconds, h.knobs, h.cli_overrides

staleness_seconds is the most useful one to alert on: it’s the time since the last successful update, measured on a monotonic clock. See Observability.


main.cc
#include "detent/client.hh"
#include <cstdio>
int main() {
detent::InitOptions opts;
opts.defaults_path = "defaults.json";
detent::Client client(std::move(opts));
std::printf("search:max_results = %lld\n",
static_cast<long long>(client.get_or_panic("search:max_results")));
std::printf("checkout:killswitch_new_path = %s\n",
client.get_or_panic("checkout:killswitch_new_path") == 1 ? "true" : "false");
}
search:max_results = 25
checkout:killswitch_new_path = false

The repository’s examples/demo.cc is a slightly longer version of this program, built as build/examples/detent_demo.