Struct Dynamic 

pub struct Dynamic<T> { /* private fields */ }

A configuration owned by a value rather than a type.

Construct one from a Builder carrying the sources; everything the type-level surface does through generated statics happens here through the instance’s own storage. Two instances of the same T are fully independent: separate snapshots, separate reload hooks, separate watchers, separate caches if configured.

Cloning is deliberately absent: a Dynamic is an owner — share one behind an Arc when several places read it, which is also what keeps “who stops the watcher” a question with one answer.

Implementations

impl<T: DeserializeOwned + Send + Sync + 'static> Dynamic<T>

pub fn new(builder: Builder<T>) -> Self

Wraps builder around storage this instance owns.

The builder’s sources, cache and validation hook all apply unchanged; an installer the builder already carried (a generated builder()’s static cell) is replaced by this instance’s own.

pub fn init(&self) -> Result<(), Error>

Loads and installs as this instance’s snapshot.

The same lifecycle as a type’s init(): validation runs before anything installs, a configured cache is written after a clean load and recovered from when the sources will not load.

Errors

Whatever the load reports: a file that will not parse, a missing required value, a validation refusal with no cache to fall back on.

pub fn init_and_current(&self) -> Result<Arc<T>, Error>

init, handing back the snapshot it installed.

Worth more here than on the type-level surface: an instance’s current is an Option — nothing can panic with a type’s name in it — so the split form ends in an expect that this removes. What comes back is this call’s snapshot, not whatever a reload made current a moment later.

Errors

Exactly init’s.

pub fn current(&self) -> Option<Arc<T>>

The installed snapshot, if init has succeeded.

One atomic load, no lock — cheap enough per request, but take it once per request and reuse the Arc, or a reload landing mid-request shows one request two configurations. None before the first successful install: an instance has no place to panic with the type’s name in it, so absence is an answer rather than an accident.

pub fn generation(&self) -> u64

Installs since this instance was created; zero before the first.

Monotonic, and the number a reload hook should read when it needs a total order — on_reload does not define one across overlapping reloads.

pub fn meta(&self) -> Option<SnapshotMeta>

What is true of the installed snapshot, or None before the first.

For operators — which generation is live, how long ago it landed — and deliberately off the read path: current does not consult it, so the value and its metadata are two loads that a reload landing between them leaves one install apart. See SnapshotMeta.

pub fn load(&self) -> Result<T, Error>

Reads the sources and deserializes, installing nothing.

Errors

The same failures as init.

pub fn reload(&self) -> Result<(), Error>

One reload: load, validate, install, rewrite the cache.

A failure installs nothing — the previous snapshot keeps serving.

Errors

The same failures as load.

pub fn on_reload(&self, hook: impl Fn(&Arc<T>, &Arc<T>) + Send + Sync + 'static)

Runs hook after every later install, for the instance’s lifetime.

The same contract as the type-level on_reload: called with the outgoing and incoming snapshots, on whichever thread performed the reload — compare, then signal the subsystem that owns the resource.

Concurrent reloads

Each call sees a consistent (previous, current) pair: both were installed, and current was installed after previous.

The order of calls is not defined when two reloads overlap. Two hooks may observe the same pair, and one hook may see (A, B) after another saw (B, C). A hook that needs a total order should read generation — which is monotonic — rather than infer one from its arguments.

Reloads are not serialised against each other on purpose: a lock held across user callbacks would let one slow hook delay every reader, and a hook that blocked would then block reloads.

pub fn on_reload_scoped( &self, hook: impl Fn(&Arc<T>, &Arc<T>) + Send + Sync + 'static, ) -> HookGuard<T>

on_reload, until the returned guard drops.

The same concurrency contract: a consistent pair every call, in no defined order across overlapping reloads.

pub fn on_reload_with( &self, hook: impl Fn(&ReloadEvent<T>) + Send + Sync + 'static, )

on_reload, told why.

The callback receives a ReloadEvent: both snapshots, the ReloadReason, and the install’s SnapshotMeta. Same list, same registration order, same panic isolation as the pair form — and it fires for the first install too, with previous: None, which the pair form has nowhere to say.

pub fn on_reload_with_scoped( &self, hook: impl Fn(&ReloadEvent<T>) + Send + Sync + 'static, ) -> HookGuard<T>

on_reload_with, until the returned guard drops.

pub fn status(&self) -> ConfigStatus

What is true of this instance right now: generation, when it landed, why, and how the reloads since have gone.

A handful of atomic loads and no I/O — no source is re-read — so an exporter can call it per scrape. See ConfigStatus for what it carries and, as deliberately, what it does not.

pub fn builder(&self) -> &Builder<T>

This instance’s builder, for the diagnostics that answer without installing: source_of, is_set, check, explain, snapshot.

The instance does not re-wrap them — the builder’s answers are the instance’s answers, because the builder is where its sources live.

pub fn key(&self) -> &str

The section key this instance reads.

impl<T: DeserializeOwned + Send + Sync + 'static> Dynamic<T>

pub fn watch(&self, debounce: Duration) -> Result<WatchHandle>

Available on crate feature watch only.

Reloads on file changes until the returned handle is dropped.

The same watcher as everything else — same debounce, same directory-level watches — registered under this instance rather than the type: two instances of one T watch side by side, and a second watch on the same instance is AlreadyExists, exactly the one-watcher-per-owner contract the type-level surface has.

Errors

As the builder’s watch: no watchable directory, a backend that cannot start, or this instance already being watched.

pub fn watch_with( &self, debounce: Duration, mode: WatchMode, ) -> Result<WatchHandle>

Available on crate feature watch only.

watch with the detection strategy chosen explicitly — polling is what network and overlay filesystems need.

Errors

As watch.

impl<T: DeserializeOwned + Send + Sync + 'static> Dynamic<T>

pub fn changes(&self) -> Changes<T>

Available on crate feature async only.

A handle woken by every later install of this instance.

The same contract as the type-level changes(): the snapshot current at this call counts as already seen, and a handle taken before init sees the first install as its first change — “wake me when configuration exists”. The handle keeps the instance’s storage alive, so it outliving the Dynamic is safe rather than subtle.

pub async fn load_async(&self) -> Result<T, Error>

Available on crate feature async only.

load, off the async executor.

Errors

The same failures as load.

pub async fn init_async(&self) -> Result<(), Error>

Available on crate feature async only.

init, off the async executor.

Errors

The same failures as init.

pub async fn init_and_current_async(&self) -> Result<Arc<T>, Error>

Available on crate feature async only.

init_and_current, off the async executor.

Errors

The same failures as init.

Trait Implementations

impl<T> Debug for Dynamic<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.