# Event API

The `numba.core.event` module provides a simple event system for applications to register callbacks to listen to specific compiler events.

The following events are built in:

- `"numba:compile"` is broadcast when a dispatcher is compiling. Events of this kind have `data` defined to be a `dict` with the following key-values:

  - `"dispatcher"`: the dispatcher object that is compiling.

  - `"args"`: the argument types.

  - `"return_type"`: the return type.

- `"numba:compiler_lock"` is broadcast when the internal compiler-lock is acquired. This is mostly used internally to measure time spent with the lock acquired.

- `"numba:llvm_lock"` is broadcast when the internal LLVM-lock is acquired. This is used internally to measure time spent with the lock acquired.

- `"numba:run_pass"` is broadcast when a compiler pass is running.

  > - `"name"`: pass name.

  > - `"qualname"`: qualified name of the function being compiled.

  > - `"module"`: module name of the function being compiled.

  > - `"flags"`: compilation flags.

  > - `"args"`: argument types.

  > - `"return_type"` return type.

Applications can register callbacks that are listening for specific events using `register(kind: str, listener: Listener)`, where `listener` is an instance of `Listener` that defines custom actions on occurrence of the specific event.

class numba.core.event.Event(kind, status, data=None, exc_details=None)

  An event.

  Parameters:
    kind str
    status EventStatus
    data any; optional

      Additional data for the event.

    exc_details 3-tuple; optional

      Same 3-tuple for `__exit__`.

  property data

    Event data

    Returns:
      res object
  property is_end

    Is it an END event?

    Returns:
      res bool
  property is_failed

    Is the event carrying an exception?

    This is used for END event. This method will never return `True` in a START event.

    Returns:
      res bool
  property is_start

    Is it a START event?

    Returns:
      res bool
  property kind

    Event kind

    Returns:
      res str
  property status

    Event status

    Returns:
      res EventStatus

class numba.core.event.EventStatus(*values)

  Status of an event.

class numba.core.event.Listener

  Base class for all event listeners.

  notify(event)

    Notify this Listener with the given Event.

    Parameters:
      event Event
  abstractmethod on_end(event)

    Called when there is a END event.

    Parameters:
      event Event
  abstractmethod on_start(event)

    Called when there is a START event.

    Parameters:
      event Event

class numba.core.event.RecordingListener

  A listener that records all events and stores them in the `.buffer` attribute as a list of 2-tuple `(float, Event)`, where the first element is the time the event occurred as returned by `time.time()` and the second element is the event.

  on_end(event)

    Called when there is a END event.

    Parameters:
      event Event
  on_start(event)

    Called when there is a START event.

    Parameters:
      event Event

class numba.core.event.TimingListener

  A listener that measures the total time spent between START and END events during the time this listener is active.

  property done

    Returns a `bool` indicating whether a measurement has been made.

    When this returns `False`, the matching event has never fired. If and only if this returns `True`, `.duration` can be read without error.

  property duration

    Returns the measured duration.

    This may raise `AttributeError`. Users can use `.done` to check that a measurement has been made.

  on_end(event)

    Called when there is a END event.

    Parameters:
      event Event
  on_start(event)

    Called when there is a START event.

    Parameters:
      event Event

numba.core.event.broadcast(event)

  Broadcast an event to all registered listeners.

  Parameters:
    event Event

numba.core.event.end_event(kind, data=None, exc_details=None)

  Trigger the end of an event of kind, exc_details.

  Parameters:
    kind str

      Event kind.

    data any; optional

      Extra event data.

    exc_details 3-tuple; optional

      Same 3-tuple for `__exit__`. Or, `None` if no error.

numba.core.event.install_listener(kind, listener)

  Install a listener for event “kind” temporarily within the duration of the context.

  Returns:
    res Listener

      The listener provided.

  Examples

      >>> with install_listener("numba:compile", listener):
      >>>     some_code()  # listener will be active here.
      >>> other_code()     # listener will be unregistered by this point.

numba.core.event.install_recorder(kind)

  Install a RecordingListener temporarily to record all events.

  Once the context is closed, users can use `RecordingListener.buffer` to access the recorded events.

  Returns:
    res RecordingListener

  Examples

  This is equivalent to:

      >>> with install_listener(kind, RecordingListener()) as res:
      >>>    ...

numba.core.event.install_timer(kind, callback)

  Install a TimingListener temporarily to measure the duration of an event.

  If the context completes successfully, the callback function is executed. The callback function is expected to take a float argument for the duration in seconds.

  Returns:
    res TimingListener

  Examples

  This is equivalent to:

      >>> with install_listener(kind, TimingListener()) as res:
      >>>    ...

numba.core.event.register(kind, listener)

  Register a listener for a given event kind.

  Parameters:
    kind str
    listener Listener

numba.core.event.start_event(kind, data=None)

  Trigger the start of an event of kind with data.

  Parameters:
    kind str

      Event kind.

    data any; optional

      Extra event data.

numba.core.event.trigger_event(kind, data=None)

  A context manager to trigger the start and end events of kind with data. The start event is triggered when entering the context. The end event is triggered when exiting the context.

  Parameters:
    kind str

      Event kind.

    data any; optional

      Extra event data.

numba.core.event.unregister(kind, listener)

  Unregister a listener for a given event kind.

  Parameters:
    kind str
    listener Listener