Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
RuleEvaluator.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include <QHash>
7#include <QList>
8#include <QSet>
9#include <QString>
10
11#include <algorithm>
12#include <functional>
13#include <optional>
14
15#include "RuleAction.h"
16#include "WindowQuery.h"
17#include "RuleSet.h"
18#include "phosphorrules_export.h"
19
20namespace PhosphorRules {
21
37class PHOSPHORRULES_EXPORT ResolvedActions
38{
39public:
41 bool hasSlot(const QString& slot) const
42 {
43 return m_slots.contains(slot);
44 }
45
49 std::optional<RuleAction> slot(const QString& slot) const;
50
53 bool isExcluded() const
54 {
55 return m_excluded;
56 }
57
59 bool isEmpty() const
60 {
61 return m_slots.isEmpty() && !m_excluded;
62 }
63
70 QStringList filledSlots() const
71 {
72 QStringList keys = m_slots.keys();
73 std::sort(keys.begin(), keys.end());
74 return keys;
75 }
76
77 // ── Accumulation API — used by RuleEvaluator ──
78
81 bool fillSlot(const QString& slot, const RuleAction& action);
82
85 {
86 m_excluded = true;
87 }
88
89 bool operator==(const ResolvedActions& other) const
90 {
91 return m_slots == other.m_slots && m_excluded == other.m_excluded;
92 }
93
94private:
95 QHash<QString, RuleAction> m_slots;
96 bool m_excluded = false;
97};
98
142class PHOSPHORRULES_EXPORT RuleEvaluator
143{
144public:
145 explicit RuleEvaluator(const RuleSet& ruleSet);
146
149
158 ResolvedActions resolveFiltered(const WindowQuery& query, const std::function<bool(const Rule&)>& admit) const;
159
164 ResolvedActions resolveCached(const QString& windowId, const WindowQuery& query) const;
165
177 ResolvedActions resolveCachedFiltered(const QString& windowId, const WindowQuery& query,
178 const std::function<bool(const Rule&)>& admit) const;
179
187 std::optional<ResolvedActions> resolveCachedIfPresent(const QString& windowId) const;
188
197 bool hasAnyMatch(const WindowQuery& query) const;
198
212 bool hasMatchTargetingFields(const WindowQuery& query, const QSet<Field>& fields) const;
213
234 bool hasAnyMatchFiltered(const WindowQuery& query, const std::function<bool(const Rule&)>& admit) const;
235
248 const std::function<bool(const Rule&)>& filter = {}) const;
249
252 void clearCache() const;
253
258 void evictCached(const QString& windowId) const
259 {
260 m_cache.remove(windowId);
261 }
262
285 void setTerminalActionScope(QSet<QString> honoredTypes)
286 {
287 m_terminalScope = std::move(honoredTypes);
288 clearCache();
289 }
290
292 int cacheSize() const
293 {
294 return m_cache.size();
295 }
296
297 const RuleSet& ruleSet() const
298 {
299 return m_ruleSet;
300 }
301
306 static constexpr int kMaxCacheEntries = 4096;
307
308private:
309 const RuleSet& m_ruleSet;
310
314 std::optional<QSet<QString>> m_terminalScope;
315
316 struct CacheEntry
317 {
318 quint64 revision = 0;
319 quint64 insertSeq = 0;
320 ResolvedActions actions;
321 };
322 mutable QHash<QString, CacheEntry> m_cache;
323 mutable quint64 m_cacheInsertSeq = 0;
324
328 void evictCache(quint64 currentRevision) const;
329
336 mutable QList<int> m_priorityOrder;
337 mutable quint64 m_priorityOrderRevision = 0;
338 mutable qsizetype m_priorityOrderRulesSize = 0;
339 mutable bool m_priorityOrderValid = false;
340 const QList<int>& priorityOrder() const;
341};
342
343} // namespace PhosphorRules
The output of a resolution — the first action filling each slot.
Definition RuleEvaluator.h:38
bool isExcluded() const
True if an in-scope terminal exclusion action matched — the window is excluded from the resolving con...
Definition RuleEvaluator.h:53
bool hasSlot(const QString &slot) const
True if slot was filled by some matching rule.
Definition RuleEvaluator.h:41
QStringList filledSlots() const
All filled slot ids — for tests / introspection.
Definition RuleEvaluator.h:70
std::optional< RuleAction > slot(const QString &slot) const
The action that filled slot, or nullopt if the slot is unfilled.
void markExcluded()
Marks the result excluded (an in-scope terminal exclusion matched).
Definition RuleEvaluator.h:84
bool isEmpty() const
True if no slot was filled and no terminal action matched.
Definition RuleEvaluator.h:59
bool operator==(const ResolvedActions &other) const
Definition RuleEvaluator.h:89
bool fillSlot(const QString &slot, const RuleAction &action)
Records action into slot iff the slot is currently unfilled.
std::optional< ResolvedActions > resolveCachedIfPresent(const QString &windowId) const
Peek the match cache without resolving: returns the cached verdict for windowId iff one exists at the...
int cacheSize() const
Number of live cache entries — for tests / benchmarks.
Definition RuleEvaluator.h:292
ResolvedActions resolveFiltered(const WindowQuery &query, const std::function< bool(const Rule &)> &admit) const
Resolve as above, but consider only rules admit accepts.
static constexpr int kMaxCacheEntries
Upper bound on live resolveCached entries.
Definition RuleEvaluator.h:306
ResolvedActions resolveCachedFiltered(const QString &windowId, const WindowQuery &query, const std::function< bool(const Rule &)> &admit) const
Cached resolve that narrows the candidate set, combining resolveCached's (windowId,...
RuleEvaluator(const RuleSet &ruleSet)
ResolvedActions resolve(const WindowQuery &query) const
Resolve query against the bound rule set. Always recomputes.
const Rule * highestPriorityMatch(const WindowQuery &query, const std::function< bool(const Rule &)> &filter={}) const
The single highest-priority enabled rule that matches query and passes the optional filter,...
void setTerminalActionScope(QSet< QString > honoredTypes)
Restrict which terminal action TYPES this evaluator honours.
Definition RuleEvaluator.h:285
void clearCache() const
Drop the entire match cache.
const RuleSet & ruleSet() const
Definition RuleEvaluator.h:297
ResolvedActions resolveCached(const QString &windowId, const WindowQuery &query) const
Resolve with a (windowId, revision) cache.
bool hasAnyMatchFiltered(const WindowQuery &query, const std::function< bool(const Rule &)> &admit) const
True if at least one enabled rule matches query AND passes admit.
bool hasAnyMatch(const WindowQuery &query) const
True if at least one enabled rule matches query — an existence test that does not allocate a Resolved...
bool hasMatchTargetingFields(const WindowQuery &query, const QSet< Field > &fields) const
True if at least one enabled rule both matches query and references one of fields in its match expres...
void evictCached(const QString &windowId) const
Drop ONE window's cache entry.
Definition RuleEvaluator.h:258
An ordered collection of Rules — the persistent rule store.
Definition RuleSet.h:33
Definition ActionParams.h:25
One action carried by a Rule.
Definition RuleAction.h:65
One rule — { id, name, enabled, priority, match, actions, managed }.
Definition Rule.h:106
The evaluation input — an attribute bag matched against a MatchExpression.
Definition WindowQuery.h:37