tilelang.instrumentation.events¶

Normalized TVM pass events shared by TileLang instrumentation tools.

This module pairs nested run_before_pass/run_after_pass callbacks, assigns stable execution order and parent/depth metadata, and drains incomplete frames when a pass fails. Consumers remain responsible for choosing what to snapshot and how to render or persist the resulting data.

Attributes¶

CapturePredicate

SequenceAllocator

Classes¶

PassEvent

Identity and execution metadata for one observed compiler pass.

IncompletePass

A pass frame that received no matching after-pass callback.

PassEventObserver

No-op observer interface consumed by StackedPassInstrument.

StackedPassInstrument

Pair nested TVM pass callbacks and dispatch normalized events.

Functions¶

pass_phase(name)

Attach a phase label to pass events emitted inside this scope.

current_pass_phase()

Return the phase label active in the current execution context.

active_stacked_pass_instruments()

Return shared stack instruments active in the current PassContext.

Module Contents¶

tilelang.instrumentation.events.pass_phase(name)¶

Attach a phase label to pass events emitted inside this scope.

Parameters:

name (str | None)

Return type:

collections.abc.Generator[None, None, None]

tilelang.instrumentation.events.current_pass_phase()¶

Return the phase label active in the current execution context.

Return type:

str | None

tilelang.instrumentation.events.active_stacked_pass_instruments()¶

Return shared stack instruments active in the current PassContext.

Return type:

tuple[StackedPassInstrument, Ellipsis]

class tilelang.instrumentation.events.PassEvent¶

Identity and execution metadata for one observed compiler pass.

name: str¶
sequence: int¶
depth: int¶
parent_sequence: int | None¶
phase: str | None¶
class tilelang.instrumentation.events.IncompletePass¶

A pass frame that received no matching after-pass callback.

name: str¶
depth: int¶
event: PassEvent | None¶
state: Any¶
class tilelang.instrumentation.events.PassEventObserver¶

No-op observer interface consumed by StackedPassInstrument.

enter_pass_context()¶

Handle entry into a TVM PassContext.

Return type:

None

exit_pass_context()¶

Handle normal exit from a TVM PassContext.

Return type:

None

pass_started(mod, event)¶

Capture consumer state before a pass and return it.

Parameters:

event (PassEvent)

pass_finished(mod, event, state)¶

Consume the module and state after a pass completes.

Parameters:
Return type:

None

passes_incomplete(passes, error)¶

Handle passes that never received an after-pass callback.

Parameters:

  • passes (collections.abc.Sequence[IncompletePass])

  • error (BaseException | None)

Return type:

None

callback_mismatch(actual, expected)¶

Handle an unmatched or out-of-order after-pass callback.

Parameters:

  • actual (str)

  • expected (str | None)

Return type:

None

tilelang.instrumentation.events.CapturePredicate¶
tilelang.instrumentation.events.SequenceAllocator¶
class tilelang.instrumentation.events.StackedPassInstrument(observer, *, capture_nested=True, capture_predicate=None, sequence_allocator=None, phase_provider=current_pass_phase)¶

Pair nested TVM pass callbacks and dispatch normalized events.

Parameters:

  • observer (PassEventObserver) – Consumer that snapshots and records the pass-specific data.

  • capture_nested (bool) – When false, nested callbacks are still tracked for correct pairing but only depth-zero passes are emitted to the observer.

  • capture_predicate (CapturePredicate | None) – Optional finer-grained predicate receiving (name, depth). It is applied after capture_nested filtering.

  • sequence_allocator (SequenceAllocator | None) – Optional allocator for consumers that need sequence numbers shared across multiple PassContexts. Without one, numbering restarts at zero whenever this instrument enters a context.

  • phase_provider (collections.abc.Callable[[], str | None]) – Supplies the phase attached to each event. Defaults to current_pass_phase().

observer¶
capture_nested = True¶
capture_predicate = None¶
sequence_allocator = None¶
phase_provider¶
property pending_events: tuple[PassEvent, Ellipsis]¶

Return currently open observed events, ordered outermost first.

Return type:

tuple[PassEvent, Ellipsis]

enter_pass_ctx()¶
Return type:

None

exit_pass_ctx()¶
Return type:

None

run_before_pass(mod, info)¶
Return type:

None

run_after_pass(mod, info)¶
Return type:

None

abort(error=None)¶

Drain open frames and notify the observer of incomplete passes.

The returned tuple is ordered outermost first. The deepest entry is therefore the pass nearest to the original failure, while earlier entries are incomplete ancestors.

Parameters:

error (BaseException | None)

Return type:

tuple[IncompletePass, Ellipsis]