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

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