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

The single evaluation model — resolves a WindowQuery against a RuleSet. More...

#include <PhosphorRules/RuleEvaluator.h>

Public Member Functions

 RuleEvaluator (const RuleSet &ruleSet)
ResolvedActions resolve (const WindowQuery &query) const
 Resolve query against the bound rule set. Always recomputes.
ResolvedActions resolveFiltered (const WindowQuery &query, const std::function< bool(const Rule &)> &admit) const
 Resolve as above, but consider only rules admit accepts.
ResolvedActions resolveCached (const QString &windowId, const WindowQuery &query) const
 Resolve with a (windowId, revision) cache.
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, revision) memo with resolveFiltered's structural admission test.
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 CURRENT rule-set revision, else nullopt.
bool hasAnyMatch (const WindowQuery &query) const
 True if at least one enabled rule matches query — an existence test that does not allocate a ResolvedActions.
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 expression.
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.
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, or nullptr if none qualifies.
void clearCache () const
 Drop the entire match cache.
void evictCached (const QString &windowId) const
 Drop ONE window's cache entry.
void setTerminalActionScope (QSet< QString > honoredTypes)
 Restrict which terminal action TYPES this evaluator honours.
int cacheSize () const
 Number of live cache entries — for tests / benchmarks.
const RuleSet & ruleSet () const

Static Public Attributes

static constexpr int kMaxCacheEntries = 4096
 Upper bound on live resolveCached entries.

Detailed Description

The single evaluation model — resolves a WindowQuery against a RuleSet.

resolve() walks the rule set in descending priority (ties broken by list order via a stable sort), accumulating the first action that fills each slot. A matching rule with a terminal exclusion action in the evaluator's terminal-action scope (any terminal action when no scope is set — see setTerminalActionScope) stops the walk and the result is marked excluded. The descending-priority index is computed once per rule-set revision and reused, so back-to-back resolves against an unchanged set do not re-sort.

resolveCached() adds a match cache keyed (windowId, ruleSetRevision). The cache is automatically bypassed/invalidated when the bound rule set's revision changes; clearCache() forces invalidation for metadata-driven changes that the revision does not capture (a window changing screen).

The cache is bounded: at most kMaxCacheEntries live entries. Two eviction passes keep it from growing without limit even though the evaluator never observes window-close events — every resolveCached call first drops every entry whose revision is stale (a rule-set edit retires the whole previous generation), and if the live set still exceeds the cap the oldest-inserted entries are evicted until it fits.

The evaluator holds a reference to the rule set — the caller owns the set's lifetime and must outlive the evaluator.

Thread-safety: hasAnyMatch() reads the bound rule set in list order and touches no internal RuleEvaluator cache or index. It is only safe to call concurrently with other hasAnyMatch() calls when (a) the bound RuleSet is not concurrently mutated and (b) no rule in the set carries a Regex leaf — MatchExpression::evaluate() dispatches a regex leaf through a shared QRegularExpression whose match() is not thread-safe for concurrent calls (see the MatchExpression thread-safety note). A rule set containing any Regex predicate must have all hasAnyMatch() calls serialized. resolve(), resolveCached() and highestPriorityMatch() mutate the lazily-built mutable priority-order index (and, for resolveCached(), the mutable match cache); clearCache() mutates only the match cache. All of these latter calls must be externally serialized — both against each other and against hasAnyMatch() (since concurrent rule-set mutation invalidates its read).

Constructor & Destructor Documentation

◆ RuleEvaluator()

PhosphorRules::RuleEvaluator::RuleEvaluator ( const RuleSet & ruleSet)
explicit

Member Function Documentation

◆ cacheSize()

int PhosphorRules::RuleEvaluator::cacheSize ( ) const
inline

Number of live cache entries — for tests / benchmarks.

◆ clearCache()

void PhosphorRules::RuleEvaluator::clearCache ( ) const

Drop the entire match cache.

Call on a window-metadata change that the rule-set revision does not reflect.

◆ evictCached()

void PhosphorRules::RuleEvaluator::evictCached ( const QString & windowId) const
inline

Drop ONE window's cache entry.

The targeted sibling of clearCache() for high-frequency per-window edges (frame-geometry ticks): a change that can only alter this window's verdict must not cold-start every other window's. No-op when the window has no entry.

◆ hasAnyMatch()

bool PhosphorRules::RuleEvaluator::hasAnyMatch ( const WindowQuery & query) const

True if at least one enabled rule matches query — an existence test that does not allocate a ResolvedActions.

Used by hot paths that only need a yes/no ("does any rule re-enable this class"). Iterates in rule-set list order, not priority order: priority is irrelevant to a pure existence check, so no sort is performed.

Not concurrency-safe against a rule set containing a Regex predicate — see the class-level thread-safety note.

◆ hasAnyMatchFiltered()

bool PhosphorRules::RuleEvaluator::hasAnyMatchFiltered ( const WindowQuery & query,
const std::function< bool(const Rule &)> & admit ) const

True if at least one enabled rule matches query AND passes admit.

hasAnyMatch with a structural admission test on the rule itself, the same shape resolveFiltered takes. The ORDER differs from that one on purpose: this matches first and admits second, so a caller pays the admission cost only for rules that already matched, whereas resolveFiltered admits first (its predicate is the cheap structural filter there). Both are equivalent for a pure predicate; one with side effects would observe a different set of rules from the two.

Exists because "some rule matches this window" is not always the question a caller means. The animation window-filter force-animates a window when the user has authored a matching rule, on the reasoning that authoring one is the opt-in signal — but a rule whose every appearance action is inert (an animation override on an event the compositor resolves windowless, which no rule can drive) signals nothing, and letting it through overrode the user's own size and exclusion filters for a rule that could not have any effect.

Same concurrency constraints as hasAnyMatch (regex leaves).

◆ hasMatchTargetingFields()

bool PhosphorRules::RuleEvaluator::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 expression.

The cheap structural referencesAnyField filter runs before the (potentially regex-bearing) evaluate, so a rule that does not mention any of the fields never pays the match cost.

Used by the animation window-filter to distinguish a rule that deliberately targets a window type (so it should override the global "ignore transient / ignore notifications-OSD" exclusion) from one that merely matches a transient window by class as a side effect. Iterates in rule-set list order — priority is irrelevant to an existence check.

Same concurrency constraints as hasAnyMatch (regex leaves).

◆ highestPriorityMatch()

const Rule * PhosphorRules::RuleEvaluator::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, or nullptr if none qualifies.

This is the same descending-priority, tie-break-by-list-order walk resolve performs, exposed as a whole-rule lookup. Callers that need the winning rule itself — not its accumulated action slots — use this so the priority-cascade semantics live in exactly one place. filter, when set, narrows the candidate set (e.g. "only context assignment rules"); an empty filter considers every enabled rule. The returned pointer aliases into the bound rule set and is valid only until the next rule-set mutation.

◆ resolve()

ResolvedActions PhosphorRules::RuleEvaluator::resolve ( const WindowQuery & query) const

Resolve query against the bound rule set. Always recomputes.

◆ resolveCached()

ResolvedActions PhosphorRules::RuleEvaluator::resolveCached ( const QString & windowId,
const WindowQuery & query ) const

Resolve with a (windowId, revision) cache.

windowId is the caller's stable per-window key (the appId|instanceId composite id). A cache entry from a stale revision is discarded on access. The cache is bounded — see the class doc for the eviction policy.

◆ resolveCachedFiltered()

ResolvedActions PhosphorRules::RuleEvaluator::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, revision) memo with resolveFiltered's structural admission test.

For resolvers that leave a field unstamped and must therefore exclude rules referencing it (see the resolveFiltered doc for the negation-polarity reason) but still want the per-window memo.

PRECONDITION: the memo is keyed on (windowId, revision) ALONE, so admit is IGNORED on a cache hit exactly as query is. Every caller sharing an evaluator must therefore pass an EQUIVALENT admit, or the first caller to resolve a window decides which rules the rest see.

◆ resolveCachedIfPresent()

std::optional< ResolvedActions > PhosphorRules::RuleEvaluator::resolveCachedIfPresent ( const QString & windowId) const

Peek the match cache without resolving: returns the cached verdict for windowId iff one exists at the CURRENT rule-set revision, else nullopt.

Lets a hot-path caller (per-frame paint resolvers) skip building the WindowQuery entirely on a cache hit — the cached verdict already reflects whatever query produced it, and the query is ignored by resolveCached on a hit anyway. A stale-revision entry reads as a miss (nullopt) here; it is pruned lazily on the next resolveCached call, not by this read-only peek.

◆ resolveFiltered()

ResolvedActions PhosphorRules::RuleEvaluator::resolveFiltered ( const WindowQuery & query,
const std::function< bool(const Rule &)> & admit ) const

Resolve as above, but consider only rules admit accepts.

For resolvers that leave a field UNSTAMPED: an absent field makes a leaf false, so a positive predicate correctly never matches — but a NEGATED one (None{Field Equals X}) matches precisely because the leaf failed. A caller that cannot answer for a field must therefore exclude rules referencing it structurally rather than rely on the empty-value coincidence. An empty admit behaves exactly like resolve().

◆ ruleSet()

const RuleSet & PhosphorRules::RuleEvaluator::ruleSet ( ) const
inline

◆ setTerminalActionScope()

void PhosphorRules::RuleEvaluator::setTerminalActionScope ( QSet< QString > honoredTypes)
inline

Restrict which terminal action TYPES this evaluator honours.

With no scope set (the default), any terminal action in a matching rule marks the result excluded and stops the walk — correct for the sliced exclusion evaluators, whose bound sets contain only rules of their own exclusion family. An evaluator bound to the FULL rule store must narrow this: the Exclude family is scoped by consumer concern (placement / decorations / animations), and honouring an out-of-scope terminal action would let, say, a decoration-only opt-out cancel placement resolution for every lower-priority rule — the exact leak the scoped actions' documentation promises cannot happen.

With a scope set, a terminal action whose type is NOT in honoredTypes is skipped entirely during resolution: it fills no slot (its slot ids are declared for registry completeness only) and does not stop the walk, so the rule's other actions and all lower-priority rules still apply.

Set the scope immediately after construction, before the first resolve — the per-window match cache memoises verdicts computed under the scope in force at resolve time, so this call defensively drops the cache.

Member Data Documentation

◆ kMaxCacheEntries

int PhosphorRules::RuleEvaluator::kMaxCacheEntries = 4096
staticconstexpr

Upper bound on live resolveCached entries.

Past this, the oldest-inserted entries are evicted. Sized generously — far more than any realistic concurrent window count — so the cap is a safety net, not a routine hot-path constraint.


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