Struct HotReloadConfig 

pub struct HotReloadConfig { /* private fields */ }

Hot-reloadable configuration container.

Construct with HotReloadConfig::from_file, then either drive reloads manually with HotReloadConfig::reload or hand off to a background watcher with HotReloadConfig::start_watching.

Configurable knobs (all consuming-builder style, intended for fluent construction):

• HotReloadConfig::on_change — register a change handler (v1.0.0+; the recommended notification API).
• HotReloadConfig::with_change_notifications — receive ConfigChangeEvents on an mpsc channel (deprecated since v1.0.0; kept as a bridge for backwards compatibility).
• HotReloadConfig::with_debounce — adjust the debounce window (default 100 ms).
• HotReloadConfig::with_poll_interval — set the polling interval. Used directly when the hot-reload feature is off; used as the watchdog interval when the feature is on.
• HotReloadConfig::with_polling_fallback — opt into a parallel polling watchdog in addition to the event-driven watcher, for environments where the kernel watcher is known unreliable.

Implementations

impl HotReloadConfig

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>

Create a new hot-reloadable configuration from a file.

Errors

Returns an error if the file cannot be read, parsed, or stat’d for its modification time.

pub fn with_poll_interval(self, interval: Duration) -> Self

Set the polling interval for file change detection.

When the hot-reload feature is enabled (the default in v0.9.6+), the primary watcher is event-driven and this interval is only consulted as the watchdog cadence if with_polling_fallback has been called.

When the hot-reload feature is disabled, this is the actual polling cadence of the background thread.

pub fn with_debounce(self, debounce: Duration) -> Self

Override the debounce window applied to clustered file-change events.

Editors that save via “write-to-tmp + atomic-rename” generate multiple kernel events for a single user save. The debounce collapses any burst within this window to a single reload. Default: 100 ms.

pub fn with_polling_fallback(self) -> Self

Opt into running a polling watchdog in addition to the event-driven watcher.

Network filesystems (SMB, NFS), some container overlay filesystems, and a handful of edge-case kernel configurations drop or delay events that notify would normally surface. Enabling the polling fallback re-derives changes from periodic stat(2) calls on the watched path, at the HotReloadConfig::with_poll_interval cadence.

Has no effect (and costs nothing) when the hot-reload Cargo feature is disabled — the watcher is already polling in that configuration.

pub fn on_change<F>(&self, handler: F) -> Subscription

where F: Fn(&ConfigChangeEvent) + Send + Sync + 'static,

Register a change handler. Recommended notification API (v1.0.0+).

The handler is invoked inline on the reloader thread every time a ConfigChangeEvent is produced — typically a few milliseconds after the underlying filesystem event, plus the debounce window. Dispatch overhead is a single atomic pointer load (~5 ns) plus the handler’s own cost; multiple handlers are called in registration order with no per-handler channel allocation.

Returns a Subscription whose Drop unregisters the handler. Bind to a let _sub = ... if you want the handler to live for the surrounding scope, or call Subscription::forget to detach the drop hook.

Panics

If the handler itself panics, the panic is caught via catch_unwind and discarded — other handlers continue to receive the event and the reloader thread is not torn down. Handler authors should avoid panicking, but a buggy handler won’t take down the whole library.

Example

use config_lib::hot_reload::{HotReloadConfig, ConfigChangeEvent};

let hot = HotReloadConfig::from_file("app.conf")?;
let _sub = hot.on_change(|event: &ConfigChangeEvent| {
    if let ConfigChangeEvent::Reloaded { path, .. } = event {
        println!("reloaded {}", path.display());
    }
});
let _handle = hot.start_watching();
// ... `_sub` and `_handle` are alive for the rest of the scope

pub fn with_change_notifications(self) -> (Self, Receiver<ConfigChangeEvent>)

👎Deprecated since 1.0.0:

use on_change for lock-free dispatch; this method continues to work but pays an mpsc allocation per event

Enable channel-based change notifications. Deprecated since v1.0.0 — prefer HotReloadConfig::on_change.

Internally bridges to the same lock-free handler list as on_change by registering a closure that forwards events to an mpsc::Sender. The bridge subscription is held by self so the channel keeps receiving events for the lifetime of the watcher.

The bridge pays one extra mpsc::Sender::send per event (~100–200 ns) on top of the lock-free dispatch cost — the inverse of why on_change exists. Existing code using Receiver<ConfigChangeEvent> continues to work unchanged.

pub fn config(&self) -> Arc<RwLock<Config>>

Get a thread-safe reference to the current configuration.

pub fn snapshot(&self) -> Result<Config>

Get a freshly-reparsed snapshot of the configuration file as it exists on disk right now.

This is distinct from reading the current Arc<RwLock<Config>> — it bypasses the watcher and re-reads the file. Useful for “what would I see if I reloaded now” inspection.

Errors

Returns an error if the file cannot be read or parsed.

pub fn reload(&mut self) -> Result<bool>

Manually trigger a reload check.

Re-stats the file, compares mtime against the last-known modification time, and re-parses if newer. Dispatches a ConfigChangeEvent::Reloaded or ConfigChangeEvent::ReloadFailed notification through the handler list.

Returns Ok(true) if a reload was performed, Ok(false) if the file was unchanged since the last check.

Errors

Returns an error if the file cannot be stat’d, read, or parsed.

pub fn start_watching(self) -> HotReloadHandle

Start automatic hot reloading in a background thread.

With the hot-reload Cargo feature enabled (the default in v0.9.6+), the background worker registers a notify::RecommendedWatcher on the file’s parent directory and reacts to kernel events. Otherwise it falls back to a poll_interval-cadence polling thread (the v0.9.5 behavior).

pub fn file_path(&self) -> &Path

Get the file path being watched.

pub fn last_modified(&self) -> SystemTime

Get the last modification time.