Monitoring C API¶

Added in version 3.13.

An extension may need to interact with the event monitoring system. Subscribingto events and registering callbacks can be done via the Python API exposed insys.monitoring.

Generating Execution Events¶

The functions below make it possible for an extension to fire monitoringevents as it emulates the execution of Python code. Each of these functionsaccepts aPyMonitoringState struct which contains concise informationabout the activation state of events, as well as the event arguments, whichinclude aPyObject* representing the code object, the instruction offsetand sometimes additional, event-specific arguments (seesys.monitoringfor details about the signatures of the different event callbacks).Thecodelike argument should be an instance oftypes.CodeTypeor of a type that emulates it.

The VM disables tracing when firing an event, so there is no need for usercode to do that.

Monitoring functions should not be called with an exception set,except those listed below as working with the current exception.

typePyMonitoringState¶

Representation of the state of an event type. It is allocated by the userwhile its contents are maintained by the monitoring API functions described below.

All of the functions below return 0 on success and -1 (with an exception set) on error.

Seesys.monitoring for descriptions of the events.

intPyMonitoring_FirePyStartEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire aPY_START event.

intPyMonitoring_FirePyResumeEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire aPY_RESUME event.

intPyMonitoring_FirePyReturnEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*retval)¶

Fire aPY_RETURN event.

intPyMonitoring_FirePyYieldEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*retval)¶

Fire aPY_YIELD event.

intPyMonitoring_FireCallEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*callable,PyObject*arg0)¶

Fire aCALL event.

intPyMonitoring_FireLineEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,intlineno)¶

Fire aLINE event.

intPyMonitoring_FireJumpEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*target_offset)¶

Fire aJUMP event.

intPyMonitoring_FireBranchLeftEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*target_offset)¶

Fire aBRANCH_LEFT event.

intPyMonitoring_FireBranchRightEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*target_offset)¶

Fire aBRANCH_RIGHT event.

intPyMonitoring_FireCReturnEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*retval)¶

Fire aC_RETURN event.

intPyMonitoring_FirePyThrowEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire aPY_THROW event with the current exception (as returned byPyErr_GetRaisedException()).

intPyMonitoring_FireRaiseEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire aRAISE event with the current exception (as returned byPyErr_GetRaisedException()).

intPyMonitoring_FireCRaiseEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire aC_RAISE event with the current exception (as returned byPyErr_GetRaisedException()).

intPyMonitoring_FireReraiseEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire aRERAISE event with the current exception (as returned byPyErr_GetRaisedException()).

intPyMonitoring_FireExceptionHandledEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire anEXCEPTION_HANDLED event with the current exception (as returned byPyErr_GetRaisedException()).

intPyMonitoring_FirePyUnwindEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset)¶

Fire aPY_UNWIND event with the current exception (as returned byPyErr_GetRaisedException()).

intPyMonitoring_FireStopIterationEvent(PyMonitoringState*state,PyObject*codelike,int32_toffset,PyObject*value)¶

Fire aSTOP_ITERATION event. Ifvalue is an instance ofStopIteration, it is used. Otherwise,a newStopIteration instance is created withvalue as its argument.