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

Source (jump to first uncovered line)
#ifndef Py_CPYTHON_MONITORING_H
#  error "this header file must not be included directly"
#endif

/* 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_LOCAL_EVENTS)

/* Other events, mainly exceptions */

#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


/* 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

Coverage Report

Created: 2025-07-04 06:49

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