Events

As a code object executes various events occur that might be of interest to tools. By activating events and by registering callback functions tools can respond to these events in any way that suits them. Events can be set globally, or for individual code objects.

For 3.12, CPython will support the following events:

• PY_START: Start of a Python function (occurs immediately after the call, the callee’s frame will be on the stack)
• PY_RESUME: Resumption of a Python function (for generator and coroutine functions), except for throw() calls.
• PY_THROW: A Python function is resumed by a throw() call.
• PY_RETURN: Return from a Python function (occurs immediately before the return, the callee’s frame will be on the stack).
• PY_YIELD: Yield from a Python function (occurs immediately before the yield, the callee’s frame will be on the stack).
• PY_UNWIND: Exit from a Python function during exception unwinding.
• C_CALL: Call to any callable, except Python functions (before the call in this case).
• C_RETURN: Return from any callable, except Python functions (after the return in this case).
• RAISE: An exception is raised.
• EXCEPTION_HANDLED: An exception is handled.
• LINE: An instruction is about to be executed that has a different line number from the preceding instruction.
• INSTRUCTION – A VM instruction is about to be executed.
• JUMP – An unconditional jump in the control flow graph is reached.
• BRANCH – A conditional branch is about to be taken (or not).
• MARKER – A marker is hit

More events may be added in the future.

All events will be attributes of the Event enum in sys.monitoring:

class Event(enum.IntFlag):
    PY_CALL = ...

Note that Event is an IntFlag which means that the events can be or-ed together to form a set of events.

Tool identifiers

The VM can support up to 6 tools at once. Before registering or activating events, a tool should choose an identifier. Identifiers are integers in the range 0 to 5.

sys.monitoring.use_tool_id(id, name:str) -> None
sys.monitoring.free_tool_id(id) -> None
sys.monitoring.get_tool(id) ->  str | None

sys.monitoring.use_tool_id raises a ValueError if id is in use. sys.monitoring.get_tool returns the name of the tool if id is in use, otherwise it returns None.

All IDs are treated the same by the VM with regard to events, but the following IDs are pre-defined to make co-operation of tools easier:

sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 3

There is no obligation to set an ID, nor is there anything preventing a tool from using an ID even it is already in use. However, tool are encouraged to use a unique ID and respect other tools.

For example, if a debugger were attached and DEBUGGER_ID were in use, it should report an error, rather than carrying on regardless.

The OPTIMIZER_ID is provided for tools like Cinder or PyTorch that want to optimize Python code, but need to decide what to optimize in a way that depends on some wider context.

Setting events globally

Events can be controlled globally by modifying the set of events being monitored:

• sys.monitoring.get_events(tool_id:int)->Event Returns the Event set for all the active events.
• sys.monitoring.set_events(tool_id:int, event_set: Event) Activates all events which are set in event_set.

No events are active by default.

Per code object events

Events can also be controlled on a per code object basis:

• sys.monitoring.get_local_events(tool_id:int, code: CodeType)->Event Returns the Event set for all the local events for code
• sys.monitoring.set_local_events(tool_id:int, code: CodeType, event_set: Event) Activates all the local events for code which are set in event_set.

Local events add to global events, but do not mask them. In other words, all global events will trigger for a code object, regardless of the local events.

Register callback functions

To register a callable for events call:

sys.monitoring.register_callback(tool_id:int, event: Event, func: Callable | None) -> Callable | None

If another callback was registered for the given tool_id and event, it is unregistered and returned. Otherwise register_callback returns None.

Functions can be unregistered by calling sys.monitoring.register_callback(tool_id, event, None).

Callback functions can be registered and unregistered at any time.

Registering or unregistering a callback function will generate a sys.audit event.

Events in callback functions

Events are suspended in callback functions and their callees for the tool that registered that callback.

That means that other tools will see events in the callback functions for other tools. This could be useful for debugging a profiling tool, but would produce misleading profiles, as the debugger tool would show up in the profile.

Inserting and removing markers

Two new functions are added to the sys module to support markers.

• sys.monitoring.insert_marker(tool_id: int, code: CodeType, offset: int)
• sys.monitoring.remove_marker(tool_id: int, code: CodeType, offset: int)

A single code object may not have more than 255 markers at once. sys.monitoring.insert_marker raises a ValueError if this limit is exceeded.

Order of events

If an instructions triggers several events they occur in the following order:

• MARKER
• INSTRUCTION
• LINE
• All other events (only one of these events can occur per instruction)

Each event is delivered to tools in ascending order of ID.

Attributes of the sys.monitoring namespace

• class Event(enum.IntFlag)
• def use_tool_id(id)->None
• def free_tool_id(id)->None
• def get_events(tool_id: int)->Event
• def set_events(tool_id: int, event_set: Event)->None
• def get_local_events(tool_id: int, code: CodeType)->Event
• def set_local_events(tool_id: int, code: CodeType, event_set: Event)->None
• def register_callback(tool_id: int, event: Event, func: Callable)->Optional[Callable]
• def insert_marker(tool_id: int, code: CodeType, offset: Event)->None
• def remove_marker(tool_id: int, code: CodeType, offset: Event)->None
• def restart_events()->None
• DISABLE: object

Access to “debug only” features

Some features of the standard library are not accessible to normal code, but are accessible to debuggers. For example, setting local variables, or the line number.

These features will be available to callback functions.

Performance

If no events are active, this PEP should have a small positive impact on performance. Experiments show between 1 and 2% speedup from not supporting sys.settrace() directly.

The performance of sys.settrace() will be worse. The performance of sys.setprofile() should be better. However, tools relying on sys.settrace() and sys.setprofile() can be made a lot faster by using the API provided by this PEP.

If a small set of events are active, e.g. for a debugger, then the overhead of callbacks will be orders of magnitudes less than for sys.settrace() and much cheaper than using PEP 523.

Coverage tools can be implemented at very low cost, by returning DISABLE in all callbacks.

For heavily instrumented code, e.g. using LINE, performance should be better than sys.settrace, but not by that much as performance will be dominated by the time spent in callbacks.

For optimizing virtual machines, such as future versions of CPython (and PyPy should they choose to support this API), changes to the set active events in the midst of a long running program could be quite expensive, possibly taking hundreds of milliseconds as it triggers de-optimizations. Once such de-optimization has occurred, performance should recover as the VM can re-optimize the instrumented code.

In general these operations can be considered to be fast:

• def get_events(tool_id: int)->Event
• def get_local_events(tool_id: int, code: CodeType)->Event
• def register_callback(tool_id: int, event: Event, func: Callable)->Optional[Callable]
• def get_tool(tool_id) -> str | None

These operations are slower, but not especially so:

• def set_local_events(tool_id: int, code: CodeType, event_set: Event)->None
• def insert_marker(tool_id: int, code: CodeType, offset: Event)->None
• def remove_marker(tool_id: int, code: CodeType, offset: Event)->None

And these operations should be regarded as slow:

• def use_tool_id(id, name:str)->None
• def free_tool_id(id)->None
• def set_events(tool_id: int, event_set: Event)->None
• def restart_events()->None

How slow the slow operations are depends on when then happen. If done early in the program, before modules are loaded, they should be fairly inexpensive.

Debuggers

sys.monitoring.insert_marker(code, offset)

sys.monitoring.remove_marker(code, offset)

Coverage Tools

Coverage tools need to track which parts of the control graph have been executed. To do this, they need to register for the PY_ events, plus JUMP and BRANCH.

This information can be then be converted back into a line based report after execution has completed.

Profilers

Simple profilers need to gather information about calls. To do this profilers should register for the following events:

• PY_CALL
• PY_RESUME
• PY_THROW
• PY_RETURN
• PY_YIELD
• PY_UNWIND
• C_CALL
• C_RETURN