Debian Codegraph @

Doc/c-api/monitoring.rst

raw
1 .. highlight:: c
2
3 .. _c-api-monitoring:
4
5 Monitoring C API
6 ================
7
8 Added in version 3.13.
9
10 An extension may need to interact with the event monitoring system. Subscribing
11 to events and registering callbacks can be done via the Python API exposed in
12 :mod:`sys.monitoring`.
13
14 Generating Execution Events
15 ===========================
16
17 The functions below make it possible for an extension to fire monitoring
18 events as it emulates the execution of Python code. Each of these functions
19 accepts a ``PyMonitoringState`` struct which contains concise information
20 about the activation state of events, as well as the event arguments, which
21 include a ``PyObject*`` representing the code object, the instruction offset
22 and sometimes additional, event-specific arguments (see :mod:`sys.monitoring`
23 for details about the signatures of the different event callbacks).
24 The ``codelike`` argument should be an instance of :class:`types.CodeType`
25 or of a type that emulates it.
26
27 The VM disables tracing when firing an event, so there is no need for user
28 code to do that.
29
30 Monitoring functions should not be called with an exception set,
31 except those listed below as working with the current exception.
32
33 .. c:type:: PyMonitoringState
34
35 Representation of the state of an event type. It is allocated by the user
36 while its contents are maintained by the monitoring API functions described below.
37
38
39 All of the functions below return 0 on success and -1 (with an exception set) on error.
40
41 See :mod:`sys.monitoring` for descriptions of the events.
42
43 .. c:function:: int PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
44
45 Fire a ``PY_START`` event.
46
47
48 .. c:function:: int PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
49
50 Fire a ``PY_RESUME`` event.
51
52
53 .. c:function:: int PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject* retval)
54
55 Fire a ``PY_RETURN`` event.
56
57
58 .. c:function:: int PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject* retval)
59
60 Fire a ``PY_YIELD`` event.
61
62
63 .. c:function:: int PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject* callable, PyObject *arg0)
64
65 Fire a ``CALL`` event.
66
67
68 .. c:function:: int PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)
69
70 Fire a ``LINE`` event.
71
72
73 .. c:function:: int PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
74
75 Fire a ``JUMP`` event.
76
77
78 .. c:function:: int PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
79
80 Fire a ``BRANCH_LEFT`` event.
81
82
83 .. c:function:: int PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)
84
85 Fire a ``BRANCH_RIGHT`` event.
86
87
88 .. c:function:: int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)
89
90 Fire a ``C_RETURN`` event.
91
92
93 .. c:function:: int PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
94
95 Fire a ``PY_THROW`` event with the current exception (as returned by
96 :c:func:`PyErr_GetRaisedException`).
97
98
99 .. c:function:: int PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
100
101 Fire a ``RAISE`` event with the current exception (as returned by
102 :c:func:`PyErr_GetRaisedException`).
103
104
105 .. c:function:: int PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
106
107 Fire a ``C_RAISE`` event with the current exception (as returned by
108 :c:func:`PyErr_GetRaisedException`).
109
110
111 .. c:function:: int PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
112
113 Fire a ``RERAISE`` event with the current exception (as returned by
114 :c:func:`PyErr_GetRaisedException`).
115
116
117 .. c:function:: int PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
118
119 Fire an ``EXCEPTION_HANDLED`` event with the current exception (as returned by
120 :c:func:`PyErr_GetRaisedException`).
121
122
123 .. c:function:: int PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
124
125 Fire a ``PY_UNWIND`` event with the current exception (as returned by
126 :c:func:`PyErr_GetRaisedException`).
127
128
129 .. c:function:: int PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)
130
131 Fire a ``STOP_ITERATION`` event. If ``value`` is an instance of :exc:`StopIteration`, it is used. Otherwise,
132 a new :exc:`StopIteration` instance is created with ``value`` as its argument.
133
134
135 Managing the Monitoring State
136 -----------------------------
137
138 Monitoring states can be managed with the help of monitoring scopes. A scope
139 would typically correspond to a Python function.
140
141 .. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
142
143 Enter a monitored scope. ``event_types`` is an array of the event IDs for
144 events that may be fired from the scope. For example, the ID of a ``PY_START``
145 event is the value ``PY_MONITORING_EVENT_PY_START``, which is numerically equal
146 to the base-2 logarithm of ``sys.monitoring.events.PY_START``.
147 ``state_array`` is an array with a monitoring state entry for each event in
148 ``event_types``, it is allocated by the user but populated by
149 :c:func:`!PyMonitoring_EnterScope` with information about the activation state of
150 the event. The size of ``event_types`` (and hence also of ``state_array``)
151 is given in ``length``.
152
153 The ``version`` argument is a pointer to a value which should be allocated
154 by the user together with ``state_array`` and initialized to 0,
155 and then set only by :c:func:`!PyMonitoring_EnterScope` itself. It allows this
156 function to determine whether event states have changed since the previous call,
157 and to return quickly if they have not.
158
159 The scopes referred to here are lexical scopes: a function, class or method.
160 :c:func:`!PyMonitoring_EnterScope` should be called whenever the lexical scope is
161 entered. Scopes can be reentered, reusing the same *state_array* and *version*,
162 in situations like when emulating a recursive Python function. When a code-like's
163 execution is paused, such as when emulating a generator, the scope needs to
164 be exited and re-entered.
165
166 The macros for *event_types* are:
167
168 .. c:namespace:: NULL
169
170 .. The table is here to make the docs searchable, and to allow automatic
171 links to the identifiers.
172
173 ================================================== =====================================
174 Macro Event
175 ================================================== =====================================
176 .. c:macro:: PY_MONITORING_EVENT_BRANCH_LEFT :monitoring-event:`BRANCH_LEFT`
177 .. c:macro:: PY_MONITORING_EVENT_BRANCH_RIGHT :monitoring-event:`BRANCH_RIGHT`
178 .. c:macro:: PY_MONITORING_EVENT_CALL :monitoring-event:`CALL`
179 .. c:macro:: PY_MONITORING_EVENT_C_RAISE :monitoring-event:`C_RAISE`
180 .. c:macro:: PY_MONITORING_EVENT_C_RETURN :monitoring-event:`C_RETURN`
181 .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED`
182 .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION`
183 .. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP`
184 .. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE`
185 .. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME`
186 .. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN`
187 .. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START`
188 .. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW`
189 .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND`
190 .. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD`
191 .. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE`
192 .. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE`
193 .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION`
194 ================================================== =====================================
195
196 .. c:function:: int PyMonitoring_ExitScope(void)
197
198 Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.
199
200
201 .. c:function:: int PY_MONITORING_IS_INSTRUMENTED_EVENT(uint8_t ev)
202
203 Return true if the event corresponding to the event ID *ev* is
204 a :ref:`local event <monitoring-event-local>`.
205
206 .. versionadded:: 3.13
207
208 .. soft-deprecated:: 3.14