监控 C API¶
3.13版本添加。
An extension may need to interact with the event monitoring system. Subscribing
to events and registering callbacks can be done via the Python API exposed in
sys.monitoring
.
Generating Execution Events¶
The functions below make it possible for an extension to fire monitoring
events as it emulates the execution of Python code. Each of these functions
accepts a PyMonitoringState
struct which contains concise information
about the activation state of events, as well as the event arguments, which
include a PyObject*
representing the code object, the instruction offset
and sometimes additional, event-specific arguments (see sys.monitoring
for details about the signatures of the different event callbacks).
The codelike
argument should be an instance of types.CodeType
or of a type that emulates it.
The VM disables tracing when firing an event, so there is no need for user code to do that.
Monitoring functions should not be called with an exception set, except those listed below as working with the current exception.
-
type PyMonitoringState¶
Representation of the state of an event type. It is allocated by the user while 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.
See sys.monitoring
for descriptions of the events.
-
int PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
发出
PY_START
事件。
-
int PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
发出
PY_RESUME
事件。
-
int PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)¶
发出
PY_RETURN
事件。
-
int PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)¶
发出
PY_YIELD
事件。
-
int PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *callable, PyObject *arg0)¶
发出
CALL
事件。
-
int PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)¶
发出
LINE
事件。
-
int PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)¶
发出
JUMP
事件。
-
int PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)¶
发出
BRANCH
事件。
-
int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)¶
发出
C_RETURN
事件。
-
int PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
使用当前(即
PyErr_GetRaisedException()
返回的)异常发出PY_THROW
事件。
-
int PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
使用当前(即
PyErr_GetRaisedException()
所返回的)异常发出RAISE
事件。event with the current ).
-
int PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
使用当前(即
PyErr_GetRaisedException()
所返回的)异常发出C_RAISE
事件。
-
int PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
使用当前(即
PyErr_GetRaisedException()
所返回的)异常发出RERAISE
事件。
-
int PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
使用当前(即
PyErr_GetRaisedException()
所返回的)异常发出EXCEPTION_HANDLED
事件。
-
int PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
使用当前(即
PyErr_GetRaisedException()
所返回的)异常发出PY_UNWIND
事件。
-
int PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶
使用当前(即
PyErr_GetRaisedException()
所返回的)异常发出STOP_ITERATION
事件。
Managing the Monitoring State¶
Monitoring states can be managed with the help of monitoring scopes. A scope would typically correspond to a python function.