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 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 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.

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.

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.

Trait Implementations

impl<T> Debug for Dynamic<T>

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

Formats the value using the given formatter.