Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorFsLoader::WatchedFileSet Class Reference

Watch an explicit set of files and report only the ones that really changed. More...

#include <PhosphorFsLoader/WatchedFileSet.h>

Inheritance diagram for PhosphorFsLoader::WatchedFileSet:
[legend]

Signals

void filesChanged (const QStringList &paths)
 Emitted once per debounce window that changed something.

Public Member Functions

 WatchedFileSet (QObject *parent=nullptr)
 ~WatchedFileSet () override
 WatchedFileSet (const WatchedFileSet &)=delete
WatchedFileSet & operator= (const WatchedFileSet &)=delete
void setPaths (const QStringList &paths)
 Replace the watched set with paths.
QStringList paths () const
 The watched paths in normalised form, in the order given to setPaths.
void setDebounceInterval (int ms)
 Change the debounce window, for reports and for identity checks alike.
int debounceInterval () const
QStringList watchedPathsForTest () const
 Test-only: every path the underlying watcher currently holds (files and directories together, in physical form), sorted.

Static Public Attributes

static constexpr int DefaultDebounceMs = 100
 Default debounce, long enough to coalesce an editor's write-temp-then-rename save into one report.

Detailed Description

Watch an explicit set of files and report only the ones that really changed.

The file-level sibling of WatchedDirectorySet. Where that class rescans a directory tree through a strategy, this one watches a caller-chosen list of individual paths (a config file and the theme it names, a shader's include and asset dependencies, one user file a script asked about) and tells the caller which of them changed.

• Any path may not exist yet, and any directory on the way to it may be a symlink. Each path is resolved component by component, the way the kernel resolves it, and the set watches every directory the walk passes through, from / down to the file's own directory (or the deepest one that exists), plus the file itself when it exists. Paths that share directories share their watches. • An inotify watch stays on the inode its path named when it was added, so a renamed or retargeted directory would leave every watch below it on the old tree. The set therefore records the identity chain of each path: the device and inode of every directory walked and the text of every symlink followed. After an event it walks the chains again, and only a watch whose path now names another inode is re-armed. A symlinked directory that is retargeted (Home Manager, stow, chezmoi), a parent or grandparent directory replaced by rename, a dangling link whose target appears and a missing directory that is created are all followed this way. • Each path carries a fingerprint (existence, device, inode, size and modification time to the nanosecond). After the debounce, one filesChanged carries exactly the paths whose fingerprint moved. A write to an unrelated file beside a watched one, or anything created, renamed or deleted in an ancestor directory, wakes the watcher but emits nothing. Its cost is a few lstat() calls for each path. Only events on a file or in the directory that holds it restart the debounce. An event further up opens a window of the same length that later events do not extend, so churn there cannot postpone a report.

Unlike WatchedDirectorySet's own watches, an ancestor watch here is never refused for being a high-churn root such as $HOME or /: every one of them can hold the entry that moves, and the identity chain turns unrelated churn there into a few lstat() calls per debounce rather than a signal.

Paths are normalised to clean absolute form (QFileInfo::absoluteFilePath then QDir::cleanPath), and that is the spelling paths() returns and filesChanged reports. Symlinks are followed for the fingerprint, so retargeting a link counts as a change of the path. The watches themselves are held under physical paths, with no symlink in them.

POSIX only: the fingerprint is read with stat() and the chain with lstat() and readlink().

Thread safety

GUI-thread only, like WatchedDirectorySet. The watcher and the debounce timer live on the thread the set was constructed on.

Constructor & Destructor Documentation

◆ WatchedFileSet() [1/2]

PhosphorFsLoader::WatchedFileSet::WatchedFileSet ( QObject * parent = nullptr)
explicit

◆ ~WatchedFileSet()

PhosphorFsLoader::WatchedFileSet::~WatchedFileSet ( )
override

◆ WatchedFileSet() [2/2]

PhosphorFsLoader::WatchedFileSet::WatchedFileSet ( const WatchedFileSet & )
delete

Member Function Documentation

◆ debounceInterval()

int PhosphorFsLoader::WatchedFileSet::debounceInterval ( ) const

◆ filesChanged

void PhosphorFsLoader::WatchedFileSet::filesChanged ( const QStringList & paths)
signal

Emitted once per debounce window that changed something.

paths lists, in paths() order, every watched path whose fingerprint differs from the last one observed: created, deleted, replaced, or edited in place. Never emitted with an empty list.

◆ operator=()

WatchedFileSet & PhosphorFsLoader::WatchedFileSet::operator= ( const WatchedFileSet & )
delete

◆ paths()

QStringList PhosphorFsLoader::WatchedFileSet::paths ( ) const

The watched paths in normalised form, in the order given to setPaths.

◆ setDebounceInterval()

void PhosphorFsLoader::WatchedFileSet::setDebounceInterval ( int ms)

Change the debounce window, for reports and for identity checks alike.

Values below 0 are clamped to 0. Takes effect from the next event; a pending window keeps its interval.

◆ setPaths()

void PhosphorFsLoader::WatchedFileSet::setPaths ( const QStringList & paths)

Replace the watched set with paths.

Reconciles rather than accumulates: watches for paths no longer listed are removed, new ones are added, and the underlying watcher ends up holding exactly what the new set needs. Empty entries and duplicates (after normalisation) are dropped.

A newly listed path takes its current fingerprint as the baseline and is not reported by this call. A path that stays listed keeps its baseline, so a change still pending in the debounce window is reported as usual.

◆ watchedPathsForTest()

QStringList PhosphorFsLoader::WatchedFileSet::watchedPathsForTest ( ) const

Test-only: every path the underlying watcher currently holds (files and directories together, in physical form), sorted.

Lets a test pin that setPaths reconciles instead of accumulating, and which ancestors are watched.

Member Data Documentation

◆ DefaultDebounceMs

int PhosphorFsLoader::WatchedFileSet::DefaultDebounceMs = 100
staticconstexpr

Default debounce, long enough to coalesce an editor's write-temp-then-rename save into one report.


The documentation for this class was generated from the following file: