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.

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
kindstr
statusEventStatus
dataany; optional

Additional data for the event.

exc_details3-tuple; optional

Same 3-tuple for __exit__.

property data

Event data

Returns
resobject
property is_end

Is it an END event?

Returns
resbool
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
resbool
property is_start

Is it a START event?

Returns
resbool
property kind

Event kind

Returns
resstr
property status

Event status

Returns
resEventStatus
class numba.core.event.EventStatus(value)

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
eventEvent
abstract on_end(event)

Called when there is a END event.

Parameters
eventEvent
abstract on_start(event)

Called when there is a START event.

Parameters
eventEvent
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
eventEvent
on_start(event)

Called when there is a START event.

Parameters
eventEvent
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
eventEvent
on_start(event)

Called when there is a START event.

Parameters
eventEvent
numba.core.event.broadcast(event)

Broadcast an event to all registered listeners.

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

Trigger the end of an event of kind, exc_details.

Parameters
kindstr

Event kind.

dataany; optional

Extra event data.

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

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
resRecordingListener

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
resTimingListener

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
kindstr
listenerListener
numba.core.event.start_event(kind, data=None)

Trigger the start of an event of kind with data.

Parameters
kindstr

Event kind.

dataany; 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
kindstr

Event kind.

dataany; optional

Extra event data.

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

Unregister a listener for a given event kind.

Parameters
kindstr
listenerListener