Struct ConfigCell 

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

Holds the current configuration snapshot for one type.

ConfigCell::new() is const, so this lives in a static — which is how #[dynamic_config] emits it.

Reads are lock-free. load clones an Arc out of an ArcSwap, so a reload never blocks a request handler and a reader that already holds an Arc keeps observing its own generation until it drops it. Call it once per unit of work: calling it twice within one request can straddle a reload and observe two different configurations.

Example

use dynamic_config::ConfigCell;

static PORT: ConfigCell<u16> = ConfigCell::new();

assert!(PORT.load().is_none());

PORT.store(8080);
assert_eq!(*PORT.load().unwrap(), 8080);

Implementations

impl<T> ConfigCell<T>

pub const fn new() -> Self

Available on non-loom only.

An empty cell.

pub fn store(&self, value: T)

Atomically installs value as the current snapshot.

Reload callbacks run, and with the async feature every waiting task is woken. Installing the first snapshot is not a reload, so on_reload callbacks do not fire for it — there is nothing to compare against. on_reload_with does fire, with previous: None, which is the difference between having somewhere to say that and not.

The install is recorded as ReloadReason::Manual: something in the program stored it. Use store_with where more is known.

pub fn store_with(&self, value: T, reason: ReloadReason) -> Arc<T>

store, stating why — and handing back what it installed.

The reason travels from the call site that knows it — the watcher knows the file, init knows it is the first — to the hooks and to status. Nothing downstream can reconstruct it: by the time a hook runs, every install is the same swap.

The returned Arc is this call’s snapshot, not whatever is current when it returns: a reload landing a moment later would make a following load answer differently, and the caller that installed a configuration means the one it installed. It costs nothing — the Arc was allocated here anyway — and ignoring it is the ordinary case.

pub fn record_failure(&self, error: &Error)

Records a reload that installed nothing.

Called by whatever decided not to install — a load that failed, a validation that refused — so that status can answer did the last attempt work and how many have failed since one did. The next successful install resets the streak.

Only the failure’s category and key path are kept; see FailureStatus.

pub fn status(&self) -> ConfigStatus

What is true of this configuration right now.

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

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

Registers a callback for every later reload.

The callback receives the outgoing and incoming snapshots, in that order, and runs on whichever thread performed the reload — the watcher thread, usually. Keep it short, and do not store again from inside one: that recurses rather than deadlocking, which is worse.

Callbacks registered this way cannot be removed — a hook for the life of the process, which is what a server wants. Anything with a shorter life — a test, a plugin, a subsystem that can be torn down — should use on_reload_scoped and hold the guard.

A hook that panics is caught, reported, and skipped for that reload; the remaining hooks still run and the watcher thread survives. It is not unregistered — a bug in a hook should be loud on every reload, not once.

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 deliberately not serialised against each other. The same store that dispatches these hooks wakes async waiters before running them, so that one slow callback cannot delay every reader; a lock held across user callbacks would undo that on purpose, and a hook that blocked would then block 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 SnapshotMeta of the install. Everything the pair form promises holds here — same list, same order of registration, same panic isolation, same absence of an order across overlapping reloads — with one difference the pair form’s signature makes impossible: this fires for the first install too, with previous: None. A hook that only wants reloads matches on that, or registers through on_reload.

use dynamic_config::{ConfigCell, ReloadReason};

static PORT: ConfigCell<u16> = ConfigCell::new();

PORT.on_reload_with(|event| {
    if let ReloadReason::FileChanged(path) = &event.reason {
        println!("generation {} came from {}", event.meta.generation, path.display());
    }
});

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

on_reload, scoped: dropping the returned guard unregisters the hook.

For anything whose life is shorter than the process — the permanent variant would keep a torn-down subsystem’s callback firing forever.

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

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

on_reload_with, scoped: dropping the returned guard unregisters the hook.

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

The current snapshot, or None if nothing has been stored yet.

pub fn generation(&self) -> u64

Installs since the process started; zero before the first.

Monotonic, so it is 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.

A load of its own: load is untouched by this and stays one atomic load, which means the value and its metadata can be one install apart. See SnapshotMeta.

pub fn get_or_panic(&self, type_name: &str) -> Arc<T>

The current snapshot, panicking if there is none.

type_name is used to build the message; the generated code passes the annotated struct’s name so the panic names the type the caller wrote.

Panics

If nothing has been stored yet.

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

where T: Send + Sync,

Available on crate feature async only.

A handle woken by every later store.

The snapshot current at this call counts as already seen, so the first changed() waits for the next store. Read the value you start from with load.

Runtime-agnostic: it is a Future, and any executor drives it.

Trait Implementations

impl<T: Debug> Debug for ConfigCell<T>

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

Formats the value using the given formatter.

impl<T> Default for ConfigCell<T>

fn default() -> Self

Returns the “default value” for a type.