/src/cpython-install/include/python3.16/cpython/monitoring.h

Source
#ifndef Py_MONITORING_H
#define Py_MONITORING_H
#ifndef Py_LIMITED_API
#ifdef __cplusplus
extern "C" {
#endif

// There is currently no limited API for monitoring


/* Local events.
 * These require bytecode instrumentation */

#define PY_MONITORING_EVENT_PY_START 0
#define PY_MONITORING_EVENT_PY_RESUME 1
#define PY_MONITORING_EVENT_PY_RETURN 2
#define PY_MONITORING_EVENT_PY_YIELD 3
#define PY_MONITORING_EVENT_CALL 4
#define PY_MONITORING_EVENT_LINE 5
#define PY_MONITORING_EVENT_INSTRUCTION 6
#define PY_MONITORING_EVENT_JUMP 7
#define PY_MONITORING_EVENT_BRANCH_LEFT 8
#define PY_MONITORING_EVENT_BRANCH_RIGHT 9
#define PY_MONITORING_EVENT_STOP_ITERATION 10

#define PY_MONITORING_IS_INSTRUMENTED_EVENT(ev) \
((ev) <= PY_MONITORING_EVENT_STOP_ITERATION)

/* Other events, mainly exceptions.
 * These can now be turned on and disabled on a per code object basis. */

#define PY_MONITORING_EVENT_RAISE 11
#define PY_MONITORING_EVENT_EXCEPTION_HANDLED 12
#define PY_MONITORING_EVENT_PY_UNWIND 13
#define PY_MONITORING_EVENT_PY_THROW 14
#define PY_MONITORING_EVENT_RERAISE 15

#define _PY_MONITORING_IS_UNGROUPED_EVENT(ev) \
((ev) < _PY_MONITORING_UNGROUPED_EVENTS)


/* Ancillary events */

#define PY_MONITORING_EVENT_C_RETURN 16
#define PY_MONITORING_EVENT_C_RAISE 17
#define PY_MONITORING_EVENT_BRANCH 18


typedef struct _PyMonitoringState {
    uint8_t active;
    uint8_t opaque;
} PyMonitoringState;


PyAPI_FUNC(int)
PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version,
                         const uint8_t *event_types, Py_ssize_t length);

PyAPI_FUNC(int)
PyMonitoring_ExitScope(void);


PyAPI_FUNC(int)
_PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                                PyObject *retval);

PyAPI_FUNC(int)
_PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                               PyObject *retval);

PyAPI_FUNC(int)
_PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                            PyObject* callable, PyObject *arg0);

PyAPI_FUNC(int)
_PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                            int lineno);

PyAPI_FUNC(int)
_PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                            PyObject *target_offset);

Py_DEPRECATED(3.14) PyAPI_FUNC(int)
_PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                              PyObject *target_offset);

PyAPI_FUNC(int)
_PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                              PyObject *target_offset);

PyAPI_FUNC(int)
_PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                              PyObject *target_offset);

PyAPI_FUNC(int)
_PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                               PyObject *retval);

PyAPI_FUNC(int)
_PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);

PyAPI_FUNC(int)
_PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value);


#define _PYMONITORING_IF_ACTIVE(STATE, X)  \
    if ((STATE)->active) { \
        return (X); \
    } \
    else { \
        return 0; \
    }

static inline int
PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FirePyStartEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FirePyResumeEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                               PyObject *retval)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FirePyReturnEvent(state, codelike, offset, retval));
}

static inline int
PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                              PyObject *retval)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FirePyYieldEvent(state, codelike, offset, retval));
}

static inline int
PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                           PyObject* callable, PyObject *arg0)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireCallEvent(state, codelike, offset, callable, arg0));
}

static inline int
PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                           int lineno)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireLineEvent(state, codelike, offset, lineno));
}

static inline int
PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                           PyObject *target_offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireJumpEvent(state, codelike, offset, target_offset));
}

static inline int
PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                             PyObject *target_offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireBranchRightEvent(state, codelike, offset, target_offset));
}

static inline int
PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                             PyObject *target_offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireBranchLeftEvent(state, codelike, offset, target_offset));
}

static inline int
PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
                              PyObject *retval)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireCReturnEvent(state, codelike, offset, retval));
}

static inline int
PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FirePyThrowEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireRaiseEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireReraiseEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireExceptionHandledEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireCRaiseEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FirePyUnwindEvent(state, codelike, offset));
}

static inline int
PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)
{
    _PYMONITORING_IF_ACTIVE(
        state,
        _PyMonitoring_FireStopIterationEvent(state, codelike, offset, value));
}

#undef _PYMONITORING_IF_ACTIVE

#ifdef __cplusplus
}
#endif
#endif  // !Py_LIMITED_API
#endif  // !Py_MONITORING_H

Coverage Report

Created: 2026-05-16 06:46

Line	Count	Source
1		#ifndef Py_MONITORING_H
2		#define Py_MONITORING_H
3		#ifndef Py_LIMITED_API
4		#ifdef __cplusplus
5		extern "C" {
6		#endif
7
8		// There is currently no limited API for monitoring
9
10
11		/* Local events.
12		* These require bytecode instrumentation */
13
14		#define PY_MONITORING_EVENT_PY_START 0
15		#define PY_MONITORING_EVENT_PY_RESUME 1
16		#define PY_MONITORING_EVENT_PY_RETURN 2
17		#define PY_MONITORING_EVENT_PY_YIELD 3
18		#define PY_MONITORING_EVENT_CALL 4
19		#define PY_MONITORING_EVENT_LINE 5
20		#define PY_MONITORING_EVENT_INSTRUCTION 6
21		#define PY_MONITORING_EVENT_JUMP 7
22		#define PY_MONITORING_EVENT_BRANCH_LEFT 8
23		#define PY_MONITORING_EVENT_BRANCH_RIGHT 9
24		#define PY_MONITORING_EVENT_STOP_ITERATION 10
25
26		#define PY_MONITORING_IS_INSTRUMENTED_EVENT(ev) \
27		((ev) <= PY_MONITORING_EVENT_STOP_ITERATION)
28
29		/* Other events, mainly exceptions.
30		* These can now be turned on and disabled on a per code object basis. */
31
32		#define PY_MONITORING_EVENT_RAISE 11
33		#define PY_MONITORING_EVENT_EXCEPTION_HANDLED 12
34		#define PY_MONITORING_EVENT_PY_UNWIND 13
35		#define PY_MONITORING_EVENT_PY_THROW 14
36		#define PY_MONITORING_EVENT_RERAISE 15
37
38		#define _PY_MONITORING_IS_UNGROUPED_EVENT(ev) \
39		((ev) < _PY_MONITORING_UNGROUPED_EVENTS)
40
41
42		/* Ancillary events */
43
44		#define PY_MONITORING_EVENT_C_RETURN 16
45		#define PY_MONITORING_EVENT_C_RAISE 17
46		#define PY_MONITORING_EVENT_BRANCH 18
47
48
49		typedef struct _PyMonitoringState {
50		uint8_t active;
51		uint8_t opaque;
52		} PyMonitoringState;
53
54
55		PyAPI_FUNC(int)
56		PyMonitoring_EnterScope(PyMonitoringState state_array, uint64_t version,
57		const uint8_t *event_types, Py_ssize_t length);
58
59		PyAPI_FUNC(int)
60		PyMonitoring_ExitScope(void);
61
62
63		PyAPI_FUNC(int)
64		_PyMonitoring_FirePyStartEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
65
66		PyAPI_FUNC(int)
67		_PyMonitoring_FirePyResumeEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
68
69		PyAPI_FUNC(int)
70		_PyMonitoring_FirePyReturnEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
71		PyObject *retval);
72
73		PyAPI_FUNC(int)
74		_PyMonitoring_FirePyYieldEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
75		PyObject *retval);
76
77		PyAPI_FUNC(int)
78		_PyMonitoring_FireCallEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
79		PyObject* callable, PyObject *arg0);
80
81		PyAPI_FUNC(int)
82		_PyMonitoring_FireLineEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
83		int lineno);
84
85		PyAPI_FUNC(int)
86		_PyMonitoring_FireJumpEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
87		PyObject *target_offset);
88
89		Py_DEPRECATED(3.14) PyAPI_FUNC(int)
90		_PyMonitoring_FireBranchEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
91		PyObject *target_offset);
92
93		PyAPI_FUNC(int)
94		_PyMonitoring_FireBranchRightEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
95		PyObject *target_offset);
96
97		PyAPI_FUNC(int)
98		_PyMonitoring_FireBranchLeftEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
99		PyObject *target_offset);
100
101		PyAPI_FUNC(int)
102		_PyMonitoring_FireCReturnEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
103		PyObject *retval);
104
105		PyAPI_FUNC(int)
106		_PyMonitoring_FirePyThrowEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
107
108		PyAPI_FUNC(int)
109		_PyMonitoring_FireRaiseEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
110
111		PyAPI_FUNC(int)
112		_PyMonitoring_FireReraiseEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
113
114		PyAPI_FUNC(int)
115		_PyMonitoring_FireExceptionHandledEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
116
117		PyAPI_FUNC(int)
118		_PyMonitoring_FireCRaiseEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
119
120		PyAPI_FUNC(int)
121		_PyMonitoring_FirePyUnwindEvent(PyMonitoringState state, PyObject codelike, int32_t offset);
122
123		PyAPI_FUNC(int)
124		_PyMonitoring_FireStopIterationEvent(PyMonitoringState state, PyObject codelike, int32_t offset, PyObject *value);
125
126
127		#define _PYMONITORING_IF_ACTIVE(STATE, X) \
128		if ((STATE)->active) { \
129		return (X); \
130		} \
131		else { \
132		return 0; \
133		}
134
135		static inline int
136		PyMonitoring_FirePyStartEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
137	0	{
138	0	_PYMONITORING_IF_ACTIVE(
139	0	state,
140	0	_PyMonitoring_FirePyStartEvent(state, codelike, offset));
141	0	}
142
143		static inline int
144		PyMonitoring_FirePyResumeEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
145	0	{
146	0	_PYMONITORING_IF_ACTIVE(
147	0	state,
148	0	_PyMonitoring_FirePyResumeEvent(state, codelike, offset));
149	0	}
150
151		static inline int
152		PyMonitoring_FirePyReturnEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
153		PyObject *retval)
154	0	{
155	0	_PYMONITORING_IF_ACTIVE(
156	0	state,
157	0	_PyMonitoring_FirePyReturnEvent(state, codelike, offset, retval));
158	0	}
159
160		static inline int
161		PyMonitoring_FirePyYieldEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
162		PyObject *retval)
163	0	{
164	0	_PYMONITORING_IF_ACTIVE(
165	0	state,
166	0	_PyMonitoring_FirePyYieldEvent(state, codelike, offset, retval));
167	0	}
168
169		static inline int
170		PyMonitoring_FireCallEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
171		PyObject* callable, PyObject *arg0)
172	0	{
173	0	_PYMONITORING_IF_ACTIVE(
174	0	state,
175	0	_PyMonitoring_FireCallEvent(state, codelike, offset, callable, arg0));
176	0	}
177
178		static inline int
179		PyMonitoring_FireLineEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
180		int lineno)
181	0	{
182	0	_PYMONITORING_IF_ACTIVE(
183	0	state,
184	0	_PyMonitoring_FireLineEvent(state, codelike, offset, lineno));
185	0	}
186
187		static inline int
188		PyMonitoring_FireJumpEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
189		PyObject *target_offset)
190	0	{
191	0	_PYMONITORING_IF_ACTIVE(
192	0	state,
193	0	_PyMonitoring_FireJumpEvent(state, codelike, offset, target_offset));
194	0	}
195
196		static inline int
197		PyMonitoring_FireBranchRightEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
198		PyObject *target_offset)
199	0	{
200	0	_PYMONITORING_IF_ACTIVE(
201	0	state,
202	0	_PyMonitoring_FireBranchRightEvent(state, codelike, offset, target_offset));
203	0	}
204
205		static inline int
206		PyMonitoring_FireBranchLeftEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
207		PyObject *target_offset)
208	0	{
209	0	_PYMONITORING_IF_ACTIVE(
210	0	state,
211	0	_PyMonitoring_FireBranchLeftEvent(state, codelike, offset, target_offset));
212	0	}
213
214		static inline int
215		PyMonitoring_FireCReturnEvent(PyMonitoringState state, PyObject codelike, int32_t offset,
216		PyObject *retval)
217	0	{
218	0	_PYMONITORING_IF_ACTIVE(
219	0	state,
220	0	_PyMonitoring_FireCReturnEvent(state, codelike, offset, retval));
221	0	}
222
223		static inline int
224		PyMonitoring_FirePyThrowEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
225	0	{
226	0	_PYMONITORING_IF_ACTIVE(
227	0	state,
228	0	_PyMonitoring_FirePyThrowEvent(state, codelike, offset));
229	0	}
230
231		static inline int
232		PyMonitoring_FireRaiseEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
233	0	{
234	0	_PYMONITORING_IF_ACTIVE(
235	0	state,
236	0	_PyMonitoring_FireRaiseEvent(state, codelike, offset));
237	0	}
238
239		static inline int
240		PyMonitoring_FireReraiseEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
241	0	{
242	0	_PYMONITORING_IF_ACTIVE(
243	0	state,
244	0	_PyMonitoring_FireReraiseEvent(state, codelike, offset));
245	0	}
246
247		static inline int
248		PyMonitoring_FireExceptionHandledEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
249	0	{
250	0	_PYMONITORING_IF_ACTIVE(
251	0	state,
252	0	_PyMonitoring_FireExceptionHandledEvent(state, codelike, offset));
253	0	}
254
255		static inline int
256		PyMonitoring_FireCRaiseEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
257	0	{
258	0	_PYMONITORING_IF_ACTIVE(
259	0	state,
260	0	_PyMonitoring_FireCRaiseEvent(state, codelike, offset));
261	0	}
262
263		static inline int
264		PyMonitoring_FirePyUnwindEvent(PyMonitoringState state, PyObject codelike, int32_t offset)
265	0	{
266	0	_PYMONITORING_IF_ACTIVE(
267	0	state,
268	0	_PyMonitoring_FirePyUnwindEvent(state, codelike, offset));
269	0	}
270
271		static inline int
272		PyMonitoring_FireStopIterationEvent(PyMonitoringState state, PyObject codelike, int32_t offset, PyObject *value)
273	0	{
274	0	_PYMONITORING_IF_ACTIVE(
275	0	state,
276	0	_PyMonitoring_FireStopIterationEvent(state, codelike, offset, value));
277	0	}
278
279		#undef _PYMONITORING_IF_ACTIVE
280
281		#ifdef __cplusplus
282		}
283		#endif
284		#endif // !Py_LIMITED_API
285		#endif // !Py_MONITORING_H