tilelang.instrumentation.events
===============================

.. py:module:: tilelang.instrumentation.events

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   tilelang.instrumentation.events.CapturePredicate
   tilelang.instrumentation.events.SequenceAllocator


Classes
-------

.. autoapisummary::

   tilelang.instrumentation.events.PassEvent
   tilelang.instrumentation.events.IncompletePass
   tilelang.instrumentation.events.PassEventObserver
   tilelang.instrumentation.events.StackedPassInstrument


Functions
---------

.. autoapisummary::

   tilelang.instrumentation.events.pass_phase
   tilelang.instrumentation.events.current_pass_phase
   tilelang.instrumentation.events.active_stacked_pass_instruments


Module Contents
---------------

.. py:function:: pass_phase(name)

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


.. py:function:: current_pass_phase()

   Return the phase label active in the current execution context.


.. py:function:: active_stacked_pass_instruments()

   Return shared stack instruments active in the current PassContext.


.. py:class:: PassEvent

   Identity and execution metadata for one observed compiler pass.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: sequence
      :type:  int


   .. py:attribute:: depth
      :type:  int


   .. py:attribute:: parent_sequence
      :type:  int | None


   .. py:attribute:: phase
      :type:  str | None


.. py:class:: IncompletePass

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


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: depth
      :type:  int


   .. py:attribute:: event
      :type:  PassEvent | None


   .. py:attribute:: state
      :type:  Any


.. py:class:: PassEventObserver

   No-op observer interface consumed by :class:`StackedPassInstrument`.


   .. py:method:: enter_pass_context()

      Handle entry into a TVM PassContext.



   .. py:method:: exit_pass_context()

      Handle normal exit from a TVM PassContext.



   .. py:method:: pass_started(mod, event)

      Capture consumer state before a pass and return it.



   .. py:method:: pass_finished(mod, event, state)

      Consume the module and state after a pass completes.



   .. py:method:: passes_incomplete(passes, error)

      Handle passes that never received an after-pass callback.



   .. py:method:: callback_mismatch(actual, expected)

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



.. py:data:: CapturePredicate

.. py:data:: SequenceAllocator

.. py:class:: 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.

   :param observer: Consumer that snapshots and records the pass-specific data.
   :param capture_nested: When false, nested callbacks are still tracked for correct pairing but
                          only depth-zero passes are emitted to the observer.
   :param capture_predicate: Optional finer-grained predicate receiving ``(name, depth)``. It is
                             applied after ``capture_nested`` filtering.
   :param sequence_allocator: Optional allocator for consumers that need sequence numbers shared
                              across multiple PassContexts. Without one, numbering restarts at zero
                              whenever this instrument enters a context.
   :param phase_provider: Supplies the phase attached to each event. Defaults to
                          :func:`current_pass_phase`.


   .. py:attribute:: observer


   .. py:attribute:: capture_nested
      :value: True



   .. py:attribute:: capture_predicate
      :value: None



   .. py:attribute:: sequence_allocator
      :value: None



   .. py:attribute:: phase_provider


   .. py:property:: pending_events
      :type: tuple[PassEvent, Ellipsis]


      Return currently open observed events, ordered outermost first.


   .. py:method:: enter_pass_ctx()


   .. py:method:: exit_pass_ctx()


   .. py:method:: run_before_pass(mod, info)


   .. py:method:: run_after_pass(mod, info)


   .. py:method:: 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.