/src/cpython-install/include/python3.15/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_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

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

Coverage Report

Created: 2025-10-10 06:33

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