qat.experimental.passes.pass_ordering module

Declarative ordering constraints for xDSL pass pipelines.

xDSL’s PassPipeline runs its passes in the order they are listed, but offers no way for a pass to declare that it must run before (or after) another. This module adds a lightweight, opt-in mix-in: a ModulePass subclass that also inherits OrderedPass may declare two class-level constraints,

• OrderedPass.runs_before() — pass classes that, if present in the same pipeline, must appear after this pass; and

• OrderedPass.required_predecessors() — pass classes that must be present in the same pipeline and appear before this pass.

Both are instance methods that return the referenced pass classes directly rather than their string names, so a typo or a renamed pass is caught at import time. An override may import the referenced pass lazily to avoid a circular import, and should memoise its result in a class field so the (trivial) computation only happens once.

OrderedPassPipeline validates these constraints when it is constructed, so an official pass grouping enforces its invariants up front rather than failing part-way through execution.

class OrderedPass

Bases: object

Mix-in that lets a ModulePass declare ordering constraints.

Combine it with ModulePass on any pass that participates in ordering, for example class MyPass(OrderedPass, ModulePass). Override either method to declare a constraint; both return the pass classes they constrain against, so the reference is a direct class rather than a loose string. An override may import the referenced pass lazily inside the method when a module-level import would be circular, and should memoise its result in a class field. The defaults impose no constraints.

required_predecessors()

Pass classes that must be present in the same pipeline and run before this pass.

Return type:

frozenset[type[ModulePass]]

runs_before()

Pass classes that, if present in the same pipeline, must run after this pass.

Return type:

frozenset[type[ModulePass]]

class OrderedPassPipeline(passes, callback=None)

Bases: PassPipeline

A PassPipeline that validates ordering on construction.

Official pass groupings should return this pipeline so that a mis-ordered or incomplete schedule fails as soon as it is built, rather than part-way through execution.

validate_pass_ordering(passes)

Verify that the ordering constraints declared by passes are satisfied.

Only passes that inherit OrderedPass carry constraints; every other pass is skipped. Two families of constraint are checked, in listing order:

• For every pass declaring OrderedPass.runs_before(), each referenced pass class that also appears in passes must appear at a later position.

• For every pass declaring OrderedPass.required_predecessors(), each referenced pass class must appear in passes at an earlier position.

Parameters:

passes (Sequence[ModulePass]) – The passes in the exact order they will be applied.

Raises:

VerifyException – If any declared constraint is violated. The message identifies the offending pass and constraint so the pipeline can be fixed.

Return type:

None