ludus::foundation::filesystem::Watcher¶

Class

Bounded polling adapter for registered final cooked paths on Windows, Linux, macOS or Emscripten MEMFS. Browser observations stay in session memory and do not watch host filesystem changes. All methods and destruction require one host owner thread. No background jobs/callbacks. Metadata polling can miss transient or metadata-preserving edits and discovers no new paths. Producers should atomically publish cooked output; debounce does not validate completeness. Watcher hints never modify opened readers, mounts or Content bindings.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

#include <ludus/foundation/filesystem/watch.hpp>

class ludus::foundation::filesystem::Watcher final

Methods¶

Watcher¶

ludus::foundation::filesystem::Watcher::Watcher() noexcept=default

Creates an uninitialized adapter.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

~Watcher¶

ludus::foundation::filesystem::Watcher::~Watcher() noexcept

Releases registration storage and the pinned root best-effort.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

Watcher¶

ludus::foundation::filesystem::Watcher::Watcher(const Watcher &)=delete

Watchers have one stable owner identity and cannot be copied.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

operator=¶

Watcher & ludus::foundation::filesystem::Watcher::operator=(const Watcher &)=delete

Watchers have one stable owner identity and cannot be assigned.

Related types: Watcher

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

Init¶

Result ludus::foundation::filesystem::Watcher::Init(std::string_view nativeRoot, const WatchConfig &config={}) noexcept

Pins a trusted native root and allocates fixed storage; failure preserves existing state. Unsupported native targets return Unsupported. Successful reinitialization retires handles.

Related types: Result · WatchConfig

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

Add¶

Result ludus::foundation::filesystem::Watcher::Add(std::string_view path, uint64 tag, WatchHandle &output) noexcept

Registers a unique byte-spelled path and captures its initial regular-file/absence baseline. Failure preserves output. No allocation occurs. Refused during a rescan.

Related types: uint64 · Result · WatchHandle

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

Remove¶

Result ludus::foundation::filesystem::Watcher::Remove(WatchHandle handle) noexcept

Retires a matching handle and removes its pending hints; stale/foreign handles are invalid. Refused during a rescan. Does not access the filesystem or allocate.

Related types: Result · WatchHandle

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

Advance¶

Result ludus::foundation::filesystem::Watcher::Advance(uint64 nowNanoseconds, usize maxSteps) noexcept

Examines at most maxSteps slot positions, advancing a round-robin cursor without allocation. maxSteps must be 1..MaxPaths; nowNanoseconds is a host monotonic timestamp, allowed to repeat. Backward time is rejected. Overflow/errors require rescan and stop incremental observation.

Related types: uint64 · usize · Result

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

Poll¶

WatchPollResult ludus::foundation::filesystem::Watcher::Poll(WatchHint &output) noexcept

Pops one changed hint or the sticky global rescan notice; no filesystem access/allocation. The global notice is delivered once until a failed rescan requests another attempt.

Related types: WatchHint · WatchPollResult

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

BeginRescan¶

Result ludus::foundation::filesystem::Watcher::BeginRescan() noexcept

Clears incremental hints and starts a rescan of the fixed registration set. Add/Remove/Advance/Poll are refused until NextRescan completes the pass.

Related types: Result

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

NextRescan¶

WatchPollResult ludus::foundation::filesystem::Watcher::NextRescan(WatchHint &output) noexcept

Observes at most one registered path per call and returns a RescanEntry, even unchanged. A successful empty result completes the pass. Any observation error other than NotFound keeps NeedsRescan set. No allocation occurs; scanning skips at most MaxPaths slots. A pass is not an atomic snapshot; hosts must open and validate selected revisions explicitly.

Related types: WatchHint · WatchPollResult

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

NeedsRescan¶

bool ludus::foundation::filesystem::Watcher::NeedsRescan() const noexcept

Returns whether incremental observations require a full registered-path rescan.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

IsRescanning¶

bool ludus::foundation::filesystem::Watcher::IsRescanning() const noexcept

Returns whether a rescan pass is in progress.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

DroppedHints¶

uint64 ludus::foundation::filesystem::Watcher::DroppedHints() const noexcept

Returns a saturating count of incremental hints discarded by overflow or observation errors in this lifetime.

Related types: uint64

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp