pub enum InvalidateReason {
WatchOverflow,
UnpairedRename,
WatchSetupRace,
PeriodicSweep,
VerificationFailed,
UnknownAncestry,
WatchContention,
ControlPopulationChanged,
Requested,
}Expand description
Why a producer had to escalate to Op::InvalidateSubtree instead of describing a
change precisely.
Each variant corresponds to a real, documented platform limitation rather than a defensive catch-all, and the scan layer resolves every one of them the same way.
Variants§
WatchOverflow
The kernel dropped events: inotify Q_OVERFLOW, FSEvents MustScanSubDirs, or a
Windows ReadDirectoryChangesW buffer overrun. All three surface through notify
as Flag::Rescan, and swallowing that flag silently corrupts any index built on
events.
UnpairedRename
A rename left entries no event describes. Renames arrive one side at a time
(FSEvents reports each path with no mechanism to associate old and new), and
each side is verified as its own path, so this is raised only where a side’s own
path does not settle it: a directory that arrived by rename is relisted, because
no backend reports a moved tree’s contents; a renamed name its parent does not
list exactly (a case-only rename on an insensitive filesystem) reconciles the
parent; and a rename of the root itself, or from a backend that may never name
the new side (kqueue), reconciles the whole root.
WatchSetupRace
A directory was created and its watch registered a moment later; anything created inside that window produced no event at all.
PeriodicSweep
A periodic reconciliation sweep, for backends that cannot signal drops at all (kqueue).
VerificationFailed
Stat verification failed without proving the path is gone. The known entry must remain until reconciliation can retry and report the underlying I/O error.
UnknownAncestry
A verified child arrived below ancestry the index has not verified. The child is withheld while reconciliation starts from the nearest known directory.
WatchContention
Repeated concurrent commits prevented a watch sample from reaching a stable arbitration boundary. The root is reconciled instead of doing filesystem I/O under the index lock or allowing an old sample to win.
ControlPopulationChanged
A control edit may admit or remove entries under a narrowed ignored population, including entries absent from the current index. Revisit its parent directory.
Requested
Requested by the caller.