Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
MetadataPackLoader.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
7
10
11#include <QtCore/QCryptographicHash>
12#include <QtCore/QHash>
13#include <QtCore/QJsonObject>
14#include <QtCore/QString>
15#include <QtCore/QStringList>
16
17#include <functional>
18#include <memory>
19#include <optional>
20#include <type_traits>
21#include <utility>
22
23QT_BEGIN_NAMESPACE
24class QLoggingCategory;
25QT_END_NAMESPACE
26
27namespace PhosphorRegistry {
28
29// Populates a Registry<Factory> from content packs discovered on disk —
30// the metadata-pack counterpart to PluginLoader (which populates a
31// Registry from the bar-widget Qt plugins a PluginCatalog finds). Both feed the SAME generic
32// Registry<T>; this is the seam that lets a domain registry (shaders,
33// animation effects, …) compose Registry<T> for storage + notify while
34// keeping a filesystem-scanned, hot-reloading content catalogue.
35//
36// ## What it does
37//
38// - Owns a phosphor-fsloader MetadataPackScanStrategy<Entry> +
39// WatchedDirectorySet (the same scan/watch substrate the
40// since-removed MetadataPackRegistryBase used), configured with a domain Parser
41// that turns one pack's metadata.json into a shared_ptr<Factory>.
42// - On every committed rescan, reconciles the Registry to match the
43// freshly-scanned set: NEW packs are registerFactory'd, REMOVED
44// packs unregisterFactory'd, and CHANGED packs (same id, different
45// content) re-registered. Reconciliation is per-entry by content
46// fingerprint, so an unchanged pack fires no spurious
47// register/unregister churn even when a sibling pack changed.
48//
49// ## Why fingerprint reconcile (not strategy-owned storage)
50//
51// MetadataPackScanStrategy rebuilds its pack map (and thus a fresh
52// shared_ptr<Factory> per pack) on every rescan, and fires its OnCommit
53// only when the cross-pack signature changed. A naive "drop all, re-add
54// all" on commit would unregister + re-register every pack on any single
55// pack's edit, so consumers connected to the Registry's per-entry
56// notifier would see the whole catalogue churn. Diffing the committed
57// set against a stored per-id fingerprint emits the minimal, accurate
58// set of factoryRegistered / factoryUnregistered signals.
59//
60// ## Ownership / lifetime
61//
62// - Does NOT own the Registry; the caller does, and the Registry MUST
63// outlive the loader. The loader holds a borrowed Registry pointer it
64// uses during LIVE rescans in reconcile() (where a removed pack calls
65// Registry::unregisterFactory); the defaulted destructor unregisters
66// nothing, so the registry simply outlives and is torn down after it.
67// - Owns the strategy + watcher. Declaration order is load-bearing:
68// m_strategy is declared before m_watcher so the watcher (which
69// holds a borrowed reference into the strategy) tears down first.
70//
71// ## Threading
72//
73// GUI-thread only — inherits WatchedDirectorySet's contract. Every
74// mutating call (addSearchPaths / setUserPath / refresh) must run on
75// the construction thread.
76//
77// Not re-entrant: reconcile() updates m_fingerprints AFTER driving the
78// Registry, whose change signals fire synchronously on this thread. A
79// slot that calls back into the loader (refresh / addSearchPaths) from
80// inside a Registry signal would run a nested reconcile against stale
81// fingerprints. Registry slots must not mutate the loader re-entrantly.
82template<typename Factory>
84{
85 static_assert(std::is_base_of_v<IFactoryBase, Factory>,
86 "MetadataPackLoader<T> requires T to derive from PhosphorRegistry::IFactoryBase");
87
88public:
89 // Turns one pack directory's parsed metadata.json into a factory, or
90 // returns null to decline the pack (the strategy then skips it, with
91 // a qDebug under the supplied logging category). @p isUser is true
92 // when the pack was discovered under the user path (see setUserPath).
93 using Parser =
94 std::function<std::shared_ptr<Factory>(const QString& subdirPath, const QJsonObject& root, bool isUser)>;
95
96 // Optional. Mixes a factory's content into the change-detection
97 // hash, so a content edit to an existing pack (same id) is detected
98 // and re-registered, while an unrelated pack's edit leaves this one
99 // untouched. Without it, only the id set drives change detection
100 // (add / remove only; in-place edits to a kept id are NOT seen).
101 using SignatureContrib = std::function<void(QCryptographicHash&, const Factory&)>;
102
103 // Optional. Extra files (beyond the pack's metadata.json, already
104 // watched) whose changes should trigger a rescan — e.g. the shader
105 // source files a pack references.
106 using PerEntryWatchPaths = std::function<QStringList(const Factory&)>;
107
108 // Optional. Files watched at the search-directory level rather than
109 // per pack — e.g. shared GLSL includes (common.glsl) every pack pulls
110 // in. An edit fires a rescan + the committed hook (so consumers
111 // re-read content) but produces no per-entry registry change, since
112 // it belongs to no single pack.
113 using PerDirectoryWatchPaths = std::function<QStringList(const QString& searchPath)>;
114
115 // Optional. Return true to skip a subdirectory during the scan — e.g.
116 // a "shared" includes dir or a "none" sentinel that is not a pack.
117 using PerSubdirSkip = std::function<bool(const QString& subdirName)>;
118
119 // Optional. Fired once after every committed rescan (after the
120 // registry reconcile), whether or not any per-entry change occurred.
121 // The coarse "the catalogue was rescanned" hook a domain facade
122 // bridges to its own contentsChanged / shadersChanged signal, so
123 // consumers re-read content (re-bake a shader) even when the change
124 // was a pack's source file or a shared include — neither of which
125 // alters a pack's parsed metadata and so fires no per-entry signal.
126 using CommittedCallback = std::function<void()>;
127
128 // @p registry must be non-null and must outlive the loader — it is a
129 // hard precondition (the loader is useless without a store and every
130 // reconcile dereferences it). The ctor `qFatal`s on null in EVERY build:
131 // it is a programmer-error contract violation, not a recoverable
132 // condition, and crashing deterministically at construction with a
133 // greppable message beats crashing inside the first reconcile, far from
134 // the cause. In practice callers pass the address of a
135 // Registry member they own, so null cannot legitimately occur. @p parser
136 // is required (a null parser would silently skip every pack). @p logCat is
137 // stored by reference and must outlive the loader (a Q_LOGGING_CATEGORY
138 // static is the standard source); it labels the scan/parse diagnostics.
139 MetadataPackLoader(Registry<Factory>* registry, Parser parser, const QLoggingCategory& logCat)
140 : m_registry(registry)
141 , m_strategy(makeStrategy(std::move(parser)))
142 , m_watcher(std::make_unique<PhosphorFsLoader::WatchedDirectorySet>(*m_strategy, nullptr))
143 {
144 // qFatal, not Q_ASSERT_X: the release-build consequence of a null
145 // registry is a crash inside the first reconcile, far from the cause,
146 // and the sibling with the identical precondition (PluginLoader) is
147 // already qFatal. Crashing here is deterministic, at construction, with
148 // a greppable message.
149 if (m_registry == nullptr) {
150 qFatal("MetadataPackLoader: registry must not be null");
151 }
152 m_strategy->setLoggingCategory(logCat);
153 }
154
156 Q_DISABLE_COPY_MOVE(MetadataPackLoader)
157
158 // Mix factory content into the change hash. Call before the first
159 // scan (i.e. before addSearchPaths) so the initial commit's
160 // fingerprints are content-aware.
162 {
163 // Two deliberate copies from the parameter: one kept for
164 // reconcile(), one captured by the strategy lambda. Spelled as two
165 // plain copies (not copy-then-move of the same object) so it cannot
166 // be misread as a use-after-move.
167 m_sigContrib = fn;
168 m_strategy->setSignatureContrib([contrib = fn](QCryptographicHash& hasher, const Entry& e) {
169 if (contrib && e.factory) {
170 contrib(hasher, *e.factory);
171 }
172 });
173 }
174
175 // Extra per-pack watch paths (the pack's own metadata.json is always
176 // watched by the strategy).
178 {
179 m_strategy->setPerEntryWatchPaths([fn = std::move(fn)](const Entry& e) -> QStringList {
180 return (fn && e.factory) ? fn(*e.factory) : QStringList{};
181 });
182 }
183
184 // Watch shared / directory-level files (passthrough to the strategy).
186 {
187 m_strategy->setPerDirectoryWatchPaths(std::move(fn));
188 }
189
190 // Skip non-pack subdirectories during the scan (passthrough).
192 {
193 m_strategy->setPerSubdirSkip(std::move(fn));
194 }
195
196 // Set the coarse post-commit hook. Fires after reconcile on every
197 // committed rescan. Set before the first scan so the initial commit
198 // is observed.
200 {
201 m_onCommitted = std::move(fn);
202 }
203
204 // Add search directories. A single
205 // batched register runs one synchronous scan; the reconcile +
206 // per-entry Registry signals fire inline before this returns.
207 //
208 // Already-registered paths are filtered out first. If EVERY path in the
209 // batch is already registered this is a complete no-op: it returns without
210 // scanning and emits nothing, so callers must not rely on it as a way to
211 // force a rescan (use rescanNow() for that).
212 void
215 {
216 const QStringList toRegister =
218 if (toRegister.isEmpty()) {
219 return;
220 }
221 m_watcher->registerDirectories(toRegister, liveReload, order);
222 }
223
228
229 [[nodiscard]] QStringList searchPaths() const
230 {
231 return m_watcher->directories();
232 }
233
234 // Mark @p path as the user-data root for isUser classification.
235 // Order-independent vs addSearchPaths; triggers a synchronous rescan
236 // (reclassifying + reconciling) when the value changes and at least
237 // one search path is already registered.
238 void setUserPath(const QString& path)
239 {
240 if (m_userPath == path) {
241 return;
242 }
243 m_userPath = path;
244 m_strategy->setUserPath(path);
245 if (!m_watcher->directories().isEmpty()) {
246 m_watcher->rescanNow();
247 }
248 }
249
250 // Synchronous rescan — re-walks every search path on the calling
251 // stack and reconciles the Registry.
252 void refresh()
253 {
254 m_watcher->rescanNow();
255 }
256
257private:
258 // One scanned pack: the id the strategy keys on + the factory the
259 // domain parser produced. `.id` (a QString field) satisfies
260 // MetadataPackScanStrategy's Payload contract.
261 struct Entry
262 {
263 QString id;
264 std::shared_ptr<Factory> factory;
265 };
266
267 std::unique_ptr<PhosphorFsLoader::MetadataPackScanStrategy<Entry>> makeStrategy(Parser parser)
268 {
269 auto wrappedParser = [parser = std::move(parser)](const QString& subdir, const QJsonObject& root,
270 bool isUser) -> std::optional<Entry> {
271 std::shared_ptr<Factory> factory = parser ? parser(subdir, root, isUser) : nullptr;
272 if (!factory) {
273 return std::nullopt;
274 }
275 return Entry{factory->id(), std::move(factory)};
276 };
277 return std::make_unique<PhosphorFsLoader::MetadataPackScanStrategy<Entry>>(std::move(wrappedParser), [this]() {
278 reconcile();
279 if (m_onCommitted) {
280 m_onCommitted(); // coarse post-commit hook (after per-entry reconcile)
281 }
282 });
283 }
284
285 // Bring the Registry in line with the strategy's freshly-committed
286 // pack set, emitting only the minimal per-entry signals.
287 void reconcile()
288 {
289 QHash<QString, QByteArray> fresh;
290 const QList<Entry> packs = m_strategy->packs();
291 for (const Entry& e : packs) {
292 QCryptographicHash hasher(QCryptographicHash::Sha1);
293 hasher.addData(e.id.toUtf8());
294 if (m_sigContrib && e.factory) {
295 m_sigContrib(hasher, *e.factory);
296 }
297 const QByteArray fp = hasher.result();
298
299 const auto prev = m_fingerprints.constFind(e.id);
300 if (prev == m_fingerprints.cend()) {
301 // Newly discovered. The RESULT matters: `registerFactory`
302 // defaults to DuplicatePolicy::Reject, so an id already present
303 // from an out-of-band registration FAILS here. Recording the
304 // fingerprint anyway would make `m_fingerprints.contains(id)`
305 // true below, and on the refresh where that pack disappears this
306 // loader would unregister a factory it never registered — the
307 // exact case the removal filter's comment claims it excludes.
308 // No warning: this is a header-only template with no logging
309 // category of its own, and the condition is benign — the
310 // out-of-band registration wins, which is what Reject means.
311 if (!m_registry->registerFactory(e.factory)) {
312 continue;
313 }
314 } else if (prev.value() != fp) {
315 // Content changed: replace in place. Replace (not a separate
316 // unregister + register) keeps the pack's REGISTRATION-ORDER
317 // position — a hot-reload must not shuffle the edited pack to
318 // the end of ids()/forEach() (Registry's documented invariant).
319 // It still fires factoryUnregistered(old) + factoryRegistered(new).
320 // (m_strategy->packs() is id-sorted, so the INITIAL scan registers
321 // in lexicographic id order; a pack discovered on a later refresh
322 // appends, so consumers that need a sorted order re-sort ids()
323 // themselves rather than relying on loader registration order.)
324 if (!m_registry->registerFactory(e.factory, QString(), DuplicatePolicy::Replace)) {
325 // Checked symmetrically with the newly-discovered branch above.
326 // Recording a fingerprint for a replace that did not land would
327 // again have this loader claim an id it does not own, and the
328 // removal sweep below would then unregister a factory it never
329 // registered — the very case the new-pack check closes.
330 continue;
331 }
332 } else if (!m_registry->factory(e.id)) {
333 // Unchanged CONTENT, but the id is gone from the registry — an
334 // out-of-band unregister. Re-register it defensively. Note this
335 // is only an OPPORTUNISTIC repair, not a general recovery:
336 // reconcile() runs solely from the OnCommit hook, which fires
337 // only when the scan signature moved, and an out-of-band
338 // unregister changes none of the signature's inputs (ids,
339 // isUser, metadata size/mtime, watch-set fingerprint). So this
340 // branch repairs an out-of-band removal only when SOME OTHER
341 // pack's bytes changed in the same scan and dragged the
342 // signature — the loader is documented as the sole writer of
343 // its borrowed Registry (see the removal-sweep note below), so
344 // an out-of-band unregister is out-of-contract to begin with,
345 // and this is belt-and-braces rather than a relied-on path.
346 if (!m_registry->registerFactory(e.factory)) {
347 continue;
348 }
349 }
350 // else: unchanged and still registered — leave the registry entry as-is.
351
352 // Recorded only once this loader is known to own the id, so the
353 // removal filter below stays an accurate "packs THIS loader
354 // registered" test.
355 fresh.insert(e.id, fp);
356 }
357 // Remove packs that disappeared. Walk the registry's ids() — which is
358 // registration order — rather than m_fingerprints (a QHash, hash order)
359 // so the per-removal factoryUnregistered signals stay in registration
360 // order, matching the contract Registry::unregisterByOwner upholds and
361 // consumers rely on. The m_fingerprints.contains() filter restricts the
362 // removal to packs THIS loader registered (it is the sole writer of its
363 // borrowed Registry), never an entry registered out-of-band.
364 const QList<QString> registered = m_registry->ids();
365 for (const QString& id : registered) {
366 if (m_fingerprints.contains(id) && !fresh.contains(id)) {
367 m_registry->unregisterFactory(id); // pack disappeared
368 }
369 }
370 m_fingerprints = std::move(fresh);
371 }
372
373 // Non-owning; caller guarantees lifetime. Not a QPointer: Registry<T>
374 // is not a QObject (its notifier is).
375 Registry<Factory>* m_registry = nullptr;
376 SignatureContrib m_sigContrib;
377 CommittedCallback m_onCommitted;
378 QString m_userPath;
379 // Last committed per-id content fingerprint, for minimal reconcile.
380 QHash<QString, QByteArray> m_fingerprints;
381 // Declaration order load-bearing: m_strategy before m_watcher (the
382 // watcher borrows a reference into the strategy).
383 std::unique_ptr<PhosphorFsLoader::MetadataPackScanStrategy<Entry>> m_strategy;
384 std::unique_ptr<PhosphorFsLoader::WatchedDirectorySet> m_watcher;
385};
386
387} // namespace PhosphorRegistry
static QStringList filterNewSearchPaths(const QStringList &candidates, const QStringList &alreadyRegistered)
Helper for consumers building search-path APIs on top of the set: canonicalises (QDir::cleanPath) eve...
std::function< std::shared_ptr< Factory >(const QString &subdirPath, const QJsonObject &root, bool isUser)> Parser
Definition MetadataPackLoader.h:93
std::function< QStringList(const QString &searchPath)> PerDirectoryWatchPaths
Definition MetadataPackLoader.h:113
void setOnCommitted(CommittedCallback fn)
Definition MetadataPackLoader.h:199
std::function< void()> CommittedCallback
Definition MetadataPackLoader.h:126
std::function< QStringList(const Factory &)> PerEntryWatchPaths
Definition MetadataPackLoader.h:106
void setPerDirectoryWatchPaths(PerDirectoryWatchPaths fn)
Definition MetadataPackLoader.h:185
void setUserPath(const QString &path)
Definition MetadataPackLoader.h:238
void refresh()
Definition MetadataPackLoader.h:252
void addSearchPaths(const QStringList &paths, PhosphorFsLoader::LiveReload liveReload=PhosphorFsLoader::LiveReload::On, PhosphorFsLoader::RegistrationOrder order=PhosphorFsLoader::RegistrationOrder::LowestPriorityFirst)
Definition MetadataPackLoader.h:213
void setSignatureContrib(SignatureContrib fn)
Definition MetadataPackLoader.h:161
std::function< bool(const QString &subdirName)> PerSubdirSkip
Definition MetadataPackLoader.h:117
std::function< void(QCryptographicHash &, const Factory &)> SignatureContrib
Definition MetadataPackLoader.h:101
MetadataPackLoader(Registry< Factory > *registry, Parser parser, const QLoggingCategory &logCat)
Definition MetadataPackLoader.h:139
void setPerSubdirSkip(PerSubdirSkip fn)
Definition MetadataPackLoader.h:191
void addSearchPath(const QString &path, PhosphorFsLoader::LiveReload liveReload=PhosphorFsLoader::LiveReload::On)
Definition MetadataPackLoader.h:224
QStringList searchPaths() const
Definition MetadataPackLoader.h:229
void setPerEntryWatchPaths(PerEntryWatchPaths fn)
Definition MetadataPackLoader.h:177
Definition Registry.h:88
Definition ContainedFileReader.h:15
RegistrationOrder
Caller's declared priority direction for registerDirectories / setDirectories input.
Definition WatchedDirectorySet.h:64
@ LowestPriorityFirst
[sys-lowest, ..., sys-highest, user] — the canonical strategy view.
Definition WatchedDirectorySet.h:69
LiveReload
Opt-in policy for directory watching.
Definition WatchedDirectorySet.h:40
@ On
Definition WatchedDirectorySet.h:42
Definition IBarWidgetFactory.h:16
@ Replace
Overwrite; fire factoryUnregistered(old) + factoryRegistered(new).
Definition Registry.h:83