Module com.darkcollective.relix.optimizer

Package com.darkcollective.relix.optimizer.internal

Class OptimizationContext

java.lang.Object

com.darkcollective.relix.optimizer.internal.OptimizationContext

public final class OptimizationContext
extends Object

Mutable accumulator for TransformationRecords produced during a query optimization run.

Rules call record(OptimizationCode, String, String, SourceLocation) each time they fire. After optimization is complete the accumulated records are available via records() and can be passed to the console's optimization report for rendering.

This class is not thread-safe. A fresh instance should be created for each optimization run.

Every record(com.darkcollective.relix.optimizer.OptimizationCode, java.lang.String, java.lang.String, com.darkcollective.relix.ast.SourceLocation) also emits a QueryEvent to the QueryEventListener supplied at construction (default QueryEventListener.NONE), so a consumer can observe rule firings live.

Usage by rule implementations

 // inside OptimizationRule.apply():
 if (ruleApplies) {
     ctx.record(OptimizationCode.EXPR_001, queryName,
                "2 * 3 folded to 6", node.location());
     return rewrittenNode;
 }
 return node; // no change, nothing recorded
 

Constructor Summary

Constructors

Constructor	Description
OptimizationContext()	Creates a context that records transformations but emits no events.
OptimizationContext(QueryEventListener listener)	Creates a context that, in addition to recording transformations, emits a QueryEvent to listener for each rule firing.
OptimizationContext(QueryEventListener listener, DistinctnessSource distinctness)	Creates a context with a listener and a per-leaf DistinctnessSource — consulted by DistinctEliminationPass so δ over an inherently-distinct leaf (e.g.
OptimizationContext(QueryEventListener listener, DistinctnessSource distinctness, MonotoneGeneratorSource monotoneGenerators)	Creates a context with a listener, a per-leaf DistinctnessSource, and a per-leaf MonotoneGeneratorSource — consulted by SelectionIntoGeneratorPass so an upper-bound σ over a monotone unbounded generator is folded into a production stop.
OptimizationContext(QueryEventListener listener, DistinctnessSource distinctness, MonotoneGeneratorSource monotoneGenerators, FunctionCatalog functions)	Creates a context that also carries the FunctionCatalog the query was analysed against — what a rule asks whether a call may be folded, de-duplicated, or reduced over a bag rather than a set.
OptimizationContext(QueryEventListener listener, DistinctnessSource distinctness, MonotoneGeneratorSource monotoneGenerators, FunctionCatalog functions, DeterminismSource determinism)	Creates a context that additionally carries a DeterminismSource — what a rule asks before it changes how many times a sub-expression is evaluated.

Method Summary

Modifier and Type	Method	Description
long	countOf(OptimizationCode code)	Returns the number of times the given optimization rule has fired.
DeterminismSource	determinism()	Returns the reproducibility lookup a rule consults before it changes how many times a sub-expression is evaluated.
DistinctnessSource	distinctness()
FunctionCatalog	functions()
boolean	isEmpty()	Returns true if no transformations have been recorded yet.
MonotoneGeneratorSource	monotoneGenerators()
void	record(OptimizationCode code, String relationName, String detail, SourceLocation location)	Records a single rule firing and emits a corresponding QueryEvent.
List<TransformationRecord>	records()	Returns all transformation records collected so far, in the order they were added.
List<TransformationRecord>	recordsFor(OptimizationCode code)	Returns all records for a specific optimization code, in the order they were added.
int	size()	Returns the total number of transformations recorded so far.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

OptimizationContext

public OptimizationContext()

Creates a context that records transformations but emits no events.

OptimizationContext

public OptimizationContext(QueryEventListener listener)

Creates a context that, in addition to recording transformations, emits a QueryEvent to listener for each rule firing.

Parameters:

listener - the listener to notify on every record(com.darkcollective.relix.optimizer.OptimizationCode, java.lang.String, java.lang.String, com.darkcollective.relix.ast.SourceLocation); must not be null

OptimizationContext

public OptimizationContext(QueryEventListener listener,
 DistinctnessSource distinctness)

Creates a context with a listener and a per-leaf DistinctnessSource — consulted by DistinctEliminationPass so δ over an inherently-distinct leaf (e.g. a duplicate-free generator) is removed.

Parameters:

listener - the listener to notify on every record(com.darkcollective.relix.optimizer.OptimizationCode, java.lang.String, java.lang.String, com.darkcollective.relix.ast.SourceLocation); must not be null

distinctness - the per-leaf duplicate-free lookup; must not be null (use DistinctnessSource.NONE when no leaves are known distinct)

OptimizationContext

public OptimizationContext(QueryEventListener listener,
 DistinctnessSource distinctness,
 MonotoneGeneratorSource monotoneGenerators)

Creates a context with a listener, a per-leaf DistinctnessSource, and a per-leaf MonotoneGeneratorSource — consulted by SelectionIntoGeneratorPass so an upper-bound σ over a monotone unbounded generator is folded into a production stop.

Parameters:

listener - the listener to notify on every record(com.darkcollective.relix.optimizer.OptimizationCode, java.lang.String, java.lang.String, com.darkcollective.relix.ast.SourceLocation); must not be null

distinctness - the per-leaf duplicate-free lookup; must not be null

monotoneGenerators - the per-leaf ascending-generator lookup; must not be null (use MonotoneGeneratorSource.NONE when no generators)

OptimizationContext

public OptimizationContext(QueryEventListener listener,
 DistinctnessSource distinctness,
 MonotoneGeneratorSource monotoneGenerators,
 FunctionCatalog functions)

Creates a context that also carries the FunctionCatalog the query was analysed against — what a rule asks whether a call may be folded, de-duplicated, or reduced over a bag rather than a set.

The catalogue arrives here rather than as a parameter of every rule because this is already the per-run bundle each rule is handed, alongside the two other per-run lookups. It is supplied, never discovered: a rule that reached for the installed libraries itself could disagree with the analysis that produced the tree it is rewriting, which is exactly the inconsistency this constructor exists to remove.

The catalogue-free constructors default to FunctionCatalog.empty(), where every property lookup answers "not declared". That is the conservative direction — a rule declines to fire — so a caller that forgets to supply one gets a slower plan, never a wrong one.

Parameters:

listener - the listener to notify on every record(com.darkcollective.relix.optimizer.OptimizationCode, java.lang.String, java.lang.String, com.darkcollective.relix.ast.SourceLocation); must not be null

distinctness - the per-leaf duplicate-free lookup; must not be null

monotoneGenerators - the per-leaf ascending-generator lookup; must not be null

functions - the functions this query was analysed against; must not be null

OptimizationContext

public OptimizationContext(QueryEventListener listener,
 DistinctnessSource distinctness,
 MonotoneGeneratorSource monotoneGenerators,
 FunctionCatalog functions,
 DeterminismSource determinism)

Creates a context that additionally carries a DeterminismSource — what a rule asks before it changes how many times a sub-expression is evaluated.

It arrives here for the same reason the catalogue does: this is the per-run bundle every rule is handed, and the authoritative answer needs a SymbolTable that no rule in OptimizationPipeline may take.

The determinism-free constructors default to DeterminismSource.NONE, which vouches for nothing, so SEL-010 and the SET family decline rather than guess.

Parameters:

listener - the listener to notify on every record(com.darkcollective.relix.optimizer.OptimizationCode, java.lang.String, java.lang.String, com.darkcollective.relix.ast.SourceLocation); must not be null

distinctness - the per-leaf duplicate-free lookup; must not be null

monotoneGenerators - the per-leaf ascending-generator lookup; must not be null

functions - the functions this query was analysed against; must not be null

determinism - the reproducibility lookup; must not be null

Method Details

functions

public FunctionCatalog functions()

Returns:

the functions this query was analysed against (default FunctionCatalog.empty())

determinism

public DeterminismSource determinism()

Returns the reproducibility lookup a rule consults before it changes how many times a sub-expression is evaluated.

Returns:

the source (default DeterminismSource.NONE, which vouches for nothing); never null

distinctness

public DistinctnessSource distinctness()

Returns:

the per-leaf distinctness source for this run (default DistinctnessSource.NONE)

monotoneGenerators

public MonotoneGeneratorSource monotoneGenerators()

Returns:

the per-leaf monotone-generator source for this run (default MonotoneGeneratorSource.NONE)

record

public void record(OptimizationCode code,
 String relationName,
 String detail,
 SourceLocation location)

Records a single rule firing and emits a corresponding QueryEvent.

Parameters:

code - the rule that fired; must not be null

relationName - the name of the query/relation being optimized; must not be blank

detail - short description of what changed; must not be blank

location - source location of the transformed node; must not be null

records

public List<TransformationRecord> records()

Returns all transformation records collected so far, in the order they were added.

Returns:

unmodifiable view of the records list; never null

size

public int size()

Returns the total number of transformations recorded so far.

Returns:

count ≥ 0

isEmpty

public boolean isEmpty()

Returns true if no transformations have been recorded yet.

Returns:

true when size() == 0

countOf

public long countOf(OptimizationCode code)

Returns the number of times the given optimization rule has fired.

Parameters:

code - the rule to count; must not be null

Returns:

count ≥ 0

recordsFor

public List<TransformationRecord> recordsFor(OptimizationCode code)

Returns all records for a specific optimization code, in the order they were added.

Parameters:

code - the rule to filter by; must not be null

Returns:

unmodifiable list; never null; may be empty