Skip to content

Sources

A client consumes at most one live source. Each kind is selected by a different InitOptions field, and they are mutually exclusive.

SourceFieldLink
None (baked defaults only)nonedetent::detent
Snapshot filesource_pathdetent::detent
Any custom pollersource_poll = your functiondetent::detent
Managed generationsread_source = make_local_read_source(...)detent::local_client

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

Every poll_interval, the updater checks the file’s modification time and size, and rereads the whole file (up to 16 MiB) when either changed. Publishers must replace the file atomically with write-then-rename.


source_poll accepts any function with this signature:

using SourcePoll = std::function<
std::optional<InitOptions::SourcePayload>(std::uint64_t after_version)>;
struct SourcePayload {
std::string bytes;
bool is_patch = false;
};

The updater calls it every poll_interval with the currently accepted version.

Your functionThe client
Returns a payload with is_patch = falseValidates it as a full snapshot
Returns a payload with is_patch = trueApplies it as a patch onto its own last accepted live snapshot
Returns std::nulloptTreats it as “nothing new”, with no backoff
ThrowsCounts a refresh failure and backs off with full jitter

The client owns parsing, version checks, merging, metrics and backoff; a source only fetches bytes. For example, a source backed by a key-value store:

opts.source_poll = [kv](std::uint64_t after) -> std::optional<detent::InitOptions::SourcePayload> {
auto latest = kv->get("knobs/snapshot"); // throws on connection failure
if (!latest || latest->version <= after) return std::nullopt;
return detent::InitOptions::SourcePayload{std::move(latest->json), false};
};

#include "detent_local/client_source.hh"
options.read_source = detent::local::make_local_read_source(
detent::local::ClientSourceOptions{.directory = generation_directory});

Reads the immutable generations a managed agent publishes. Refresh work runs on one configuration thread; acquiring a view and lookups need no allocation. Unchanged polls check selection metadata without remapping. A failed refresh keeps the prior view, and health() reports source connectivity.

Clients with a read source:

  1. Read through read_view(); current_snapshot() throws std::logic_error.
  2. Apply CLI overrides first, fall back to baked defaults for missing live keys, and never fall back on a conversion error.
  3. Must be destroyed outside an event-loop turn, since destruction joins the refresh worker.