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.
1. Add the Dependency
Section titled “1. Add the Dependency”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.
2. Write Your Baked Defaults
Section titled “2. Write Your Baked Defaults”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:
{ "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.
3. Construct a Client
Section titled “3. Construct a Client”#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;4. Read Knobs
Section titled “4. Read Knobs”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.5. Read a Consistent Set of Knobs
Section titled “5. Read a Consistent Set of Knobs”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.
6. Add a Live Source
Section titled “6. Add a Live Source”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.
7. Check Health
Section titled “7. Check Health”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_overridesstaleness_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.
A Complete Program
Section titled “A Complete Program”#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 = 25checkout:killswitch_new_path = falseThe repository’s examples/demo.cc is a slightly longer version of this
program, built as build/examples/detent_demo.